Connessioni API

Collega le tue API esterne a enuchat così IA e regole possono recuperare dati in tempo reale dai tuoi sistemi.

Come funziona

Le connessioni API ti permettono di integrare enuchat con i tuoi sistemi backend — motori di prenotazione, CRM, gestione ordini, inventario e altro. Quando un visitatore pone una domanda, enuchat può chiamare la tua API per ottenere dati reali e includerli nella risposta.

Il flusso

Configura una connessione — URL base della tua API e autenticazione
Aggiungi endpoint — chiamate API specifiche con template di percorso e mappatura della risposta
Crea una regola — una regola IA o statica con un'azione CALL_API
Il visitatore pone una domanda — la regola si attiva, chiama la tua API, mappa la risposta alle variabili di sessione
L'IA risponde con dati reali — le variabili di sessione sono disponibili all'IA per generare una risposta accurata

Esempio: Disponibilità camera hotel

Visitatore: «La camera 205 è disponibile la prossima settimana?»

Regola IA corrisponde: «Quando il visitatore chiede disponibilità camera»

Azione CALL_API: GET https://api.hotel.com/rooms/205/availability

Risposta mappata: room_available = true, price = «120€/notte»

L'IA risponde: «La camera 205 è disponibile la prossima settimana a 120€/notte. Vorresti prenotarla?»

Configurare una connessione

Vai su Impostazioni → Connessioni API nel tuo pannello.

1. Crea una connessione

Una connessione rappresenta una API esterna. Hai bisogno di:

Campo	Descrizione	Esempio
Nome	Un'etichetta per questa connessione	Hotel Booking API
URL Base	URL radice dell'API	`https://api.hotel.com/v1`
Tipo Auth	Come autenticare	Bearer Token, OAuth2, ecc.

2. Tipi di autenticazione

Nessuno

Per API pubbliche che non richiedono autenticazione.

Chiave API

Invia una chiave statica come header o parametro query.

Campo	Descrizione
Chiave	Il valore della tua chiave API
Nome Header	Header da usare (default: `X-Api-Key`)

La chiave viene inviata come: X-Api-Key: your_key_here

Bearer Token

Invia un token statico nell'header Authorization.

Inviato come: Authorization: Bearer your_token_here

Basic Auth

Invia username e password, codificati in base64.

Inviato come: Authorization: Basic dXNlcjpwYXNz

OAuth 2.0 (Client Credentials)

Recupera automaticamente un access token e lo memorizza in cache fino alla scadenza. Ottimo per API moderne come Salesforce, Google o server OAuth personalizzati.

Campo	Descrizione
Token URL	Endpoint token OAuth (es. `https://auth.example.com/oauth/token`)
Client ID	Il tuo client ID OAuth
Client Secret	Il tuo client secret OAuth
Scope	Scope separati da spazi (es. `read write`)

enuchat gestisce automaticamente il ciclo di vita del token — recupera alla prima chiamata, mette in cache fino alla scadenza, aggiorna quando necessario.

Sicurezza: Tutte le credenziali sono crittografate a riposo usando libsodium. Non vengono mai esposte nelle risposte API — solo valori mascherati sono mostrati nel pannello.

Configurare endpoint

Ogni connessione può avere più endpoint — chiamate API specifiche che vuoi fare.

Campo	Descrizione	Esempio
Nome	Etichetta per questo endpoint	Verifica disponibilità
Metodo	Metodo HTTP	GET, POST, PUT, DELETE
Percorso	Percorso URL (aggiunto all'URL base). Usa `{'{'}variable}` per valori dinamici	`/rooms/{'{'}roomId}/availability`
Parametri Query	Parametri URL come coppie chiave-valore. I valori supportano `{'{'}variable}`	`date={'{'}checkIn}`
Template Corpo	Corpo JSON per POST/PUT. Supporta interpolazione `{'{'}variable}`	`{'{'}"guest": "{'{'}name}"}`
Mappatura Risposta	Mappa campi della risposta JSON a variabili di sessione usando dot notation	`data.available → room_available`
Descrizione	Contesto per l'IA (quali dati restituisce questo endpoint)	Restituisce disponibilità e prezzi camere

Interpolazione variabili

Usa {'{'}variableName} in percorsi, parametri query e template di corpo. Le variabili provengono da:

Variabili di sessione — impostate da regole precedenti (azione SET_VARIABLE)
Parametri azione — hardcoded nell'azione regola CALL_API

Mappatura risposta

Mappa campi della risposta JSON a variabili di sessione usando dot notation:

// API returns:
{'{'}
  "data": {'{'}
    "available": true,
    "price": {'{'} "amount": 120, "currency": "EUR" }
  }
}

// Mapping:
data.available  →  room_available    // "true"
data.price.amount  →  room_price    // "120"
data.price.currency  →  room_currency  // "EUR"

Le variabili mappate sono memorizzate come variabili di sessione nella conversazione e sono disponibili all'IA per generare risposte.

Uso con le regole

Le chiamate API sono attivate dall'azione CALL_API nelle regole. Puoi combinarle con altre azioni.

Ricetta: Ricerca stato ordine

Connessione: Order Management API — https://api.shop.com/v2 — Bearer Token

Endpoint: GET /orders/{'{'}orderId} → mappa data.status → order_status, data.eta → delivery_eta

Regola (tipo IA): «Quando il visitatore chiede dello stato del suo ordine o della consegna»

Azioni:

CALL_API → endpoint stato ordine
REPLY_AI → l'IA usa order_status e delivery_eta per rispondere

Risultato: Visitatore: «Dov'è il mio ordine #4521?» — IA: «Il tuo ordine #4521 è attualmente in spedizione e dovrebbe arrivare entro giovedì.»

Ricetta: Prezzi in tempo reale

Connessione: Pricing API — https://pricing.example.com — Chiave API

Endpoint: GET /products/{'{'}productId}/price → mappa price → current_price, currency → price_currency

Regola (statica): MESSAGE_MATCHES_REGEX: /\b(price|cost|how much)\b/i

Azioni:

CALL_API → endpoint prezzi
REPLY_TEXT → «Il prezzo attuale è {'{'}current_price} {'{'}price_currency}.»

Test

Testa sempre le tue connessioni ed endpoint prima di usarle nelle regole:

Testa connessione — verifica che l'autenticazione funzioni (per OAuth2: recupera un token)
Testa endpoint — effettua una vera chiamata API con variabili di esempio e mostra la risposta
Testa regola (dry-run) — nella pagina Regole, testa se una regola corrisponderebbe e quali azioni verrebbero eseguite

Suggerimento: Inizia testando la connessione, poi ogni endpoint, poi la regola completa. In questo modo puoi isolare i problemi a ogni livello.

Sicurezza

Crittografia a riposo — tutte le credenziali sono crittografate usando libsodium prima della memorizzazione
Mai esposte — le risposte API non includono mai credenziali decrittate, solo valori mascherati
Protezione SSRF — enuchat blocca le chiamate a localhost, IP privati e hostname interni
Timeout — le chiamate API esterne hanno un timeout di 5 secondi per evitare blocchi
Caching token OAuth2 — gli access token sono memorizzati in cache in modo sicuro e rinnovati automaticamente
Isolamento tenant — le connessioni sono limitate al tuo tenant, inaccessibili ad altri

Pronto a collegare le tue API?

Inizia oggi a integrare i tuoi sistemi con enuchat.

Inizia gratis