Documentación de la API

Inicio rápido

1. Inicia sesión en la consola y crea una clave de API en la pestaña Claves de API. Cópiala: solo se muestra una vez.
2. Ten a mano un proxy residencial o ISP sticky (que mantenga la misma IP de salida al menos 10 minutos).
3. Llama a POST /v1/fetch con la URL y el proxy.

curl -X POST https://orpheus-api.lapetiteagora.fr/v1/fetch \
  -H "Authorization: Bearer $LPA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/",
    "proxy": "http://user:pass@proxy.example:8080"
  }'

import os, requests

resp = requests.post(
    "https://orpheus-api.lapetiteagora.fr/v1/fetch",
    headers={"Authorization": f"Bearer {os.environ['LPA_KEY']}"},
    json={
        "url": "https://www.example.com/",
        "proxy": "http://user:pass@proxy.example:8080",
    },
    timeout=70,
)
page = resp.json()
print(page["status"], page["solved"], page["session_id"])

const resp = await fetch("https://orpheus-api.lapetiteagora.fr/v1/fetch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LPA_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.example.com/",
    proxy: "http://user:pass@proxy.example:8080",
  }),
});
const page = await resp.json();
console.log(page.status, page.solved, page.session_id);

Pon en tu cliente un timeout de unos 70 segundos: superar un desafío puede llevar unos segundos, a veces más.

Autenticación

Cada petición lleva tu clave de API en el header Authorization:

Authorization: Bearer lpa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Las claves se crean y se revocan en la consola. Trátalas como contraseñas: guárdalas en el servidor, nunca en un navegador ni en un repositorio público. Una clave revocada, o una cuenta suspendida, recibe 401 invalid_key de inmediato.

Obtener una página

Cuerpo de la petición (JSON)

Respuesta

La API responde 200 en cuanto el sitio de destino ha respondido — sea cual sea el estado que devuelva el sitio. Ese estado lo lees en status.

{
  "status": 200,
  "headers": { "content-type": ["text/html; charset=utf-8"] },
  "body": "<!doctype html>…",
  "encoding": "text",
  "url": "https://www.example.com/",
  "session_id": "s_Ij4oudr1bYPzUA8U3sdlACAf",
  "solved": ["datadome"],
  "cookies": [{ "name": "datadome", "value": "…", "domain": ".example.com", "path": "/" }],
  "elapsed_ms": 2343
}

Sesiones

Las cookies anti-bot están ligadas a la identidad de navegador que las obtuvo: IP, huella, almacén de cookies. Una sesión conserva esa identidad por ti, así que un desafío superado una vez sigue superado.

• La primera llamada (con un proxy, sin session_id) crea una sesión y devuelve su session_id.
• Envía ese session_id en las siguientes llamadas: mismo proxy, misma huella, mismas cookies. Las páginas siguientes suelen llegar en unos cientos de milisegundos, con solved: [].
• Una sesión caduca tras 30 minutos sin peticiones. Cada petición la prolonga.
• Una sesión conserva su proxy toda su vida. Enviar un proxy distinto con un session_id devuelve 409 proxy_mismatch: inicia una sesión nueva en su lugar.
• Una petición a la vez por sesión. Una segunda petición simultánea espera hasta 10 segundos y luego recibe 409 session_busy. Para ir más rápido, usa varias sesiones en paralelo, cada una con su propio proxy.

import os, requests

API = "https://orpheus-api.lapetiteagora.fr/v1/fetch"
HEADERS = {"Authorization": f"Bearer {os.environ['LPA_KEY']}"}

def fetch(**payload):
    r = requests.post(API, headers=HEADERS, json=payload, timeout=70)
    data = r.json()
    if r.status_code != 200:
        raise RuntimeError(data["error"])
    return data

# 1. Primero la página de inicio: crea la sesión y supera el desafío
home = fetch(url="https://www.shop.example/", proxy="http://user:pass@proxy.example:8080")

# 2. Luego la página del producto, con la misma identidad
product = fetch(
    url="https://www.shop.example/product/42",
    session_id=home["session_id"],
    headers={"Referer": "https://www.shop.example/"},
)
print(product["status"], product["solved"])

# 1. Página de inicio: apunta el session_id de la respuesta
curl -s -X POST https://orpheus-api.lapetiteagora.fr/v1/fetch \
  -H "Authorization: Bearer $LPA_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://www.shop.example/","proxy":"http://user:pass@proxy.example:8080"}'

# 2. Página del producto en la misma sesión
curl -s -X POST https://orpheus-api.lapetiteagora.fr/v1/fetch \
  -H "Authorization: Bearer $LPA_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://www.shop.example/product/42","session_id":"s_…",
       "headers":{"Referer":"https://www.shop.example/"}}'

Cookies

Inicia una sesión con cookies que ya tengas (un login, un carrito, una elección de consentimiento), o añádelas más tarde. Se guardan en la sesión y se envían en cada petición siguiente hasta que el sitio las sustituya.

Forma simple

Un objeto {"name": "value"}. Las cookies se asignan al host de la url.

{
  "url": "https://www.shop.example/cart",
  "proxy": "http://user:pass@proxy.example:8080",
  "cookies": { "cart_id": "42", "lang": "fr" }
}

Forma detallada

Una lista de objetos, para elegir el domain (p. ej. .shop.example para todos los subdominios) o el path (por defecto /).

{
  "url": "https://www.shop.example/",
  "session_id": "s_…",
  "cookies": [
    { "name": "auth", "value": "eyJ…", "domain": ".shop.example", "path": "/" }
  ]
}

• Hasta 50 cookies por petición, 4096 caracteres por valor, sin ; ni saltos de línea en los valores.
• Una cookie con el mismo nombre, dominio y ruta sustituye a la anterior.
• Cada respuesta devuelve las cookies de la sesión en cookies, para que puedas reutilizarlas en otro sitio.
• Los valores de las cookies nunca se escriben en tu registro de peticiones.

Errores

Los errores usan un estado distinto de 200 y siempre la misma forma. Cuando existe una sesión, se incluye su session_id.

{
  "error": { "code": "proxy_blocked", "message": "…" },
  "session_id": "s_…"
}

Límites

El consumo, los desafíos superados y tus últimas peticiones están en la consola.

Otros endpoints

Peticiones usadas este mes, tu cuota y el desglose diario de los últimos 30 días (peticiones, éxitos, errores, bytes, resoluciones por protección).

curl -s https://orpheus-api.lapetiteagora.fr/v1/usage -H "Authorization: Bearer $LPA_KEY"

Cierra una sesión de inmediato (si no, caduca sola). Devuelve {"deleted": true}, o 404 si ya no existe.

curl -s -X DELETE https://orpheus-api.lapetiteagora.fr/v1/sessions/s_… -H "Authorization: Bearer $LPA_KEY"

Buenas prácticas

• Solo proxies sticky. Un proxy rotativo cambia de IP entre peticiones e invalida las cookies que acabas de obtener. Apunta a sesiones de 10 minutos o más.
• Una sesión por identidad. Reutilízala para todas las páginas de un mismo recorrido; abre más sesiones (con más proxies) para escalar.
• Navega con naturalidad. Carga primero la página de inicio o de categoría y luego la del producto con un header Referer. Los accesos directos a páginas profundas se marcan más a menudo.
• No machaques una sola sesión. Supera el desafío con una petición y sigue; evita ráfagas desde la misma IP.
• Ante proxy_blocked, aparca la sesión y su proxy durante un tiempo; una IP quemada sigue quemada.
• Respeta los sitios a los que accedes. Eres responsable de cumplir sus condiciones y las leyes que te aplican.