Rellenar un formulario PDF con NextPDF Connect (Pro)

Visión general

Rellenar los campos interactivos de un formulario PDF con XFDF (XML Forms Data Format) mediante NextPDF Connect. Para firmas y formularios, la herramienta es fill_form. El proveedor de herramientas Pro registra new FillFormTool(), cuyo nombre de protocolo es fill_form. fill_form es una herramienta de nivel Pro. Durante el arranque, el servidor comprueba la presencia del paquete Pro con class_exists() y registra la herramienta solo cuando el paquete está presente. En una instalación solo con Core, fill_form no figura en el registro.

Instalación

composer require nextpdf/server
composer require nextpdf/pro

Enlazar un transporte. Confirmar que la herramienta existe con diagnostic.capabilities (consulte environment-diagnostics). No asumir un conjunto fijo de herramientas.

Visión conceptual

XFDF asigna nombres de campo a valores mediante elementos <field>. Cada nombre debe coincidir con un campo AcroForm ya definido en el documento de destino. El diccionario de campos del formulario interactivo contiene cada campo (ISO 32000-2 §12.7), y el valor proporcionado pasa a ser el valor del campo (ISO 32000-2 §12.7). Un nombre que no coincide con ningún campo se omite en lugar de tratarse como error. La herramienta indica cuántos campos rellenó y cuántos omitió.

Superficie de la API

Herramienta	Nivel	Función	Nivel de riesgo
`create_pdf`	Core	Abrir una sesión	Seguro
`fill_form`	Pro	Aplicar valores XFDF a campos AcroForm	Precaución
`output_pdf`	Core	Representar y devolver el PDF	Aprobación requerida / Revisión (base64)

Los nombres de las herramientas son los nombres de protocolo del registro. El catálogo de herramientas es la referencia. El conjunto de herramientas disponibles depende del nivel instalado. Las herramientas Pro aparecen solo cuando el paquete Pro está instalado.

Ejemplo de código — Inicio rápido

create_pdf (o cargar una plantilla que ya tenga campos de formulario).
fill_form con xfdf_data que asigna nombres de campo a valores.
output_pdf → base64.

El resultado indica fields_filled, fields_skipped y los nombres de los campos coincidentes.

Ejemplo de código — Producción

Usar una plantilla cuyos nombres de campo AcroForm se controlen explícitamente. Validar el XFDF con el esquema XFDF antes de enviarlo. Revisar fields_skipped y la lista de nombres devuelta para detectar discrepancias de nombre (los nombres distinguen mayúsculas y minúsculas). Para operaciones de relleno grandes, mantenerse por debajo del límite de tamaño de XFDF y dividir los datos si es necesario.

Casos límite y problemas frecuentes

XFDF malformado. Un error de análisis indica la ubicación que lo causó. Escapar las entidades XML e incluir el xmlns.
Discrepancia de nombre. Un campo que no coincide se omite silenciosamente y fields_skipped se incrementa. Los nombres distinguen mayúsculas y minúsculas.
Sin campos de formulario. Un documento sin AcroForm produce cero campos rellenados.
XFDF demasiado grande. El servidor rechaza los datos que superan el límite de tamaño. Dividirlos o recortar los espacios en blanco.
Pro ausente. En una instalación solo con Core, fill_form no está registrado y llamarlo devuelve un error de herramienta desconocida. Comprobarlo antes con diagnostic.capabilities.

Rendimiento

El relleno es rápido en comparación con la representación. La salida puede variar de unos pocos KB a decenas de KB, según el número de campos y la incrustación de fuentes. El perfil es structural.

Notas de seguridad

Los valores de los campos son contenido del documento. No incluir secretos en campos de formulario si después se devuelve el PDF por un canal no confiable. La ruta base64 no tiene ningún efecto secundario en el sistema de archivos. La salida a archivo está restringida.

Conformidad

Declaración	Especificación	Cláusula	reference_id
Un campo de formulario se conserva en el diccionario de campos del formulario interactivo.	ISO 32000-2	§12.7
Los datos proporcionados pasan a ser el valor del campo.	ISO 32000-2	§12.7

Contexto comercial

fill_form es una herramienta de nivel Pro. El servidor la registra solo cuando el paquete Pro se resuelve durante el arranque (la comprobación class_exists()). Las implementaciones Core no la exponen.

Disponibilidad por transporte

Transporte	Disponible	Notas
MCP (stdio)	Sí (Pro)	Presente solo cuando Pro está instalado.
REST	Sí (Pro)	Igual.
gRPC	Sí (Pro)	Igual.

Nivel de riesgo HITL

fill_form es Precaución porque es una mutación de contenido reversible. output_pdf es Aprobación requerida, y se reduce a Revisión en modo base64 (niveles de riesgo HITL).

Sobre JSON de la barrera de confirmación

Salida base64:

{ "allowed": true }

La salida a archivo devuelve el sobre de desafío descrito en output-approval.