Automatize a verificação por SMS com a API: guia para desenvolvedores

A API REST do SMS Activate App permite que seu código compre um número privado, dispare uma verificação e leia o código SMS, para seus apps, contas e testes.

Este guia cobre o fluxo completo: escolher um número, comprá-lo com segurança, ler o código OTP (senha de uso único) e liberar o número quando você terminar.

Quando automatizar

A automação serve para trabalho que é seu e que se repete. Três casos comuns:

  • Testes de ponta a ponta das etapas de SMS no seu próprio app: cadastro, login, redefinição de senha e 2FA (autenticação de dois fatores).
  • Manter o 2FA funcionando nas contas de serviço e nas ferramentas internas que são suas.
  • Uma etapa de verificação dentro de um produto que você opera.

Cada número é um número virtual privado. É um número real, móvel ou local, da faixa de uma operadora, conforme o país. Sua conta fica com ele por um período de 28 dias. O mesmo número pode receber códigos depois, então a reverificação e a recuperação de conta continuam funcionando durante o período.

Valem dois limites. Depois de emitido, o número é definitivo e não tem reembolso. Quem decide se aceita um número é a plataforma em que você faz a verificação, não nós.

A maioria dos códigos chega poucos minutos depois que a plataforma os envia. Ainda não publicamos uma taxa de entrega, então teste um número com a plataforma de destino antes de montar um pipeline em torno dele.

A API recebe SMS. Ela não envia SMS.

Antes de começar

  • Crie uma conta gratuita na página de cadastro.
  • Adicione saldo à conta.
  • Crie uma chave de API pessoal no painel da conta, na aba de chaves de API, ou no bot do Telegram.

Envie a chave em toda requisição, inclusive nas do catálogo:

A chave gasta o seu saldo. Guarde-a no servidor, em um cofre de segredos ou em um secret de CI. Nunca a coloque em código do cliente nem faça commit dela em um repositório.

Detalhes de referência:

  • URL base: https://api.sms-activate.app/v1/public
  • Valores em dinheiro são centavos de dólar (USD) em números inteiros. balanceCents: 2000 significa US$ 20,00.
  • Especificação legível por máquina: o arquivo OpenAPI (OpenAPI 3.1).
  • Documentação para leitura: a documentação da API.
  • Uma skill pronta para agentes de LLM: a skill para agentes.
  • Limites: pelo menos 120 requisições por minuto por conta e 30 compras por minuto. Acima disso, a resposta é rate_limited com um cabeçalho Retry-After.

O fluxo de verificação

  • Chame GET /countries. O endpoint retorna a disponibilidade e a faixa de preço de cada país.
  • Chame GET /numbers/search?country=US&limit=1 para escolher um número disponível. Cada resultado traz phoneNumber e o seu preço em priceCents.
  • Compre o número com POST /numbers e o corpo {"phone": "<phoneNumber>", "country": "US"}. Adicione um cabeçalho Idempotency-Key: <uuid>, para que uma nova tentativa nunca cobre você duas vezes. Uma compra bem-sucedida retorna 201 com number, chargedCents e balanceAfterCents. Há dois campos opcionais: autoRenew (padrão true) e note.
  • Digite o número no fluxo que você está testando e dispare o SMS.
  • Leia o código. Consulte GET /numbers/{id}/sms para esse número, ou GET /sms para todos, mais ou menos a cada 5 a 15 segundos, e defina um tempo limite. Cada SMS tem id, numberId, from, to, body e receivedAt; tire o código de body. Os feeds usam paginação por cursor com cursor, limit e nextCursor.
  • Finalize. Envie PATCH /numbers/{id} com {"autoRenew": false} para parar a renovação, ou DELETE /numbers/{id} para liberar o número. Para uma suíte de testes que você roda todo dia, manter um número com renovação costuma ser mais simples do que comprar um novo a cada execução.

Exemplo em curl

A primeira chamada encontra um número. A segunda o compra. A terceira lê os SMS recebidos.

Substitua +15551234567 por um número retornado pela primeira chamada. Se você repetir a compra depois de um erro de rede, reutilize o mesmo valor de Idempotency-Key em vez de gerar um novo.

Exemplo em Python

Esta função espera um código em um número que já é seu. Ela usa a biblioteca requests e lê a chave da variável de ambiente.

Se SMS anteriores no mesmo número puderem coincidir, compare receivedAt com o momento em que o seu teste disparou a mensagem e aceite só uma mais recente.

Um webhook em vez de polling

Envie PATCH /numbers/{id} com {"forwardWebhookUrl": "https://your-app.example.com/sms"}, e cada SMS e cada ligação para esse número são enviados ao seu servidor assim que chegam. O endereço é verificado antes: ele precisa responder a um POST de teste com um status 2xx.

Cada requisição traz x-vpn-event, x-vpn-timestamp e x-vpn-signature. A assinatura é HMAC-SHA256 de v1.<timestamp>.<raw body> com o seu segredo de webhook. Verifique-a sobre os bytes brutos e rejeite um timestamp com diferença de mais de cinco minutos.

O polling é mais simples para um teste que roda uma vez. Um webhook serve para um serviço de longa duração que processa os códigos conforme eles chegam.

Trate erros como respostas

Todo erro tem o mesmo formato:

Decida pelo código em error, nunca pelo status HTTP. Um mesmo status pode representar mais de uma recusa, então o status sozinho não diz o que aconteceu. Algumas recusas trazem um objeto details, por exemplo requiredCents e availableCents em insufficient_balance.

Códigos para tratar:

  • insufficient_balance: seu saldo não cobre a compra. Pare e adicione saldo.
  • no_numbers: não há número correspondente disponível agora. Escolha outro número ou país.
  • number_unavailable: o número foi vendido ou não está mais à venda. Faça a busca de novo.
  • validation_failed: o corpo ou os parâmetros da requisição estão errados, ou a compra veio sem Idempotency-Key. Corrija a entrada.
  • idempotent_replay: uma requisição com esta Idempotency-Key chegou com outro corpo ou ainda está sendo processada. Não trate isso como uma compra nova.
  • rate_limited: requisições demais. Espere o tempo indicado no cabeçalho Retry-After.
  • priceexceeded e providerfailure: leia message, mostre a mensagem e interrompa a execução. Depois de provider_failure, confira seus números antes de comprar de novo.

Nenhum desses erros é uma falha para repetir às cegas. Mostre o erro para quem está rodando o código ou interrompa a execução. Guarde o reqId nos seus logs. O suporte usa esse valor para encontrar a sua requisição.

Em uma suíte de testes de CI

  • Rode os testes de SMS como um job separado e serial, para que dois testes nunca leiam o mesmo código.
  • Guarde a chave da API como um secret do CI.
  • Associe cada código ao seu teste pelo número e pelo horário em que o teste começou.
  • Defina um timeout e falhe com uma mensagem clara que indique o número e a etapa.
  • Mantenha um número com renovação para execuções repetidas em vez de comprar um novo a cada vez.

Vídeos úteis

Vídeos de terceiros sobre as técnicas que este guia usa. Eles ensinam técnicas gerais e não tratam do nosso serviço.

Próximos passos