Documentação da API do LocalSERP Proxy

Autenticação

Todas as solicitações, exceto as do catálogo público, exigem uma chave de API: Authorization: Bearer API_KEY. A chave é exibida completa uma única vez, quando você a cria: guarde-a como uma senha. Você pode revogar uma chave a qualquer momento; depois disso, as solicitações feitas com ela retornam 401 unauthorized.

curl -s "https://localserpproxy.com/api/v1/balance" \
  -H "Authorization: Bearer $API_KEY"

Solicitações e respostas

• JSON de entrada, JSON de saída: envie Content-Type: application/json com um corpo.
• Listas que podem crescer são paginadas com page (a partir de 1) e perPage (1–100, padrão 20) e retornam { "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }. Listas curtas retornam { "data": [...] }.
• IDs são strings opacas com um prefixo de tipo: ord_ (pedido), top_ (recarga), txn_ (movimentação de saldo), res_ (assinatura de tráfego), mob_ (porta móvel), key_ (chave de API) e ipw_ (entrada da lista de permissões de IP).
• Repetições seguras: POST /v1/orders e POST /v1/topups aceitam um cabeçalho Idempotency-Key (qualquer string exclusiva, mantida por 24 h). Reenviar a mesma chave retorna a primeira resposta, em vez de comprar ou recarregar duas vezes.
• Os exemplos mostram o formato de cada resposta: os IDs, IPs, valores e datas são ilustrativos; os IDs dos planos e os preços são reais.

Erros

Todos os erros têm o mesmo corpo. code é estável e destinado ao seu código; message é uma frase em inglês que pode mudar. Erros de validação listam cada campo inválido em fields. Novos códigos podem ser adicionados: trate códigos desconhecidos como uma falha genérica.

{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": [
      {
        "field": "amountUsd",
        "code": "too_small",
        "message": "The minimum top-up is 25.00 USD."
      }
    ],
    "requestId": "req_2b7c0f"
  }
}

Limites de requisições

Todas as respostas incluem RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Ao ultrapassar o limite, a API responde com 429 rate_limited e um cabeçalho Retry-After (em segundos): aguarde esse tempo e tente novamente. O IP de uma porta móvel pode ser alterado no máximo uma vez a cada 30 segundos (429 rotation_too_soon, com Retry-After).