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

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:

aceito — o provedor recebeu e vai tentar;
enviado — saiu do provedor;
entregue — chegou ao aparelho;
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: interpretar o que o outro lado disse com mais certeza do que ele realmente ofereceu.