v1REST · JSON

SNSOTP OTP API

Uma API REST para verificação por SMS. Solicite um número para um dos 182 serviços em um dos 154 países, leia o código único do pedido e receba o valor total de volta se nenhum código chegar em 20 minutos.

Cada endpoint aceita parâmetros como parâmetros de consulta (GET) ou como campos de formulário ou JSON (POST). As respostas são em JSON; o dinheiro é uma string em USD com duas casas decimais e os horários são ISO 8601 em UTC.

Servidor

https://snsotp.com/api/v1

AutenticaçãoToken Bearer

Sua chave API da console, enviada como Authorization: Bearer sok_...

Autenticação

Crie uma chave na página da API na console. Ela começa com sok_ e é mostrada apenas uma vez, então armazene-a em uma variável de ambiente. Substituir a chave interrompe a antiga imediatamente. Chamadas para /services, /countries e /prices funcionam sem uma chave.

Cabeçalho
Authorization: Bearer sok_your_key_here

A chave também pode ser enviada como um parâmetro de consulta ou campo de formulário key, o que ajuda ferramentas que não podem definir cabeçalhos.

Início rápido

Solicite um número, forneça-o ao aplicativo e então consulte o pedido até que o código esteja lá. O mesmo fluxo em quatro linguagens:

# 1. Order a number for whatsapp in US
curl -X POST https://snsotp.com/api/v1/orders \
  -H "Authorization: Bearer $SNSOTP_KEY" \
  -d service=whatsapp -d country=us

# 2. Read the code (poll every 3 to 5 seconds)
curl https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB \
  -H "Authorization: Bearer $SNSOTP_KEY"

GET/services

Cada serviço com seu código e menor preço · sem chave

Cada serviço que você pode solicitar, com seu código (use-o como service em outras chamadas), sua categoria e o menor preço entre os países. Nenhuma chave necessária.

SolicitaçãocURL
curl https://snsotp.com/api/v1/services
Resposta200
{
  "services": [
    { "code": "whatsapp", "name": "WhatsApp", "category": "social", "from": "0.09" },
    { "code": "telegram", "name": "Telegram", "category": "social", "from": "0.03" }
  ]
}

GET/countries

Cada país com seu código e código de discagem · sem chave

Cada país com seu código (ISO 3166 alpha-2 em minúsculas, use-o como country) e seu código de discagem. Nenhuma chave necessária.

SolicitaçãocURL
curl https://snsotp.com/api/v1/countries
Resposta200
{
  "countries": [
    { "code": "us", "name": "United States", "dial_code": "1" },
    { "code": "gb", "name": "United Kingdom", "dial_code": "44" }
  ]
}

GET/prices

Preços para um serviço, um país ou ambos · sem chave

O preço por pedido para um serviço em cada país, um país para cada serviço ou um par. Envie pelo menos um filtro. Nenhuma chave necessária.

Parâmetros

  • servicestring

    Código do serviço, por exemplo whatsapp

  • countrystring

    Código do país, por exemplo us

SolicitaçãocURL
curl "https://snsotp.com/api/v1/prices?service=whatsapp&country=us"
Resposta200
{
  "prices": [
    { "service": "whatsapp", "country": "us", "price": "0.93" }
  ]
}

GET/balance

Seu saldo em USD · chave necessária

Seu saldo em USD.

SolicitaçãocURL
curl https://snsotp.com/api/v1/balance \
  -H "Authorization: Bearer $SNSOTP_KEY"
Resposta200
{
  "balance": "42.50",
  "currency": "USD"
}

POST/orders

Solicite um número para um serviço e um país · chave necessária

Solicita um número e cobra seu preço. A resposta tem o número completo (phone) e sem o código de discagem (number). O pedido permanece aberto por 20 minutos; se nenhum código chegar nesse tempo, o valor retorna ao seu saldo automaticamente. Resposta com status 201.

Parâmetros

  • servicestringobrigatório

    Código do serviço de GET /services

  • countrystringobrigatório

    Código do país de GET /countries

SolicitaçãocURL
curl -X POST https://snsotp.com/api/v1/orders \
  -H "Authorization: Bearer $SNSOTP_KEY" \
  -d service=whatsapp -d country=us
Resposta201
{
  "order": {
    "id": "OT-7K2M9QX4PB",
    "service": "whatsapp",
    "country": "us",
    "phone": "+13475550182",
    "number": "3475550182",
    "dial_code": "1",
    "price": "0.93",
    "status": "waiting",
    "code": null,
    "sms": null,
    "codes": [],
    "expires_at": "2026-11-03T12:20:00.000Z"
  },
  "window_minutes": 20
}

GET/orders/{id}

Status, código e texto do SMS de um pedido · chave necessária

Um pedido com seu status, o último código, o último texto SMS e todos os códigos recebidos até agora. Consulte a cada 3 a 5 segundos enquanto o status for waiting.

Parâmetros

  • idpathobrigatório

    ID do pedido de POST /orders

SolicitaçãocURL
curl https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB \
  -H "Authorization: Bearer $SNSOTP_KEY"
Resposta200
{
  "order": {
    "id": "OT-7K2M9QX4PB",
    "service": "whatsapp",
    "country": "us",
    "phone": "+13475550182",
    "number": "3475550182",
    "price": "0.93",
    "status": "received",
    "code": "284913",
    "sms": "Your WhatsApp code is 284913",
    "expires_at": "2026-11-03T12:20:00.000Z"
  }
}

GET/orders

Seus pedidos abertos (ou todos com status=all) · chave necessária

Seus pedidos abertos, os mais recentes primeiro. Adicione status=all para pedidos recentes em todos os status.

Parâmetros

  • statusstring

    open (padrão) ou all

  • limitnumber

    1 a 100, padrão 50

SolicitaçãocURL
curl "https://snsotp.com/api/v1/orders?status=open" \
  -H "Authorization: Bearer $SNSOTP_KEY"
Resposta200
{
  "orders": [
    { "id": "OT-7K2M9QX4PB", "service": "whatsapp", "status": "received", "code": "284913" }
  ]
}

POST/orders/{id}/resend

Outro código no mesmo número · chave necessária

Solicita outro código no mesmo número após o primeiro código, dentro da janela, sem custo adicional. Em seguida, acione um novo SMS no aplicativo; waiting_for_resend é verdadeiro até que ele chegue.

Parâmetros

  • idpathobrigatório

    ID do pedido

SolicitaçãocURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/resend \
  -H "Authorization: Bearer $SNSOTP_KEY"
Resposta200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "received", "waiting_for_resend": true }
}

POST/orders/{id}/finish

Encerre um pedido após usar o código · chave necessária

Fecha um pedido que recebeu um código após você tê-lo usado. Finalizar é opcional: pedidos abertos fecham sozinhos quando a janela termina.

Parâmetros

  • idpathobrigatório

    ID do pedido

SolicitaçãocURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/finish \
  -H "Authorization: Bearer $SNSOTP_KEY"
Resposta200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "finished" }
}

POST/orders/{id}/cancel

Cancele antes de receber um código, reembolso total · chave necessária

Cancela um pedido antes que um código chegue e devolve o valor total ao seu saldo imediatamente. Após um código, cancelar responde has_code.

Parâmetros

  • idpathobrigatório

    ID do pedido

SolicitaçãocURL
curl -X POST https://snsotp.com/api/v1/orders/OT-7K2M9QX4PB/cancel \
  -H "Authorization: Bearer $SNSOTP_KEY"
Resposta200
{
  "order": { "id": "OT-7K2M9QX4PB", "status": "canceled", "refunded": "0.93" }
}

Status do pedido

valores de status
  • waitingO número está pronto e nenhum SMS chegou ainda. Cancelar é possível.
  • receivedPelo menos um código chegou. code e sms contêm o último.
  • finishedFechado após um código, por finish ou quando a janela terminou.
  • refundedNenhum código chegou em 20 minutos. O valor total está de volta no seu saldo.
  • canceledCancelado antes de um código. O valor total está de volta no seu saldo.

Erros

Erros usam o status HTTP e um corpo com um código estável e uma mensagem legível.

Status HTTP e códigos
  • 400missing_filter, bad_jsonUm valor obrigatório está faltando ou o corpo não pode ser lido.
  • 401no_key, bad_keyA chave está faltando, incorreta ou foi excluída.
  • 402no_balanceSaldo insuficiente para este pedido. Adicione saldo na console.
  • 404unknown_service, unknown_country, not_sold, not_foundO código ou o pedido não existe, ou o par não é vendido.
  • 409too_many_open, has_code, not_ready, no_numbersA ação não se encaixa no estado do pedido ou nenhum número está disponível no momento (nada é cobrado).
  • 429rate_limitedMais de 300 solicitações em um minuto com uma chave.
Corpo do erro402
{
  "error": {
    "code": "no_balance",
    "message": "Not enough credit. Add credit in the console."
  }
}

Limites de taxa

  • 300 solicitações por minuto por chave. Acima disso, a API responde 429 rate_limited pelo resto do minuto.
  • Até 20 pedidos abertos por conta. Finalize ou cancele um para abrir outro.
  • Consulte um pedido a cada 3 a 5 segundos; os códigos geralmente chegam em até um minuto.

Formato de ativação por SMS

Scripts escritos para o formato comum handler_api.php funcionam com a mesma chave de API: altere o endereço base para https://snsotp.com/stubs/handler_api.php e mantenha as ações. Os códigos de serviço e país são os mesmos da API REST.

Ações

  • getBalance

    ACCESS_BALANCE:42.50

  • getServicesList

    Lista JSON de serviços

  • getCountries

    Mapa JSON de países

  • getPricesservice, country (opcional)

    JSON {country: {service: {cost, count}}}

  • getNumberservice, country

    ACCESS_NUMBER:<id>:<phone>

  • getStatusid

    STATUS_WAIT_CODE, STATUS_OK:<code>, STATUS_WAIT_RETRY:<code>, STATUS_CANCEL

  • setStatusid, status 1 / 3 / 6 / 8

    ACCESS_READY, ACCESS_RETRY_GET, ACCESS_ACTIVATION, ACCESS_CANCEL

SolicitaçãocURL
curl "https://snsotp.com/stubs/handler_api.php\
?api_key=$SNSOTP_KEY&action=getNumber\
&service=telegram&country=gb"

ACCESS_NUMBER:OT-3QF8ZK2W7M:447700900182

valores de setStatus: 1 pronto, 3 outro código, 6 finalizar, 8 cancelar com reembolso total.

Documentação da API OTP: API de Verificação por SMS REST | SNSOTP