API de Capturas v1

Parámetros, restricciones y ejemplos para POST /api/v1/screenshots.

Autenticación

Envíe su clave API en el encabezado Authorization :

Authorization: Bearer <api_key>

Crear captura

Endpoint: POST /api/v1/screenshots

Cuerpo: JSON

Solicitud mínima

curl -X POST "https://api.page-ops.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Solicitud sync (cuando esté permitida)

curl -X POST "https://api.page-ops.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "mode": "sync",
    "timeoutMs": 8000,
    "fullPage": false
  }'

Si la ventana sync expira antes de completarse, la API devuelve status=processing. Continúe consultando con GET /api/v1/screenshots/{jobId}.

Parámetros clave

url

Obligatorio. URL objetivo que se va a capturar.

mode

Opcional. async (por defecto) o sync.

timeoutMs

Obligatorio para sync. Debe ser > 0 y < 10000.

fullPage

Opcional. Para el modo sync , debe ser false.

Restricciones del modo síncrono

Aunque solicite mode=sync, , el servidor volverá a async salvo que:

mode == "sync"

timeoutMs != null

0 < timeoutMs < 10000

fullPage == false

Referencia de parámetros (completa)

Campo	Tipo	Obligatorio	Valor por defecto	Notas
url	string	Sí	-	URL objetivo.
mode	string	No	async	Acepta async o sync (sin distinción entre mayúsculas y minúsculas).;
timeoutMs	int?	No	-	Solo se usa para sync. Debe ser 0 < timeoutMs < 10000.
fullPage	bool	No	false	Sync requiere false.
viewport	object?	No	-	Sobrescribe el viewport.
format	string?	No	-	Actualmente solo se admite png . Los demás formatos quedan reservados para futuras versiones.
quality	int?	No	-	Actualmente se ignora (solo se usará para jpeg/webp en el futuro).
waitUntil	string?	No	-	Sugerido: load, domcontentloaded, networkidle.
delayMs	int?	No	-	Retraso adicional después de waitUntil.
selector	string?	No	-	Captura solo un elemento específico.
headers	object?	No	-	Diccionario de encabezados de solicitud adicionales.
cookies	array?	No	-	Lista de cookies que se inyectarán.
javascript	string?	No	-	JS personalizado a inyectar (según la implementación).;
css	string?	No	-	CSS personalizado a inyectar (según la implementación).;
device	string?	No	-	Sugerido: desktop/iphone/ipad/pixel.
strictDevice	bool?	No	-	Si es true, un dispositivo no compatible debería fallar (según la implementación).;
colorScheme	string?	No	-	Sugerido: light/dark/no-preference.
proxy	string?	No	-	Reservado para futuras versiones. Actualmente se ignora.
trace	bool?	No	-	Reservado para futuras versiones. Actualmente se ignora.
har	bool?	No	-	Reservado para futuras versiones. Actualmente se ignora.
returnDom	bool?	No	-	Reservado para futuras versiones. Actualmente se ignora.
returnNetwork	bool?	No	-	Reservado para futuras versiones. Actualmente se ignora.
priority	int?	No	-	Reservado para futuras versiones. Actualmente se ignora.

viewport

Campo	Tipo	Obligatorio	Notas
viewport.width	int	No	Ancho del viewport.
viewport.height	int	No	Alto del viewport.

cookies[]

Campo	Tipo	Obligatorio	Notas
cookies[].name	string	Sí	Nombre de la cookie.
cookies[].value	string	Sí	Valor de la cookie.
cookies[].domain	string?	No	Dominio de la cookie.
cookies[].path	string?	No	Ruta de la cookie.

Respuestas

Async (por defecto)

{ "jobId": "<guid>", "status": "pending" }

Sync (completada)

{ "jobId": "<guid>", "status": "completed", "result": { "url": "https://..." } }

Sync (fallida)

{ "jobId": "<guid>", "status": "failed", "errorMessage": "..." }

Sync (timeout)

{ "jobId": "<guid>", "status": "processing" }

Para llamadas async (o timeouts sync), use GET /api/v1/screenshots/{jobId} para comprobar el estado. Valores posibles: pending, processing, completed, failed, expired.

Errores

HTTP	Cuándo	Cuerpo
400	Body ausente o url ausente/vacía	BadRequest
401	Clave API inválida/ausente	Respuesta del middleware
402	Cuota excedida	{ "error": "quota_exceeded", "operationKey": "screenshot.capture", ... }
429	Límite de velocidad alcanzado	{ "error": "rate_limited", "operationKey": "screenshot.capture", ... }
404	Trabajo no encontrado	NotFound

Ejemplos prácticos

Ejemplos prácticos para necesidades comunes de integración.

Pasar el token de autenticación del sitio objetivo (vía headers)

Si la página que quiere capturar está protegida (Bearer/JWT/session token), reenvíelo usando headers:

{
  "url": "https://example.com/dashboard",
  "headers": {
    "Authorization": "Bearer <target_site_token>"
  }
}

Configurar cookies (inicio de sesión basado en sesión)

Si el sitio web usa cookies para autenticación, páselas usando cookies:

{
  "url": "https://example.com/account",
  "cookies": [
    { "name": "session", "value": "<cookie_value>", "domain": "example.com", "path": "/" }
  ]
}

Encabezados personalizados (User-Agent / locale)

{
  "url": "https://example.com",
  "headers": {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "Accept-Language": "en-US,en;q=0.9"
  }
}

Viewport + formato + calidad

{
  "url": "https://example.com",
  "viewport": { "width": 1280, "height": 720 },
  "format": "jpeg",
  "quality": 85
}

Esperar a que cargue la página + añadir retraso

{
  "url": "https://example.com",
  "waitUntil": "networkidle",
  "delayMs": 500
}

Capturar un elemento específico (selector)

{
  "url": "https://example.com/pricing",
  "selector": "#pricing"
}

Obtener estado

Consultar el trabajo:

GET /api/v1/screenshots/{jobId}