# Documentación de la API de LocalSERP Proxy

> API REST de LocalSERP Proxy en localserpproxy.com/api: claves de API, errores, límites y endpoints para el saldo, las recargas, los pedidos y los proxies.

- URL: https://localserpproxy.com/es/docs/api/
- Última actualización: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

Puedes automatizar todo lo que haces en tu cuenta: consultar el saldo, recargar con criptomonedas, comprar un plan, crear credenciales de proxy y cambiar una IP móvil. JSON sobre HTTPS, una clave de API y ejemplos en curl, Python y Node.js.

## ¿Cómo uso la API de LocalSERP Proxy?

**Respuesta rápida**

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

## Resumen

| Atributo | Valor |
| --- | --- |
| URL base | `https://localserpproxy.com/api/v1` |
| Formato | JSON por HTTPS, UTF-8 |
| Autenticación | Clave de API: `Authorization: Bearer API_KEY` |
| Permisos de la clave de API | `read`, `proxies`, `billing` |
| Moneda | USD como cadena con 2 decimales (`"29.00"`) |
| Importes en criptomonedas | Cadenas decimales, nunca números de punto 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 cada ruta |

## Autenticación

Todas las solicitudes, excepto las del catálogo público, requieren una clave de API: `Authorization: Bearer API_KEY`. La clave se muestra completa **una sola vez**, al crearla: guárdala como una contraseña. Puedes revocar una clave en cualquier momento; a partir de entonces, las solicitudes que la usen devolverán `401 unauthorized`.

### Permisos

Asigna a cada clave solo los permisos que necesite tu script. Una clave sin el permiso necesario devuelve `403 forbidden`.

| Permiso | Qué permite |
| --- | --- |
| `read` | leer todo (cuenta, saldo, servicios, uso). |
| `proxies` | cambiar la configuración y las credenciales del proxy (etiquetas, renovación automática y contraseñas nuevas), gestionar subusuarios, gestionar la lista de IP permitidas y rotar los 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**, diseñado para abrirse desde un marcador del navegador o una `curl` simple: `GET https://localserpproxy.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (clave con el alcance `proxies`). Consulta [Puertos móviles y rotación de IP](https://localserpproxy.com/es/docs/api/mobile/).

*Consultar el saldo*

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

## Solicitudes y respuestas

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

## Errores

Todos los errores tienen el mismo cuerpo. `code` es estable y está pensado para 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`. Se pueden añadir códigos nuevos: trata los códigos desconocidos como un error 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 más campos no son válidos. |
| `401` | `unauthorized`: falta el token, no es válido o ha caducado. |
| `402` | `insufficient_balance`: el saldo no cubre el pedido. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: la clave API no tiene el alcance 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 se puede realizar 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`. Si se supera el límite, la API responde con `429 rate_limited` y un encabezado `Retry-After` (en segundos): espera ese tiempo y vuelve a intentarlo. La IP de un puerto móvil se puede cambiar como máximo una vez cada 30 segundos (`429 rotation_too_soon`, con `Retry-After`).

## Referencia de la API

- **[Cuenta y saldo](https://localserpproxy.com/es/docs/api/account/)** — Consulta la configuración de tu cuenta, tu saldo prepago en USD y todos los movimientos de ese saldo (recargas, compras y reembolsos).
- **[Recargas con criptomonedas](https://localserpproxy.com/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, informa que el pago se ha enviado (el ID de transacción es opcional) y luego consulta el estado de la recarga hasta que se acredite el saldo. El saldo sirve para pagar cualquiera de nuestros planes.
- **[Pedidos](https://localserpproxy.com/es/docs/api/orders/)** — Consulta los planes y sus precios, compra un plan con el saldo (un servicio nuevo, más tráfico o una extensión de puerto) y consulta tus pedidos anteriores.
- **[Proxies residenciales y credenciales](https://localserpproxy.com/es/docs/api/residential/)** — Gestiona suscripciones de tráfico (residencial y 4G/5G rotativo por GB): credenciales de proxy, subusuarios con credenciales propias y límite de tráfico, uso diario y las ubicaciones a las que puedes dirigirte desde el nombre de usuario del proxy.
- **[Puertos móviles y rotación de IP](https://localserpproxy.com/es/docs/api/mobile/)** — Puertos dedicados 4G/5G: 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](https://localserpproxy.com/es/docs/api/api-keys/)** — Crea y revoca claves API con permisos limitados y gestiona la lista de IP permitidas: hasta 10 IP de origen pueden usar los proxies sin nombre de 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.00 USD) con POST /v1/topups y luego compra con POST /v1/orders. Puedes hacer ambas cosas en una sola llamada: la recarga puede incluir el pedido en purchase y el plan se compra en cuanto se acredita la recarga.

---

LocalSERP Proxy: LocalSERP Proxy es un servicio de proxy residencial de Estados Unidos para comprobar resultados de búsqueda locales, anuncios y precios ciudad por ciudad, con pago en criptomonedas y sin subir documentos de identidad.