API
Formular-Weiterleitung (Webhook)
Jedes ausgefüllte Formular an deine API
# Formular-Weiterleitung (Webhook) > Jedes ausgefüllte Formular an deine API - Seite: https://tbit.app/de/docs/api/forms-webhook - Basis-URL: `https://rest-api.tbit.app/v1` - Authentifizierung: Header `X-API-Key` mit deinem Schlüssel in jeder Anfrage (die Beispiele lesen ihn aus der Umgebungsvariable `TBIT_API_KEY`) ## Überblick Wenn eine Person im Gespräch ein Formular ausfüllt, kann TBit deine API mit den Antworten aufrufen. Es gibt zwei Modi. Validieren und weiterleiten (empfohlen, wenn das Formular Dokumente verlangt): TBit prüft die angehängten Dokumente per Bilderkennung, gleicht sie mit den Angaben der Person ab, teilt ihr das Ergebnis mit und schickt nur, wenn alles passt, das Profil per POST an deine URL, mit Wiederholungsversuchen. Direkter Aufruf: TBit schickt die Werte des Formulars per POST an deine URL, sobald es ausgefüllt ist, ohne Validierung und ohne Wiederholungsversuche. ## So richtest du es ein Jeder dieser drei Wege schreibt dieselbe Konfiguration ins Formular (seine Abschlussaktion): - Canvas (newui.tbit.app): Formulare → Zeile des Formulars öffnen → „Nach Abschluss weiterleiten…“. Ein vorausgefülltes Formular fragt nach Modus, Ziel-URL, einem optionalen Token und dem Profil des Payloads. - MCP (Claude, ChatGPT…): manage_form mit action=set_forward, der form_id aus list_forms, mode, url, token und profile. Die Änderung wird vorgeschlagen und du bestätigst sie. - App der Plattform: Formulare → bearbeiten → Abschlussaktion → API. Das ist die technische Ansicht: die URL des Dokumentenvalidators, ein Bearer mit dem TBit-Secret und die Header X-Tbit-Forward-*. ## Beispiel: Einrichtung über den 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 · Dokumente validieren und weiterleiten ### Ablauf 1. Die Person füllt das Formular aus (mit Dateifeldern für die Dokumente). 2. TBit liest jedes Dokument, extrahiert Name und Nummer und gleicht sie mit den Angaben ab. 3. Die Person bekommt eine Nachricht: Alles passt, es gibt eine Abweichung (und was sie erneut schicken soll) oder die Datei ist nicht lesbar. 4. Lautet das Ergebnis MATCH, schickt TBit einen POST an deine URL. ### Header, die wir senden | | | | | `Content-Type` | application/json | | `Authorization` | Bearer <dein konfiguriertes Token> (nur wenn ein Token gesetzt ist) | | `X-Bot-Provider` | tbit | | `X-Event-Type` | profile.completed | | `X-Tbit-Form-Data-Id` | <ID der Antwort, zum Deduplizieren> | ### Payload (Profil generic) fields enthält jedes beantwortete Feld unter seinem Namen im Formular; document_validation enthält das Ergebnis pro Dokument. Hat TBit für dein Unternehmen ein eigenes Profil gebaut, folgt der Body diesem Data Contract und der Profilname ist der, den du bekommen hast. ### Wiederholungsversuche und Idempotenz Antworte so schnell wie möglich mit 2xx (Timeout 10 s). Bei 500, 502, 503, 504 oder Netzwerkfehler versucht TBit es nach 30 s, 2 min, 10 min und 1 h erneut. Andere Codes werden nicht wiederholt. Die Wiederholungsversuche liegen im Arbeitsspeicher: Startet die Engine zwischendurch neu, gehen sie verloren. Bau deinen Endpoint also auf at-least-once und dedupliziere per formDataId (steht auch im 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 · Direkter Aufruf Sobald das Formular ausgefüllt ist, schickt TBit per POST ein JSON mit einem Schlüssel pro Feld (sein Name im Formular) plus formId, agentId und formDataId. Die Authentifizierung ist die, die du einrichtest: Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) oder API-Key (Header X-API-Key), plus die zusätzlichen Header, die du festlegst. Es gibt keine Wiederholungsversuche: Ein fehlgeschlagener Aufruf bleibt fehlgeschlagen. ```json { "Nombre completo": "Ana Pérez", "Cédula": "1032456789", "Gasto en alimentación": 900, "formId": "6917da72ed0bc91ea5532858", "agentId": "6aaab0521c2b87a579ccc624", "formDataId": "6aabbe45706082120e74fc75" } ``` ## Die Aufrufe prüfen Jeder Aufruf wird mit Anfrage, Antwort, HTTP-Code und Versuchen protokolliert. Das TBit-Team sieht sie im Entwickler-Panel des Canvas und kann sie mit dir durchgehen; für deine eigenen Logs protokollierst du die formDataId auf deiner Seite.Wenn eine Person im Gespräch ein Formular ausfüllt, kann TBit deine API mit den Antworten aufrufen. Es gibt zwei Modi. Validieren und weiterleiten (empfohlen, wenn das Formular Dokumente verlangt): TBit prüft die angehängten Dokumente per Bilderkennung, gleicht sie mit den Angaben der Person ab, teilt ihr das Ergebnis mit und schickt nur, wenn alles passt, das Profil per POST an deine URL, mit Wiederholungsversuchen. Direkter Aufruf: TBit schickt die Werte des Formulars per POST an deine URL, sobald es ausgefüllt ist, ohne Validierung und ohne Wiederholungsversuche.
Jeder dieser drei Wege schreibt dieselbe Konfiguration ins Formular (seine Abschlussaktion):
- Canvas (newui.tbit.app): Formulare → Zeile des Formulars öffnen → „Nach Abschluss weiterleiten…“. Ein vorausgefülltes Formular fragt nach Modus, Ziel-URL, einem optionalen Token und dem Profil des Payloads.
- MCP (Claude, ChatGPT…): manage_form mit action=set_forward, der form_id aus list_forms, mode, url, token und profile. Die Änderung wird vorgeschlagen und du bestätigst sie.
- App der Plattform: Formulare → bearbeiten → Abschlussaktion → API. Das ist die technische Ansicht: die URL des Dokumentenvalidators, ein Bearer mit dem TBit-Secret und die 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"
}Ablauf
1. Die Person füllt das Formular aus (mit Dateifeldern für die Dokumente). 2. TBit liest jedes Dokument, extrahiert Name und Nummer und gleicht sie mit den Angaben ab. 3. Die Person bekommt eine Nachricht: Alles passt, es gibt eine Abweichung (und was sie erneut schicken soll) oder die Datei ist nicht lesbar. 4. Lautet das Ergebnis MATCH, schickt TBit einen POST an deine URL.
Header, die wir senden
Content-Type | application/json |
Authorization | Bearer <dein konfiguriertes Token> (nur wenn ein Token gesetzt ist) |
X-Bot-Provider | tbit |
X-Event-Type | profile.completed |
X-Tbit-Form-Data-Id | <ID der Antwort, zum Deduplizieren> |
Payload (Profil generic)
fields enthält jedes beantwortete Feld unter seinem Namen im Formular; document_validation enthält das Ergebnis pro Dokument. Hat TBit für dein Unternehmen ein eigenes Profil gebaut, folgt der Body diesem Data Contract und der Profilname ist der, den du bekommen hast.
Wiederholungsversuche und Idempotenz
Antworte so schnell wie möglich mit 2xx (Timeout 10 s). Bei 500, 502, 503, 504 oder Netzwerkfehler versucht TBit es nach 30 s, 2 min, 10 min und 1 h erneut. Andere Codes werden nicht wiederholt. Die Wiederholungsversuche liegen im Arbeitsspeicher: Startet die Engine zwischendurch neu, gehen sie verloren. Bau deinen Endpoint also auf at-least-once und dedupliziere per formDataId (steht auch im 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 } }
]
}
}Sobald das Formular ausgefüllt ist, schickt TBit per POST ein JSON mit einem Schlüssel pro Feld (sein Name im Formular) plus formId, agentId und formDataId. Die Authentifizierung ist die, die du einrichtest: Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) oder API-Key (Header X-API-Key), plus die zusätzlichen Header, die du festlegst. Es gibt keine Wiederholungsversuche: Ein fehlgeschlagener Aufruf bleibt fehlgeschlagen.
{
"Nombre completo": "Ana Pérez",
"Cédula": "1032456789",
"Gasto en alimentación": 900,
"formId": "6917da72ed0bc91ea5532858",
"agentId": "6aaab0521c2b87a579ccc624",
"formDataId": "6aabbe45706082120e74fc75"
}Jeder Aufruf wird mit Anfrage, Antwort, HTTP-Code und Versuchen protokolliert. Das TBit-Team sieht sie im Entwickler-Panel des Canvas und kann sie mit dir durchgehen; für deine eigenen Logs protokollierst du die formDataId auf deiner Seite.