# Documentação da API AfricaProxies

> API REST AfricaProxies em africaproxies.com/api: chaves API, erros, limites e endpoints para saldo, cripto, encomendas, proxies e rotação IP móvel.

- URL: https://africaproxies.com/pt/docs/api/
- Última atualização: 2026-10-15
- Editor: AfricaProxies (https://africaproxies.com)

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

**Resposta rápida — Como utilizo a API AfricaProxies?**

Envie pedidos HTTPS para `https://africaproxies.com/api/v1` com a sua chave API no cabeçalho `Authorization: Bearer API_KEY`. Crie a chave na [página de programador](/app/developer?lang=pt) da sua conta (ou com `POST /v1/api-keys`) e atribua apenas as permissões necessárias. Pedidos e respostas são JSON; os erros são sempre devolvidos como `{ "error": { "code", "message" } }`.

## Visão geral

| Atributo | Valor |
| --- | --- |
| URL base | `https://africaproxies.com/api/v1` |
| Formato | JSON por HTTPS, UTF-8 |
| Autenticação | Chave API: `Authorization: Bearer API_KEY` |
| Permissões das chaves API | `read`, `proxies`, `billing` |
| Valores monetários | USD como cadeia com 2 casas decimais (`"29.00"`) |
| Montantes em cripto | Cadeias decimais, nunca valores de vírgula 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

Todos os pedidos, exceto o catálogo público, incluem uma chave API: `Authorization: Bearer API_KEY`. A chave é mostrada na íntegra **uma vez**, quando a cria: guarde-a como uma palavra-passe. Revogue uma chave a qualquer momento; os pedidos efetuados com ela passam a devolver `401 unauthorized`.

### Permissões

Dê a cada chave apenas o que o seu script necessita. Uma chave sem a permissão necessária recebe `403 forbidden`.

| Permissão | O que permite |
| --- | --- |
| `read` | ler tudo (conta, saldo, serviços, utilização). |
| `proxies` | alterar definições e credenciais de proxy (nomes, renovação automática, novas palavras-passe), gerir subutilizadores, gerir a lista de IP permitidos e rodar portas móveis (inclui a ligação de rotação). |
| `billing` | criar encomendas e carregamentos, pagar com o saldo. |

A única exceção é a **ligação de rotação móvel**, concebida para ser chamada a partir de um marcador do navegador ou de um simples `curl`: `GET https://africaproxies.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (chave com a permissão `proxies`). Consulte [Portas móveis e rotação IP](/pt/docs/api/mobile/).

*Consultar o saldo*

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

## Pedidos e respostas

- **JSON na entrada, JSON na saída**: envie `Content-Type: application/json` quando incluir um corpo.
- **Listas** que podem crescer são paginadas com `page` (a partir de 1) e `perPage` (1–100, predefinição 20) e devolvem `{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }`. Listas curtas devolvem `{ "data": [...] }`.
- **Identificadores** são cadeias opacas com um prefixo de tipo: `ord_` (encomenda), `top_` (carregamento), `txn_` (movimento do saldo), `res_` (subscrição de tráfego), `mob_` (porta móvel), `key_` (chave API) e `ipw_` (entrada da lista de IP permitidos).
- **Repetições seguras**: `POST /v1/orders` e `POST /v1/topups` aceitam um cabeçalho `Idempotency-Key` (qualquer cadeia única, conservada durante 24 h). Repetir a mesma chave devolve a primeira resposta em vez de comprar ou carregar duas vezes.
- **Os exemplos** mostram a estrutura de cada resposta: identificadores, endereços, montantes e datas são ilustrativos; os identificadores dos planos e os preços são reais.

## Erros

Todos os erros têm o mesmo corpo. `code` é estável e destina-se ao seu código; `message` é uma frase em inglês que pode mudar. Os erros de validação enumeram cada campo inválido em `fields`. Podem ser acrescentados novos códigos: trate os 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 estado

| Estado | 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 a encomenda. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: a chave API não tem a permissão necessária 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 pedidos

Cada resposta inclui `RateLimit-Limit`, `RateLimit-Remaining` e `RateLimit-Reset`. Acima do limite, a API responde `429 rate_limited` com um cabeçalho `Retry-After` (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](/pt/docs/api/account/)** — Consulte as definições da conta, o saldo pré-pago em USD e todos os movimentos desse saldo (carregamentos, compras, reembolsos).
- **[Carregamentos em cripto](/pt/docs/api/top-ups/)** — Carregue o saldo em cripto: obtenha o endereço de depósito e o montante exato, envie exatamente esse montante, assinale o pagamento como enviado (o ID da transação é opcional) e acompanhe o carregamento até o saldo ser creditado. O saldo paga qualquer um dos nossos planos.
- **[Encomendas](/pt/docs/api/orders/)** — Liste os planos e os preços, compre um plano com o saldo (novo serviço, mais tráfego ou prolongamento de uma porta) e consulte encomendas anteriores.
- **[Proxies residenciais e credenciais](/pt/docs/api/residential/)** — Gira subscrições de tráfego (residencial e 4G/5G rotativo por GB): credenciais de proxy, subutilizadores com credenciais e limite de tráfego próprios, utilização diária e locais selecionáveis no nome de utilizador do proxy.
- **[Portas móveis e rotação IP](/pt/docs/api/mobile/)** — Portas 4G/5G dedicadas: altere o IP agora ou por temporizador, utilize a ligação de rotação e consulte o tráfego diário.
- **[Chaves API e lista de IP permitidos](/pt/docs/api/api-keys/)** — Crie e revogue chaves API com permissões limitadas e gira a lista de IP permitidos: até 10 endereços de origem podem usar os proxies sem nome de utilizador nem palavra-passe.

> **Pagar a partir de um script** Os planos são sempre pagos com o saldo pré-pago em USD. Carregue em cripto (mínimo US$ 25) com POST /v1/topups, depois compre com POST /v1/orders. Pode combinar ambos numa chamada: um carregamento pode incluir a encomenda em purchase, e o plano é comprado assim que o carregamento é creditado.

---

AfricaProxies: AfricaProxies é um fornecedor de proxies residenciais para a África Subsaariana, com pagamento em cripto e sem envio de documento de identificação.