Come utilizzare le API di Kuba Labs

Quando un flusso parte da un Trigger (blocchetto) API, ogni parametro che definisci ha un'espressione: un piccolo frammento di codice che estrae un valore dal corpo (JSON) della richiesta in arrivo. Questa guida ti spiega come scriverle, con particolare attenzione alle chiavi (nome del parametro) "speciali" che richiedono la notazione input["..."].

Non serve saper programmare. Le espressioni che userai nel 99% dei casi sono semplici e le trovi tutte qui sotto.

Prima di iniziare: genera la tua chiave API

Per far sì che Kuba accetti le richieste in arrivo, ogni chiamata al Trigger API deve essere autenticata con una chiave API. Generarla è il primo passo.

Vai su Impostazioni → Chiavi API in Kuba e clicca su Genera chiave. Copia la chiave e conservala in un posto sicuro.

Il sistema esterno deve inviare la chiave nell'header Authorization di ogni richiesta, senza la parola Bearer, solo la chiave:

Authorization: <la-tua-chiave-api>

ℹ️ Tratta la chiave API come una password: chiunque ne sia in possesso può inviare richieste al tuo flusso. Non inserirla in codice pubblico o condiviso.

La variabile `input`

L'intero corpo JSON della richiesta è disponibile in una variabile chiamata input. Tu scrivi un'espressione, Kuba la valuta e il valore restituito diventa il parametro.

Per tutti gli esempi di questa guida, immagina di ricevere questo corpo:

json

{   "customer": {     "phone": "+393331234567",     "first_name": "Anna"   },   "order-total": 49.9,   "items": [{ "sku": "ABC-1" }],   "2nd_choice": "rosso" }

Da qui in avanti, ogni espressione "pesca" un valore da questo JSON.

Passo 1: Chiavi normali → notazione con punto

Per le chiavi "normali" — quelle che iniziano con una lettera e contengono solo lettere, numeri o underscore — usa il punto:

Espressione	Valore
`input.customer.phone`	`"+393331234567"`
`input.customer.first_name`	`"Anna"`
`input.items[0].sku`	`"ABC-1"`

⚠️ Ricordati sempre del prefisso input.. Scrivere solo customer.phone non funziona: customer non esiste come variabile a sé. Tutto parte da input.

Passo 2: Chiavi speciali → notazione con parentesi quadre

Alcune chiavi non si possono leggere con il punto, perché contengono caratteri non validi per un nome di variabile JavaScript:

trattini → order-total
spazi → order total
punti → order.total
chiavi che iniziano con un numero → 2nd_choice

Per queste chiavi devi usare le parentesi quadre con la chiave tra virgolette:

Chiave nel JSON	✅ Corretto	❌ Sbagliato
`order-total`	`input["order-total"]`	`input.order-total`
`order total`	`input["order total"]`	`input.order total`
`2nd_choice`	`input["2nd_choice"]`	`input.2nd_choice`

Perché? input.order-total viene interpretato dal codice come una sottrazione, input.order meno total, non come la lettura della chiave order-total. Le parentesi quadre dicono esplicitamente "leggi la chiave con questo nome esatto".

ℹ️ La notazione con parentesi quadre funziona sempre, anche per le chiavi normali: input["customer"]["phone"] equivale a input.customer.phone. Se hai dubbi, le parentesi quadre sono la scelta sicura.

Passo 3: Annidamento, array e operazioni

Le espressioni sono JavaScript completo, quindi puoi combinarle:

input.items[0].sku                          // primo elemento di un array input.customer.first_name.toUpperCase()     // metodi sulle stringhe input.email ? input.email : "n/d"           // condizioni 
input["order-total"] * 1.22                 // operazioni aritmetiche

Il tipo del parametro

Oltre all'espressione, ogni parametro ha un tipo (testo, numero, telefono, email, link, valuta). Il tipo dice a Kuba come interpretare il valore restituito.

Esempio pratico: per inviare un messaggio WhatsApp serve un parametro di tipo telefono la cui espressione restituisce il numero del destinatario: es. input.customer.phone.

Errori comuni

Sintomo	Causa
Il parametro risulta vuoto	La chiave non esiste nel corpo, o manca il prefisso `input.`
Errore di configurazione sul contatto	L'espressione è vuota, o fa riferimento a un campo inesistente
Valore strano / numerico inatteso su una chiave con trattino	Hai usato il punto (`input.order-total`) invece delle parentesi quadre (`input["order-total"]`)

In sintesi

Tutto parte da input: il corpo JSON della richiesta.
Chiavi normali → punto: input.customer.phone.
Chiavi con trattini, spazi, punti o iniziali numeriche → parentesi quadre: input["order-total"].
Nel dubbio usa le parentesi quadre.

Passo 4: Verificare un esecuzione

Dopo aver configurato i parametri, conviene controllare che le tue espressioni stiano "pescando" i valori giusti dal corpo della richiesta. Lo fai esattamente come per qualsiasi altro flusso.

Clicca su uno dei blocchi del flusso, ad esempio "Manda un messaggio", e seleziona la tab Esecuzioni. Lì trovi lo stato di ogni esecuzione, con l'eventuale errore.

Cosa cercare:

Esecuzione riuscita — la richiesta è arrivata, le espressioni hanno restituito i valori attesi e l'azione è partita.
Parametro vuoto o errore sul contatto — di solito significa che un'espressione fa riferimento a una chiave che non esiste nel corpo, oppure manca il prefisso input.. Torna alla configurazione del parametro e confronta l'espressione con il JSON che stai effettivamente inviando.
Valore strano su una chiave con trattino — hai usato il punto al posto delle parentesi quadre (vedi Passo 2).

ℹ️ Se non vedi nessuna esecuzione, vuol dire che la richiesta non è ancora arrivata a Kuba. Verifica che il sistema esterno stia chiamando l'URL corretto del Trigger API e che il corpo sia un JSON valido.
Se non ci sono esecuzioni su Kuba, è un errore del sistema esterno, o le chiavi non corrispondono.

Collegare Zapier, Make o n8n

Il Trigger API è pensato per essere chiamato da qualsiasi sistema esterno: che tu usi Zapier, Make, n8n o codice tuo, la logica è sempre la stessa. Lo strumento esterno invia una richiesta HTTP a Kuba, e il flusso parte.

Cosa ti serve

Tre informazioni, tutte già viste in questa guida:

URL del webhook: ogni Trigger API ha un suo URL univoco, lo trovi sul blocco del Trigger API quando costruisci il flusso. Copialo.
Chiave API: quella che hai generato in Impostazioni → Chiavi API (vedi inizio guida).
Il corpo JSON: i dati che vuoi inviare, da cui le tue espressioni "pescheranno" i valori.

Come configurare la richiesta

Qualunque sia lo strumento, configura una chiamata HTTP così:

Metodo: POST
URL: l'URL del webhook del tuo Trigger API
Header Authorization: la tua chiave API (senza Bearer)
Header Content-Type: application/json
Body: il JSON con i tuoi dati

Zapier

Aggiungi un'azione Webhooks by Zapier → POST. Incolla l'URL del webhook, imposta il Payload Type su JSON, aggiungi negli header Authorization con la tua chiave e Content-Type: application/json. Mappa i campi del tuo trigger Zapier nel body.

Make

Aggiungi un modulo HTTP → Make a request. Metodo POST, incolla l'URL, attiva Parse response se vuoi leggere la risposta. Negli header aggiungi Authorization e Content-Type: application/json, poi componi il body JSON con i dati dei moduli precedenti.

n8n

Usa il nodo HTTP Request. Metodo POST, incolla l'URL, Body Content Type su JSON. In Headers aggiungi Authorization con la chiave e Content-Type: application/json. Costruisci il body con le espressioni n8n (es. {{ $json.email }}).

ℹ️ Ricordati che il JSON che invii da qui è esattamente il input di cui parla questa guida. Se invii { "customer": { "phone": "..." } }, nelle espressioni del flusso scriverai input.customer.phone. Tieni i due lati allineati e tutto funziona.

⚠️ Dopo aver collegato lo strumento, fai un invio di prova e controlla la tab Esecuzioni del flusso (vedi Passo 4) per verificare che la richiesta sia arrivata e che le espressioni restituiscano i valori giusti.

Hai bisogno di aiuto? Scrivici a [email protected] o visita kubalabs.com.