La configurazione corretta dell'URL e del metodo HTTP è fondamentale per il successo della tua Action. Questi elementi determinano dove e come viene inviata la richiesta al servizio esterno.
Configurazione dell'URL
Formato dell'URL
L'URL deve essere completo e accessibile pubblicamente:
- Protocollo: Sempre HTTPS per sicurezza (https://)
- Dominio: Il dominio del servizio che vuoi chiamare
- Percorso: Il path specifico dell'endpoint API
- Versione API: Spesso inclusa nel percorso (es. /v1/, /api/v2/)
Esempi di URL validi:
https://api.esempio.com/v1/ticketshttps://miosito.com/api/contattihttps://webhook.zapier.com/hooks/catch/12345/abcdefhttps://api.mailgun.com/v3/sandbox.mailgun.org/messages
URL con parametri dinamici
Alcuni endpoint richiedono parametri nell'URL stesso. Evolbot supporta placeholder che vengono sostituiti automaticamente:
- Formato:
{nome_parametro} - Esempio:
https://api.esempio.com/users/{user_id}/orders - Sostituzione:
{user_id}verrà sostituito con il valore del parametro user_id
Metodi HTTP disponibili
GET - Recupero informazioni
Quando usarlo:
- Controllare lo stato di un ordine
- Verificare disponibilità prodotti
- Ottenere informazioni da database
- Recuperare lista appuntamenti disponibili
Caratteristiche:
- Non modifica dati sul server
- Parametri vengono inviati nell'URL (query string)
- Idempotente (può essere ripetuto senza effetti collaterali)
- Risposta spesso cacheable
Esempio configurazione GET:
URL: https://api.negozio.com/prodotti/{product_id}/disponibilita
Metodo: GET
Parametri URL: product_id
POST - Creazione nuove risorse
Quando usarlo:
- Creare nuovi ticket di supporto
- Inviare email o messaggi
- Registrare nuovi utenti
- Salvare moduli di contatto
Caratteristiche:
- Crea nuove risorse sul server
- Parametri inviati nel body della richiesta
- Non idempotente (ripetere può creare duplicati)
- Formato body spesso JSON
Esempio configurazione POST:
URL: https://api.support.com/tickets
Metodo: POST
Content-Type: application/json
Body parametri: email, subject, description, priority
PUT - Aggiornamento risorse
Quando usarlo:
- Aggiornare profilo utente
- Modificare stato di un ordine
- Cambiare impostazioni account
- Aggiornare informazioni prodotto
Caratteristiche:
- Modifica risorse esistenti
- Idempotente (stesso risultato se ripetuto)
- Sostituisce completamente la risorsa
- Richiede spesso ID della risorsa nell'URL
DELETE - Eliminazione risorse
Quando usarlo:
- Cancellare prenotazioni
- Rimuovere prodotti dal carrello
- Eliminare account utenti
- Annullare sottoscrizioni
Attenzione: Usa DELETE con cautela, operazioni irreversibili!
Headers HTTP importanti
Content-Type
Specifica il formato dei dati inviati:
- application/json: Dati in formato JSON (più comune)
- application/x-www-form-urlencoded: Dati come form HTML
- multipart/form-data: Per upload di file
- text/xml: Dati in formato XML
Accept
Specifica il formato di risposta desiderato:
- application/json: Risposta in JSON
- text/plain: Risposta in testo semplice
- application/xml: Risposta in XML
User-Agent
Identifica il client che fa la richiesta:
- Esempio:
Evolbot/1.0 (ChatBot Assistant) - Utilità: Alcuni servizi richiedono un User-Agent specifico
Esempi pratici completi
Integrazione con Slack
Obiettivo: Inviare messaggi in un canale Slack
URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
Metodo: POST
Headers: Content-Type: application/json
Parametri body: text (obbligatorio), channel (opzionale), username (opzionale)
Integrazione con Mailchimp
Obiettivo: Aggiungere contatto alla newsletter
URL: https://us1.api.mailchimp.com/3.0/lists/{list_id}/members
Metodo: POST
Headers: Content-Type: application/json, Authorization: Basic apikey
Parametri URL: list_id
Parametri body: email_address, status, merge_fields
Integrazione con Google Calendar
Obiettivo: Creare evento nel calendario
URL: https://www.googleapis.com/calendar/v3/calendars/{calendar_id}/events
Metodo: POST
Headers: Content-Type: application/json, Authorization: Bearer {access_token}
Parametri: summary, start, end, description
Test e debugging
Strumenti utili per testare
- Postman: Per testare API prima di configurarle in Evolbot
- curl: Comando da terminale per test rapidi
- Browser DevTools: Per analizzare richieste HTTP
- Webhook.site: Per testare webhook e vedere cosa viene inviato
Verifiche da fare
- URL raggiungibile: L'endpoint risponde a una richiesta di test
- Metodo corretto: Il servizio accetta il metodo HTTP configurato
- Headers necessari: Tutti gli header richiesti sono configurati
- Formato parametri: I dati vengono inviati nel formato atteso
- Autenticazione: Le credenziali sono corrette e valide
Gestione errori comuni
- 404 Not Found: URL errato o endpoint non esistente
- 405 Method Not Allowed: Metodo HTTP non supportato dall'endpoint
- 401 Unauthorized: Problemi di autenticazione
- 400 Bad Request: Parametri mancanti o formato dati errato
- 429 Too Many Requests: Troppo chiamate, rispetta i rate limits
- 500 Internal Server Error: Errore lato server del servizio esterno