Descripción general de NextPDF Gotenberg

De un vistazo

NextPDF Gotenberg es un puente ligero entre NextPDF y el servicio externo Gotenberg. Toma un documento de Office que NextPDF no puede representar de forma nativa, lo envía a una instancia de Gotenberg por HTTP, recibe como respuesta un PDF y lo entrega a la aplicación. A partir de ahí, el resto de la funcionalidad de NextPDF se encarga del posprocesamiento.

El paquete es compacto y explícito. No incorpora un motor de representación, no inicia LibreOffice y no ejecuta un navegador. Cada conversión es una única petición HTTP multipart a un punto de conexión de Gotenberg. Ese punto de conexión se opera por separado, y el puente se dirige hacia él mediante la configuración.

Conviene usar este puente cuando se trabaje con archivos de origen .docx, .xlsx, .pptx, .odt, .ods o .odp y se quiera obtener un PDF dentro de un flujo de NextPDF. Todo lo que ocurre una vez creado el PDF —firma, conversión a PDF/A, marca de agua, fusión— se ejecuta a través del propio NextPDF o del paquete nextpdf/premium.

De qué depende el puente

El puente tiene una dependencia de tiempo de ejecución que no es un paquete de PHP: un servicio de Gotenberg en ejecución al que el puente pueda llegar por HTTPS.

El puente no instala, gestiona ni supervisa Gotenberg. Gotenberg se despliega por separado (el proyecto original publica una imagen de contenedor), y su disponibilidad, capacidad y exposición de red quedan bajo responsabilidad de la aplicación operadora.
El puente se comunica con la ruta de conversión de LibreOffice de Gotenberg. La URL de la petición se construye como <apiUrl>/forms/libreoffice/convert, donde <apiUrl> es la URL base configurada. Esta ruta define el conjunto de formatos admitidos para el puente.
La comprobación de estado apunta a <apiUrl>/health con una petición HTTP HEAD y considera disponible cualquier estado inferior a 500.

La conversión ocurre en un servicio operado fuera del puente, por lo que su comportamiento depende de la versión de Gotenberg que se ejecute. El puente envía una estructura fija de petición multipart, y la ruta de conversión (/forms/libreoffice/convert) y la ruta de estado (/health) son el único contrato del lado de Gotenberg que asume. Consultar /integrations/gotenberg/install/ para conocer la base de despliegue y /integrations/gotenberg/security-and-operations/ para reforzar el servicio.

Formatos de documento admitidos

El puente convierte exactamente los formatos enumerados en el tipo OfficeFormat. Cada formato se detecta a partir de la extensión del archivo (sin distinguir mayúsculas de minúsculas y con tolerancia a un punto inicial). A continuación, cada formato se envía a Gotenberg con un tipo MIME fijo:

Formato	Extensión	Tipo MIME enviado a Gotenberg
Word (OOXML)	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel (OOXML)	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint (OOXML)	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

Esta lista es exhaustiva. Una extensión fuera de este conjunto genera un ValueError antes de que se realice cualquier petición de red, de modo que el puente nunca intenta convertir un formato que no puede describir. El puente no afirma admitir «cualquier archivo de Office» ni «todos los formatos de documento». Admite los seis formatos anteriores, porque son los seis que el código reconoce y los seis cubiertos por la suite de pruebas.

Los formatos binarios heredados (.doc, .xls, .ppt), el texto enriquecido (.rtf), el texto sin formato, el CSV y los formatos de imagen no forman parte del conjunto reconocido por el puente. La propia ruta de LibreOffice de Gotenberg puede aceptar un conjunto más amplio de entradas. El puente se limita deliberadamente al conjunto enumerado para que la detección de formato, el tipo MIME y los metadatos del resultado sean siempre coherentes y verificables.

Cómo fluye una conversión

Una conversión es una secuencia lineal única. Valida cada paso antes de que cualquier byte salga del proceso:

Se comprueba la configuración. Una URL de API vacía falla de inmediato con una excepción de conversión.
Se valida la URL de la API: se requiere HTTPS, y el host se resuelve y se examina para que no pueda apuntar a una dirección privada o reservada. El conjunto de direcciones resueltas se captura para su posterior fijación.
Se lee la entrada (en las conversiones de archivo, primero se canoniza la ruta para bloquear el traversal) y su extensión se asigna a un OfficeFormat.
Se comprueba la longitud en bytes frente al máximo configurado, y el nombre de archivo se examina en busca de secuencias de traversal, barras, bytes nulos y caracteres de control.
El conjunto de direcciones se vuelve a comprobar inmediatamente antes de la petición para cerrar la brecha entre la validación y la conexión.
Se construye un cuerpo multipart/form-data y se envía por POST a la ruta de LibreOffice, con un token bearer si se ha configurado uno.
Se analiza la respuesta: el estado debe ser 200, el Content-Type debe contener application/pdf, y el cuerpo debe comenzar con la firma %PDF. Solo entonces se devuelve un resultado.

Cualquier fallo en los pasos 1-7 genera una excepción tipada, en lugar de devolver un resultado parcial o sin verificar. Las excepciones exactas y sus desencadenantes están catalogados en /integrations/gotenberg/troubleshooting/.

Qué se obtiene como resultado

Una conversión correcta devuelve un objeto de resultado. El objeto contiene los bytes en bruto del PDF, el formato de origen convertido y una medición opcional del tiempo de representación, y expone una comprobación de validez (un cuerpo no vacío que empieza por %PDF) junto con un descriptor de acceso al tamaño en bytes. Los bytes son un flujo de PDF normal, por lo que se pueden escribir en disco, transmitir a un cliente o introducir en un documento de NextPDF para su procesamiento posterior.

Dónde termina el alcance del puente

El puente convierte y valida. No realiza lo siguiente:

Firmar, cifrar, linealizar o convertir la salida a PDF/A. Esas son tareas de posprocesamiento que gestiona el núcleo de NextPDF o el paquete nextpdf/premium.
Reintentar peticiones fallidas, encolar trabajo o almacenar resultados en caché. Esas son tareas del nivel de aplicación. /integrations/gotenberg/production-usage/ muestra dónde añadirlas alrededor del puente.
Gestionar el ciclo de vida del servicio de Gotenberg. El despliegue y las operaciones se tratan en /integrations/gotenberg/security-and-operations/.

Ediciones y posprocesamiento

El núcleo de código abierto puede escribir el PDF convertido tal cual. Si se necesita firmar el documento convertido, producir un perfil de archivado PDF/A o aplicar una marca de agua, el paquete nextpdf/premium añade esas capacidades por encima. El puente en sí es neutral respecto de la edición: produce un PDF. Lo que se haga con ese PDF determina si se necesita una edición comercial.

La base PAdES disponible en la edición Pro es únicamente B-B. Los perfiles de validación a largo plazo (B-T, B-LT, B-LTA) no forman parte de la edición Pro y no los proporciona este puente. No inferir capacidades de marca de tiempo ni LTV a partir de la presencia de este paquete.

Véase también

/integrations/gotenberg/install/ — instalar el paquete y poner en marcha una base de Gotenberg.
/integrations/gotenberg/configuration/ — cada opción de configuración, con su tipo, valor predeterminado y efecto.
/integrations/gotenberg/quickstart/ — una primera conversión ejecutable.
/integrations/gotenberg/production-usage/ — integrar el puente en una aplicación real.
/integrations/gotenberg/troubleshooting/ — catálogo de excepciones y significado de cada una.
/integrations/gotenberg/security-and-operations/ — modelo de seguridad y operación segura del servicio del que se depende.
/integrations/gotenberg/boot-and-discovery/ — cómo los frameworks anfitriones descubren y conectan el puente.
/integrations/gotenberg/integration/ — control de la representación de NextPDF a través del servicio.