Documentação da API

Esta documentação descreve a API REST para revendedores. Use-a para integrar compra de números SMS, consulta de status e gestão de pedidos. Todos os endpoints exigem autenticação via API key.

Base URL: https://api.seusite.com

Autenticação

Envie sua API key em todas as requisições. Aceita dois formatos:

Authorization: Bearer rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Nunca exponha sua API key em repositórios públicos ou no frontend. Use variáveis de ambiente.

Saldo

GET/api/reseller/me

Retorna dados da conta, saldo disponível e bloqueado, limites e configurações.

Exemplo de resposta

{
  "id": "clx...",
  "name": "Revendedor",
  "email": "[email protected]",
  "status": "ACTIVE",
  "balance": 150.50,
  "lockedBalance": 0,
  "currency": "BRL",
  "rateLimitRpm": 60,
  "lowBalanceThreshold": 10
}

cURL

curl -X GET "https://api.seusite.com/api/reseller/me" \
  -H "Authorization: Bearer rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

JavaScript

const res = await fetch('https://api.seusite.com/api/reseller/me', {
  headers: { 'Authorization': 'Bearer ' + apiKey }
});
const data = await res.json();

PHP

$ch = curl_init('https://api.seusite.com/api/reseller/me');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);

GET/api/reseller/balance

Retorna apenas saldo disponível, bloqueado e moeda.

Exemplo de resposta

{
  "balance": 150.50,
  "lockedBalance": 0,
  "currency": "BRL"
}

cURL

curl -X GET "https://api.seusite.com/api/reseller/balance" \
  -H "X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Serviços

GET/api/reseller/services

Lista serviços disponíveis para um país. Use o parâmetro q para filtrar por nome.

Query parameters

countryobrigatório— Código do país (ex: brazil, russia)
q— Busca por nome ou ID do serviço

Exemplo de resposta

{
  "services": [
    { "id": "whatsapp", "name": "WhatsApp" },
    { "id": "telegram", "name": "Telegram" }
  ]
}

cURL

curl -X GET "https://api.seusite.com/api/reseller/services?country=brazil&q=whatsapp" \
  -H "X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Ofertas

GET/api/reseller/service-offers

Lista ofertas/modalidades disponíveis para um serviço e país. Use o offerId retornado ao criar o pedido.

Query parameters

countryobrigatório— Código do país
serviceobrigatório— ID do serviço canônico (ex: whatsapp)

Exemplo de resposta

{
  "offers": [
    {
      "offerId": "provider1::whatsapp::default",
      "providerId": "provider1",
      "providerName": "Provedor 1",
      "providerServiceId": "whatsapp",
      "variantId": "default",
      "label": "Padrão",
      "priceUsd": 0.15,
      "priceBrl": 0.90,
      "available": true
    }
  ]
}

cURL

curl -X GET "https://api.seusite.com/api/reseller/service-offers?country=brazil&service=whatsapp" \
  -H "Authorization: Bearer rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Pedidos

POST/api/reseller/orders

Cria um pedido de número SMS. O saldo é debitado imediatamente. Use /orders/:id/status para obter o código.

Body (JSON)

countryobrigatório— Código do país
serviceId— ID do serviço (alternativa: canonicalServiceId ou service)
canonicalServiceId— ID canônico do serviço
offerId— ID da oferta (de service-offers). Se omitido, usa a mais barata
providerId— ID do provedor preferido
variantId— ID da variante

Exemplo de resposta

{
  "id": "clx...",
  "status": "WAITING_CODE",
  "service": "whatsapp",
  "country": "brazil",
  "provider": "Provedor 1",
  "phoneNumber": "+5511999999999",
  "salePrice": 0.90
}

cURL

curl -X POST "https://api.seusite.com/api/reseller/orders" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"country":"brazil","canonicalServiceId":"whatsapp","offerId":"provider1::whatsapp::default"}'

JavaScript

const order = await fetch('https://api.seusite.com/api/reseller/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + apiKey
  },
  body: JSON.stringify({
    country: 'brazil',
    canonicalServiceId: 'whatsapp',
    offerId: 'provider1::whatsapp::default'
  })
}).then(r => r.json());

PHP

$ch = curl_init('https://api.seusite.com/api/reseller/orders');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'country' => 'brazil',
  'canonicalServiceId' => 'whatsapp',
  'offerId' => 'provider1::whatsapp::default'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'Authorization: Bearer ' . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$order = json_decode(curl_exec($ch), true);

GET/api/reseller/orders

Lista pedidos com paginação.

Query parameters

page— Página (padrão 1)
limit— Itens por página (padrão 20, máx 100)

Exemplo de resposta

{
  "items": [...],
  "total": 42,
  "page": 1,
  "totalPages": 3
}

cURL

curl -X GET "https://api.seusite.com/api/reseller/orders?page=1&limit=20" \
  -H "X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET/api/reseller/orders/:id

Retorna detalhes de um pedido específico.

Exemplo de resposta

{
  "id": "clx...",
  "status": "COMPLETED",
  "service": "whatsapp",
  "phoneNumber": "+5511999999999",
  "code": "123456",
  "salePrice": 0.90,
  "smsReceived": true
}

cURL

curl -X GET "https://api.seusite.com/api/reseller/orders/clx123/..." \
  -H "X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET/api/reseller/orders/:id/status

Consulta status e código SMS. Faça polling a cada 5–10 segundos até receber o código ou status final.

Exemplo de resposta

{
  "id": "clx...",
  "status": "COMPLETED",
  "code": "123456",
  "smsReceived": true,
  "error": null
}

cURL

curl -X GET "https://api.seusite.com/api/reseller/orders/clx123/status" \
  -H "X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Cancelamento e refund

POST/api/reseller/orders/:id/cancel

Cancela um pedido em WAITING_CODE. Se o provedor aceitar, o saldo é reembolsado automaticamente.

Exemplo de resposta

{
  "success": true,
  "refunded": 0.90,
  "message": "Cancelado com sucesso"
}

cURL

curl -X POST "https://api.seusite.com/api/reseller/orders/clx123/cancel" \
  -H "X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Transações

GET/api/reseller/transactions

Histórico financeiro da carteira (créditos, débitos, reembolsos).

Query parameters

page— Página
limit— Itens por página

Exemplo de resposta

{
  "items": [
    {
      "type": "DEBIT",
      "amount": -0.90,
      "balanceBefore": 100,
      "balanceAfter": 99.10,
      "description": "Compra API reseller whatsapp"
    }
  ],
  "total": 50,
  "page": 1,
  "totalPages": 3
}

cURL

curl -X GET "https://api.seusite.com/api/reseller/transactions" \
  -H "X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Códigos de erro

Status	Significado
400	Requisição inválida (parâmetros, oferta inexistente, etc.)
401	API key inválida ou revendedor inativo
402	Saldo insuficiente
403	IP não autorizado (quando whitelist ativa)
404	Recurso não encontrado
429	Rate limit excedido
500	Erro interno do servidor

Respostas de erro incluem { "error": "mensagem" }.

Exemplos completos

Fluxo típico: listar ofertas → criar pedido → fazer polling do status até receber o código.

# 1. Listar ofertas
curl -X GET "https://api.seusite.com/api/reseller/service-offers?country=brazil&service=whatsapp" \
  -H "X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 2. Criar pedido
curl -X POST "https://api.seusite.com/api/reseller/orders" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"country":"brazil","canonicalServiceId":"whatsapp"}'

# 3. Consultar status (repetir até status=COMPLETED)
curl -X GET "https://api.seusite.com/api/reseller/orders/{ORDER_ID}/status" \
  -H "X-API-Key: rsl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Fluxo recomendado

Obter API key no painel do revendedor
Consultar /services e /service-offers para o país/serviço desejado
Criar pedido com POST /orders (country, serviceId, offerId opcional)
Fazer polling em GET /orders/:id/status a cada 5–10 segundos
Quando status=COMPLETED, usar o campo code
Se o usuário desistir antes do código, chamar POST /orders/:id/cancel

Boas práticas

Armazene a API key em variáveis de ambiente, nunca no código
Use X-Request-Id para rastrear requisições em caso de suporte
Implemente retry com backoff em erros 5xx ou de rede
Respeite o rate limit; use os headers X-RateLimit-Remaining para monitorar
Trate 402 (saldo insuficiente) com mensagem clara ao usuário

Limites e rate limit

Rate limit: Requisições por minuto (RPM) configurável por revendedor. Padrão: 60 RPM.
Headers: X-RateLimit-Limit e X-RateLimit-Remaining em cada resposta.
IP whitelist: Opcional por API key; quando ativa, apenas IPs cadastrados podem acessar.

Começar integração