API
Reenvío de formularios (webhook)
Recibe en tu API cada formulario terminado
# Reenvío de formularios (webhook) > Recibe en tu API cada formulario terminado - Página: https://tbit.app/es/docs/api/forms-webhook - URL base: `https://rest-api.tbit.app/v1` - Autenticación: encabezado `X-API-Key` con tu clave en cada solicitud (los ejemplos la leen de la variable de entorno `TBIT_API_KEY`) ## Descripción general Cuando una persona termina un formulario en la conversación, TBit puede llamar a tu API con las respuestas. Hay dos modos. Validar y reenviar (recomendado cuando el formulario pide documentos): TBit revisa los documentos adjuntos con visión, los cruza con lo que la persona declaró, le cuenta el resultado y, solo si todo cuadra, hace POST del perfil a tu URL con reintentos. Llamada directa: TBit hace POST de los valores del formulario a tu URL apenas se completa, sin validación y sin reintentos. ## Cómo se configura Cualquiera de estas tres puertas escribe la misma configuración en el formulario (su acción de cierre): - Canvas (newui.tbit.app): Formularios → abre la fila del formulario → «Reenviar al terminar…». Un formulario prellenado pide el modo, la URL de destino, un token opcional y el perfil del payload. - MCP (Claude, ChatGPT…): manage_form con action=set_forward, el form_id de list_forms, mode, url, token y profile. El cambio se propone y tú lo confirmas. - App de la plataforma: Formularios → editar → acción de cierre → API. Es la vista de bajo nivel: la URL del validador de documentos, un bearer con el secreto de TBit y los headers X-Tbit-Forward-*. ## Ejemplo: configurar desde el 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" } ``` ## Modo 1 · Validar documentos y reenviar ### Flujo 1. La persona completa el formulario (con campos de archivo para los documentos). 2. TBit lee cada documento, extrae nombre y número y los cruza con lo declarado. 3. La persona recibe un mensaje: todo cuadra, hay una diferencia (y qué reenviar) o el archivo no se lee. 4. Si el veredicto es MATCH, TBit hace POST a tu URL. ### Headers que mandamos | | | | | `Content-Type` | application/json | | `Authorization` | Bearer <token que configuraste> (solo si hay token) | | `X-Bot-Provider` | tbit | | `X-Event-Type` | profile.completed | | `X-Tbit-Form-Data-Id` | <id de la respuesta, para deduplicar> | ### Payload (perfil generic) fields trae cada campo contestado por su nombre en el formulario; document_validation trae el veredicto por documento. Si TBit construyó un perfil propio para tu empresa, el body sigue ese data contract y el nombre del perfil es el que te dieron. ### Reintentos e idempotencia Responde 2xx lo más rápido que puedas (timeout de 10 s). Ante 500, 502, 503, 504 o error de red, TBit reintenta a los 30 s, 2 min, 10 min y 1 h. Otros códigos no se reintentan. Los reintentos viven en memoria: si el motor reinicia en el medio se pierden, así que diseña tu endpoint como at-least-once y deduplica por formDataId (también viene en el 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 } } ] } } ``` ## Modo 2 · Llamada directa Apenas el formulario se completa, TBit hace POST de un JSON con una clave por campo (su nombre en el formulario) más formId, agentId y formDataId. La autenticación es la que configures: Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) o API key (header X-API-Key), más los headers extra que definas. No hay reintentos: una llamada fallida queda fallida. ```json { "Nombre completo": "Ana Pérez", "Cédula": "1032456789", "Gasto en alimentación": 900, "formId": "6917da72ed0bc91ea5532858", "agentId": "6aaab0521c2b87a579ccc624", "formDataId": "6aabbe45706082120e74fc75" } ``` ## Verificar las llamadas Cada llamada queda registrada con su petición, respuesta, código HTTP e intentos. El equipo de TBit las ve en el panel Desarrollador del canvas y puede revisarlas contigo; para tus propios logs, registra el formDataId de tu lado.Cuando una persona termina un formulario en la conversación, TBit puede llamar a tu API con las respuestas. Hay dos modos. Validar y reenviar (recomendado cuando el formulario pide documentos): TBit revisa los documentos adjuntos con visión, los cruza con lo que la persona declaró, le cuenta el resultado y, solo si todo cuadra, hace POST del perfil a tu URL con reintentos. Llamada directa: TBit hace POST de los valores del formulario a tu URL apenas se completa, sin validación y sin reintentos.
Cualquiera de estas tres puertas escribe la misma configuración en el formulario (su acción de cierre):
- Canvas (newui.tbit.app): Formularios → abre la fila del formulario → «Reenviar al terminar…». Un formulario prellenado pide el modo, la URL de destino, un token opcional y el perfil del payload.
- MCP (Claude, ChatGPT…): manage_form con action=set_forward, el form_id de list_forms, mode, url, token y profile. El cambio se propone y tú lo confirmas.
- App de la plataforma: Formularios → editar → acción de cierre → API. Es la vista de bajo nivel: la URL del validador de documentos, un bearer con el secreto de TBit y los 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"
}Flujo
1. La persona completa el formulario (con campos de archivo para los documentos). 2. TBit lee cada documento, extrae nombre y número y los cruza con lo declarado. 3. La persona recibe un mensaje: todo cuadra, hay una diferencia (y qué reenviar) o el archivo no se lee. 4. Si el veredicto es MATCH, TBit hace POST a tu URL.
Headers que mandamos
Content-Type | application/json |
Authorization | Bearer <token que configuraste> (solo si hay token) |
X-Bot-Provider | tbit |
X-Event-Type | profile.completed |
X-Tbit-Form-Data-Id | <id de la respuesta, para deduplicar> |
Payload (perfil generic)
fields trae cada campo contestado por su nombre en el formulario; document_validation trae el veredicto por documento. Si TBit construyó un perfil propio para tu empresa, el body sigue ese data contract y el nombre del perfil es el que te dieron.
Reintentos e idempotencia
Responde 2xx lo más rápido que puedas (timeout de 10 s). Ante 500, 502, 503, 504 o error de red, TBit reintenta a los 30 s, 2 min, 10 min y 1 h. Otros códigos no se reintentan. Los reintentos viven en memoria: si el motor reinicia en el medio se pierden, así que diseña tu endpoint como at-least-once y deduplica por formDataId (también viene en el 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 } }
]
}
}Apenas el formulario se completa, TBit hace POST de un JSON con una clave por campo (su nombre en el formulario) más formId, agentId y formDataId. La autenticación es la que configures: Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) o API key (header X-API-Key), más los headers extra que definas. No hay reintentos: una llamada fallida queda fallida.
{
"Nombre completo": "Ana Pérez",
"Cédula": "1032456789",
"Gasto en alimentación": 900,
"formId": "6917da72ed0bc91ea5532858",
"agentId": "6aaab0521c2b87a579ccc624",
"formDataId": "6aabbe45706082120e74fc75"
}Cada llamada queda registrada con su petición, respuesta, código HTTP e intentos. El equipo de TBit las ve en el panel Desarrollador del canvas y puede revisarlas contigo; para tus propios logs, registra el formDataId de tu lado.