Como integrar a API de números virtuais no seu sistema
Integrar números virtuais num sistema próprio, seja um painel interno, um bot de Telegram ou uma loja, segue sempre o mesmo fluxo: pedir o número, mostrar o número para quem vai usar, esperar o SMS e entregar o código. Este guia mostra esse fluxo e os cuidados que evitam dor de cabeça.
- Fluxo: getNumber, mostrar o número, getStatus em intervalos, entregar o código.
- Guarde o id da ativação: é ele que liga cada consulta à compra certa.
- Consulte a cada 5 a 10 segundos e pare ao receber STATUS_OK ou STATUS_CANCEL.
- O estorno é automático: sem SMS, o valor volta para o saldo.
Passo a passo
Como integrar a API de números virtuais no seu sistema
Consulte preço e estoque
Antes de vender, use getPrices com o serviço e o país para mostrar o valor e saber se há números.
Peça o número
Chame getNumber ou getNumberV2. Guarde o id da ativação e o número no seu banco de dados.
Mostre o número e aguarde
Exiba o número para o usuário e consulte getStatus em intervalos até o código chegar.
Entregue e finalize
Mostre o código e chame setStatus com status=6. Se não chegar nada, cancele a partir de 2 minutos ou deixe expirar.
Desenho recomendado
- Faça as chamadas pelo seu servidor, nunca pelo navegador: a chave não pode aparecer no código do site.
- Grave cada ativação com id, serviço, número, valor e status. Isso resolve qualquer dúvida depois.
- Use uma fila ou um job para consultar getStatus, em vez de deixar o usuário recarregando a página.
- Trate NO_NUMBERS, NO_BALANCE e BAD_ACTION com mensagens claras para o usuário.
Saldo e preço
As compras pela API usam o saldo da sua conta no Flash SMS. Monitore getBalance e recarregue antes de acabar, para o seu sistema não começar a devolver NO_BALANCE. Se você revende, o seu preço de venda é livre: o custo que aparece em getPrices é o que sai do seu saldo.
Quando o código não chega
Isso acontece com qualquer fornecedor: o serviço pode demorar ou recusar o número. Depois de 2 minutos, setStatus com status=8 cancela e devolve o valor. Se você não fizer nada, o número expira em 20 minutos e o valor volta do mesmo jeito. Ofereça ao usuário a opção de tentar outro número.
Escolher operadora e DDD
No server=2, para números do Brasil, os parâmetros operator e ddd deixam você pedir uma operadora específica (sem custo extra) ou um DDD (com 30% a mais no preço). Sem números com esse filtro, a resposta é NO_NUMBERS.
Dúvidas
Perguntas frequentes
Posso chamar a API direto do aplicativo do cliente?
Não é recomendado. Quem tiver a chave usa o seu saldo. Faça as chamadas pelo seu servidor.
Funciona com sistemas feitos para o sms-activate?
Sim, o formato é o mesmo. Normalmente basta trocar o endereço e a chave.
Qual o intervalo ideal para consultar o status?
De 5 a 10 segundos. Consultas mais rápidas não fazem o SMS chegar antes.
API e integrações
Continue lendo
Para que serve uma API de números virtuais
Revenda, testes, bots e painéis internos, e o que é proibido.
Revenda de números para WhatsApp: como fazer do jeito certo
Você vende o número para o cliente verificar a conta dele, não a conta pronta.
Como montar um painel de SMS próprio usando a API
Catálogo, compra, tela de espera, histórico e saldo dos seus clientes.
API de número virtual para WhatsApp: o fluxo completo
service=wa, do getNumber ao setStatus, com cada resposta possível.
Como precificar a revenda de números virtuais
Custo do getPrices, margem em percentual e regras para quando o custo muda.
Bot do Telegram para vender números virtuais: como estruturar
Comandos, servidor, banco de dados e a rotina que entrega o código.
Receba seu primeiro código hoje
Cadastro em menos de um minuto, recarga por Pix, cartão ou cripto e o SMS no painel. Se não chegar, o valor volta.
Criar conta grátis