Chiamare un'API esterna

Lo usi per cercare un cliente nel gestionale, creare un lead nel CRM, aprire un ticket, controllare lo stato di un ordine.

#Configurare la chiamata

Aggiungi il nodo con il + e scegli API. Il pannello ha tre fasce: API, Test e Schema della Risposta, Accesso ai Dati (Output).

Nome del Nodo Testo · massimo 50 caratteri

Per esempio «CRM».

Metodo GET, POST, PUT, DELETE

GET per leggere, POST per creare, PUT per aggiornare, DELETE per eliminare: segui la documentazione del servizio.

Predefinito: GET

URL Testo con variabili

L'indirizzo dell'API, oppure una variabile. Deve iniziare con https:// o http://: con altri inizi il nodo segnala «L'URL non è un indirizzo valido.». Usa https:// quando il servizio lo offre: vedi Sicurezza: buone pratiche.

Parametri Chiave e valore

I parametri da aggiungere all'indirizzo, dopo il «?». Si aggiungono con Aggiungi parametro. Un parametro che dopo la sostituzione delle variabili resta vuoto non viene mandato.

Headers Chiave e valore

Gli header della richiesta, per esempio Authorization con il valore Bearer LA-TUA-CHIAVE. Si aggiungono con Aggiungi header.

Corpo della richiesta (JSON) Solo con POST e PUT

Il corpo in JSON, nella scheda Body, con Aggiungi variabile. Un JSON non valido è segnalato sotto il campo.

Il servizio ha 60 secondi per rispondere: cosa succede se non va è in Quando la chiamata non va.

#Usare le variabili nella chiamata

Indirizzo, parametri, header e corpo accettano le variabili. Quando l'automazione parte, al loro posto entrano i valori veri.

• Nell'indirizzo: https://api.esempio.it/clienti/{{webhook.idCliente}}.
• In un parametro: chiave email, valore {{user.email}}.
• Nel corpo, un valore fatto solo da una variabile mantiene il suo tipo: "totale": "{{webhook.ordine.totale}}" parte come numero. Dentro un testo più lungo diventa testo.

#Provare la chiamata

Nella fascia Test e Schema della Risposta, in «Come ottenere la risposta», scegli una delle due strade. Serve una risposta per sapere quali dati arriveranno ai nodi successivi.

Risposta Live Predefinita

In Valori di prova c'è un campo per ogni variabile usata nella chiamata: scrivi i valori da usare nel test, quelli vuoti partono vuoti. Premi Effettua test, che si accende quando la fascia API è completa.

Risposta di Esempio

Incolla in Risposta di esempio (JSON) una risposta realistica, presa dalla documentazione del servizio. Nessuna chiamata parte.

Se il test riesce compare «Test API completato» con il JSON della risposta. Se il servizio risponde con un errore, un riquadro rosso mostra lo stato, per esempio 404, e il corpo dell'errore.

Con la Risposta Live il nodo non si pubblica finché il test non è riuscito. Dopo una modifica alla chiamata, rifai il test per controllare la risposta.

#Scegliere i dati della risposta

Nella fascia Accesso ai Dati (Output) decidi cosa passa ai nodi successivi.

• Pieno accesso ai dati, il predefinito: tutta la risposta è disponibile.
• Accesso ristretto ai dati: solo i dati che spunti nell'albero di caselle, con Seleziona tutti se servono. Un dato scelto arriva intero, con tutto ciò che contiene; se la risposta è una lista, la scelta vale per ogni elemento.

Se la risposta non ha chiavi, l'accesso ristretto non si può usare.

#Usare la risposta

Se il nodo si chiama «Gestionale», la risposta è in {{Gestionale}}. I singoli campi si leggono col punto e, nelle liste, con la posizione da 0. Il pannello delle variabili, scheda Nodi, propone i campi letti dalla risposta di prova o di esempio. Come per gli altri nodi, vedi Risultati dei nodi.

JSON · la risposta del servizioCopia

{
  "trovato": true,
  "cliente": { "id": 381, "nome": "Mario Rossi", "livello": "gold" },
  "ordini": [ { "numero": "A-1029", "stato": "spedito" } ]
}

Puoi usare questi valori in una Condizione, per esempio {{Gestionale.trovato}} con È vero. Vanno bene anche in un'email, in un template WhatsApp o nel corpo di una Risposta Webhook.

#Due esempi completi

Cercare un cliente nel gestionale. Nodo «Gestionale»: metodo GET; URL https://api.esempio.it/clienti; parametro email = {{user.email}}; header Authorization = Bearer LA-TUA-CHIAVE. Dopo il test, una Condizione su {{Gestionale.cliente.livello}} «Uguale a» gold manda i clienti migliori su un ramo dedicato.

Aprire un ticket. Nodo «Ticket»: metodo POST; URL https://api.esempio.it/ticket; stesso header; nel Body:

JSON · il Body del nodo TicketCopia

{
  "oggetto": "Cliente non raggiunto al telefono",
  "telefono": "{{user.phone}}",
  "nota": "Richiamare {{user.fullName}}",
  "priorita": 2
}

Per il test scegli Risposta di Esempio, così non apri un ticket vero, e incolla la risposta della documentazione, per esempio {"id": 77, "stato": "aperto"}.

#Quando la chiamata non va

Se la chiamata fallisce in modo definitivo, l'automazione si ferma al nodo e i nodi successivi non lavorano. Nel dettaglio dell'esecuzione la scheda del nodo mostra la richiesta inviata, lo Stato HTTP e la Risposta.

#Sicurezza: buone pratiche

• Metti chiavi e token solo negli header del nodo API. Nel dettaglio delle esecuzioni l'autorizzazione compare mascherata.
• Non scrivere mai una chiave nelle istruzioni di un Prompt o nel testo di un messaggio. Le istruzioni arrivano al modello AI e compaiono nel dettaglio dell'esecuzione.
• Crea una chiave dedicata a SupportFast, con i soli permessi che servono, per esempio la sola lettura dei clienti. Se serve, la revochi senza toccare il resto.
• Usa indirizzi https://. Un indirizzo http:// è accettato e la chiamata parte, ma dati e chiavi viaggiano senza cifratura.
• Manda solo i dati personali che servono al servizio esterno: vedi Privacy e sicurezza.
• Chi gestisce le automazioni vede la configurazione del nodo, chiavi comprese: dai il permesso Gestisci solo a chi serve.

#Domande frequenti

#Leggi anche