# 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.