Referência da API

Compre números virtuais e receba códigos SMS programaticamente. URL base: http://127.0.0.1:4178/api/v1

Autenticação

Toda requisição deve incluir sua chave de API no header Authorization. Chaves são criadas e revogadas na sua página de perfil.

Authorization: Bearer sk_live_XXXXXXXXXXXXXXXXXXXXXXXX

Todas as respostas são em JSON. Erros seguem este formato:

{ "error": { "code": "SMS_INSUFFICIENT_BALANCE", "message": "Insufficient balance for this purchase" } }

Códigos de erro comuns: INVALID_API_KEY, API_KEY_REVOKED, INVALID_INPUT, INVALID_SERVER_ID, SMS_NUMBER_UNAVAILABLE, SMS_INSUFFICIENT_BALANCE, SMS_ORDER_NOT_FOUND, SMS_NOT_CANCELLABLE, SMS_PROVIDER_ERROR.

GET /balance

Retorna o saldo atual da sua conta em BRL e USD.

curl -H "Authorization: Bearer sk_live_..." \
  http://127.0.0.1:4178/api/v1/balance

{ "balanceBRL": 124.97, "balanceUSD": 0 }

GET /services

Lista todos os serviços SMS disponíveis (WhatsApp, Telegram, Facebook etc) com preços agregados.

curl -H "Authorization: Bearer sk_live_..." \
  http://127.0.0.1:4178/api/v1/services

{
  "services": [
    {
      "slug": "whatsapp",
      "name": "WhatsApp",
      "category": "messaging",
      "brandColor": "#25D366",
      "lowestPriceBRL": 0.75,
      "lowestPriceUSD": 0.15,
      "countryCount": 48,
      "totalStock": 12400
    }
  ]
}

GET /services/{slug}/countries

Países onde um dado serviço está disponível.

curl -H "Authorization: Bearer sk_live_..." \
  http://127.0.0.1:4178/api/v1/services/whatsapp/countries

{
  "countries": [
    { "isoCode": "BR", "name": "Brazil", "flagEmoji": "🇧🇷", "bestPriceBRL": 1.20, "totalStock": 5400, "offerCount": 6 },
    { "isoCode": "IN", "name": "India", "flagEmoji": "🇮🇳", "bestPriceBRL": 0.75, "totalStock": 8900, "offerCount": 4 }
  ]
}

GET /services/{slug}/offers?country={iso}

Ofertas detalhadas para serviço e país — uma por combinação de servidor/operadora/DDD.

curl -H "Authorization: Bearer sk_live_..." \
  "http://127.0.0.1:4178/api/v1/services/whatsapp/offers?country=BR"

{
  "offers": [
    {
      "serverId": "srv_a1b2c3d4",
      "serverLabel": "Server 1",
      "country": "BR",
      "countryName": "Brazil",
      "countryFlag": "🇧🇷",
      "operator": null,
      "operatorCode": null,
      "areaCodeSupported": false,
      "priceBRL": 1.20,
      "priceUSD": 0.24,
      "stock": 1200
    },
    {
      "serverId": "srv_a1b2c3d4",
      "serverLabel": "Server 1",
      "country": "BR",
      "operator": "Vivo",
      "operatorCode": "vivo",
      "areaCodeSupported": true,
      "priceBRL": 1.35,
      "priceUSD": 0.27,
      "stock": 340
    }
  ]
}

serverId: Identificador opaco e estável de um servidor. Use ao criar pedidos.
operator / operatorCode: Filtro opcional de operadora. Passe operatorCode em POST /orders para forçar uma operadora específica.
areaCodeSupported: Se true, você pode passar areaCode (DDD) no corpo do pedido para filtrar. Disponível atualmente para números brasileiros em servidores selecionados.
stock: Quantidade aproximada de números disponíveis nesta oferta.

GET /servers/{serverId}/operators?country={iso}

Lista operadoras reais para um servidor+país (quando suportado). Use o code retornado como operator ao criar pedido.

curl -H "Authorization: Bearer sk_live_..." \
  "http://127.0.0.1:4178/api/v1/servers/srv_a1b2c3d4/operators?country=BR"

{
  "operators": [
    { "code": "tim", "name": "TIM" },
    { "code": "vivo", "name": "Vivo" },
    { "code": "claro", "name": "Claro" }
  ]
}

POST /orders

Compre um número virtual. O saldo é debitado imediatamente em BRL.

curl -X POST -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "service": "whatsapp",
    "country": "BR",
    "serverId": "srv_a1b2c3d4",
    "operator": "vivo",
    "areaCode": "11"
  }' \
  http://127.0.0.1:4178/api/v1/orders

service: Slug unificado do serviço, obtido em GET /services.
country: Código ISO 3166-1 alpha-2 do país.
serverId: Identificador de servidor obtido em GET /services/{slug}/offers.
operator: Opcional. Código de operadora obtido em /operators.
areaCode: Opcional. DDD (ex: "11" para São Paulo) — só é aplicado quando a oferta tem areaCodeSupported: true.
idempotencyKey: Opcional. Se fornecido, duas chamadas com a mesma chave da mesma conta retornam o mesmo pedido sem criar duplicata.

{
  "order": {
    "id": "ord_abc123xyz456",
    "status": "PENDING",
    "service": "whatsapp",
    "country": "BR",
    "phoneNumber": "5511987654321",
    "smsCode": null,
    "priceBRL": 1.35,
    "priceUSD": 0.27,
    "serverId": "srv_a1b2c3d4",
    "createdAt": "2026-04-14T03:30:00Z",
    "expiresAt": "2026-04-14T03:50:00Z",
    "canResend": true,
    "minCancelSeconds": 120
  }
}

Retorna 402 SMS_INSUFFICIENT_BALANCE se você não tem BRL suficiente. Recarregue em /recharge.

GET /orders/{id}

Busca o status atual de um pedido. Ao fazer polling, este endpoint também avança o pedido para EXPIRED (com reembolso) se a janela de 20 minutos passou.

curl -H "Authorization: Bearer sk_live_..." \
  http://127.0.0.1:4178/api/v1/orders/ord_abc123xyz456

Status possíveis: PENDING, RECEIVED, CANCELLED, EXPIRED, REPLACED.

POST /orders/{id}/cancel

Cancela um pedido pendente e reembolsa o custo em BRL. Mínimo de 2 minutos após a criação.

curl -X POST -H "Authorization: Bearer sk_live_..." \
  http://127.0.0.1:4178/api/v1/orders/ord_abc123xyz456/cancel

{ "success": true, "refundedBRL": 1.35, "newBalanceBRL": 123.62 }

POST /orders/{id}/replace

Troca um pedido pendente por um número novo sem custo extra — o pagamento original rola para o novo pedido. Útil quando o primeiro número não recebe o SMS. Mesma espera mínima de 2 minutos.

curl -X POST -H "Authorization: Bearer sk_live_..." \
  http://127.0.0.1:4178/api/v1/orders/ord_abc123xyz456/replace

O pedido antigo vai para REPLACED e um novo pedido com priceBRL: 0 é retornado. Se a compra de substituição falhar no provedor, o custo original é reembolsado no seu saldo.

POST /orders/{id}/resend

Solicita um novo SMS para o mesmo número (só disponível se a flag canResend do pedido for true).

curl -X POST -H "Authorization: Bearer sk_live_..." \
  http://127.0.0.1:4178/api/v1/orders/ord_abc123xyz456/resend

POST /orders/{id}/complete

Marca o pedido como finalizado explicitamente no provedor. Útil para liberar o número mais cedo.

curl -X POST -H "Authorization: Bearer sk_live_..." \
  http://127.0.0.1:4178/api/v1/orders/ord_abc123xyz456/complete

GET /orders

Lista seus pedidos com paginação. Filtre por status com ?status=PENDING.

curl -H "Authorization: Bearer sk_live_..." \
  "http://127.0.0.1:4178/api/v1/orders?status=RECEIVED&page=1&limit=50"

Webhooks

Em vez de fazer polling em GET /orders/{id}, configure uma URL de webhook ao criar sua chave de API. A gente faz POST nela no instante em que o SMS chega.

POST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-Signature: sha256=<hmac-sha256 of body>

{
  "event": "sms.received",
  "order": {
    "id": "ord_abc123xyz456",
    "phoneNumber": "5511987654321",
    "smsCode": "123456",
    "smsText": "Your WhatsApp code: 123456",
    "service": "whatsapp",
    "country": "BR",
    "serverId": "srv_a1b2c3d4"
  },
  "timestamp": 1776140000
}

Verifique a assinatura no servidor usando o webhook signing secret mostrado ao criar a chave:

jsimport crypto from 'crypto'

function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
}

Fazemos retry de entregas falhadas 3 vezes (backoff 1s, 5s, 30s). Seu endpoint deve responder 200 rapidamente e processar async. Handlers devem ser idempotentes — entregas duplicadas podem acontecer.

Boas práticas

Use Idempotency-Key em POST /orders para que retentativas não comprem em dobro.
Prefira webhooks em vez de polling para integrações de alto volume.
Trate SMS_INSUFFICIENT_BALANCE (402) recarregando e tentando de novo.
Para números brasileiros, inspecione areaCodeSupported antes de passar areaCode.
Chaves de API são secretas — nunca commite. Rotacione regularmente.