API
Inoltro dei moduli (webhook)
Ricevi nella tua API ogni modulo completato
# Inoltro dei moduli (webhook) > Ricevi nella tua API ogni modulo completato - Pagina: https://tbit.app/it/docs/api/forms-webhook - URL base: `https://rest-api.tbit.app/v1` - Autenticazione: header `X-API-Key` con la tua chiave in ogni richiesta (gli esempi la leggono dalla variabile d'ambiente `TBIT_API_KEY`) ## Panoramica Quando una persona completa un modulo nella conversazione, TBit può chiamare la tua API con le risposte. Ci sono due modalità. Convalida e inoltra (consigliata quando il modulo chiede documenti): TBit controlla i documenti allegati con la visione artificiale, li confronta con quanto dichiarato dalla persona, le comunica il risultato e, solo se tutto torna, fa POST del profilo al tuo URL con nuovi tentativi. Chiamata diretta: TBit fa POST dei valori del modulo al tuo URL appena viene completato, senza convalida e senza nuovi tentativi. ## Come si configura Ognuna di queste tre porte scrive la stessa configurazione nel modulo (la sua azione di chiusura): - Canvas (newui.tbit.app): Moduli → apri la riga del modulo → «Inoltra al termine…». Un modulo precompilato chiede la modalità, l'URL di destinazione, un token facoltativo e il profilo del payload. - MCP (Claude, ChatGPT…): manage_form con action=set_forward, il form_id di list_forms, mode, url, token e profile. La modifica viene proposta e tu la confermi. - App della piattaforma: Moduli → modifica → azione di chiusura → API. È la vista di basso livello: l'URL del validatore di documenti, un bearer con il segreto di TBit e gli header X-Tbit-Forward-*. ## Esempio: configurare dall'MCP ```json manage_form { "action": "set_forward", "form_id": "6917da72ed0bc91ea5532858", "mode": "validate_forward", "url": "https://api.tunegocio.com/tbit/perfiles", "token": "<tu bearer>", "profile": "generic" } ``` ## Modalità 1 · Convalida i documenti e inoltra ### Flusso 1. La persona completa il modulo (con campi file per i documenti). 2. TBit legge ogni documento, estrae nome e numero e li confronta con quanto dichiarato. 3. La persona riceve un messaggio: tutto torna, c'è una differenza (e cosa reinviare) oppure il file non si legge. 4. Se il verdetto è MATCH, TBit fa POST al tuo URL. ### Header che inviamo | | | | | `Content-Type` | application/json | | `Authorization` | Bearer <token che hai configurato> (solo se c'è un token) | | `X-Bot-Provider` | tbit | | `X-Event-Type` | profile.completed | | `X-Tbit-Form-Data-Id` | <id della risposta, per deduplicare> | ### Payload (profilo generic) fields contiene ogni campo compilato con il suo nome nel modulo; document_validation contiene il verdetto per documento. Se TBit ha costruito un profilo su misura per la tua azienda, il body segue quel data contract e il nome del profilo è quello che ti hanno dato. ### Nuovi tentativi e idempotenza Rispondi 2xx il più in fretta possibile (timeout di 10 s). In caso di 500, 502, 503, 504 o errore di rete, TBit riprova dopo 30 s, 2 min, 10 min e 1 h. Gli altri codici non vengono ritentati. I nuovi tentativi vivono in memoria: se il motore si riavvia nel frattempo si perdono, quindi progetta il tuo endpoint come at-least-once e deduplica per formDataId (arriva anche nell'header X-Tbit-Form-Data-Id). ```json { "formDataId": "6aabbe45706082120e74fc75", "agentId": "6aaab0521c2b87a579ccc624", "activityId": "6aabbe3c58181a93243f7298", "fields": { "Nombre completo": "Ana Pérez", "Cédula": "1032456789", "Gasto en alimentación": 900, "Foto del DNI": { "kind": "file", "url": "https://api.tbit.app/media/…/dni.jpeg" } }, "document_validation": { "verdict": "MATCH", "results": [ { "field": "Foto del DNI", "document_kind": "dni", "verdict": "MATCH", "checks": { "full_name": true, "document_number": true } } ] } } ``` ## Modalità 2 · Chiamata diretta Appena il modulo viene completato, TBit fa POST di un JSON con una chiave per campo (il suo nome nel modulo) più formId, agentId e formDataId. L'autenticazione è quella che configuri: Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) o API key (header X-API-Key), più gli header extra che definisci. Non ci sono nuovi tentativi: una chiamata fallita resta fallita. ```json { "Nombre completo": "Ana Pérez", "Cédula": "1032456789", "Gasto en alimentación": 900, "formId": "6917da72ed0bc91ea5532858", "agentId": "6aaab0521c2b87a579ccc624", "formDataId": "6aabbe45706082120e74fc75" } ``` ## Verificare le chiamate Ogni chiamata resta registrata con richiesta, risposta, codice HTTP e tentativi. Il team di TBit le vede nel pannello Sviluppatore del canvas e può rivederle con te; per i tuoi log, registra il formDataId dalla tua parte.Quando una persona completa un modulo nella conversazione, TBit può chiamare la tua API con le risposte. Ci sono due modalità. Convalida e inoltra (consigliata quando il modulo chiede documenti): TBit controlla i documenti allegati con la visione artificiale, li confronta con quanto dichiarato dalla persona, le comunica il risultato e, solo se tutto torna, fa POST del profilo al tuo URL con nuovi tentativi. Chiamata diretta: TBit fa POST dei valori del modulo al tuo URL appena viene completato, senza convalida e senza nuovi tentativi.
Ognuna di queste tre porte scrive la stessa configurazione nel modulo (la sua azione di chiusura):
- Canvas (newui.tbit.app): Moduli → apri la riga del modulo → «Inoltra al termine…». Un modulo precompilato chiede la modalità, l'URL di destinazione, un token facoltativo e il profilo del payload.
- MCP (Claude, ChatGPT…): manage_form con action=set_forward, il form_id di list_forms, mode, url, token e profile. La modifica viene proposta e tu la confermi.
- App della piattaforma: Moduli → modifica → azione di chiusura → API. È la vista di basso livello: l'URL del validatore di documenti, un bearer con il segreto di TBit e gli header X-Tbit-Forward-*.
manage_form
{
"action": "set_forward",
"form_id": "6917da72ed0bc91ea5532858",
"mode": "validate_forward",
"url": "https://api.tunegocio.com/tbit/perfiles",
"token": "<tu bearer>",
"profile": "generic"
}Flusso
1. La persona completa il modulo (con campi file per i documenti). 2. TBit legge ogni documento, estrae nome e numero e li confronta con quanto dichiarato. 3. La persona riceve un messaggio: tutto torna, c'è una differenza (e cosa reinviare) oppure il file non si legge. 4. Se il verdetto è MATCH, TBit fa POST al tuo URL.
Header che inviamo
Content-Type | application/json |
Authorization | Bearer <token che hai configurato> (solo se c'è un token) |
X-Bot-Provider | tbit |
X-Event-Type | profile.completed |
X-Tbit-Form-Data-Id | <id della risposta, per deduplicare> |
Payload (profilo generic)
fields contiene ogni campo compilato con il suo nome nel modulo; document_validation contiene il verdetto per documento. Se TBit ha costruito un profilo su misura per la tua azienda, il body segue quel data contract e il nome del profilo è quello che ti hanno dato.
Nuovi tentativi e idempotenza
Rispondi 2xx il più in fretta possibile (timeout di 10 s). In caso di 500, 502, 503, 504 o errore di rete, TBit riprova dopo 30 s, 2 min, 10 min e 1 h. Gli altri codici non vengono ritentati. I nuovi tentativi vivono in memoria: se il motore si riavvia nel frattempo si perdono, quindi progetta il tuo endpoint come at-least-once e deduplica per formDataId (arriva anche nell'header X-Tbit-Form-Data-Id).
{
"formDataId": "6aabbe45706082120e74fc75",
"agentId": "6aaab0521c2b87a579ccc624",
"activityId": "6aabbe3c58181a93243f7298",
"fields": {
"Nombre completo": "Ana Pérez",
"Cédula": "1032456789",
"Gasto en alimentación": 900,
"Foto del DNI": { "kind": "file", "url": "https://api.tbit.app/media/…/dni.jpeg" }
},
"document_validation": {
"verdict": "MATCH",
"results": [
{ "field": "Foto del DNI", "document_kind": "dni", "verdict": "MATCH",
"checks": { "full_name": true, "document_number": true } }
]
}
}Appena il modulo viene completato, TBit fa POST di un JSON con una chiave per campo (il suo nome nel modulo) più formId, agentId e formDataId. L'autenticazione è quella che configuri: Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) o API key (header X-API-Key), più gli header extra che definisci. Non ci sono nuovi tentativi: una chiamata fallita resta fallita.
{
"Nombre completo": "Ana Pérez",
"Cédula": "1032456789",
"Gasto en alimentación": 900,
"formId": "6917da72ed0bc91ea5532858",
"agentId": "6aaab0521c2b87a579ccc624",
"formDataId": "6aabbe45706082120e74fc75"
}Ogni chiamata resta registrata con richiesta, risposta, codice HTTP e tentativi. Il team di TBit le vede nel pannello Sviluppatore del canvas e può rivederle con te; per i tuoi log, registra il formDataId dalla tua parte.