# "Enviado" não é "entregue": o número de teste que mentia

> A API aceitou, devolveu identificador e registrou sucesso. A mensagem nunca chegou. Por que o resultado de um envio assíncrono não cabe no retorno da chamada.

Publicado em 2026-08-13 por Time Orion · Blog da Orion
Versão canônica: https://orion.moe/blog/o-numero-de-teste-que-mentia
Índice do blog: https://orion.moe/blog

---

Passamos um tempo achando que a integração de mensageria estava funcionando. A chamada retornava 200, com um identificador de mensagem. Gravávamos como enviada. A tela mostrava enviada.

Ninguém recebia nada.

## O que estava acontecendo

Estávamos usando o número de teste que a plataforma oferece para desenvolvimento. Ele aceita o envio, valida o formato, devolve identificador — e **só depois**, de forma assíncrona, informa que a conta não tem permissão para enviar mensagens para destinatários naquele país.

O retorno da chamada não sabia disso. Ele não podia saber: o envio de verdade acontece depois, do outro lado.

## A lição de arquitetura

O erro conceitual foi nosso, e é comum: **tratar o retorno de uma chamada assíncrona como o resultado da operação**.

Num envio de mensagem existem pelo menos quatro estados, e eles acontecem em momentos diferentes:

1. **aceito** — o provedor recebeu e vai tentar;
2. **enviado** — saiu do provedor;
3. **entregue** — chegou ao aparelho;
4. **lido** — o destinatário abriu.

E existe um quinto que não é uma etapa, mas um desfecho: **falhou** — que pode acontecer *depois* de qualquer um dos anteriores.

O retorno da chamada só te dá o primeiro. Todos os outros chegam por notificação posterior. Um sistema que grava "enviada" no retorno e nunca mais atualiza está exibindo uma informação que era verdadeira por dois segundos.

## O que mudamos

**Uma coluna de erro na mensagem.** Parece óbvio depois; não era antes. Se a falha chega assincronamente, ela precisa de lugar para morar — e precisa aparecer na interface, junto da mensagem. A bolha na tela não pode mentir para o operador: se não foi entregue, ele tem que ver isso ali, e não descobrir pelo cliente reclamando.

**Estados de fato, não presumidos.** Cada notificação de status atualiza a mensagem. "Enviado" deixa de ser um estado final e vira um estado intermediário.

**Cautela com ambiente de teste.** O número de teste é útil para validar o formato da requisição e a assinatura do webhook — e é enganoso para validar **entrega**. Nossa regra hoje: comportamento de entrega só é validado com destinatário real, e o teste da integração termina no aparelho de alguém, não no log.

## O aviso que quase ninguém lê

Um detalhe operacional que aprendemos e que vale registrar: registrar um número na API oficial de uma dessas plataformas é uma operação **irreversível na prática** — ela desvincula o número do aplicativo comum no celular. Se aquele número era o que a equipe usava no dia a dia, o dia a dia acabou.

Não é um erro técnico; é uma decisão de negócio disfarçada de passo de configuração. Vale ler duas vezes antes de executar, e vale documentar no repositório para a próxima pessoa não descobrir sozinha.

## O padrão que generaliza

Isso não é sobre mensageria. Vale para qualquer operação em que o efeito acontece fora do seu processo: cobrança, e-mail, nota fiscal, integração com terceiros.

O padrão é sempre:

- **o retorno da chamada é uma promessa**, não um resultado;
- **o resultado chega depois**, por notificação ou por consulta;
- **a interface precisa distinguir os dois** — "estamos processando" é diferente de "deu certo";
- **e a falha precisa de lugar para morar** no seu modelo de dados, com espaço para o motivo.

Sempre que um sistema exibe "sucesso" no instante da chamada, ele está apostando que a segunda parte não vai falhar. Ela falha.

## O resumo

Um identificador de volta significa "aceitei", não "entreguei". Modele os estados que existem de verdade, guarde o erro assíncrono e faça a interface contar a verdade — inclusive quando ela é "ainda não sei".

É a mesma família de erro do [405 tratado como terminal](/blog/405-nunca-apaga-credencial): interpretar o que o outro lado disse com mais certeza do que ele realmente ofereceu.