Automatización de flujos de trabajo # Cómo convertir HTML a PDF a gran escala Genera facturas, informes y recibos en PDF desde una URL o un HTML subido, y permite obtener el mismo resultado de forma reproducible. Publicado el 13 de agosto de 2026 ## Conclusiones clave * Configura el formato pdf en /html/convert; los demás formatos producen capturas de pantalla. * Controla cuándo se toma la instantánea con wait\_until y, solo cuando sea necesario, con delay. * Envía la autenticación mediante headers en lugar de insertar credenciales en la URL. La mayoría de los requisitos de un PDF parten de una página que ya se renderiza correctamente en un navegador. Renderizar esa página del lado del servidor suele ser más económico que mantener un segundo diseño en una biblioteca para PDF, siempre que se controlen los tiempos y las entradas. ## En esta guía 1. [Renderiza la página que ya tienes](#convert-html-to-pdf-section-1) 2. [Controla cuándo se toma la instantánea](#convert-html-to-pdf-section-2) 3. [Accede a páginas protegidas sin exponer credenciales](#convert-html-to-pdf-section-3) 4. [Haz que el documento reemitido sea idéntico al original](#convert-html-to-pdf-section-4) 5. [Mantén predecible el costo de renderizar](#convert-html-to-pdf-section-5) 6. [Verifica el documento antes de que lo vea un cliente](#convert-html-to-pdf-section-6) ## Lo más importante * Renderiza desde una URL estable de una plantilla con control de versiones para que un cambio de diseño no pueda alterar un documento ya emitido. * Combina documentos de varias partes con /document/merge en lugar de concatenar los PDF por tu cuenta. ## Renderiza la página que ya tienes La mayoría de los requisitos de PDF comienzan como una página que ya se renderiza correctamente en un navegador: una factura, un estado de cuenta o un informe. Mantener un segundo diseño en una biblioteca de PDF duplica ese trabajo y hace inevitable que ambos diverjan. `/html/convert` renderiza la página con un navegador sin interfaz gráfica y devuelve el resultado; establecer `format: "pdf"` es lo que distingue un documento de una captura de pantalla. El mismo Robot genera `jpeg`, `jpg` y `png`, que son imágenes de la página en lugar de documentos paginados. El Robot acepta una `url` para renderizar o un archivo HTML subido. Renderizar una URL suele ser la mejor opción para los documentos que ya existen como páginas, porque mantiene una única fuente de verdad. Subir HTML es adecuado para documentos generados al momento cuando no existe una URL estable. Renderizar a PDF la URL con versión de una factura y almacenar el resultado ``` { "steps": { "rendered": { "robot": "/html/convert", "url": "https://example.com/inv/1043?v=3", "format": "pdf", "wait_until": "networkidle" }, "exported": { "use": "rendered", "robot": "/s3/store", "credentials": "my_s3_credentials", "path": "inv/1043.pdf" } } } ``` ### format: "pdf" Produce el documento. Los demás formatos capturan una imagen de la página. ### url o subida Renderiza una página existente mediante su URL o sube el HTML generado cuando no exista una URL estable. ### omit\_background Solo se aplica a la salida de imagen. La transparencia no puede conservarse en un PDF. ## Controla cuándo se toma la instantánea El fallo más común es que un documento que se renderiza correctamente de forma manual llegue casi vacío desde el Robot porque la instantánea se tomó antes de que se cargaran las fuentes o terminara de dibujarse un gráfico. `wait_until` se corresponde con el estado de carga del navegador y es la forma precisa de expresar esa dependencia. Elegir el estado de carga adecuado resuelve la mayoría de los problemas de sincronización sin agregar una latencia fija. `delay` agrega después una pausa fija. En ocasiones es necesario para animaciones o widgets de terceros que indican que están listos antes de estarlo realmente, pero esa pausa se cobra en cada renderizado, incluso en los que no la necesitaban. Primero recurre a un `wait_until` más específico y considera `delay` como respaldo, no como opción predeterminada. ### wait\_until Expresa la dependencia real respecto del estado de carga del navegador. Dale preferencia. ### delay Una pausa fija que se cobra en cada renderizado. Úsala solo cuando un estado de carga no permita expresar la espera. ### Hoja de estilos de impresión Verifica la página en la vista previa de impresión de un navegador antes de renderizarla del lado del servidor. ## Accede a páginas protegidas sin exponer credenciales Como el renderizado ejecuta un navegador real, Transloadit debe poder acceder a la página. Los documentos suelen estar protegidos mediante autenticación, lo que deja dos opciones viables. El parámetro `headers` pasa la autenticación con la solicitud, una opción adecuada para el acceso basado en tokens. Como alternativa, emite una URL firmada de corta duración que conceda acceso exactamente a un documento durante un periodo breve. La opción que debe evitarse es incluir credenciales en la cadena de consulta de la URL renderizada. Esas URL terminan en los registros y en el registro almacenado de lo que se renderizó y, a diferencia de un encabezado, pueden reutilizarse con suma facilidad si el registro llega a quedar expuesto. Autenticar con un encabezado en lugar de una cadena de consulta ``` { "steps": { "rendered": { "robot": "/html/convert", "url": "https://example.com/reports/q3", "format": "pdf", "wait_until": "networkidle", "headers": [ "Authorization: Bearer ${fields.token}" ] } } } ``` ### headers Transporta los tokens con la solicitud en lugar de incluirlos en la URL, por lo que no aparecen en los registros. ### URL firmadas de un solo uso Concede acceso a un solo documento durante un periodo breve cuando la autenticación mediante encabezados no está disponible. ### No usar nunca la cadena de consulta Las credenciales incluidas allí quedan registradas dondequiera que se almacene la URL renderizada. ## Haz que el documento reemitido sea idéntico al original Una factura es un registro legal, y la versión que un cliente recibe en marzo debe seguir renderizándose de forma idéntica en noviembre. Dos prácticas permiten conseguirlo. Renderiza desde la URL de una plantilla con control de versiones para que un cambio de diseño posterior no pueda alterar un documento ya emitido, y almacena el archivo resultante en lugar de volver a generarlo bajo demanda. Conviene gestionar explícitamente los documentos formados por varias partes. `/document/merge` combina las páginas renderizadas en un solo archivo dentro de la misma Assembly, lo que mantiene un orden determinista y evita recurrir a un segundo servicio al que se deba dar acceso a las partes. Combinar documentos de varias partes dentro de una Assembly ``` { "steps": { "cover": { "robot": "/html/convert", "url": "https://example.com/stmt/cover?v=3", "format": "pdf", "wait_until": "networkidle" }, "detail": { "robot": "/html/convert", "url": "https://example.com/stmt/detail?v=3", "format": "pdf", "wait_until": "networkidle" }, "statement": { "use": ["cover", "detail"], "robot": "/document/merge" } } } ``` ### Versionar la plantilla Un cambio de diseño debe producir documentos nuevos, no modificar retroactivamente los ya emitidos. ### Almacenar, no volver a generar Conserva el archivo producido para que una reemisión sea una copia y no un nuevo renderizado. ### /document/merge Combina documentos de varias partes en una Assembly con un orden determinista. ## Mantén predecible el costo de renderizar Renderizar una página es más costoso que convertir un formato, porque se inicia un navegador, se obtienen subrecursos y se espera a que la página se estabilice. Ese costo es razonable para un documento solicitado por un cliente, pero supone un desperdicio cuando el mismo estado de cuenta se vuelve a renderizar cada vez que alguien abre una vista de lista. La solución habitual es renderizarlo una vez cuando el documento pasa a ser definitivo y luego entregar el archivo almacenado. La generación masiva requiere un tratamiento separado. Una ejecución de fin de mes que produzca miles de estados de cuenta no debe competir con el renderizado que espera un cliente, y un `delay` fijo aplicado a todo el lote se multiplica hasta representar tiempo y dinero considerables. Medir el costo por documento emitido, en lugar de por Assembly, suele revelar rápidamente estos patrones. ### Renderizar al finalizar Produce el archivo cuando el documento pase a ser definitivo, no cada vez que se visualice. ### Separar las ejecuciones masivas Mantén los lotes de fin de mes separados de los renderizados que una persona está esperando. ### Auditar los retrasos fijos Una pausa de un segundo es imperceptible una sola vez, pero costosa al aplicarla a diez mil documentos. ## Verifica el documento antes de que lo vea un cliente Un renderizado puede completarse correctamente y aun así ser incorrecto. El Robot devuelve un PDF válido independientemente de que el gráfico se haya dibujado o no, por lo que una comprobación que solo verifique si se produjo un archivo no detectará una página en blanco. Algunas verificaciones sencillas permiten detectar la mayoría de estos problemas: un tamaño en bytes plausible, la cantidad esperada de páginas y la presencia de una cadena conocida, como el número del documento. Durante el desarrollo, renderizar en `png` junto con el PDF permite hacer una comprobación visual rápida y fácil de evaluar a simple vista durante la revisión. Además, comparar un nuevo renderizado con una imagen de referencia almacenada permite detectar regresiones de diseño que una comprobación del tamaño en bytes no puede identificar. Ninguna de estas prácticas corresponde a la ruta de producción, pero conviene incluir ambas en el pipeline que publica los cambios de las plantillas. ### Verificar el contenido, no la existencia Comprueba la cantidad de páginas y un identificador conocido, no solo que exista un archivo. ### Renderizar imágenes para revisión Un `png` de la misma página permite revisar de un vistazo los cambios de la plantilla. ### Comparar con una referencia La comparación visual detecta regresiones de diseño que las comprobaciones de tamaño no identificarán. ## Detalles técnicos que conviene conocer * El parámetro format acepta jpeg, jpg, pdf y png. Solo pdf produce un documento; los demás capturan una imagen de la página. * El parámetro omit\_background se aplica a la salida de imagen y no tiene efecto cuando format es pdf, por lo que la transparencia no puede conservarse en el documento. * El parámetro wait\_until se corresponde con el estado de carga subyacente del navegador, que es la forma confiable de esperar a que se carguen las fuentes, los gráficos y los datos de carga tardía antes de tomar la instantánea. * El parámetro delay añade una pausa fija después de alcanzar el estado de carga. Es un mecanismo poco específico que aumenta el costo y la latencia de cada renderizado, por lo que debes preferir un valor de wait\_until más específico cuando sea posible. * Una factura renderizada es un registro legal. Renderizarla desde la URL inmutable de una plantilla y almacenar el archivo resultante, en lugar de volver a generarlo bajo demanda, mantiene una copia reemitida idéntica al original. * Como el renderizado ejecuta un navegador real, Transloadit debe poder acceder a la página. Las páginas protegidas por una cookie de sesión necesitan una URL firmada de un solo uso o que las credenciales se transmitan mediante el parámetro headers. ## Un enfoque práctico 1. 1\ Crea el documento como una página normal con una hoja de estilos de impresión y verifícalo primero en un navegador. 2. 2\ Renderízalo con /html/convert mediante el formato pdf y un wait\_until explícito. 3. 3\ Almacena el resultado en tu propio bucket junto con los identificadores que lo generaron. 4. 4\ Combina las páginas complementarias en un solo archivo con /document/merge cuando el documento tenga varias partes. Un flujo de trabajo multimedia de cuatro etapas ## Cuándo resulta útil Transloadit Usa /html/convert con el formato pdf cuando el documento ya exista como página web o pueda renderizarse como tal. Indica una url, o sube el HTML y deja que el Robot renderice el archivo subido. Combínalo con /document/merge cuando varias páginas deban formar un solo archivo. ## Límite de la arquitectura /html/convert renderiza una página con un navegador sin interfaz gráfica, por lo que produce una copia visual paginada en lugar de un PDF etiquetado y accesible. Los documentos que necesiten una estructura seleccionable, campos de formulario o formatos de archivo a largo plazo como PDF/A deben generarse con un generador de documentos específico. ## Preguntas frecuentes ### ¿Por qué faltan gráficos o fuentes en mi PDF? Es casi seguro que la instantánea se tomó antes de que esos elementos terminaran de cargarse. Configura `wait_until` con un estado de carga que abarque la dependencia. Agrega `delay` solo si un estado de carga no puede expresarla, teniendo en cuenta que la pausa se cobra en cada renderizado. ### ¿Puedo generar un PDF con fondo transparente? No. `omit_background` afecta la salida de imagen y no tiene efecto cuando `format` es `pdf`. Si necesitas transparencia, renderiza a `png` y coloca esa imagen en un documento. ### ¿Cómo renderizo una página que requiere iniciar sesión? Pasa la autenticación mediante el parámetro `headers` o emite una URL firmada de corta duración cuyo alcance se limite a un solo documento. Evita incluir credenciales en la cadena de consulta, porque la URL renderizada queda registrada dondequiera que se registre el renderizado. ### ¿El resultado es un PDF accesible y etiquetado? No. Un navegador sin interfaz gráfica produce una copia visual paginada, no un documento etiquetado con un orden de lectura, campos de formulario o conformidad con PDF/A. Ese tipo de requisitos necesita un generador de documentos específico, no el renderizado de una página. ### ¿Cómo combino varias páginas renderizadas en un solo archivo? Renderiza cada parte y pasa los resultados a /document/merge dentro de la misma Assembly. Mantener la combinación dentro de la Assembly hace que el orden sea determinista y evita conceder a otro servicio acceso a las partes individuales. ## Crea el flujo de trabajo Pasa del concepto a una Assembly probada con documentación de Robots y demos funcionales. ### Robots relevantes * [/html/convert](/es/docs/robots/html-convert.md) * [/document/merge](/es/docs/robots/document-merge.md) * [Lee la documentación de la API](/es/docs.md) * [Explora demos funcionales EN (English)](/demos.md) * [Crea un Workspace gratuito](/c/signup/) Automatización de flujos de trabajo ## Continúa con guías relacionadas * [Automatización de medios: de la subida a resultados confiables](/es/guides/media-automation.md)\ Automatiza la recepción, transformación, validación y exportación repetibles de medios, a la vez que preservas la observabilidad y el control. * [Guía completa de flujos de trabajo de recursos digitales](/es/guides/digital-asset-workflows.md)\ Diseña un flujo de trabajo de recursos digitales desde la recepción y el procesamiento hasta la revisión, publicación, retención y eliminación. * [Moderación de contenido con IA en un flujo de trabajo de subidas](/es/guides/ai-content-moderation-workflows.md)\ Integra la moderación con IA en un flujo de trabajo controlado de subidas, con umbrales de confianza y revisión humana. * [Moderación automatizada de contenido: diseño y gestión de fallos](/es/guides/automated-content-moderation.md)\ Crea una moderación automatizada por capas con comprobaciones de archivos, clasificadores, decisiones de política y colas de revisión. * [Análisis automatizado de imágenes: flujos de trabajo observables](/es/guides/automated-image-analysis.md)\ Convierte el análisis de imágenes en un flujo de trabajo asíncrono y repetible, en lugar de una solicitud que bloquee la aplicación.