Pedidos

Compre e gerencie pedidos de número virtual pela API.

Ciclo de vida do pedido

PROCESSING → ACTIVE → COMPLETED

ACTIVE → CANCELLED | EXPIRED | FAILED

PROCESSING — o número está sendo comprado no fornecedor
ACTIVE — número pronto, aguardando o SMS
COMPLETED — encerrado com /finish depois do SMS
CANCELLED — cancelado com /cancel
EXPIRED — o prazo do número venceu
FAILED — o fornecedor não entregou o número

Criar pedido

POST /api/v1/orders

{
  "countryId": "clxxx...",
  "serviceId": "clxxx..."
}

Os IDs vêm das listas de /countries e /services. Cada pedido compra um número.

Resposta

JSON

{
  "success": true,
  "data": {
    "id": "clxxx...",
    "status": "ACTIVE",
    "phoneNumber": "+5511999999999",
    "sellPrice": 3.5,
    "expiresAt": "2026-07-05T15:30:00.000Z",
    "country": { "code": "BR", "name": "Brasil", "flag": "🇧🇷" },
    "service": { "slug": "whatsapp", "name": "WhatsApp" }
  }
}

Cancelar ou encerrar

cURL

# Cancela um pedido que ainda não recebeu SMS — estorno integral
POST /api/v1/orders/{id}/cancel

# Encerra depois de receber o SMS
POST /api/v1/orders/{id}/finish

Estornos

Número que não entregou código não é serviço prestado, então o valor inteiro volta para a carteira automaticamente:

Cancelado sem SMS — estornado quando você chama /cancel.
Expirado sem SMS — estornado automaticamente quando o número vence. Não precisa chamar nada.
Falha do fornecedor — estornado, e o pedido fica como FAILED.

Assim que qualquer SMS chega, o número conta como entregue e não há estorno. Cancelar um pedido nesse estado é recusado com 400 — encerre com /finish. Todo estorno aparece como uma transação REFUND no histórico da carteira.

Limites de requisição

Cada chave de API permite 120 requisições por minuto, e a criação de pedidos tem teto de 20 por minuto por conta — o painel e a API dividem esse limite. Passar do limite devolve 429 com Retry-After, X-RateLimit-Limit e X-RateLimit-Remaining, para você saber exatamente quanto esperar.