# Documentação da API do LocalSERP Proxy

> API REST do LocalSERP Proxy em localserpproxy.com/api: chaves de API, erros, limites e endpoints para saldo, recargas, pedidos e proxies.

- URL: https://localserpproxy.com/pt/docs/api/
- Última atualização: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

Tudo o que você faz na sua conta pode ser automatizado por scripts: consultar o saldo, pagar com cripto, comprar um plano, criar credenciais de proxy e trocar um IP móvel. JSON por HTTPS, uma chave de API e exemplos em curl, Python e Node.js.

## Como usar a API do LocalSERP Proxy?

**Resposta rápida**

Envie solicitações HTTPS para `https://localserpproxy.com/api/v1` com sua chave de API no cabeçalho `Authorization: Bearer API_KEY`. Crie a chave na [página de desenvolvedor](https://localserpproxy.com/app/developer?lang=pt) da sua conta (ou com `POST /v1/api-keys`) e conceda apenas os escopos necessários. As solicitações e respostas são em JSON; os erros sempre retornam como `{ "error": { "code", "message" } }`.

## Visão geral

| Atributo | Valor |
| --- | --- |
| URL base | `https://localserpproxy.com/api/v1` |
| Formato | JSON via HTTPS, UTF-8 |
| Autenticação | Chave de API: `Authorization: Bearer API_KEY` |
| Escopos da chave de API | `read`, `proxies`, `billing` |
| Moeda | USD como texto com 2 casas decimais (`"29.00"`) |
| Valores em cripto | Strings decimais, nunca números de ponto flutuante (`"0.00045210"`) |
| Tráfego | Bytes (1 GB = 1.000.000.000 bytes) |
| Datas | ISO 8601 em UTC (`2026-10-05T14:03:11Z`) |
| Versão | `/v1` em todos os caminhos |

## 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`.

### Escopos

Conceda a cada chave apenas as permissões necessárias para o seu script. Uma chave sem o escopo exigido retorna `403 forbidden`.

| Escopo | O que permite |
| --- | --- |
| `read` | ler tudo (conta, saldo, serviços, uso). |
| `proxies` | alterar configurações e credenciais do proxy (rótulos, renovação automática, novas senhas), gerenciar subusuários, gerenciar a lista de permissões de IP e rotacionar portas móveis (inclui o link de rotação). |
| `billing` | criar pedidos e recargas, pagar com o saldo. |

A única exceção é o **link de rotação móvel**, feito para ser acessado por um favorito do navegador ou por um `curl` simples: `GET https://localserpproxy.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (chave com o escopo `proxies`). Consulte [Portas móveis e rotação de IP](https://localserpproxy.com/pt/docs/api/mobile/).

*Consultar seu saldo*

```bash
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.

*422 validation_failed*

```json
{
  "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"
  }
}
```

### Códigos de status

| Status | Significado |
| --- | --- |
| `422` | `validation_failed`: um ou mais campos são inválidos. |
| `401` | `unauthorized`: token ausente, inválido ou expirado. |
| `402` | `insufficient_balance`: o saldo não cobre o pedido. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: a chave da API não tem o escopo necessário ou a conta está suspensa. |
| `404` | `not_found`: o recurso não existe ou pertence a outra conta. |
| `409` | `conflict` (ou um código mais específico): a ação não é possível no estado atual. |
| `429` | `rate_limited` ou `rotation_too_soon`. |

## 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`).

## Referência da API

- **[Conta e saldo](https://localserpproxy.com/pt/docs/api/account/)** — Consulte as configurações da sua conta, seu saldo pré-pago em USD e todas as movimentações desse saldo (recargas, compras e reembolsos).
- **[Recargas com cripto](https://localserpproxy.com/pt/docs/api/top-ups/)** — Adicione saldo com cripto: obtenha o endereço de depósito e o valor exato, envie exatamente esse valor, informe que o pagamento foi enviado (o ID da transação é opcional) e acompanhe a recarga até o saldo ser creditado. O saldo pode ser usado para pagar qualquer um dos nossos planos.
- **[Pedidos](https://localserpproxy.com/pt/docs/api/orders/)** — Consulte os planos e seus preços, compre um plano usando o saldo (novo serviço, mais tráfego ou extensão de porta) e consulte seus pedidos anteriores.
- **[Proxies residenciais e credenciais](https://localserpproxy.com/pt/docs/api/residential/)** — Gerencie assinaturas de tráfego (residencial e 4G/5G rotativo por GB): credenciais de proxy, subusuários com credenciais próprias e limite de tráfego, uso diário e os locais que você pode segmentar no nome de usuário do proxy.
- **[Portas móveis e rotação de IP](https://localserpproxy.com/pt/docs/api/mobile/)** — Portas dedicadas 4G/5G: altere o IP agora ou programe a troca, use o link de rotação e consulte o tráfego diário.
- **[Chaves de API e lista de IPs permitidos](https://localserpproxy.com/pt/docs/api/api-keys/)** — Crie e revogue chaves de API com escopos limitados e gerencie a lista de IPs permitidos: até 10 IPs de origem podem usar os proxies sem nome de usuário e senha.

> **Pagamentos por script** Os planos são sempre pagos com o saldo pré-pago em USD. Adicione saldo com cripto (mínimo de 25.00 USD) usando POST /v1/topups e, em seguida, compre usando POST /v1/orders. As duas operações podem ser feitas em uma única chamada: a recarga pode incluir o pedido em purchase, e o plano é comprado assim que o saldo da recarga é creditado.

---

LocalSERP Proxy: LocalSERP Proxy é um serviço de proxy residencial dos Estados Unidos para verificar resultados de busca locais, anúncios e preços cidade por cidade, com pagamento em cripto e sem envio de documento de identidade.