Pular para o conteúdo principal

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-Key em 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.
  • ⚠️ interlocutor mapeado corretamente: o atendente humano é Operador, a URA é Bot, o cliente é Cliente, evento de canal é Sistema.
  • ⚠️ emitidaEm e ocorridaEm com fuso (-03:00 ou Z).
  • ⚠️ ocorridaEm sempre pelo mesmo critério (início ou fim da conversa) — e o mesmo na reingestão.
  • ⚠️ id em toda mensagem, único na conversa e estável entre envios. Obrigatório em conversa parcial, 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: true quando o gatilho foi ociosidade; false quando 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.
  • metadadosNovos monitorado: 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 400 e 401.
  • 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: true começar a aparecer.
  • Alerta quando a taxa de 400 subir (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.