API de verificação por SMS: guia rápido

A primeira é o protocolo handler_api. É o formato de requisição usado pelas ferramentas escritas para o SMS-Activate. Se a sua ferramenta fala esse protocolo, você troca o endereço da API e a chave, e mantém o seu código.

A segunda é a API JSON v2. Ela tem requisições e respostas em JSON simples, webhooks e status claros. Use-a para tudo o que você escrever do zero.

Toda requisição vai para um único endereço, com a sua chave e o nome de uma ação. O endereço está na documentação. As ações principais são as que a sua ferramenta já envia.

• getNumber: compra um número para um serviço e um país.
• getStatus: pergunta se o código chegou.
• setStatus: muda o estado de uma ativação, por exemplo para cancelá-la.
• getBalance: lê o saldo da sua carteira.

A sua chave está na página Desenvolvedores da sua conta. Envie-a como token Bearer no cabeçalho Authorization de toda requisição.

Comece com GET /catalog. Ele retorna as ofertas que você pode comprar agora, com o seu preço, e você pode filtrar por país e por serviço. GET /balance retorna o saldo da carteira em dólares americanos. A recarga da carteira é a partir de US$ 3.

O fluxo inteiro são poucas chamadas.

Uma ativação tem um de quatro status: waiting, completed, expired ou cancelled. Só é possível cancelar enquanto ela ainda está em waiting.

Por padrão, uma ativação espera dez minutos pelo código e depois expira. Você pode definir uma espera mais curta ou mais longa na chamada de compra, de dois a vinte minutos. GET /activations lista as suas ativações, da mais recente para a mais antiga.

• POST /activations com um serviço e um país compra um número.
• GET /activations/:id retorna a ativação. Consulte até o código estar lá.
• Ou informe um endereço de webhook na chamada de compra, e nós chamamos o seu servidor quando o código chegar.
• POST /activations/:id/cancel cancela uma ativação em waiting, com reembolso total.

Redes falham, e uma chamada de compra que deu timeout pode ter sido concluída. Envie um cabeçalho Idempotency-Key em POST /activations. Se você tentar de novo com a mesma chave, recebe de volta a primeira ativação, não uma segunda compra.

Cada endpoint tem o seu próprio limite, de 30 a 120 requisições por minuto, e a documentação lista cada um. Se você usa o webhook, quase não precisa consultar. Os webhooks são assinados, então confira a assinatura antes de confiar em um.

Todo número é um cartão SIM real em uma rede móvel, vendido para uma ativação de um serviço. Ele recebe apenas SMS, não ligações. Não prometemos que um app vai aceitar um número ou enviar um código, então o seu código precisa prever ativações que terminam sem nenhum.

Você só paga pelo código que chega. Quando nenhum vier, cancele a ativação ou deixe expirar, e o valor total volta para a sua carteira automaticamente. Trate isso como um ramo comum do fluxo, não como um erro.

A maioria dos problemas iniciais vem de pular estas etapas.

• Faça primeiro uma ativação manualmente e leia cada campo da resposta.
• Deixe uma ativação expirar de propósito e veja o saldo voltar.
• Compare os seus códigos de país e de serviço com a documentação. Um código errado pode retornar um número que você não queria.
• Mantenha a chave no seu servidor, nunca em um app ou em uma página web.