API de verificação por SMS
A API de verificação por SMS são três chamadas: compre um número, espere o código, libere o número. Ela alcança 517 serviços em 225 países, os números começam em € 0,07 e uma ativação que não recebe nada é reembolsada sem abrir chamado. As chaves têm escopo, as compras são idempotentes e os clientes antigos de handler_api continuam funcionando sem mudança.
A API em um bloco
Atualizado em 28 de ago. de 2026- URL base
- https://virtualsmsnumbers.com/api/v1
- Autenticação
- Chave bearer ou X-Api-Key
- Limite de requisições
- 120/min, pico de 20/s
- Janela de idempotência
- 24 horas
- Reembolso automático após
- 20 minutos
- Ativação mais barata
- € 0,07
- Países cobertos
- 225
- Formato
- JSON, centavos, ISO 8601 UTC
Os preços e o estoque vêm do pool de operadoras como ele está agora, não de uma tabela de preços publicada.
O fluxo de três chamadas
Todo o resto da referência é opcional. Este é o caminho inteiro de uma verificação, e ele não muda desde 2019.
- 1
POST /activations
Peça um serviço, e um país se você se importar com qual. A resposta traz o número, o preço em centavos e o carimbo de expiração. Envie uma Idempotency-Key para que uma requisição repetida não compre um segundo número, e um max_price_cents se quem chama for automatizado.
- 2
GET /activations/{id}?wait=180
Long polling. A conexão fica aberta até a mensagem chegar ou o tempo estourar, então uma requisição substitui um laço que faria noventa. O status volta como code_received, com o código já extraído ao lado do texto bruto, porque cada remetente formata do seu jeito.
- 3
POST /activations/{id}/complete
Feche a ativação e libere a linha. Se nada chegou, não faça nada: a janela expira sozinha e o saldo é creditado de volta. Cancelar antes da hora é a mesma chamada com outro nome.
Um exemplo que funciona
Defina VSN_KEY e rode. As respostas comentadas são os formatos reais, incluindo os campos que você vai querer guardar.
# 1. Buy a Telegram number in Portugal
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations \
-H "Authorization: Bearer $VSN_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"service":"telegram","country":"PT"}'
# {"id":"1043872915","phone_number":"351926114508","status":"waiting",
# "price_cents":11,"expires_at":"2026-08-26T12:41:07Z"}
# 2. Long-poll until the code lands (blocks up to 120 s)
-kw">curl "https://virtualsmsnumbers.com/api/v1/activations/1043872915?wait=120" \
-H "Authorization: Bearer $VSN_KEY"
# {"id":"1043872915","status":"code_received",
# "messages":[{"code":"48219","text":"Telegram code: 48219"}]}
# 3. Release the number
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations/1043872915/complete \
-H "Authorization: Bearer $VSN_KEY"Limites de requisições
120 requisições por minuto por chave, com picos de 20 por segundo. Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, e um 429 diz quanto tempo esperar em vez de deixar você adivinhar.
O limite raramente é a restrição se a API for usada como se pretende: um long poll no lugar de noventa consultas, um webhook no lugar de um timer e as listas de países e serviços em cache na inicialização. Se você realmente precisa de mais folga, peça — aumentar um limite é mais fácil para nós dois do que depurar uma frota de chaves.
Idempotência
Envie um cabeçalho Idempotency-Key no POST /activations. Repetir a mesma chave dentro de 24 horas devolve a ativação original como ela está agora, com um cabeçalho Idempotent-Replay, em vez de comprar um segundo número e cobrar você duas vezes.
A chave não é um hash do corpo: um conteúdo diferente sob uma chave já usada ainda devolve a primeira ativação. Gere uma chave por compra lógica — um UUID serve — e reutilize entre as tentativas, nunca entre compras.
Clientes antigos de handler_api
Scripts escritos para o protocolo clássico handler_api.php continuam funcionando. Aponte-os para o endpoint de compatibilidade, troque a api_key, e as mesmas ações devolvem os mesmos tokens ACCESS_ e STATUS_ de sempre.
É uma camada de tradução sobre o mesmo pool, então preços, estoque e reembolsos se comportam igual pelos dois caminhos. Código novo deveria usar /api/v1 mesmo assim: as respostas JSON trazem carimbos de tempo, códigos de erro e campos de preço para os quais o formato de tokens não tem espaço.
# Existing scripts keep working: same actions, same response tokens.
BASE="https://virtualsmsnumbers.com/stubs/handler_api.php"
-kw">curl "$BASE?api_key=$KEY&action=getNumber&service=tg&country=117"
# ACCESS_NUMBER:1043872915:351926114508
-kw">curl "$BASE?api_key=$KEY&action=getStatus&id=1043872915"
# STATUS_WAIT_CODE
# STATUS_OK:48219
-kw">curl "$BASE?api_key=$KEY&action=setStatus&id=1043872915&status=6"
# ACCESS_ACTIVATION
-kw">curl "$BASE?api_key=$KEY&action=getBalance"
# ACCESS_BALANCE:41.87Agentes, MCP e descoberta
Existe um servidor MCP hospedado, um documento OpenAPI 3.1 e um índice llms.txt, então um agente consegue descobrir as três ferramentas de que precisa sem cola escrita à mão. Aponte o seu cliente para o endpoint abaixo e ele vai encontrar comprar, esperar e liberar.
Antes de deixar algo autônomo gastar do saldo: limite a chave a numbers:read e numbers:write, coloque um teto max_price_cents em toda compra e dê a ela uma chave própria, para que revogá-la não derrube a sua integração de produção.
{
"mcpServers": {
"virtualsmsnumbers": {
"type": "http",
"url": "https://virtualsmsnumbers.com/api/mcp",
"headers": { "Authorization": "Bearer vsn_live_xxxxxxxxxxxx" }
}
}
}Antes da produção
- Defina max_price_cents em toda compra. Os preços se movem com o pool, e um agente sem limite vai comprar alegremente a ponta cara dele.
- Trate os identificadores como cadeias opacas. Os ids de ativação por acaso têm dez dígitos hoje; isso não é uma promessa, e o tamanho deles também não.
- Ramifique pelo código de erro, nunca pela mensagem. Os códigos são estáveis dentro de uma versão; as mensagens são escritas para pessoas e são reescritas.
- Assine sms.received e verifique a assinatura — HMAC-SHA256 sobre o corpo bruto, com janela de repetição de cinco minutos — em vez de consultar um estado sobre o qual você pode ser avisado.
- Faça as contas com os campos inteiros em centavos. As cadeias formatadas ao lado deles são para exibição e dependem do idioma.
A referência completa
Seis endpoints, tabelas de erro, payloads de webhook, escopos e o mapa de tokens antigos.
Perguntas frequentes
A entrega mediana fica abaixo de nove segundos a partir do momento em que o serviço envia. O long polling existe porque a cauda é longa: a ativação fica aberta por 20 minutos e expira em reembolso se nada chegar.
Nada que você precise tratar. A janela fecha, o saldo é creditado de volta automaticamente e a ativação termina em um estado expirado que você pode ler pela API.
Sim, e não custa nada. As chaves têm escopos fixos, uma lista de IPs opcional e uma expiração escolhida na criação, então uma chave de homologação que vaze não consegue comprar números em produção.
Existem wrappers leves e sem dependências, mas a API são seis endpoints sobre JSON — fetch, requests ou curl dão conta do fluxo de três chamadas.
Em uma mesma ativação, sim: as mensagens extras chegam no mesmo número enquanto ela estiver aberta. Entre sessões você precisa de um aluguel, que segura a linha de quatro horas a doze meses.
Não. É o mesmo pool pelos mesmos preços; o que muda é só a codificação da resposta.