Crear un documento multipágina con NextPDF Connect

De un vistazo

Crear un documento de varias páginas con NextPDF Connect. add_page añade una página que hereda la geometría predeterminada del documento o permite anular la orientación. Después de cada add_page, el cursor vuelve al margen superior izquierdo de la nueva página. Se utilizan cuatro herramientas, todas de Core: create_pdf, add_text, add_page y output_pdf.

Instalación

composer require nextpdf/server

Enlazar un transporte: MCP stdio, REST o gRPC. No se requiere ningún nivel de licencia.

Descripción conceptual

Un documento es un árbol de páginas. Cada página es un nodo accesible a través de ese árbol (ISO 32000-2 §7.7.3). Cada página incluye sus propios atributos de geometría, incluido el cuadro de medios que define el área visible (ISO 32000-2 §7.7.3.3). create_pdf crea automáticamente la primera página, y add_page añade las páginas siguientes. Omitir page_size/orientation para heredar el valor predeterminado del documento. Definir orientation: "landscape" para girar una página A4 a 297×210 mm.

Superficie de la API

Herramienta	Función	Nivel de riesgo
`create_pdf`	Abre la sesión; crea la primera página	Seguro
`add_text`	Escribe texto en la posición del cursor	Precaución
`add_page`	Añade una página (con herencia o anulación)	Precaución
`output_pdf`	Representa y devuelve el PDF	Aprobación requerida / Revisión (base64)

Los nombres de las herramientas corresponden a los nombres de protocolo del registro. El catálogo de herramientas es el catálogo de referencia. Las herramientas disponibles dependen del nivel instalado.

Ejemplo de código — Inicio rápido

En palabras:

create_pdf (A4 en vertical, título, autor) → document_id.
add_text (título, fuente grande, centrado) y luego add_text (párrafo de introducción, fuente de cuerpo).
add_page con solo el document_id → hereda A4 en vertical. Se devuelve el nuevo page_number y el cursor se reinicia.
add_text para el encabezado de sección y el cuerpo en la página 2.
add_page con orientation: "landscape" → una página A4 apaisada.
add_text para el contenido en orientación apaisada.
output_pdf → base64.

Ejemplo de código — Producción

Validar cada respuesta. Después de add_page, asumir que el contenido empieza en la parte superior de la nueva página. El reinicio del cursor es un comportamiento previsto, no un defecto. Hacer seguimiento de position.page en las respuestas de add_text para detectar cuándo el contenido ha pasado a una página posterior. Llamar a output_pdf exactamente una vez y, a continuación, descartar el document_id.

Casos límite y trampas

Reinicio del cursor. Después de add_page, el cursor queda situado en el margen superior izquierdo de la nueva página. Esperar que siga desde la página anterior es el error más habitual.
document_id obligatorio. Todas las herramientas excepto create_pdf requieren el document_id. Omitirlo es un error.
Orientación no válida. Solo "portrait" y "landscape" son válidos.
Edición después de la salida. El contenido añadido después de output_pdf con destroy: true falla porque la sesión ya no existe.

Rendimiento

Un documento de texto de varias páginas queda dentro del presupuesto de páginas y la salida ocupa unos pocos KB. El perfil es structural: el /ID del tráiler y las marcas de tiempo no son estables entre ejecuciones.

Notas de seguridad

El modo base64 no tiene efectos secundarios. La salida a archivo está sujeta a control (sección HITL). El document_id es un identificador opaco. No compartirlo entre solicitudes concurrentes.

Conformidad

Declaración	Especificación	Cláusula	reference_id
Se accede a las páginas a través del árbol de páginas.	ISO 32000-2	§7.7.3
Un objeto de página define sus propios atributos de geometría.	ISO 32000-2	§7.7.3.3

Contexto comercial

No aplicable — todas las herramientas son de Core.

Disponibilidad de transportes

Transporte	Disponible	Notas
MCP (stdio)	Sí	`tools/call` por herramienta.
REST	Sí	Una operación por herramienta.
gRPC	Sí	Unario por herramienta.

Nivel de riesgo HITL

create_pdf es Seguro; add_text y add_page son Precaución; output_pdf es Aprobación requerida, que pasa a Revisión en el modo base64. La salida a archivo conserva Aprobación requerida. Consultar output-approval y niveles de riesgo HITL.

Envoltorio JSON de la puerta de confirmación

Salida base64 en este caso:

{ "allowed": true }

El formulario de desafío se muestra en output-approval.