# Documentación de la API AfricaProxies

> API REST AfricaProxies en africaproxies.com/api: claves API, errores, límites y endpoints de saldo, cripto, pedidos, proxies y rotación IP móvil.

- URL: https://africaproxies.com/es/docs/api/
- Última actualización: 2026-10-15
- Editor: AfricaProxies (https://africaproxies.com)

Todo lo que haces en tu cuenta puede automatizarse con scripts: consultar el saldo, recargar con criptomonedas, comprar un plan, crear credenciales de proxy y rotar una IP móvil. JSON mediante HTTPS, una clave API y ejemplos en curl, Python y Node.js.

**Respuesta rápida — ¿Cómo uso la API AfricaProxies?**

Envía solicitudes HTTPS a `https://africaproxies.com/api/v1` con tu clave API en la cabecera `Authorization: Bearer API_KEY`. Crea la clave en la [página de desarrollador](/app/developer?lang=es) de tu cuenta (o con `POST /v1/api-keys`) y asigna solo los permisos necesarios. Las solicitudes y respuestas son JSON; los errores siempre se devuelven como `{ "error": { "code", "message" } }`.

## De un vistazo

| Atributo | Valor |
| --- | --- |
| URL base | `https://africaproxies.com/api/v1` |
| Formato | JSON mediante HTTPS, UTF-8 |
| Autenticación | Clave API: `Authorization: Bearer API_KEY` |
| Permisos de las claves API | `read`, `proxies`, `billing` |
| Valores monetarios | USD como cadena con 2 decimales (`"29.00"`) |
| Importes en criptomonedas | Cadenas decimales, nunca números de coma flotante (`"0.00045210"`) |
| Tráfico | Bytes (1 GB = 1,000,000,000 bytes) |
| Fechas | ISO 8601 en UTC (`2026-10-05T14:03:11Z`) |
| Versión | `/v1` en todas las rutas |

## Autenticación

Todas las solicitudes, salvo el catálogo público, incluyen una clave API: `Authorization: Bearer API_KEY`. La clave se muestra completa **una vez**, al crearla: guárdala como una contraseña. Revoca una clave en cualquier momento; las solicitudes realizadas con ella pasarán a devolver `401 unauthorized`.

### Permisos

Asigna a cada clave solo lo que necesite tu script. Una clave sin el permiso necesario recibe `403 forbidden`.

| Permiso | Qué permite |
| --- | --- |
| `read` | leer todo (cuenta, saldo, servicios, uso). |
| `proxies` | cambiar ajustes y credenciales de proxy (nombres, renovación automática, nuevas contraseñas), gestionar subusuarios, gestionar la lista de IP permitidas y rotar puertos móviles (incluye el enlace de rotación). |
| `billing` | crear pedidos y recargas, pagar con el saldo. |

La única excepción es el **enlace de rotación móvil**, pensado para llamarse desde un marcador del navegador o un simple `curl`: `GET https://africaproxies.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (clave con el permiso `proxies`). Consulta [Puertos móviles y rotación IP](/es/docs/api/mobile/).

*Consultar el saldo*

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

## Solicitudes y respuestas

- **JSON de entrada, JSON de salida**: envía `Content-Type: application/json` cuando incluyas un cuerpo.
- **Las listas** que pueden crecer se paginan con `page` (desde 1) y `perPage` (1–100, valor predeterminado 20) y devuelven `{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }`. Las listas cortas devuelven `{ "data": [...] }`.
- **Los identificadores** son cadenas opacas con un prefijo de tipo: `ord_` (pedido), `top_` (recarga), `txn_` (movimiento del saldo), `res_` (suscripción de tráfico), `mob_` (puerto móvil), `key_` (clave API) e `ipw_` (entrada de la lista de IP permitidas).
- **Reintentos seguros**: `POST /v1/orders` y `POST /v1/topups` aceptan una cabecera `Idempotency-Key` (cualquier cadena única, conservada durante 24 h). Repetir la misma clave devuelve la primera respuesta en lugar de comprar o recargar dos veces.
- **Los ejemplos** muestran la estructura de cada respuesta: los identificadores, direcciones, importes y fechas son ilustrativos; los identificadores de planes y precios son reales.

## Errores

Todos los errores tienen el mismo cuerpo. `code` es estable y está destinado a tu código; `message` es una frase en inglés que puede cambiar. Los errores de validación enumeran cada campo no válido en `fields`. Pueden añadirse códigos nuevos: trata los desconocidos como un fallo genérico.

*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`: uno o varios campos no son válidos. |
| `401` | `unauthorized`: token ausente, no válido o caducado. |
| `402` | `insufficient_balance`: el saldo no cubre el pedido. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: la clave API no tiene el permiso necesario o la cuenta está suspendida. |
| `404` | `not_found`: el recurso no existe o pertenece a otra cuenta. |
| `409` | `conflict` (o un código más específico): la acción no es posible en el estado actual. |
| `429` | `rate_limited` o `rotation_too_soon`. |

## Límites de solicitudes

Cada respuesta incluye `RateLimit-Limit`, `RateLimit-Remaining` y `RateLimit-Reset`. Por encima del límite, la API responde `429 rate_limited` con una cabecera `Retry-After` (segundos): espera ese tiempo y vuelve a intentarlo. La IP de un puerto móvil puede cambiarse como máximo una vez cada 30 segundos (`429 rotation_too_soon`, con `Retry-After`).

## Referencia de la API

- **[Cuenta y saldo](/es/docs/api/account/)** — Consulta los ajustes de la cuenta, tu saldo prepago en USD y todos los movimientos de ese saldo (recargas, compras, reembolsos).
- **[Recargas con criptomonedas](/es/docs/api/top-ups/)** — Recarga el saldo con criptomonedas: obtén la dirección de depósito y el importe exacto, envía exactamente ese importe, notifica el pago como enviado (el ID de la transacción es opcional) y sigue la recarga hasta que se abone el saldo. El saldo sirve para pagar cualquiera de nuestros planes.
- **[Pedidos](/es/docs/api/orders/)** — Lista los planes y precios, compra un plan con el saldo (nuevo servicio, más tráfico o ampliación de un puerto) y consulta pedidos anteriores.
- **[Proxies residenciales y credenciales](/es/docs/api/residential/)** — Gestiona suscripciones de tráfico (residencial y 4G/5G rotativo por GB): credenciales de proxy, subusuarios con sus propias credenciales y límite de tráfico, uso diario y ubicaciones seleccionables en el usuario del proxy.
- **[Puertos móviles y rotación IP](/es/docs/api/mobile/)** — Puertos 4G/5G dedicados: cambia la IP ahora o con un temporizador, usa el enlace de rotación y consulta el tráfico diario.
- **[Claves API y lista de IP permitidas](/es/docs/api/api-keys/)** — Crea y revoca claves API con permisos limitados y gestiona la lista de IP permitidas: hasta 10 direcciones de origen pueden usar los proxies sin usuario ni contraseña.

> **Pagar desde un script** Los planes siempre se pagan con el saldo prepago en USD. Recarga con criptomonedas (mínimo 25 US$) mediante POST /v1/topups, y compra con POST /v1/orders. Puedes combinar ambos en una llamada: una recarga puede incluir el pedido en purchase, y el plan se compra en cuanto se abona la recarga.

---

AfricaProxies: AfricaProxies es un proveedor de proxies residenciales para África subsahariana, con pago en cripto y sin subir documentos de identidad.