Documentación de la API de LocalSERP Proxy

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.

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.

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

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