Cómo obtener capturas web mediante una API

Elige el proceso de API más pequeño

Una API de capturas puede resolver varios trabajos. Quizá necesitas una imagen para un informe, un render configurado con cabeceras y cookies o una comprobación visual repetible con referencia e historial. Decide qué resultado necesitas antes de elegir la forma de la petición.

La API de screenshots de RenderLog ofrece tres caminos. Usa GET para una captura rápida basada en URL. Usa POST cuando necesites opciones estructuradas. Ejecuta una comprobación guardada cuando la página necesite una referencia aprobada y un historial que alguien vaya a revisar.

Crea y envía un token de forma segura

Crea un token de API en el espacio de trabajo con el alcance que necesita el endpoint y conserva el secreto de forma privada. Envíalo en la cabecera Authorization: Bearer rl_live_xxx. RenderLog comprueba el token, su caducidad y sus alcances antes de iniciar la ejecución. Puedes revocar el token o asignarle una caducidad desde la configuración del espacio de trabajo.

No pongas el token en una URL ni en código del navegador. Los valores de GET pueden terminar en registros, historial del navegador o analítica. Por eso las cabeceras y cookies sensibles deben ir en el cuerpo de POST. La documentación de la API muestra la autenticación y los campos disponibles.

• Usa un token del espacio de trabajo en lugar de una sesión de usuario.
• Concede runs:write para iniciar un render y runs:read para consultar el trabajo o leer el resultado.
• Envía secretos en cabeceras o campos POST que el endpoint admita.
• Rota o revoca el token cuando cambie el sistema que lo utiliza.

Usa GET para una captura sencilla

Para una página pública sin preparación especial, llama a /api/render con una URL y parámetros opcionales. La petición puede incluir format, width, height, dpr, selector y fullPage. Por ejemplo, puedes codificar la URL y capturar un PNG con un viewport de escritorio estable.

La respuesta tiene la forma de un trabajo público con id, status y un resultado cuando termina. El resultado incluye información de la ejecución y del artefacto. Usa GET cuando la URL y las opciones sean seguras en la query y no necesites un cuerpo JSON estructurado.

• Codifica la URL de destino antes de colocarla en la query.
• Usa selector para un elemento o fullPage=true para toda la página.
• Mantén estables el ancho, la altura y la escala del dispositivo.
• Lee el estado del trabajo antes de asumir que el artefacto está listo.

Usa POST para opciones de render completas

Usa POST /api/render con un cuerpo JSON cuando la captura necesite cabeceras, cookies, user agent, idioma, pasos de interacción, selectores ocultos o reglas de fallo. El cuerpo acepta una URL y usa PNG como formato predeterminado. También puede renderizar HTML o Markdown si envías el contenido correspondiente. Un render puntual usa el almacenamiento de artefactos de RenderLog por defecto; recupera la URL del artefacto que devuelve el trabajo en lugar de añadir una opción de almacenamiento a la petición.

Un cuerpo POST práctico puede incluir url, format, headers y failureRules. Las reglas de fallo pueden marcar un resultado como incorrecto cuando aparece un desafío conocido o falta un selector necesario. Así una sesión de navegador técnicamente completada no se confunde con una página válida.

• Usa JSON para opciones que deban quedar legibles y revisables.
• Usa cabeceras y cookies solo para el estado permitido que necesitas.
• Añade una regla de selector ausente para el elemento raíz necesario.
• Usa async: true cuando el llamador deba iniciar el trabajo y consultar después.

Consulta el trabajo y lee el artefacto

Un render puede estar en cola o ejecutándose antes de que el resultado del navegador esté disponible. Consulta GET /api/jobs/{id} con el mismo token bearer hasta llegar a un estado final. Los estados documentados son queued, running, passed, failed y canceled. Lee las filas del resultado y las URL de los artefactos después de terminar.

Guarda el identificador del trabajo junto a la compilación, el informe o el registro que lo solicitó. La URL del artefacto es la evidencia que otro sistema puede recuperar. Si el trabajo falla, conserva el estado y sus detalles para diagnosticar en vez de repetir a ciegas. Un reintento puede crear otra ejecución facturable y ocultar el problema original.

• Consulta con un intervalo limitado y detente en un estado final.
• Trata failed y canceled como resultados que requieren una acción.
• Guarda los identificadores del trabajo y la ejecución junto a la compilación.
• Recupera el artefacto desde la URL devuelta cuando esté listo.

Diagnostica fallos y elige el siguiente nivel

Un 401 suele indicar que falta el token bearer, que ha caducado o que no es válido. Un 403 puede indicar que falta runs:write para iniciar, runs:read para consultar o que el token intenta acceder a otro espacio de trabajo. Una petición correcta con una ejecución fallida apunta al estado de la página, al acceso, a un desafío o a un objetivo ausente. Revisa el resultado y las opciones antes de cambiar la URL.

El endpoint de render crea evidencia de una página. Si necesitas una referencia aprobada, escenarios repetibles, assertions o revisión visual, pasa a una comprobación guardada y ejecútala mediante la API. Para una imagen puntual, mantén el flujo pequeño. Los ejemplos de GET y POST ayudan a decidir cuándo cambiar la forma de la petición.