Como receber SMS com um número virtual

O que acontece entre comprar o número e o código chegar, como escolher o país certo e por que consultar em laço é a pior das três formas de esperar o SMS.

Toda vez que um serviço pede "confirme seu telefone", ele está resolvendo um problema que não é o seu: provar que existe uma pessoa por trás do cadastro. O custo cai no seu colo — você entrega o número pessoal e passa a receber o que vier depois.

Número virtual resolve isso separando as duas coisas. Você recebe o código, o serviço fica satisfeito, e o seu número continua sendo seu.

O que acontece quando você compra um número

O fluxo tem quatro passos, e entender cada um evita quase todo erro de integração:

Você escolhe país e serviço. Não é só o país: o número precisa estar habilitado para aquele serviço específico. Um número que recebe SMS do Google pode não receber do WhatsApp, porque a operadora e o destino tratam as faixas de numeração de forma diferente.
O número é reservado para você. Enquanto o pedido está aberto, aquele número não vai para mais ninguém. É o que garante que o código que chegar seja o do seu cadastro.
O SMS chega. O código aparece no painel e na API.
O pedido termina. O número volta para o estoque e fica disponível para outra pessoa.

O passo 4 é o que costuma surpreender quem começa. O número não é seu para sempre. Ele é uma linha emprestada pelo tempo de uma verificação. Se o serviço mandar um segundo SMS uma semana depois, você não vai receber.

Escolhendo o país certo

A escolha do país não é uma preferência estética. Ela muda se o cadastro funciona.

Serviços olham o prefixo do número e tiram conclusões. Alguns só aceitam número do país onde você diz morar. Outros bloqueiam faixas inteiras que já foram usadas demais. E alguns oferecem preço, conteúdo ou até funcionalidade diferente conforme o país da linha.

Na prática: se o cadastro é em um serviço brasileiro, use número do Brasil. Se você está testando como o seu próprio produto se comporta para um cliente na Alemanha, use um número alemão. Escolher o país "mais barato da lista" é a forma mais comum de gastar dinheiro em um pedido que nunca vai receber o código.

Recebendo o código pela API

Se for uma vez só, o painel resolve. Se for parte de um processo, a API v1 é o caminho.

Primeiro, o pedido:

curl -X POST https://altiviacloud.com.br/api/v1/orders \
  -H "Authorization: Bearer ac_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"countryId": "id_do_pais", "serviceId": "id_do_servico"}'

Os identificadores de país e serviço vêm de /api/v1/countries e /api/v1/services. Vale consultar uma vez e guardar, em vez de buscar a cada pedido.

Depois, o SMS:

curl https://altiviacloud.com.br/api/v1/orders/ID_DO_PEDIDO/sms \
  -H "Authorization: Bearer ac_live_SUA_CHAVE"

Três formas de esperar o código, e a que você deve evitar

Aqui está a decisão que mais separa uma integração que aguenta volume de uma que não aguenta.

Consultar em laço é o que quase todo mundo escreve primeiro: um while que chama o endpoint de SMS a cada segundo até o código chegar. Funciona com um pedido. Com trezentos pedidos simultâneos, você criou um gerador de requisições inúteis — a esmagadora maioria delas devolvendo "ainda nada".

SSE serve quando existe alguém esperando na tela. A conexão fica aberta e o código chega assim que existe, sem você perguntar.

Webhook é o que sustenta automação de verdade. Você registra uma URL, segue com a sua vida, e o seu servidor é chamado quando o SMS chega. Nenhuma requisição desperdiçada, nenhuma conexão pendurada.

A regra prática: se tem pessoa olhando, SSE. Se é processo automático, webhook. Laço de consulta, só em rascunho.

Quando o SMS não chega

Acontece, e não é necessariamente erro seu. As causas mais comuns, em ordem:

O serviço não envia para aquele país. Você comprou uma linha que o destino recusa.
O número está queimado para aquele serviço. Já foi usado ali antes e o destino bloqueou.
O serviço mandou por ligação, não por SMS. Alguns caem para voz depois de tentativas.
Você demorou. Muitos códigos expiram em poucos minutos.

Em todos esses casos, cancelar o pedido antes de o código chegar devolve o valor para a carteira. Cancele em vez de esperar até o fim — pedido abandonado ocupa o número e não devolve nada.

Onde isso vale a pena

Não é só sobre privacidade pessoal. Os usos que mais aparecem são de trabalho:

Teste automatizado que passa por OTP. O time de QA não precisa de um celular físico numa gaveta, com alguém lendo o código na mão a cada rodada.
Operação em outro país. O serviço só manda SMS para número local e você não está lá.
Onboarding em escala. Criação de contas pela API, com o código voltando por webhook direto para o processo.

Por onde começar

Adicione saldo, escolha país e serviço, e faça um pedido pelo painel para ver o fluxo inteiro antes de escrever qualquer linha de código. Depois disso, a página de números virtuais mostra o que está disponível e a documentação leva você da primeira chamada até o webhook em produção.