Dez erros comuns ao integrar uma API de SMS

Toda integração de SMS erra nas mesmas coisas. Não porque quem escreve é descuidado, mas porque o caminho feliz funciona de primeira e esconde o resto.

Aqui estão os erros que mais aparecem, na ordem em que costumam morder.

1. Tratar o número como permanente

O número é emprestado pelo tempo de uma verificação. Terminado o pedido, ele volta para o estoque e pode ir para outra pessoa.

O que quebra: você guarda o número no cadastro do cliente como telefone dele. Meses depois, dispara uma mensagem para aquele número. Ela chega para um estranho.

O que fazer: guarde o número como dado do pedido, não do cliente. Se você precisa de um telefone permanente, número virtual descartável é o produto errado.

2. Escolher o país pelo preço

O país mais barato da lista é o mais barato porque tem menos demanda — muitas vezes porque o serviço que você quer não aceita aquela faixa.

O que quebra: o pedido nunca recebe o código, e você repete com outro número do mesmo país.

O que fazer: escolha o país pela regra do destino. Serviço brasileiro, número do Brasil.

3. Não tratar o pedido que não recebe

O caminho feliz tem retorno. O caminho triste tem silêncio, e silêncio não dispara catch.

O que quebra: o processo fica esperando para sempre, ou o cliente vê uma tela girando sem fim.

O que fazer: defina um tempo máximo de espera no seu lado, menor que a expiração do pedido. Estourou, cancele o pedido — o valor volta para a carteira. Pedido abandonado ocupa o número e não devolve nada.

4. Confundir "pedido criado" com "número pronto"

São dois momentos. O primeiro é rápido; o segundo depende do fornecedor.

O que quebra: você mostra o número ao cliente antes de ele estar ativo, ou tenta consultar o SMS de um pedido que ainda está sendo provisionado, recebe vazio, e conclui que falhou.

O que fazer: leia o status do pedido antes de agir. Vazio não é o mesmo que erro.

5. Colocar a chave de API no navegador

A chave é do tipo ac_live_* e dá acesso ao saldo da conta.

O que quebra: qualquer visitante abre o inspetor, copia a chave e gasta o seu saldo.

O que fazer: a chave fica no servidor. O navegador chama o seu backend, e o seu backend chama a API. Se o seu código de frontend precisa da chave, a arquitetura está errada, não a chave.

6. Não guardar o identificador do pedido

O identificador é como você consulta status, cancela, recebe webhook e pede suporte.

O que quebra: algo dá errado, você não sabe qual pedido era, e a conversa com o suporte vira adivinhação.

O que fazer: grave o identificador junto com o registro do seu lado, antes de qualquer outra coisa. É a primeira linha depois de criar o pedido, não a última.

7. Assumir que o webhook chega uma vez só

A entrega é ao menos uma vez. Retentativa e rede instável produzem repetição.

O que quebra: cada aviso libera um cadastro, e o cliente ganha dois.

O que fazer: guarde o identificador do evento e ignore o que já foi processado.

8. Consultar em laço apertado

Um while com intervalo de um segundo, multiplicado por muitos pedidos, esbarra em limite de taxa — e o limite derruba também a criação de pedidos.

O que fazer: webhook para automação, SSE para tela. Consulta direta só em rascunho.

9. Buscar o catálogo a cada pedido

Países e serviços mudam devagar. Buscar a lista inteira antes de cada compra é requisição desperdiçada e latência somada ao seu fluxo.

O que fazer: consulte uma vez, guarde os identificadores, atualize periodicamente.

10. Testar só o caminho feliz

O teste que existe é o que compra e recebe. Os que faltam são os que doem em produção: saldo insuficiente, SMS que não chega, pedido cancelado, webhook repetido, fornecedor indisponível.

O que fazer: escreva o teste de cada um desses antes de subir. São cinco testes que evitam os cinco chamados mais comuns.

Por onde começar

Se você está integrando agora, o guia de início cobre a primeira chamada e a documentação de pedidos traz os estados possíveis — que é justamente onde os erros 3 e 4 se resolvem.

E o que a API entrega, por país e serviço, está resumido em números virtuais.