Il nodo Esegui chiamata API trasforma il workflow in un punto di integrazione attivo con sistemi esterni, permettendoti di inviare dati, sincronizzare piattaforme e attivare processi personalizzati nel momento esatto in cui avviene un evento.
È lo strumento pensato per estendere la marketing automation oltre magnews, mantenendo controllo sul flusso, sui dati scambiati e sulla gestione delle risposte, senza uscire dal workflow.
Quando usarlo
Questo nodo è ideale quando il workflow deve reagire a un evento e notificare un sistema esterno in tempo reale. Ad esempio puoi usarlo per:
- Inviare dati a un CRM quando un contatto entra in un percorso specifico
- Aggiornare un sistema di ticketing dopo un’azione del contatto
- Attivare processi personalizzati su piattaforme di terze parti
- Sincronizzare stati, punteggi o attributi mentre il contatto avanza nel flusso
Ogni volta che un workflow deve comunicare con sistemi esterni a magnews, questo nodo rappresenta il punto di integrazione naturale.
Come funziona
Il nodo invia una richiesta API REST a un endpoint esterno. La configurazione richiede l’URL dell’endpoint e il metodo HTTP da utilizzare. Sono supportati i principali metodi REST:
- GET
- POST
- PUT
- DELETE
- HEAD
- PATCH
In questo modo puoi adattare la chiamata alle specifiche dell’endpoint che stai contattando.
Descrizione del nodo
Nel nodo puoi personalizzare la descrizione per documentare lo scopo della specifica chiamata API.
Una volta salvato il nodo, la descrizione viene mostrata direttamente nella board del workflow, all’interno del nodo stesso. In questo modo, lo scopo della chiamata è immediatamente visibile senza riaprire la configurazione.
È particolarmente utile quando nello stesso workflow usi più nodi di questo tipo perché rende il flusso più leggibile e facile da mantenere nel tempo.
Header della richiesta
Puoi aggiungere header personalizzati per fornire informazioni aggiuntive all’endpoint, come token di autenticazione o parametri di contesto. Gli header supportano variabili e placeholder del workflow per passare valori dinamici legati al contatto o al flusso.
Esempi di header:
Content-Type: application/textAuthorization: Bearer ${access_token}, dove ${access_token} è il placeholder per il token OAuthX-Email: [contact:email], dove email indica l’indirizzo email del contattoX-Variable: [workflow:myvariable], dove myvariable indica il nome di una variabile di workflowX-Wfname: [workflowproperties:name], dove name indica il nome del workflow
Body della richiesta
Quando previsto, il body della richiesta è sempre in formato JSON. Anche qui puoi usare variabili e placeholder per inserire valori dinamici, ad esempio dati del contatto, variabili di workflow o informazioni raccolte in precedenza.
Esempio di body:
{
"email": "[contact:email]",
"punteggio": "[workflow:myvariable]",
"token": "${access_token}"
}Autenticazione OAuth
Se l’endpoint richiede un token di autenticazione, puoi associare al nodo un certificato digitale di tipo Server OAuth oppure crearne uno nuovo da Impostazioni > Web service.
Se l’API richiede che il token venga inserito in un punto specifico della richiesta, puoi scrivere il placeholder ${access_token} dove necessario, ad esempio in un header o nel body.
Se non lo specifichi esplicitamente, l’header Authorization: Bearer ${access_token} viene aggiunto automaticamente alla chiamata REST basandosi sul certificato digitale selezionato.
Se l’endpoint non richiede autenticazione, questo campo può rimanere vuoto.
Salvare la risposta della chiamata
Il nodo permette anche di salvare la risposta della chiamata API all’interno di una variabile di workflow, sia in caso di successo sia in caso di errore.
La risposta viene memorizzata in formato JSON nella variabile che selezioni in configurazione, con questa struttura:
{
"httpstatus": 200,
"body": "...raw response..."
}Il campo httpstatus contiene il codice di stato HTTP restituito dall’endpoint, mentre body contiene la risposta in formato raw, ovvero il pacchetto di dati non elaborato.
Gestione SSL e retry
Il nodo consente anche di contattare endpoint con certificati SSL scaduti o non verificabili, tramite un’opzione dedicata. L’opzione è pensata esclusivamente per ambienti di test o contesti controllati.
In caso di errore 401 Unauthorized, la chiamata può essere ripetuta automaticamente con un nuovo token OAuth. Questo secondo tentativo è l’unico retry previsto. Se fallisce anche questo, la richiesta viene considerata non riuscita e il workflow prosegue secondo la logica che hai impostato.