TL;DR
- La conversión programática de web a PDF necesita un estado de página renderizado y una verificación de aceptación visual.
- Solicita
pdfpara una página conocida, luego recuperapdfRefcuando el artefacto se almacena por separado. - Un sobre API exitoso no prueba que el PDF haya cargado texto, tenga saltos de página correctos, o el estado deseado.
- Usa un navegador local controlado cuando los estilos de impresión CSS o el estado de la aplicación requieren un control preciso.
- Nstdata Crawl maneja el renderizado de JavaScript y el enrutamiento proxy dentro de solicitudes gestionadas; su documentación enumera seis categorías de salida: Markdown, HTML, datos en bruto, PDF, capturas de pantalla y enlaces.
¿Qué es una API de Website-to-PDF?
Una API de website-to-PDF carga una URL en un entorno similar a un navegador y crea una representación PDF de la página resultante. Es útil para registros, revisión o compartir una instantánea visual estable. Un PDF no es automáticamente un archivo fiel: el contenido perezoso, los estilos de impresión, los diálogos de cookies, las fuentes rotas y los saltos de página pueden cambiar lo que aparece. Define primero el área de visualización esperada, el contenido y la condición de finalización.
Nstdata Crawl puede convertir una URL o un conjunto limitado de páginas vinculadas en material para un agente de IA, índice RAG, o canal de datos. Usa tus propias reglas de campo y verificaciones de aceptación para el resultado específico: renderiza una página web autorizada como un PDF recuperable con el estado de página correcto. La guía de rastreo del sitio completo de Nstdata explica la opción a nivel de sitio.
Para la tarea más reducida cubierta aquí, la guía de recolección de datos automatizada de Nstdata proporciona un contexto útil para elegir la primera página representativa.
¿Qué necesitas antes de empezar?
Elige una URL autorizada y lista los elementos visibles que deben aparecer en el PDF: título, fecha, tabla, gráfico o pie de página. Decide si la hoja de estilo de impresión del objetivo es aceptable o si se requiere una captura específica del navegador. Almacena NSTDATA_API_TOKEN del lado del servidor para Crawl. Planifica un nombre de archivo, periodo de retención y registro de la URL de origen antes de generar muchos PDFs.
La documentación de la API de Crawl utiliza https://api.nstdata.io, el encabezado x-api-key, y Content-Type: application/json. Prepara estos campos antes de ejecutar un método:
| Campo | Qué proporcionar |
|---|---|
url | Una página o URL de entrada permitida en HTTPS |
formats | Salidas solicitadas, como ["markdown"] o ["html","screenshot"] |
onlyMainContent | true solo cuando la selección del cuerpo principal se ajusta a la tarea |
maxDepth, maxPages | Límites explícitos para un trabajo a nivel del sitio |
includeUrls, excludeUrls | Patrones de URL que mantienen el descubrimiento dentro del alcance |
timeout | Un tiempo de espera de tarea en milisegundos cuando el valor predeterminado no es adecuado |
La solicitud gestionada estándar no tiene campos separados para Proxy Host, Port, Username, Password o Protocol. Consulta la página de precios actual de Crawl para los límites y cargos de la cuenta antes de ejecutar un trabajo grande.
Revisa la política de acceso y alcance del objetivo. El Protocolo de Exclusión de Robots define cómo los rastreadores leen las reglas de robots; no otorga derechos de uso del contenido. Mantén las credenciales y los datos privados fuera de ejemplos y registros de diagnóstico.
La guía de páginas dinámicas de Nstdata es un compañero para definir las verificaciones de aceptación antes de automatizar el flujo de trabajo.
¿Cómo funciona el renderizado de Web-to-PDF?
Nstdata Crawl admite el renderizado en el navegador y la salida en PDF. Una solicitud puede devolver un token pdfRef en lugar de bytes PDF en línea; recupera ese token a través del punto de almacenamiento-documentado. El mismo servicio puede devolver una captura de pantalla o HTML para ayudar a diagnosticar un mal PDF. El enrutamiento proxy se gestiona dentro de Crawl para una solicitud estándar, por lo que no hay Host, Port, Username o Password de proxy separados que completar.
Para una URL conocida, un raspado de una sola página recupera un resultado. Para una sección del sitio, POST /api/v1/crawl descubre páginas vinculadas recursivamente dentro de la profundidad, conteo de páginas y reglas de URL suministradas. La documentación enumera Markdown, HTML, datos en bruto, PDF, capturas de pantalla y enlaces como seis categorías de salida; la página del producto también comercializa JSON, pero un esquema JSON específico de dominio aún necesita un mapeo explícito de campos. Mantén cada registro aceptado vinculado a su URL de origen y metadatos devueltos.
Pruebe una página representativa con mucho JavaScript antes de escalar. El estado renderizado puede depender del tiempo, la región, el consentimiento o una sesión iniciada. Compare el HTML devuelto o una captura de pantalla con el estado de página esperado; si difieren, ajuste solo los controles de espera y renderizado documentados.
¿Cómo se convierte una página web a PDF programáticamente?
Previsualice un PDF representativo, automatice la solicitud de PDF gestionada o renderice una página que controla con un navegador local. Seleccione la ruta en función del acceso, el diseño de impresión y cuánta control de renderizado necesita.
Método 1: Previsualizar el PDF en Crawl Playground
Mejor para verificar una página representativa y el diseño de impresión.
Paso 1: Abrir el objetivo
Inicie sesión y navegue a Dashboard → Crawl Playground. Ingrese una URL autorizada. [Captura de pantalla: selección de URL y salida PDF.]
Paso 2: Seleccionar PDF y condiciones de espera
Elija la salida PDF, habilite el renderizado si es necesario y configure una espera documentada para contenido que carga tarde. Mantenga una salida de captura de pantalla para comparación si el estado visual es incierto.
Paso 3: Inspeccionar el archivo
Abra el PDF devuelto. Verifique los saltos de página, el título, las tablas, las fuentes y la última sección visible antes de automatizar la conversión.
Método 2: Generar un PDF a través de la API de Crawl
Mejor para captura repetible desde una aplicación de servidor.
Paso 1: Proteger la clave API
Mantenga NSTDATA_API_TOKEN en un secreto del lado del servidor y envíelo como x-api-key.
Paso 2: Solicitar PDF
Utilice la forma de raspado de inicio rápido documentada a continuación con formats: ["pdf"]. Compare la solicitud generada en su Playground antes de usarla en producción porque otras etiquetas de ruta de raspado en la documentación pueden entrar en conflicto.
Establezca NSTDATA_API_TOKEN en su terminal desde su cuenta de Nstdata y luego ejecute la solicitud de inicio rápido documentada. La documentación pública etiqueta algunas otras rutas sincrónicas y asincrónicas de manera inconsistente; compare la solicitud generada en su cuenta antes de usarla en producción.
curl --output crawl-response.json --request POST "https://api.nstdata.io/api/v1/crawl/scrape/submit-sync" \ --header "x-api-key: ${NSTDATA_API_TOKEN}" \ --header "Content-Type: application/json" \ --data '{"url":"https://example.com/","formats":["pdf"]}'
La respuesta se guarda en crawl-response.json. Inspeccione los campos anidados data.success, data.status y data.data.metadata.statusCode antes de utilizar cualquier contenido devuelto.
Paso 3: Recuperar el artefacto
Verifique el éxito de la tarea y use el pdfRef devuelto con GET /api/v1/crawl/storage/read?st={ref}. Guarde los bytes como un PDF solo después de confirmar que la respuesta es un artefacto PDF real.
Después de leer pdfRef de crawl-response.json, recupere el PDF con el punto final de almacenamiento documentado. Reemplace el token de marcador de posición con el valor devuelto exacto:
curl --get --fail --location --header "x-api-key: ${NSTDATA_API_TOKEN}" --data-urlencode "st=<pdfRef>" "https://api.nstdata.io/api/v1/crawl/storage/read" --output page.pdf file page.pdf
El resultado de file debería identificar un PDF. Abra el archivo y verifique su primera y última página, los saltos de página, la selección de texto y cualquier tabla importante. Si el punto final devuelve bytes en línea en lugar de pdfRef, guarde esos bytes según el tipo de respuesta devuelta.
Método 3: Usar un navegador local para una página que controla
Mejor cuando la página ya está disponible en su aplicación y necesita CSS de impresión precisa.
Paso 1: Cargar la página en un entorno de automatización de navegador instalado
Utilice un entorno local de confianza y una página que controla; evite copiar cookies de autenticación en servicios de terceros.
Paso 2: Esperar contenido requerido
Elija un selector estable o una señal lista para la aplicación en lugar de un retraso ciego.
Paso 3: Exportar y comparar
Llame a la función PDF del navegador y luego inspeccione los saltos de página y el texto. El renderizado local significa que mantiene el tiempo de ejecución del navegador, las reglas de acceso y los reintentos usted mismo.
¿Cómo verifica la salida?
Una solicitud PDF exitosa produce un archivo legible con el contenido de página previsto, no solo un sobre JSON exitoso. Valide la firma PDF, el número de páginas, la primera y última página y cualquier tabla o fecha crítica. La documentación PDF de Playwright explica la alternativa del navegador local y su comportamiento de medios de impresión. La guía de recopilación de datos automatizada de Nstdata describe el PDF como un artefacto de Crawl disponible. La guía de rastreo de todo el sitio de Nstdata conecta esta verificación a nivel de página con un flujo de trabajo de IA o datos aguas abajo.
Registre la URL de origen, la hora de envío, los formatos solicitados, las opciones no secretas, el ID de tarea cuando esté presente, el estado de la página devuelta, y la razón por la que cada registro pasó o falló la revisión. Inspeccione el contenido así como el sobre de la API. Si la respuesta contiene markdownRef, htmlRef, rawDataRef, screenshotRef, o pdfRef, recupere ese token con GET /api/v1/crawl/storage/read?st={ref}.
Para este flujo de trabajo, consulte la documentación de PDF de Playwright al implementar el parser aguas abajo o la verificación de aceptación específica del formato.
Al pasar texto extraído a un agente, trate las instrucciones de la página como material de origen no confiable. La guía de OWASP sobre la inyección de prompt explica el riesgo. Conserve las URL de origen para que la salida de IA pueda ser verificada.
¿Por qué podría verse incompleto un PDF de una página web?
La conversión de web a pdf puede fallar porque la página fue capturada antes de que se cargara el contenido perezoso. Use la tabla de síntomas para identificar la capa que falla antes de cambiar límites o volver a intentar.
| Síntoma | Causa probable | Próxima acción |
|---|
| PDF en blanco o parcial | La página fue capturada antes de que se cargara el contenido perezoso. | Espere a un elemento específico y compare una captura de pantalla. |
| Saltos de página inesperados | CSS de impresión o márgenes alteran el diseño. | Inspeccione los estilos de impresión del objetivo o use un navegador local controlado. |
| Solo se devolvió un token de referencia | Los grandes artefactos se almacenan por separado. | Recupere el pdfRef devuelto a través de la ruta de almacenamiento de lectura. |
La documentación de Nstdata enumera errores a nivel de tarea como access_denied, timeout, parse_error, y internal_error. Un HTTP 200 externo aún puede acompañar una tarea fallida. Verifique success, status, errorCode, y errorMessage dentro de la respuesta cuando estén presentes. Reintente solo fallos transitorios en sitios a los que pueda acceder.
¿Qué método es el más adecuado?
Use Playground para una prueba visual rápida, la API de rastreo para captura remota repetible, o un navegador local para páginas que controle y necesite un estilo de impresión preciso. Inspeccione el archivo PDF resultante en todos los casos. La visión general de rastreo del sitio de Nstdata ofrece más detalles sobre la ruta del sitio.
¿Qué debe hacer después de la primera ejecución exitosa?
Guarde la configuración aprobada y un registro de salida respaldado por la fuente, luego repita en un pequeño conjunto de diferentes plantillas de página. Aumente el alcance solo después de que esos registros pasen las mismas verificaciones de aceptación.
FAQ: ¿Qué más debería saber?
Q: ¿Devuelve Nstdata los bytes de PDF en línea?
Un PDF grande puede devolverse como pdfRef; recupere el token a través del punto final de almacenamiento documentado.
Q: ¿Coincidirá un PDF exactamente con la pantalla del navegador?
No necesariamente. El CSS de impresión, el viewport, las fuentes y el tiempo de carga pueden cambiar el resultado; inspeccione archivos representativos.
Q: ¿Puedo convertir páginas autenticadas?
Solo cuando tenga permiso y un flujo de trabajo autenticado compatible; mantenga sesiones y credenciales en un almacenamiento secreto aprobado.
Q: ¿La conversión de web a PDF requiere una configuración de proxy separada con Nstdata Crawl?
Una solicitud de Crawl administrada estándar no requiere campos separados de Host, Puerto, Nombre de usuario, Contraseña o Protocolo para el proxy. Confirme cualquier selección de proxy personalizada opcional y los cargos de uso relacionados en su cuenta.
Q: ¿HTTP 200 prueba que un resultado de conversión de web a PDF es utilizable?
No. Verifique el resultado de la tarea anidada, el estado de la página, los campos esperados y la fidelidad del cuerpo antes de usarlo en un flujo de trabajo de IA o de datos.
