API
Transfert de formulaires (webhook)
Recevez sur votre API chaque formulaire terminé
# Transfert de formulaires (webhook) > Recevez sur votre API chaque formulaire terminé - Page: https://tbit.app/fr/docs/api/forms-webhook - URL de base: `https://rest-api.tbit.app/v1` - Authentification: en-tête `X-API-Key` avec votre clé dans chaque requête (les exemples la lisent depuis la variable d'environnement `TBIT_API_KEY`) ## Vue d'ensemble Quand une personne termine un formulaire dans la conversation, TBit peut appeler votre API avec les réponses. Il y a deux modes. Valider et transférer (recommandé quand le formulaire demande des documents) : TBit vérifie les documents joints par vision, les recoupe avec ce que la personne a déclaré, lui communique le résultat et, seulement si tout concorde, fait un POST du profil vers votre URL avec des tentatives répétées. Appel direct : TBit fait un POST des valeurs du formulaire vers votre URL dès qu'il est complété, sans validation et sans nouvelle tentative. ## Configuration Chacune de ces trois portes écrit la même configuration dans le formulaire (son action de clôture) : - Canvas (newui.tbit.app) : Formulaires → ouvrez la ligne du formulaire → « Transférer à la fin… ». Un formulaire prérempli demande le mode, l'URL de destination, un token facultatif et le profil du payload. - MCP (Claude, ChatGPT…) : manage_form avec action=set_forward, le form_id de list_forms, mode, url, token et profile. Le changement est proposé et vous le confirmez. - App de la plateforme : Formulaires → modifier → action de clôture → API. C'est la vue bas niveau : l'URL du validateur de documents, un bearer avec le secret de TBit et les en-têtes X-Tbit-Forward-*. ## Exemple : configurer depuis le 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" } ``` ## Mode 1 · Valider les documents et transférer ### Parcours 1. La personne remplit le formulaire (avec des champs fichier pour les documents). 2. TBit lit chaque document, en extrait le nom et le numéro et les recoupe avec ce qui a été déclaré. 3. La personne reçoit un message : tout concorde, il y a une différence (et quoi renvoyer) ou le fichier est illisible. 4. Si le verdict est MATCH, TBit fait un POST vers votre URL. ### En-têtes envoyés | | | | | `Content-Type` | application/json | | `Authorization` | Bearer <token que vous avez configuré> (seulement s'il y a un token) | | `X-Bot-Provider` | tbit | | `X-Event-Type` | profile.completed | | `X-Tbit-Form-Data-Id` | <id de la réponse, pour dédupliquer> | ### Payload (profil generic) fields contient chaque champ rempli, sous son nom dans le formulaire ; document_validation contient le verdict par document. Si TBit a construit un profil sur mesure pour votre entreprise, le body suit ce data contract et le nom du profil est celui qui vous a été communiqué. ### Nouvelles tentatives et idempotence Répondez 2xx le plus vite possible (timeout de 10 s). En cas de 500, 502, 503, 504 ou d'erreur réseau, TBit réessaie après 30 s, 2 min, 10 min et 1 h. Les autres codes ne sont pas retentés. Les nouvelles tentatives vivent en mémoire : si le moteur redémarre entre-temps, elles sont perdues ; concevez donc votre endpoint en at-least-once et dédupliquez par formDataId (il figure aussi dans l'en-tête 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 } } ] } } ``` ## Mode 2 · Appel direct Dès que le formulaire est complété, TBit fait un POST d'un JSON avec une clé par champ (son nom dans le formulaire) plus formId, agentId et formDataId. L'authentification est celle que vous configurez : Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) ou API key (en-tête X-API-Key), plus les en-têtes supplémentaires que vous définissez. Aucune nouvelle tentative : un appel échoué reste échoué. ```json { "Nombre completo": "Ana Pérez", "Cédula": "1032456789", "Gasto en alimentación": 900, "formId": "6917da72ed0bc91ea5532858", "agentId": "6aaab0521c2b87a579ccc624", "formDataId": "6aabbe45706082120e74fc75" } ``` ## Vérifier les appels Chaque appel est enregistré avec sa requête, sa réponse, son code HTTP et ses tentatives. L'équipe TBit les voit dans le panneau Développeur du canvas et peut les passer en revue avec vous ; pour vos propres logs, enregistrez le formDataId de votre côté.Quand une personne termine un formulaire dans la conversation, TBit peut appeler votre API avec les réponses. Il y a deux modes. Valider et transférer (recommandé quand le formulaire demande des documents) : TBit vérifie les documents joints par vision, les recoupe avec ce que la personne a déclaré, lui communique le résultat et, seulement si tout concorde, fait un POST du profil vers votre URL avec des tentatives répétées. Appel direct : TBit fait un POST des valeurs du formulaire vers votre URL dès qu'il est complété, sans validation et sans nouvelle tentative.
Chacune de ces trois portes écrit la même configuration dans le formulaire (son action de clôture) :
- Canvas (newui.tbit.app) : Formulaires → ouvrez la ligne du formulaire → « Transférer à la fin… ». Un formulaire prérempli demande le mode, l'URL de destination, un token facultatif et le profil du payload.
- MCP (Claude, ChatGPT…) : manage_form avec action=set_forward, le form_id de list_forms, mode, url, token et profile. Le changement est proposé et vous le confirmez.
- App de la plateforme : Formulaires → modifier → action de clôture → API. C'est la vue bas niveau : l'URL du validateur de documents, un bearer avec le secret de TBit et les en-têtes 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"
}Parcours
1. La personne remplit le formulaire (avec des champs fichier pour les documents). 2. TBit lit chaque document, en extrait le nom et le numéro et les recoupe avec ce qui a été déclaré. 3. La personne reçoit un message : tout concorde, il y a une différence (et quoi renvoyer) ou le fichier est illisible. 4. Si le verdict est MATCH, TBit fait un POST vers votre URL.
En-têtes envoyés
Content-Type | application/json |
Authorization | Bearer <token que vous avez configuré> (seulement s'il y a un token) |
X-Bot-Provider | tbit |
X-Event-Type | profile.completed |
X-Tbit-Form-Data-Id | <id de la réponse, pour dédupliquer> |
Payload (profil generic)
fields contient chaque champ rempli, sous son nom dans le formulaire ; document_validation contient le verdict par document. Si TBit a construit un profil sur mesure pour votre entreprise, le body suit ce data contract et le nom du profil est celui qui vous a été communiqué.
Nouvelles tentatives et idempotence
Répondez 2xx le plus vite possible (timeout de 10 s). En cas de 500, 502, 503, 504 ou d'erreur réseau, TBit réessaie après 30 s, 2 min, 10 min et 1 h. Les autres codes ne sont pas retentés. Les nouvelles tentatives vivent en mémoire : si le moteur redémarre entre-temps, elles sont perdues ; concevez donc votre endpoint en at-least-once et dédupliquez par formDataId (il figure aussi dans l'en-tête 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 } }
]
}
}Dès que le formulaire est complété, TBit fait un POST d'un JSON avec une clé par champ (son nom dans le formulaire) plus formId, agentId et formDataId. L'authentification est celle que vous configurez : Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) ou API key (en-tête X-API-Key), plus les en-têtes supplémentaires que vous définissez. Aucune nouvelle tentative : un appel échoué reste échoué.
{
"Nombre completo": "Ana Pérez",
"Cédula": "1032456789",
"Gasto en alimentación": 900,
"formId": "6917da72ed0bc91ea5532858",
"agentId": "6aaab0521c2b87a579ccc624",
"formDataId": "6aabbe45706082120e74fc75"
}Chaque appel est enregistré avec sa requête, sa réponse, son code HTTP et ses tentatives. L'équipe TBit les voit dans le panneau Développeur du canvas et peut les passer en revue avec vous ; pour vos propres logs, enregistrez le formDataId de votre côté.