API
Formulieren doorsturen (webhook)
Ontvang elk ingevuld formulier in je API
# Formulieren doorsturen (webhook) > Ontvang elk ingevuld formulier in je API - Pagina: https://tbit.app/nl/docs/api/forms-webhook - Basis-URL: `https://rest-api.tbit.app/v1` - Authenticatie: header `X-API-Key` met je sleutel bij elk verzoek (de voorbeelden lezen hem uit de omgevingsvariabele `TBIT_API_KEY`) ## Overzicht Als iemand in het gesprek een formulier invult, kan TBit je API aanroepen met de antwoorden. Er zijn twee modi. Valideren en doorsturen (aanbevolen als het formulier om documenten vraagt): TBit controleert de bijgevoegde documenten met computer vision, vergelijkt ze met wat de persoon heeft opgegeven, laat de uitkomst weten en doet, alleen als alles klopt, een POST van het profiel naar je URL, met nieuwe pogingen. Directe aanroep: TBit doet een POST van de formulierwaarden naar je URL zodra het formulier compleet is, zonder validatie en zonder nieuwe pogingen. ## Zo stel je het in Elk van deze drie ingangen schrijft dezelfde configuratie in het formulier (de afsluitende actie): - Canvas (newui.tbit.app): Formulieren → open de rij van het formulier → «Doorsturen na afronden…». Een vooraf ingevuld formulier vraagt om de modus, de doel-URL, een optioneel token en het profiel van de payload. - MCP (Claude, ChatGPT…): manage_form met action=set_forward, het form_id uit list_forms, mode, url, token en profile. De wijziging wordt voorgesteld en jij bevestigt hem. - App van het platform: Formulieren → bewerken → afsluitende actie → API. Dit is de technische weergave: de URL van de documentvalidator, een bearer met het geheim van TBit en de headers X-Tbit-Forward-*. ## Voorbeeld: instellen vanuit de 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" } ``` ## Modus 1 · Documenten valideren en doorsturen ### Flow 1. De persoon vult het formulier in (met bestandsvelden voor de documenten). 2. TBit leest elk document, haalt naam en nummer eruit en vergelijkt ze met wat is opgegeven. 3. De persoon krijgt een bericht: alles klopt, er is een verschil (en wat opnieuw te sturen) of het bestand is onleesbaar. 4. Als het oordeel MATCH is, doet TBit een POST naar je URL. ### Headers die we meesturen | | | | | `Content-Type` | application/json | | `Authorization` | Bearer <token dat je hebt ingesteld> (alleen als er een token is) | | `X-Bot-Provider` | tbit | | `X-Event-Type` | profile.completed | | `X-Tbit-Form-Data-Id` | <id van het antwoord, om te ontdubbelen> | ### Payload (profiel generic) fields bevat elk ingevuld veld onder zijn naam in het formulier; document_validation bevat het oordeel per document. Als TBit een eigen profiel voor je bedrijf heeft gebouwd, volgt de body dat data contract en is de profielnaam de naam die je hebt gekregen. ### Nieuwe pogingen en idempotentie Antwoord zo snel mogelijk met 2xx (timeout van 10 s). Bij 500, 502, 503, 504 of een netwerkfout probeert TBit het opnieuw na 30 s, 2 min, 10 min en 1 u. Andere codes worden niet opnieuw geprobeerd. De nieuwe pogingen staan in het geheugen: als de engine tussendoor herstart, gaan ze verloren, dus ontwerp je endpoint als at-least-once en ontdubbel op formDataId (die staat ook in de 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 } } ] } } ``` ## Modus 2 · Directe aanroep Zodra het formulier compleet is, doet TBit een POST van een JSON met één sleutel per veld (de naam in het formulier) plus formId, agentId en formDataId. De authenticatie is wat jij instelt: Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) of API key (header X-API-Key), plus de extra headers die je definieert. Er zijn geen nieuwe pogingen: een mislukte aanroep blijft mislukt. ```json { "Nombre completo": "Ana Pérez", "Cédula": "1032456789", "Gasto en alimentación": 900, "formId": "6917da72ed0bc91ea5532858", "agentId": "6aaab0521c2b87a579ccc624", "formDataId": "6aabbe45706082120e74fc75" } ``` ## De aanroepen controleren Elke aanroep wordt vastgelegd met verzoek, response, HTTP-code en pogingen. Het team van TBit ziet ze in het Developer-paneel van het canvas en kan ze met je doornemen; voor je eigen logs leg je de formDataId aan jouw kant vast.Als iemand in het gesprek een formulier invult, kan TBit je API aanroepen met de antwoorden. Er zijn twee modi. Valideren en doorsturen (aanbevolen als het formulier om documenten vraagt): TBit controleert de bijgevoegde documenten met computer vision, vergelijkt ze met wat de persoon heeft opgegeven, laat de uitkomst weten en doet, alleen als alles klopt, een POST van het profiel naar je URL, met nieuwe pogingen. Directe aanroep: TBit doet een POST van de formulierwaarden naar je URL zodra het formulier compleet is, zonder validatie en zonder nieuwe pogingen.
Elk van deze drie ingangen schrijft dezelfde configuratie in het formulier (de afsluitende actie):
- Canvas (newui.tbit.app): Formulieren → open de rij van het formulier → «Doorsturen na afronden…». Een vooraf ingevuld formulier vraagt om de modus, de doel-URL, een optioneel token en het profiel van de payload.
- MCP (Claude, ChatGPT…): manage_form met action=set_forward, het form_id uit list_forms, mode, url, token en profile. De wijziging wordt voorgesteld en jij bevestigt hem.
- App van het platform: Formulieren → bewerken → afsluitende actie → API. Dit is de technische weergave: de URL van de documentvalidator, een bearer met het geheim van TBit en de headers 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"
}Flow
1. De persoon vult het formulier in (met bestandsvelden voor de documenten). 2. TBit leest elk document, haalt naam en nummer eruit en vergelijkt ze met wat is opgegeven. 3. De persoon krijgt een bericht: alles klopt, er is een verschil (en wat opnieuw te sturen) of het bestand is onleesbaar. 4. Als het oordeel MATCH is, doet TBit een POST naar je URL.
Headers die we meesturen
Content-Type | application/json |
Authorization | Bearer <token dat je hebt ingesteld> (alleen als er een token is) |
X-Bot-Provider | tbit |
X-Event-Type | profile.completed |
X-Tbit-Form-Data-Id | <id van het antwoord, om te ontdubbelen> |
Payload (profiel generic)
fields bevat elk ingevuld veld onder zijn naam in het formulier; document_validation bevat het oordeel per document. Als TBit een eigen profiel voor je bedrijf heeft gebouwd, volgt de body dat data contract en is de profielnaam de naam die je hebt gekregen.
Nieuwe pogingen en idempotentie
Antwoord zo snel mogelijk met 2xx (timeout van 10 s). Bij 500, 502, 503, 504 of een netwerkfout probeert TBit het opnieuw na 30 s, 2 min, 10 min en 1 u. Andere codes worden niet opnieuw geprobeerd. De nieuwe pogingen staan in het geheugen: als de engine tussendoor herstart, gaan ze verloren, dus ontwerp je endpoint als at-least-once en ontdubbel op formDataId (die staat ook in de 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 } }
]
}
}Zodra het formulier compleet is, doet TBit een POST van een JSON met één sleutel per veld (de naam in het formulier) plus formId, agentId en formDataId. De authenticatie is wat jij instelt: Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) of API key (header X-API-Key), plus de extra headers die je definieert. Er zijn geen nieuwe pogingen: een mislukte aanroep blijft mislukt.
{
"Nombre completo": "Ana Pérez",
"Cédula": "1032456789",
"Gasto en alimentación": 900,
"formId": "6917da72ed0bc91ea5532858",
"agentId": "6aaab0521c2b87a579ccc624",
"formDataId": "6aabbe45706082120e74fc75"
}Elke aanroep wordt vastgelegd met verzoek, response, HTTP-code en pogingen. Het team van TBit ziet ze in het Developer-paneel van het canvas en kan ze met je doornemen; voor je eigen logs leg je de formDataId aan jouw kant vast.