A resposta
Os dois endpoints de ingestão devolvem o mesmo objeto.
{
"interacaoId": "019205a1-7c3e-7f10-b2d4-3a9c21e8f0aa",
"status": "Análise pendente",
"resultado": "Criada",
"duplicada": false,
"versao": 1,
"mensagensNovas": 0,
"mensagensEditadas": 0,
"consumiuVaga": true,
"aguardandoLimite": false,
"pendenteMetadadoObrigatorio": false,
"metadadosNovos": ["fila"],
"metadadosIgnorados": []
}
Campo a campo
| Campo | Tipo | O que significa |
|---|---|---|
interacaoId | uuid | O id da interação nesta versão. É o que o cliente vê na tela e o que um chamado de suporte vai pedir. Guarde em log. |
status | string | O status inicial, legível: Análise pendente, Transcrição pendente ou Aguardando limite. |
resultado | string | O que a ingestão fez: Criada, Reingerida ou Duplicada. Ver a tabela abaixo. |
duplicada | bool | true quando resultado é Duplicada. Mantido por compatibilidade com quem integrou antes de resultado existir — é a mesma informação, dita do jeito antigo. |
versao | int | Ordem da versão desta conversa: 1 na original, 2 na primeira continuação, e assim por diante. |
mensagensNovas | int | Na reingestão, quantas falas passaram a existir que não existiam antes. A conta é sobre a conversa unida, então vale igual para quem manda o delta e para quem manda a conversa inteira. Zero nos outros casos. |
mensagensEditadas | int | Na reingestão, quantas falas já existentes chegaram com texto diferente — a origem corrigiu. Vale um olhar: a nota da versão anterior foi dada sobre o texto antigo. Zero nos outros casos. |
consumiuVaga | bool | Houve material novo admitido ao processamento, contando contra o limite de uso do cliente. É o campo que diz "isto vai para a fatura". |
aguardandoLimite | bool | O ciclo do cliente chegou ao teto. A conversa foi gravada e está visível, só não foi analisada. Ver Limite de uso. |
pendenteMetadadoObrigatorio | bool | O cliente marcou algum metadado como obrigatório e ele não veio. A interação é auditada normalmente; a pendência aparece na curadoria dele. |
metadadosNovos | string[] | Chaves de metadado que a plataforma nunca tinha visto nesta conta e criou agora. |
metadadosIgnorados | string[] | Chaves descartadas por colidir com campos de sistema. Ver Metadados. |
resultado × código HTTP
resultado | HTTP | O que aconteceu | Consome vaga? |
|---|---|---|---|
Criada | 201 | Interação nova. | sim |
Reingerida | 201 | Conversa parcial que continuou — nasceu uma versão nova, auditada do zero. | sim |
Duplicada | 200 | O conteúdo é idêntico ao gravado, ou a conversa já estava concluída e não aceita continuação. Nada foi criado. | não |
200, não 409Para quem integra, reenviar é comportamento esperado — webhook falha, rede cai, fila reprocessa —,
e não erro. Devolver 409 faria você tratar como problema algo que é a proteção funcionando.
É seguro reenviar sempre. O pior caso é um 200 Duplicada.
consumiuVaga é falso em dois casos diferentes
E os motivos não são os mesmos:
Reenvio idêntico (resultado: "Duplicada") — não consome porque a idempotência existe justamente
porque webhook de terceiro erra e repete. Cobrar por retry de rede transformaria uma proteção em
armadilha.
Conversa parada esperando limite (aguardandoLimite: true) — não consome porque ela ainda não
foi analisada. Cobrar o que está na fila seria vender o que não se entregou. Ela passa a consumir se
e quando o cliente liberar.
Se você monitora custo do cliente, consumiuVaga é o campo a somar — não a contagem de requisições
bem-sucedidas.
Duas leituras da mesma coisa, de propósito
resultado e consumiuVaga carregam informação sobreposta. Isso é deliberado: quem integra lê o
booleano e decide, quem depura lê o rótulo e entende. Um campo que exige tabela de-para para saber se
houve cobrança é um campo que alguém vai interpretar errado.
O que guardar em log
O mínimo útil, do lado do parceiro:
chaveExterna · interacaoId · resultado · versao · consumiuVaga · aguardandoLimite · HTTP
Por quê cada um:
chaveExterna+interacaoId— é o par que resolve chamado. O cliente vê ointeracaoIdna tela; você conhece achaveExterna. Sem os dois lado a lado, correlacionar é escavação.resultado— distingue "não criou porque já existia" de "não criou porque falhou". Sem ele, todo200parece igual.versao+consumiuVaga— explicam a fatura antes de alguém perguntar. Se o cliente estranhar o volume, o seu log responde na hora quantas foram continuação.aguardandoLimite— quando ele começa a virtrue, o cliente bateu o teto. Vale um alerta na sua operação, para você avisar antes de o cliente notar.