API de verificação SMS

1. GET /api/v2/tn101/get-services — o catálogo, com o identificador que você vai usar no pedido e o preço atual.
2. POST /api/v2/tn101/request-number — peça um número. Recebe service_key, além de state e códigos de área opcionais. Responde com o id do pedido, o número e quando ele expira.
3. GET /api/v2/tn101/get-number-details — consulte com order_id. pin fica nulo até o código chegar e passa a contê-lo depois. É a leitura mais barata da API e a que foi feita para ser chamada em loop.
4. POST /api/v2/tn101/reject-number — libere um número que não recebeu nada. É isso também que devolve o valor.

Nada é enviado para você nesse caminho, então o passo 3 é uma consulta periódica. Se você prefere ser avisado a perguntar, a conta também envia webhooks nos eventos de pedido, configurados no painel.

Toda requisição leva Authorization: Bearer <token>. Os tokens são gerados no painel, em acesso à API, e podem ser trocados ali a qualquer momento — trocar invalida o token antigo na hora, então atualize a sua configuração primeiro.

Uma requisição sem token válido recebe 401. Uma conta suspensa, ou com o acesso à API desativado, recebe 403. Quando a API está desativada no site inteiro, todos os endpoints respondem 503 em vez de fingir que está tudo bem.

Todos os endpoints respondem com os mesmos três campos:

data traz o conteúdo, success é o booleano para tomar decisões e summery é a mensagem legível. Essa grafia não é um erro de digitação desta página — é o nome do campo que a API sempre usou, ele está em todas as integrações escritas para ela, e renomeá-lo quebraria todas para corrigir uma letra. Leia summery.

Falhas de validação respondem 422 com data como um objeto que associa nomes de campos a mensagens de erro, para que quem chama possa informar qual argumento estava errado, e não apenas que algo estava.

A API é uma forma prática de exercitar um fluxo de cadastro ou de redefinição de senha em uma rota real de operadora em vez de uma simulada — peça um número, preencha o seu próprio formulário com ele, consulte o código e verifique o que a sua aplicação faz em seguida. É um teste mais lento do que um stub, e pega o que um stub não pega: normalização, filtragem por tipo de linha e os atrasos de entrega que os seus usuários vão realmente enfrentar.

Não há limite de requisições por segundo na API, mas há duas cotas sobre os pedidos, e são as mesmas que o painel aplica:

• Pedidos em aberto. Uma conta só pode ter um número limitado de números reservados ao mesmo tempo. Consulte e libere, em vez de abrir muitos em paralelo.
• Pedidos cancelados e expirados por dia. Ultrapasse a cota diária e os pedidos ficam pausados por um tempo, que aumenta a cada repetição. Toda reserva consome estoque real, chegue um código ou não, e é isso que a cota protege.

O andamento de um pedido, do início ao fim, está explicado em números temporários.