API
Reenvio de formulários (webhook)
Receba na sua API cada formulário concluído
# Reenvio de formulários (webhook) > Receba na sua API cada formulário concluído - Página: https://tbit.app/pt/docs/api/forms-webhook - URL base: `https://rest-api.tbit.app/v1` - Autenticação: cabeçalho `X-API-Key` com a sua chave em cada requisição (os exemplos a leem da variável de ambiente `TBIT_API_KEY`) ## Visão geral Quando uma pessoa termina um formulário na conversa, o TBit pode chamar a sua API com as respostas. Há dois modos. Validar e reenviar (recomendado quando o formulário pede documentos): o TBit revisa os documentos anexados com visão, confere com o que a pessoa declarou, conta o resultado a ela e, só se tudo bater, faz POST do perfil para a sua URL com novas tentativas. Chamada direta: o TBit faz POST dos valores do formulário para a sua URL assim que ele é concluído, sem validação e sem novas tentativas. ## Como configurar Qualquer uma destas três portas grava a mesma configuração no formulário (a sua ação de fechamento): - Canvas (newui.tbit.app): Formulários → abra a linha do formulário → «Reenviar ao terminar…». Um formulário pré-preenchido pede o modo, a URL de destino, um token opcional e o perfil do payload. - MCP (Claude, ChatGPT…): manage_form com action=set_forward, o form_id de list_forms, mode, url, token e profile. A mudança é proposta e você a confirma. - App da plataforma: Formulários → editar → ação de fechamento → API. É a visão de baixo nível: a URL do validador de documentos, um bearer com o segredo do TBit e os headers X-Tbit-Forward-*. ## Exemplo: configurar pelo 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 e reenviar ### Fluxo 1. A pessoa preenche o formulário (com campos de arquivo para os documentos). 2. O TBit lê cada documento, extrai nome e número e confere com o que foi declarado. 3. A pessoa recebe uma mensagem: tudo bate, há uma diferença (e o que reenviar) ou o arquivo não pôde ser lido. 4. Se o veredito for MATCH, o TBit faz POST para a sua URL. ### Headers que enviamos | | | | | `Content-Type` | application/json | | `Authorization` | Bearer <token que você configurou> (só se houver token) | | `X-Bot-Provider` | tbit | | `X-Event-Type` | profile.completed | | `X-Tbit-Form-Data-Id` | <id da resposta, para deduplicar> | ### Payload (perfil generic) fields traz cada campo respondido pelo seu nome no formulário; document_validation traz o veredito por documento. Se o TBit construiu um perfil próprio para a sua empresa, o body segue esse data contract e o nome do perfil é o que você recebeu. ### Novas tentativas e idempotência Responda 2xx o mais rápido que puder (timeout de 10 s). Diante de 500, 502, 503, 504 ou erro de rede, o TBit tenta de novo após 30 s, 2 min, 10 min e 1 h. Outros códigos não têm nova tentativa. As novas tentativas ficam em memória: se o motor reiniciar no meio do caminho, elas se perdem; por isso, projete o seu endpoint como at-least-once e deduplique por formDataId (também vem no 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 · Chamada direta Assim que o formulário é concluído, o TBit faz POST de um JSON com uma chave por campo (o seu nome no formulário) mais formId, agentId e formDataId. A autenticação é a que você configurar: Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) ou chave de API (header X-API-Key), mais os headers extras que você definir. Não há novas tentativas: uma chamada que falhou fica falha. ```json { "Nombre completo": "Ana Pérez", "Cédula": "1032456789", "Gasto en alimentación": 900, "formId": "6917da72ed0bc91ea5532858", "agentId": "6aaab0521c2b87a579ccc624", "formDataId": "6aabbe45706082120e74fc75" } ``` ## Verificar as chamadas Cada chamada fica registrada com a requisição, a resposta, o código HTTP e as tentativas. A equipe do TBit as vê no painel Desenvolvedor do canvas e pode revisá-las com você; para os seus próprios logs, registre o formDataId do seu lado.Quando uma pessoa termina um formulário na conversa, o TBit pode chamar a sua API com as respostas. Há dois modos. Validar e reenviar (recomendado quando o formulário pede documentos): o TBit revisa os documentos anexados com visão, confere com o que a pessoa declarou, conta o resultado a ela e, só se tudo bater, faz POST do perfil para a sua URL com novas tentativas. Chamada direta: o TBit faz POST dos valores do formulário para a sua URL assim que ele é concluído, sem validação e sem novas tentativas.
Qualquer uma destas três portas grava a mesma configuração no formulário (a sua ação de fechamento):
- Canvas (newui.tbit.app): Formulários → abra a linha do formulário → «Reenviar ao terminar…». Um formulário pré-preenchido pede o modo, a URL de destino, um token opcional e o perfil do payload.
- MCP (Claude, ChatGPT…): manage_form com action=set_forward, o form_id de list_forms, mode, url, token e profile. A mudança é proposta e você a confirma.
- App da plataforma: Formulários → editar → ação de fechamento → API. É a visão de baixo nível: a URL do validador de documentos, um bearer com o segredo do TBit e os 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"
}Fluxo
1. A pessoa preenche o formulário (com campos de arquivo para os documentos). 2. O TBit lê cada documento, extrai nome e número e confere com o que foi declarado. 3. A pessoa recebe uma mensagem: tudo bate, há uma diferença (e o que reenviar) ou o arquivo não pôde ser lido. 4. Se o veredito for MATCH, o TBit faz POST para a sua URL.
Headers que enviamos
Content-Type | application/json |
Authorization | Bearer <token que você configurou> (só se houver token) |
X-Bot-Provider | tbit |
X-Event-Type | profile.completed |
X-Tbit-Form-Data-Id | <id da resposta, para deduplicar> |
Payload (perfil generic)
fields traz cada campo respondido pelo seu nome no formulário; document_validation traz o veredito por documento. Se o TBit construiu um perfil próprio para a sua empresa, o body segue esse data contract e o nome do perfil é o que você recebeu.
Novas tentativas e idempotência
Responda 2xx o mais rápido que puder (timeout de 10 s). Diante de 500, 502, 503, 504 ou erro de rede, o TBit tenta de novo após 30 s, 2 min, 10 min e 1 h. Outros códigos não têm nova tentativa. As novas tentativas ficam em memória: se o motor reiniciar no meio do caminho, elas se perdem; por isso, projete o seu endpoint como at-least-once e deduplique por formDataId (também vem no 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 } }
]
}
}Assim que o formulário é concluído, o TBit faz POST de um JSON com uma chave por campo (o seu nome no formulário) mais formId, agentId e formDataId. A autenticação é a que você configurar: Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) ou chave de API (header X-API-Key), mais os headers extras que você definir. Não há novas tentativas: uma chamada que falhou fica falha.
{
"Nombre completo": "Ana Pérez",
"Cédula": "1032456789",
"Gasto en alimentación": 900,
"formId": "6917da72ed0bc91ea5532858",
"agentId": "6aaab0521c2b87a579ccc624",
"formDataId": "6aabbe45706082120e74fc75"
}Cada chamada fica registrada com a requisição, a resposta, o código HTTP e as tentativas. A equipe do TBit as vê no painel Desenvolvedor do canvas e pode revisá-las com você; para os seus próprios logs, registre o formDataId do seu lado.