Pegar minha chave
Voltar ao site

Documentação · v1

API para revendedores

Compre números virtuais e receba os códigos SMS automaticamente no seu site, bot do Telegram ou sistema. A API usa o mesmo saldo e os mesmos preços do painel, com reembolso automático quando o SMS não chega.

Autenticação

Crie uma chave em Painel → API e envie em todas as requisições. Guarde a chave no servidor, nunca no navegador ou no app.

Authorization: Bearer nx_live_SUA_CHAVE
Base URL: https://smsnexo.com/api/v1

Endpoints

GET/balance

Saldo da conta.

Resposta

{ "balance": 42.5, "currency": "BRL" }

GET/countries

Países disponíveis (use o id nas outras chamadas).

Resposta

{ "countries": [ { "id": 73, "name": "Brazil", "iso": "BR" } ] }

GET/services?country=73

Serviços do país com preço de venda e estoque ao vivo.

Resposta

{ "country": 73, "services": [ { "code": "wa", "name": "Whatsapp", "price": 9.6, "currency": "BRL", "stock": 4100 } ] }

POST/orders

Compra um número. O valor é descontado do saldo.

Corpo

{ "service": "wa", "country": 73 }

Resposta

{ "order": { "id": "9b1c…", "phone": "+5511987654321", "status": "waiting", "price": 9.6, "code": null, "expires_at": "2026-10-24T15:20:00Z" } }

GET/orders/:id?wait=30

Status da ativação e o código, quando chegar. Use ?wait=30 para a resposta esperar o código (até 30 s) em vez de consultar várias vezes.

Resposta

{ "order": { "id": "9b1c…", "status": "received", "code": "482913", "sms": [ { "code": "482913", "text": "Seu código…" } ] } }

GET/orders?status=waiting

Suas últimas 100 ativações (filtro opcional por status).

Resposta

{ "orders": [ … ] }

POST/orders/:id/cancel

Cancela antes de chegar SMS. O valor volta para o saldo.

Resposta

{ "order": { "status": "cancelled", … } }

POST/orders/:id/finish

Conclui a ativação depois de usar o código.

Resposta

{ "order": { "status": "finished", … } }

Receber o SMS na hora (webhook)

Em Painel → API, cadastre uma URL https. Assim que o código chega, enviamos um POST para ela, sem você precisar consultar nada. Se a sua URL não responder 2xx, tentamos de novo depois de 5 s e de 30 s.

POST https://seu-sistema.com/nexo-webhook
Content-Type: application/json
X-Nexo-Event: sms.received
X-Nexo-Signature: sha256=<HMAC-SHA256 do corpo com o seu segredo whsec_...>

{ "event": "sms.received", "order": { "id": "9b1c…", "phone": "+5511987654321", "status": "received", "code": "482913", "sms": [ … ] } }

Valide a assinatura antes de usar o conteúdo. Exemplo completo no guia de integração com IA.

OpenAPI e IA

A especificação completa está em https://smsnexo.com/api/v1/openapi.json. Importe no ChatGPT (GPT personalizado), n8n, Make, Postman ou no seu agente. Passo a passo em Integrar com IA.

Status de uma ativação

  • waitingNúmero comprado, aguardando o SMS.
  • receivedCódigo recebido (campo code).
  • finishedConcluída por você.
  • cancelledCancelada; valor devolvido ao saldo.
  • expiredPrazo acabou sem SMS; valor devolvido ao saldo.

Exemplos

cURL

curl -X POST https://smsnexo.com/api/v1/orders \
  -H "Authorization: Bearer $NEXO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"wa","country":73}'

JavaScript (Node 18+)

const API = "https://smsnexo.com/api/v1";
const headers = { Authorization: "Bearer " + process.env.NEXO_KEY, "Content-Type": "application/json" };

// 1. compra
const { order } = await fetch(API + "/orders", { method: "POST", headers, body: JSON.stringify({ service: "wa", country: 73 }) }).then((r) => r.json());
console.log("Número:", order.phone);

// 2. espera o código
let code = null;
while (!code) {
  await new Promise((r) => setTimeout(r, 4000));
  const res = await fetch(API + "/orders/" + order.id, { headers }).then((r) => r.json());
  if (["cancelled", "expired"].includes(res.order.status)) break; // estornado automaticamente
  code = res.order.code;
}
console.log("Código:", code);

Python

import os, time, requests

API = "https://smsnexo.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['NEXO_KEY']}"}

order = requests.post(f"{API}/orders", json={"service": "wa", "country": 73}, headers=H).json()["order"]
print("Número:", order["phone"])

while True:
    time.sleep(4)
    o = requests.get(f"{API}/orders/{order['id']}", headers=H).json()["order"]
    if o["code"] or o["status"] in ("cancelled", "expired"):
        print("Código:", o["code"])
        break

Erros

Toda resposta de erro vem como { "error": { "code", "message" } }.

401unauthorizedChave ausente, inválida ou revogada.
402balanceSaldo insuficiente para a compra.
404unavailable / not_foundServiço, país ou ativação não encontrados.
409no_numbers / state / earlySem estoque agora, ou a ação não vale para o status atual.
429rate_limitedMais de 120 requisições (ou 60 compras) por minuto.
502providerFornecedor indisponível. O valor é devolvido automaticamente.

Limites

  • 120 requisições por minuto por chave; 60 compras por minuto por conta.
  • Até 5 chaves ativas por conta. Revogue no painel quando não usar mais.
  • Os preços seguem os do painel e podem mudar com o estoque; consulte /services antes de comprar.