Documentação técnica

API de proxy: gerencie seus IPs por código

REST simples em JSON para listar proxies, testar conexão, trocar IP com falha técnica e pedir renovação sem abrir o painel. Autenticação por token com escopo de leitura ou escrita — o mesmo que move o botão “Testar” do painel, exposto para o seu script.

Criar conta e gerar chave Ver endpoints

Base URL

proxybox.com.br

Autenticação

Bearer token

Rate limit

60/min leitura

Formato

JSON

Para quem é essa API

Não substitui o painel — é para quando você quer o mesmo dado ou ação sem clicar.

Monitoramento próprio

Puxar status e vigência dos proxies para o seu Zabbix, Grafana ou script de cron, sem entrar no painel toda hora.

Automação com n8n

Disparar o teste de conexão antes de abrir uma sessão de automação e abortar o fluxo se o IP não responder.

Agências com muitos IPs

Listar todos os proxies da conta e cruzar com a sua própria planilha ou CRM, em vez de exportar manualmente.

Aviso de renovação

Checar days_to_expire por código e abrir o link de checkout automaticamente quando um IP estiver perto do fim.

Autenticação

Toda chamada leva um Bearer token no cabeçalho Authorization. Gere a chave em Minha conta → API Keys; o segredo aparece uma única vez, guardamos só o hash.

read Lista e consulta proxies. Não testa, não troca nem pede renovação.

write Inclui tudo do read, mais testar conexão, troca técnica (depois do diagnóstico) e pedir renovação.

Guardamos só o hash SHA-256 — o segredo em texto puro não fica em lugar nenhum além da tela em que você o copiou.
Até 10 chaves ativas por conta. Revogue a qualquer momento sem afetar as outras.
Rate limit contado por chave — outra chave sua, ou de outra conta no mesmo IP, não divide a sua cota.

Cabeçalho obrigatório

Authorization: Bearer pb_a1b2c3_9f8e7d6c5b4a3f2e1d0c...

Exemplo de erro (401)

{
  "error": "unauthenticated",
  "message": "Envie o header Authorization: Bearer <sua chave>."
}

Comece em 1 minuto

Listar os seus proxies — a chamada mais simples, na linguagem que você já usa.

curl "https://proxybox.com.br/api/v1/proxies" \
  -H "Authorization: Bearer pb_a1b2c3_..." \
  -H "Accept: application/json"

import requests

r = requests.get(
    "https://proxybox.com.br/api/v1/proxies",
    headers={"Authorization": "Bearer pb_a1b2c3_..."},
)
print(r.json())

const res = await fetch("https://proxybox.com.br/api/v1/proxies", {
  headers: { Authorization: "Bearer pb_a1b2c3_..." },
});
const { data } = await res.json();
console.log(data);

$ch = curl_init("https://proxybox.com.br/api/v1/proxies");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer pb_a1b2c3_...",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);

Endpoints

Cinco rotas. Sem paginação de credenciais expostas por acidente: a senha só aparece na consulta de 1 proxy específico.

GET /proxies read

Lista os proxies da conta, paginados. Os campos de credencial (senha, string de conexão) não vêm aqui — só em GET /proxies/{id}.

status opcional — filtra pelo status exato (ex: active)

per_page opcional — padrão 25, máximo 100

{
  "data": [
    {
      "id": 42,
      "label": "IPv4 Ads",
      "status": "active",
      "type": "ipv4",
      "country": "BR",
      "host": "br1.proxybox.io",
      "http_port": 8080,
      "socks5_port": 1080,
      "username": "pb_9f2a1c",
      "plan": "IPv4 Brasil",
      "is_trial": false,
      "expires_at": "2026-11-10T00:00:00+00:00",
      "days_to_expire": 30,
      "can_renew": true,
      "can_replace": true
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1 }
}

GET /proxies/{id} read

Detalhe de um proxy, incluindo password e connection_string prontos para colar na sua ferramenta.

Proxy de outra conta ou ID inexistente devolvem a mesma resposta 404 — de propósito, para não confirmar se um ID existe quando não é seu.

{
  "data": {
    "id": 42,
    "label": "IPv4 Ads",
    "status": "active",
    "...": "...",
    "password": "S3nh4Gerada",
    "connection_string": "http://pb_9f2a1c:[email protected]:8080"
  }
}

POST /proxies/{id}/test write

Dispara uma conexão HTTPS real pelo proxy e devolve IP de saída, operadora e latência — o mesmo teste do botão “Testar” no painel. O resultado fica registrado no histórico do proxy.

Responde 200 quando o teste passa e 422 quando falha — o corpo muda de formato, não é erro de chamada.

// 200 — sucesso
{
  "data": {
    "ok": true,
    "ip": "191.96.10.42",
    "country": "Brazil",
    "city": "São Paulo",
    "asn": "AS262589",
    "org": "Operadora XY",
    "latency_ms": 148,
    "checked_at": "10/09/2026 14:32"
  }
}

// 422 — falha
{
  "data": {
    "ok": false,
    "error": "Autenticação recusada (407)",
    "hint": "Usuário ou senha não conferem."
  }
}

POST /proxies/{id}/replace write

O mesmo fluxo do botão Não funciona no painel: testa o túnel e só recompra o IP se a falha for técnica (timeout, host mudo, 407 com a senha do painel). Proxy no ar, verificador fora ou plano por GB não geram troca — a resposta diz o que fazer.

200 quando o diagnóstico conclui (incluindo “está no ar” ou “IP substituído”). 422 quando não dá para trocar agora. Ban de plataforma continua fora desta rota.

// 200 — substituído
{
  "data": {
    "ok": true,
    "action": "replaced",
    "message": "IP substituído. A vigência original foi mantida.",
    "replaced_id": 42,
    "proxy": { "id": 87, "host": "br2.proxybox.io", "...": "..." }
  }
}

// 200 — está no ar (não troca)
{
  "data": {
    "ok": true,
    "action": "healthy",
    "message": "O proxy está no ar."
  }
}

// 422 — verificador ou cota
{
  "data": {
    "ok": false,
    "action": "retry",
    "message": "O verificador não respondeu"
  }
}

POST /proxies/{id}/renew write

Não cobra cartão. Devolve o link de checkout do plano do proxy para você (ou o seu fluxo de automação) concluir o pagamento. A API não guarda dados de cartão nem PIX na v1.

Elegibilidade: proxy precisa estar ativo, ter plano vigente e não ser trial.

// 200 — elegível
{
  "data": {
    "proxy_id": 42,
    "sku": "ipv4-br-30d",
    "checkout_url": "https://proxybox.com.br/checkout/ipv4-br-30d",
    "message": "Abra o checkout para concluir o pagamento."
  }
}

// 422 — não elegível
{
  "error": "not_renewable",
  "message": "Este proxy não está elegível para renovação
    (precisa estar ativo, com plano vigente e não ser trial)."
}

Erros e limites

Todo erro vem em JSON, com o mesmo status HTTP que a chamada equivalente pelo painel geraria.

Status	Quando acontece	Corpo
401	Sem token, ou token inválido/revogado	{"error":"unauthenticated","message":"..."}
403	Chave read tentando endpoint write	{"error":"forbidden","message":"..."}
404	Proxy não existe ou não é da sua conta	{"error":"not_found","message":"..."}
422	Teste falhou, troca recusada ou renovação inelegível	{"ok":false,...} ou {"error":"not_renewable",...}
429	Rate limit da chave estourado	{"message":"Too Many Attempts."}

A resposta 429 também traz os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e Retry-After em segundos.

Perguntas sobre a API

A API tem custo além do plano?

Não. Está incluída em qualquer conta com proxy ativo — não é um plano ou add-on separado.

Dá para comprar um proxy novo pela API?

Não na v1. A API gerencia o que você já tem (listar, testar, trocar por falha técnica, renovar). Compra de plano novo continua pelo checkout do site — o /renew devolve o link, não cobra direto. O /replace só recompra se o teste técnico falhar.

Como vocês guardam minha chave?

Só o hash SHA-256. O valor em texto puro existe uma única vez, na tela em que você gera a chave. Se perder, revogue e gere outra — não recuperamos o valor original.

O rate limit é por chave ou por IP?

Por chave. Gerar uma segunda chave não soma cota com a primeira nem depende do seu IP — cada uma tem o próprio limite de 60 req/min em leitura e 20 em escrita.

A API substitui o painel?

Não. Ela cobre automação e monitoramento. Pagamento, tickets de suporte e configuração de conta continuam no painel.

Tem SDK ou biblioteca oficial?

Ainda não. É REST simples em JSON com Bearer token — qualquer cliente HTTP resolve, como nos exemplos acima.

Posso revogar uma chave comprometida na hora?

Sim, em Minha conta → API Keys. A revogação é imediata; a próxima chamada com aquele token já recebe 401.

Pronto para automatizar?

A chave é gerada no painel em menos de um minuto. Escopo read para monitorar, write quando precisar agir.

Criar conta e gerar chave Ver guias de configuração Tirar dúvida técnica