Pular para o conteúdo principal

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​

CampoTipoO que significa
interacaoIduuidO 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.
statusstringO status inicial, legível: Análise pendente, Transcrição pendente ou Aguardando limite.
resultadostringO que a ingestão fez: Criada, Reingerida ou Duplicada. Ver a tabela abaixo.
duplicadabooltrue quando resultado é Duplicada. Mantido por compatibilidade com quem integrou antes de resultado existir — é a mesma informação, dita do jeito antigo.
versaointOrdem da versão desta conversa: 1 na original, 2 na primeira continuação, e assim por diante.
mensagensNovasintNa 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.
mensagensEditadasintNa 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.
consumiuVagaboolHouve material novo admitido ao processamento, contando contra o limite de uso do cliente. É o campo que diz "isto vai para a fatura".
aguardandoLimiteboolO ciclo do cliente chegou ao teto. A conversa foi gravada e está visível, só não foi analisada. Ver Limite de uso.
pendenteMetadadoObrigatorioboolO cliente marcou algum metadado como obrigatório e ele não veio. A interação é auditada normalmente; a pendência aparece na curadoria dele.
metadadosNovosstring[]Chaves de metadado que a plataforma nunca tinha visto nesta conta e criou agora.
metadadosIgnoradosstring[]Chaves descartadas por colidir com campos de sistema. Ver Metadados.

resultado × código HTTP​

resultadoHTTPO que aconteceuConsome vaga?
Criada201Interação nova.sim
Reingerida201Conversa parcial que continuou — nasceu uma versão nova, auditada do zero.sim
Duplicada200O conteúdo é idêntico ao gravado, ou a conversa já estava concluída e não aceita continuação. Nada foi criado.não
Duplicata é 200, não 409

Para 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ê o interacaoId na tela; você conhece a chaveExterna. 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, todo 200 parece 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 vir true, o cliente bateu o teto. Vale um alerta na sua operação, para você avisar antes de o cliente notar.