Checklist de go-live
Os itens marcados com ⚠️ são os que não dão erro quando estão errados. São eles que valem o tempo de teste.
Contrato
- Header
X-Api-Keyem toda chamada, com a chave do ambiente certo. - Chave guardada em cofre ou variável de ambiente — nunca em código, log ou front-end.
-
chaveExternaé o id que a origem já tem, estável entre envios, única por interação no canal. - ⚠️
interlocutormapeado corretamente: o atendente humano éOperador, a URA éBot, o cliente éCliente, evento de canal éSistema. - ⚠️
emitidaEmeocorridaEmcom fuso (-03:00ouZ). - ⚠️
ocorridaEmsempre pelo mesmo critério (início ou fim da conversa) — e o mesmo na reingestão. - ⚠️
idem toda mensagem, único na conversa e estável entre envios. Obrigatório em conversaparcial, e é o que permite continuá-la depois. - Na continuação, o formato que for mais fácil para você: a conversa inteira ou só as mensagens
novas. A plataforma une pelos
ids e chega ao mesmo resultado. -
parcial: truequando o gatilho foi ociosidade;falsequando foi tabulação.
Metadados
- ⚠️ Chaves combinadas com o cliente e conferidas contra a declaração dele: id do atendente, nome, equipe.
- Chaves estáveis — sem variação de grafia entre envios.
-
metadadosNovosmonitorado: vindo preenchido em produção, algo mudou no seu mapeamento. - Id e nome do atendente enviados os dois (agrupa por id, exibe o nome).
Áudio
- URLs
https, host por nome, terminando na extensão. - ⚠️ URLs duráveis — meses, não horas. Ver URLs de áudio.
- Arquivos abaixo de 25 MB.
- Conversas com no máximo 50 áudios.
- Quando você já tem a transcrição, ela vai em
texto(mais barato e mais fiel).
Resiliência
- Retry com backoff em
5xx, timeout e erro de rede. - Sem retry em
400e401. - Parser de erro que cobre os três formatos (
detalhes,erro,messages). - Fila de mortos: payload guardado depois da última tentativa, de onde dê para reenviar à mão.
Observabilidade
- Log por envio com:
chaveExterna,interacaoId,resultado,versao,consumiuVaga,aguardandoLimite, código HTTP. - Alerta quando
aguardandoLimite: truecomeçar a aparecer. - Alerta quando a taxa de
400subir (indica mudança no seu upstream).
Os cinco testes de homologação
Faça os cinco, na tela do cliente em homologação. Os três primeiros pegam o que a validação não pega.
1. ⚠️ Quem falou de cada lado
Envie uma conversa real, abra a interação na tela e confira: as falas do atendente aparecem do lado do operador? Se estiverem invertidas, todo critério de conduta vai medir a pessoa errada — e a nota vai sair parecendo legítima.
2. ⚠️ Ordem e horário
Na mesma interação: as falas estão na ordem em que aconteceram, e o horário confere com o real? Se estiver deslocado, é fuso.
3. ⚠️ O atendente foi reconhecido
A interação mostra o nome do atendente? Se aparecer vazio ou só o id, as chaves de metadado não batem com o que o cliente declarou.
4. Parcial e continuação
Envie uma conversa parcial: true com três falas, confira versao: 1. Reenvie com duas falas a mais,
confira resultado: "Reingerida", versao: 2, mensagensNovas: 2. Na tela, deve aparecer uma
conversa, na versão 2, com as cinco falas.
Faça no formato que a sua integração usa. Se ela manda só o delta, mande só as duas novas — as cinco
falas na tela é justamente o que prova que a união funcionou. Se ela manda a conversa inteira, mande
as cinco: mensagensNovas deve continuar 2, e não 5.
5. Reenvio idêntico
Reenvie exatamente o mesmo payload de uma conversa já enviada. Deve vir 200,
resultado: "Duplicada", mesmo interacaoId, consumiuVaga: false. Isso valida que o seu retry não vai
duplicar nem cobrar.
Extra, se houver áudio
Envie uma conversa com uma mensagem só de urlAudio. Confira que o status inicial é
Transcrição pendente, e que minutos depois o texto transcrito aparece na tela — com a etiqueta
indicando que veio do áudio.
Antes de virar a chave
- Prazo de ociosidade alinhado com o cliente (afeta quantas reingestões ele vai ver).
- Volume esperado por dia comunicado ao cliente (afeta o teto que ele contrata).
- Combinado quem avisa quem em caso de rotação de chave.
- Se o canal de voz está no escopo: confirmado que o discador entrega transcrição. Ver O que ainda não existe.