Documentação da API

API REST para comprar números virtuais e receber códigos SMS de forma programática. Você pode testar cada endpoint direto desta página.

Base URL: https://nexsms.pro/api/v1

🔑 Seu token (para testar nesta página)

Cole o token gerado em Perfil → API. Ele fica salvo só no seu navegador e é usado nos botões "Testar".

Autenticação

Envie o token em toda requisição no cabeçalho:

Authorization: Bearer nsms_live_xxxxxxxxxxxxxxxx

Regras

Saldo mínimo: POST /numeros exige saldo ≥ R$20. Abaixo disso, os demais endpoints funcionam normalmente.
Limite: 120 requisições/min por token. Excedeu → 429 com Retry-After.
Idempotência: Idempotency-Key em POST /numeros evita compra dupla em retries.
Expiração: números expiram em 20 min. Cancelar: entre 2 e 18 min, se o código não chegou. Sem código no prazo → reembolso automático.

Fluxo típico

GET /servicos → escolha o serviço e pegue o application_id.
POST /numeros → recebe o id e o numero.
Use o número no app que quer verificar.
Pegue o código: polling em GET /numeros/{id} ou via webhook (recomendado).
Sem código? cancelar (2–18 min) ou aguarde o reembolso automático.

Endpoints

GET/api/v1/conta

Status da conta

Testa o token e retorna o status da conta: saldo, se a API está ativa (saldo ≥ R$20) e os limites. Use este endpoint para validar a integração.

curl -X GET "https://nexsms.pro/api/v1/conta" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

{
  "usuario": "João Silva",
  "saldo": 45.00,
  "api_ativa": true,
  "saldo_minimo_compra": 20,
  "limite_por_minuto": 120
}

GET/api/v1/saldo

Consultar saldo

Retorna o saldo atual da conta em reais.

curl -X GET "https://nexsms.pro/api/v1/saldo" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

{ "saldo": 45.00, "moeda": "BRL" }

GET/api/v1/paises

Listar países

Lista todos os países disponíveis com seu código e nome. Use o código (ex.: "BR") no campo "pais" dos outros endpoints.

curl -X GET "https://nexsms.pro/api/v1/paises" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

{
  "paises": [
    { "codigo": "BR", "nome": "Brasil" },
    { "codigo": "US", "nome": "Estados Unidos" }
  ]
}

GET/api/v1/servicos

Listar serviços e preços

Lista os serviços disponíveis com preço (já com markup) e estoque. Todos os filtros são opcionais e combináveis. Use o "application_id" retornado aqui para comprar um número.

paisquery · opcional

Filtra por código de país (ex.: BR).

tipoquery · opcional

normal (padrão) ou premium.

servicoquery · opcional

Busca por nome do serviço (ex.: whatsapp).

disponivel_minquery · opcional

Estoque mínimo de números.

curl -X GET "https://nexsms.pro/api/v1/servicos" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

{
  "tipo": "normal",
  "servicos": [
    {
      "servico": "whatsapp",
      "nome": "WhatsApp",
      "pais": "BR",
      "pais_nome": "Brasil",
      "application_id": "1",
      "preco": 1.50,
      "disponivel": 230
    }
  ]
}

POST/api/v1/numeros⚠ ação real

Comprar um número

Compra um número para o serviço/país informados e debita o preço do saldo. Exige saldo ≥ R$20. Envie o cabeçalho opcional "Idempotency-Key" para evitar compra dupla em caso de retry/timeout: a mesma chave nunca compra duas vezes.

⚠ Compra de verdade — debita o saldo da sua conta.

application_idbody · obrigatório

ID do serviço (vem de /servicos).

paisbody · obrigatório

Código do país.

tipobody · opcional

normal (padrão) ou premium.

Idempotency-Keyheader · opcional

Chave única opcional para evitar compra dupla.

curl -X POST "https://nexsms.pro/api/v1/numeros" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

{
  "id": "663f1c...",
  "numero": "+55 11 9xxxx-xxxx",
  "servico": "whatsapp",
  "pais": "BR",
  "premium": false,
  "preco": 1.50,
  "status": "ativo",
  "expira_em": "2026-06-12T12:20:00.000Z"
}

GET/api/v1/numeros

Histórico de números

Lista os números que você comprou (mais recentes primeiro), com paginação. Filtros opcionais.

statusquery · opcional

ativo | recebido | expirado | cancelado.

tipoquery · opcional

normal ou premium.

paginaquery · opcional

Número da página (20 por página).

curl -X GET "https://nexsms.pro/api/v1/numeros" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

{
  "pagina": 1,
  "total": 134,
  "numeros": [
    {
      "id": "663f1c...",
      "numero": "+55 11 9xxxx-xxxx",
      "servico": "whatsapp",
      "status": "recebido",
      "codigo": "123456",
      "premium": false,
      "preco": 1.50,
      "criado_em": "2026-06-12T12:00:00.000Z"
    }
  ]
}

GET/api/v1/numeros/{id}

Status de um número

Consulta o status e o código SMS de um número específico. O campo "codigo" fica null até o SMS chegar. Faça polling neste endpoint (a cada poucos segundos) OU use o webhook para receber o código automaticamente.

idpath · obrigatório

ID do número (retornado na compra).

curl -X GET "https://nexsms.pro/api/v1/numeros/{id}" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

{
  "id": "663f1c...",
  "numero": "+55 11 9xxxx-xxxx",
  "servico": "whatsapp",
  "status": "recebido",
  "codigo": "123456",
  "premium": false,
  "preco": 1.50,
  "expira_em": "2026-06-12T12:20:00.000Z",
  "criado_em": "2026-06-12T12:00:00.000Z"
}

POST/api/v1/numeros/{id}/cancelar⚠ ação real

Cancelar um número

Cancela um número e devolve o valor ao saldo. Só é possível entre 2 e 18 minutos após a compra, e apenas se o código ainda não chegou. Números sem código expiram e são reembolsados automaticamente em 20 minutos.

⚠ Ação real — cancela o número e reembolsa o saldo.

idpath · obrigatório

ID do número a cancelar.

curl -X POST "https://nexsms.pro/api/v1/numeros/{id}/cancelar" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

{ "sucesso": true, "reembolsado": 1.50, "saldo": 46.50 }

POST/api/v1/webhook⚠ ação real

Configurar webhook

Cadastra (ou atualiza) a URL que receberá os códigos em tempo real. A URL deve usar https e não pode apontar para um IP interno. Retorna um "secret" usado para validar a assinatura das notificações — guarde-o.

⚠ Salva/atualiza a configuração de webhook da sua conta.

urlbody · obrigatório

URL https que receberá os POSTs.

curl -X POST "https://nexsms.pro/api/v1/webhook" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

{ "url": "https://seusistema.com/callback", "secret": "whsec_...", "ativo": true }

DELETE/api/v1/webhook⚠ ação real

Remover webhook

Desativa o webhook da conta. As notificações param de ser enviadas.

⚠ Desativa o webhook.

curl -X DELETE "https://nexsms.pro/api/v1/webhook" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

{ "ativo": false }

Webhook

Em vez de ficar consultando, cadastre uma URL e receba o código no instante em que chega. Quando o código chega (ou o número expira), enviamos um POST para sua URL:

POST https://seusistema.com/callback
X-NexSMS-Signature: <hmac-sha256 do corpo>

{ "evento": "codigo_recebido", "numero_id": "663f...", "servico": "whatsapp", "numero": "+55...", "codigo": "123456", "status": "recebido" }

Valide a assinatura com seu secret (Node.js):

import { createHmac } from 'crypto';
const esperado = createHmac('sha256', SEU_SECRET).update(corpoBruto).digest('hex');
const valido = esperado === req.headers['x-nexsms-signature'];

Entrega com até 3 tentativas (imediata, +30s, +2min). Responda com HTTP 2xx para confirmar.

Códigos de erro

Formato: { "erro": "mensagem", "codigo": "identificador" }

401 nao_autenticado / token_invalido — token ausente ou inválido.
403 saldo_minimo_api — saldo abaixo de R$20 para comprar.
403 conta_suspensa — conta suspensa.
429 limite_excedido — passou de 120 req/min.
400 saldo_insuficiente / aguarde_2min / prazo_encerrado / sms_ja_recebido
409 servico_indisponivel / numero_indisponivel
502 falha_fornecedor — erro temporário no fornecedor.

Quer integrar com ajuda de uma IA? Use o botão Baixar Markdown no topo e entregue o arquivo para a IA — ele contém tudo que ela precisa. Dúvidas: [email protected]