1. IronPDF
  2. Guías
  3. Rellenar Formularios PDF

Cómo completar campos de formularios PDF en Node.js

Darrius Serrant
Darrius Serrant
Actualizado:
This article was translated from English: Does it need improvement?
Translated
View the article in English

Llenar formularios PDF programáticamente en Node.js te permite automatizar flujos de trabajo de documentos: desde completar formularios de aplicación con registros de bases de datos hasta generar certificados personalizados a escala. IronPDF for Node.js proporciona una API sencilla para cargar PDFs existentes, escribir valores en los campos de un formulario y guardar los documentos completados sin salir de tu entorno de JavaScript.

Esta guía cubre el flujo de trabajo completo: instalar el paquete, aplicar una clave de licencia, completar campos de texto, casillas de verificación, menús desplegables y botones de opción, aplanar los campos del formulario para bloquear los valores y guardar el resultado. Todos los ejemplos de código utilizan await y el paquete @ironsoftware/ironpdf.

Inicio rápido: Completar un formulario PDF en Node.js

Instala el paquete, luego carga y completa un formulario en unas pocas líneas:

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/install.sh
npm install @ironsoftware/ironpdf
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/install.sh
npm install @ironsoftware/ironpdf
SHELL
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/quickstart.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = "YOUR-LICENSE-KEY-HERE";

(async () => {
    const pdf = await PdfDocument.fromFile("./form.pdf");
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("email", "jane@example.com");
    await pdf.saveAs("./filled-form.pdf");
})();
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/quickstart.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = "YOUR-LICENSE-KEY-HERE";

(async () => {
    const pdf = await PdfDocument.fromFile("./form.pdf");
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("email", "jane@example.com");
    await pdf.saveAs("./filled-form.pdf");
})();
JAVASCRIPT

Flujo de trabajo mínimo (5 pasos)

1. Instalar IronPDF: `npm install @ironsoftware/ironpdf` 2. Establece tu clave de licencia a través de `IronPdfGlobalConfig.getConfig().licenseKey` 3. Carga el PDF existente con `PdfDocument.fromFile(path)` 4. Establece cada valor de campo con `await pdf.setFormFieldValue(fieldName, value)` 5. Guarda el resultado con `await pdf.saveAs(outputPath)`

¿Qué requisitos previos necesito para completar formularios PDF en Node.js?

Antes de ejecutar los siguientes ejemplos de código, confirma que tres cosas están en su lugar: una versión compatible de Node.js, una clave de licencia de IronPDF y el binario IronPdfEngine.

Versión de Node.js: IronPDF requiere Node.js 18 o superior. Descarga la versión actual de LTS desde el sitio web oficial de Node.js. La biblioteca utiliza I/O asincrónico de Node.js para todas las operaciones PDF, por lo que await o el encadenamiento de Promises es el patrón estándar en todo. Las versiones antiguas de Node.js no son compatibles porque el paquete depende de características nativas ESM y async_hooks que requieren Node.js 18+.

Clave de licencia: una clave de licencia activa de IronPDF desbloquea la API completa. Inicia una prueba gratuita para obtener una clave para el desarrollo y la prueba o compra una licencia para su uso en producción. Para opciones de implementación (variables de entorno, archivos de configuración, gestores de secretos), consulta la guía Usando Claves de Licencia.

IronPdfEngine: El paquete de Node.js incluye IronPdfEngine, un motor de renderizado multiplataforma que maneja la manipulación real del PDF. Las notas de configuración y específicas de la plataforma (Windows, Linux, macOS) se encuentran en la documentación Usar IronPdfEngine.

¿Cómo configuro la clave de licencia en el código de Node.js?

Aplica la clave de licencia una vez al iniciar la aplicación, antes de cualquier llamada PdfDocument:

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/license-setup.js
const { IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

// Apply once at startup -- before any PdfDocument operations
IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/license-setup.js
const { IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

// Apply once at startup -- before any PdfDocument operations
IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;
JAVASCRIPT

Almacenar la clave en una variable de entorno (como se muestra arriba con process.env.IRONPDF_LICENSE_KEY) mantiene las credenciales fuera del control de fuente. La Descripción general para empezar cubre patrones de inicialización adicionales para diferentes entornos de despliegue.

¿Cómo instalo IronPDF for Node.js?

Instalar IronPDF for Node.js toma un solo comando de npm. Ejecuta el comando en tu directorio de proyecto:

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/install-full.sh
npm install @ironsoftware/ironpdf
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/install-full.sh
npm install @ironsoftware/ironpdf
SHELL

El paquete se entrega con declaraciones de tipo TypeScript, por lo que los proyectos TypeScript obtienen soporte IntelliSense completo sin un paquete @types separado. Los binarios específicos de la plataforma para Windows, Linux y macOS se descargan automáticamente durante la instalación. El paquete @Iron Software/ironpdf en npm lista todas las versiones publicadas y dependencias de pares.

Por favor notaPara proyectos TypeScript, las declaraciones .d.ts incluidas significan que IntelliSense funciona de inmediato en VS Code y otros editores que soportan servicios de lenguaje TypeScript.

Para instrucciones sobre cómo añadir IronPDF a un monorepo existente o flujo de trabajo basado en Docker, consulta la documentación de IronPDF for Node.js.

¿Cómo rellenar formularios PDF mediante programación?

Cargar un PDF y escribir valores en sus campos de formulario requiere tres llamadas async: PdfDocument.fromFile(), setFormFieldValue(), y saveAs(). El ejemplo siguiente llena un formulario de aplicación de varios campos y opcionalmente lo aplana para que los valores no puedan cambiarse después de la entrega.

¿Cómo se ve un ejemplo completo de llenado de formularios?

El siguiente ejemplo carga un PDF con varios tipos de campos, los llena y guarda el resultado. Para un enfoque centrado en crear formularios en lugar de llenarlos, consulta la página de ejemplos de formularios PDF.

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/fill-pdf-form.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillApplicationForm() {
    // Load the PDF containing form fields
    const pdf = await PdfDocument.fromFile("./forms/application-form.pdf");

    // Discover available field names before filling
    const fieldNames = await pdf.getFormFieldNames();
    console.log("Form fields:", fieldNames);

    // Text fields
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("lastName", "Doe");
    await pdf.setFormFieldValue("email", "jane.doe@example.com");
    await pdf.setFormFieldValue("phone", "+1-555-987-6543");

    // Date field
    await pdf.setFormFieldValue("dateOfBirth", "03/22/1988");

    // Casilla de verificación fields -- pass "true" or "false" as strings
    await pdf.setFormFieldValue("agreeToTerms", "true");
    await pdf.setFormFieldValue("subscribeNewsletter", "false");

    // Dropdown / select field
    await pdf.setFormFieldValue("country", "United States");

    // Multi-line text area
    await pdf.setFormFieldValue("comments", "Application submitted via automated workflow.");

    // Flatten the form to lock values -- prevents further editing
    // await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/filled-application.pdf");
    console.log("Form saved.");
}

fillApplicationForm().catch(console.error);
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/fill-pdf-form.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillApplicationForm() {
    // Load the PDF containing form fields
    const pdf = await PdfDocument.fromFile("./forms/application-form.pdf");

    // Discover available field names before filling
    const fieldNames = await pdf.getFormFieldNames();
    console.log("Form fields:", fieldNames);

    // Text fields
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("lastName", "Doe");
    await pdf.setFormFieldValue("email", "jane.doe@example.com");
    await pdf.setFormFieldValue("phone", "+1-555-987-6543");

    // Date field
    await pdf.setFormFieldValue("dateOfBirth", "03/22/1988");

    // Casilla de verificación fields -- pass "true" or "false" as strings
    await pdf.setFormFieldValue("agreeToTerms", "true");
    await pdf.setFormFieldValue("subscribeNewsletter", "false");

    // Dropdown / select field
    await pdf.setFormFieldValue("country", "United States");

    // Multi-line text area
    await pdf.setFormFieldValue("comments", "Application submitted via automated workflow.");

    // Flatten the form to lock values -- prevents further editing
    // await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/filled-application.pdf");
    console.log("Form saved.");
}

fillApplicationForm().catch(console.error);
JAVASCRIPT

Después de llamar a getFormFieldNames(), el array devuelto te indica qué nombres de campo utilizó el autor del PDF. Esta es la forma más rápida de evitar errores tipográficos en los nombres de campo al integrar con formularios que no creaste.

ConsejosLlame a getFormFieldNames() una vez durante el desarrollo para imprimir los nombres de campo exactos en su PDF. Codificar erróneamente el nombre es la causa más común de que los campos aparezcan vacíos después de setFormFieldValue().

¿Cómo manejo diferentes tipos de campos de formulario?

IronPDF soporta los tipos estándar de campos AcroForm: cuadros de texto, casillas de verificación, botones de opción, menús desplegables, cuadros de lista y campos de firma. El método setFormFieldValue() acepta valores de tipo cadena para todos los tipos; para los campos de casillas de verificación y radio, los valores aceptados dependen de la definición específica del campo en el PDF.

La tabla a continuación muestra el formato del valor para cada tipo de campo:

Tipos de campos AcroForm en PDF y sus formatos de valor aceptados
Tipo de campoFormato de ValorEjemplo
Texto / MultilíneaCualquier cadena"Jane Doe"
Casilla de verificación"true" o "false""true"
Botón de OpciónValor de exportación de la opción"Female"
Desplegable (Combo)Texto de visualización de la opción"United States"
Cuadro de lista (selección múltiple)Array de cadenas["Option1", "Option2"]
Fecha / NuméricoRepresentación de cadena"2024-06-15"

¿Cómo funcionan las casillas de verificación y los botones de opción?

Las casillas aceptan "true" para marcar y "false" para desmarcar. Los botones de opción aceptan el valor exportado de la opción para seleccionar; la cadena exportada suele ser visible en las propiedades del campo del PDF y es distinta de la etiqueta de visualización.

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/field-types.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function handleFieldTypes() {
    const pdf = await PdfDocument.fromFile("./forms/complex-form.pdf");

    // Radio button -- use the field's export value, not its display label
    await pdf.setFormFieldValue("gender", "Female");

    // Casilla de verificación
    await pdf.setFormFieldValue("termsAccepted", "true");

    // Dropdown
    await pdf.setFormFieldValue("preferredContact", "Email");

    // Numeric field -- pass the number as a string
    await pdf.setFormFieldValue("invoiceAmount", "1250.00");

    // Date picker
    await pdf.setFormFieldValue("appointmentDate", "2024-06-15");

    await pdf.saveAs("./output/complex-form-filled.pdf");
}

handleFieldTypes().catch(console.error);
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/field-types.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function handleFieldTypes() {
    const pdf = await PdfDocument.fromFile("./forms/complex-form.pdf");

    // Radio button -- use the field's export value, not its display label
    await pdf.setFormFieldValue("gender", "Female");

    // Casilla de verificación
    await pdf.setFormFieldValue("termsAccepted", "true");

    // Dropdown
    await pdf.setFormFieldValue("preferredContact", "Email");

    // Numeric field -- pass the number as a string
    await pdf.setFormFieldValue("invoiceAmount", "1250.00");

    // Date picker
    await pdf.setFormFieldValue("appointmentDate", "2024-06-15");

    await pdf.saveAs("./output/complex-form-filled.pdf");
}

handleFieldTypes().catch(console.error);
JAVASCRIPT

Los campos de cuadro de lista de selección múltiple siguen el mismo patrón. Cuando un campo permite múltiples selecciones, pase un array de cadenas en lugar de un solo valor. Los campos de firma pueden recibir una cadena de imagen codificada en base64 que representa el gráfico de la firma.

ImportanteSi setFormFieldValue() no parece cambiar el valor de un campo, verifica que el nombre del campo coincida exactamente -- Los nombres de campo PDF distinguen entre mayúsculas y minúsculas. Usa getFormFieldNames() para listar los nombres reales en el documento.

¿Cómo aplano los campos de formulario PDF después de llenarlos?

Aplanar un formulario PDF fusiona todos los valores de los campos en el contenido estático de la página, eliminando la capa interactiva. El documento resultante no se puede editar más, lo que previene cambios accidentales durante la distribución y asegura una representación consistente en todos los visores PDF.

Llama a flattenAllFormFields() en el documento cargado después de establecer todos los valores de campo y antes de guardar:

//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/flatten-form.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillAndFlattenForm() {
    const pdf = await PdfDocument.fromFile("./forms/contract.pdf");

    // Fill the required fields
    await pdf.setFormFieldValue("signerName", "Jane Doe");
    await pdf.setFormFieldValue("signatureDate", "2024-06-15");
    await pdf.setFormFieldValue("agreementAccepted", "true");

    // Flatten -- converts interactive fields to static content
    await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/contract-signed.pdf");
    console.log("Contract flattened and saved.");
}

fillAndFlattenForm().catch(console.error);
//:path=/static-assets/pdf/content-code-examples/nodejs/how-to/nodejs-fill-pdf-form/flatten-form.js
const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillAndFlattenForm() {
    const pdf = await PdfDocument.fromFile("./forms/contract.pdf");

    // Fill the required fields
    await pdf.setFormFieldValue("signerName", "Jane Doe");
    await pdf.setFormFieldValue("signatureDate", "2024-06-15");
    await pdf.setFormFieldValue("agreementAccepted", "true");

    // Flatten -- converts interactive fields to static content
    await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/contract-signed.pdf");
    console.log("Contract flattened and saved.");
}

fillAndFlattenForm().catch(console.error);
JAVASCRIPT

Aplanar es apropiado para entregas finales: contratos después de firmar, certificados después de emitir o facturas después de aprobar. Para documentos que necesitan revisión adicional antes de la finalización, omite flattenAllFormFields() y guarda sin él.

AdvertenciaEl aplanado es irreversible en la copia guardada. Guarde el PDF original sin llenar como una plantilla si necesita regenerar el documento.

¿Cuáles son los casos de uso comunes para la automatización de formularios PDF?

El llenado automatizado de formularios elimina la entrada manual de datos en flujos de trabajo de documentos de alto volumen. Los siguientes escenarios cubren los patrones más frecuentes que los desarrolladores implementan con IronPDF.

Procesamiento de solicitudes: Extraiga datos de solicitantes de una base de datos o API REST y complete formularios PDF para servicios financieros, seguros o flujos de trabajo de recepción gubernamental. Combine formularios llenados utilizando el ejemplo Fusionar PDFs para producir un solo paquete de envío de varias páginas.

Generación de facturas y recibos: Complete plantillas de facturas con datos de líneas de ítems, detalles del cliente y totales calculados. Agregue encabezados y pies de página utilizando las técnicas mostradas en el ejemplo Encabezados y Pies de Página HTML.

Generación de certificados y credenciales: Personalice plantillas de certificados con nombres de destinatarios, fechas de finalización y títulos de cursos. Agregue seguridad utilizando el ejemplo Firmas Digitales para evitar manipulaciones después de la emisión. El estándar PDF/A es comúnmente requerido para archivo a largo plazo de certificados en industrias reguladas.

Generación de informes: Complete plantillas de informes con datos analíticos o resultados de encuestas. Para casos donde necesita construir el diseño del PDF desde cero en lugar de llenar un formulario existente, vea el tutorial HTML a PDF.

¿Cuáles son los próximos pasos para llenar formularios PDF en Node.js?

Esta guía demostró cómo cargar un PDF, llenar campos de texto, casillas de verificación, desplegables y botones de radio, aplanar el formulario para bloquear valores y guardar el documento completo. La misma instancia PdfDocument soporta más operaciones -- agrega firmas digitales, comprime el resultado o extrae texto -- sin volver a cargar el archivo.

Inicie una prueba gratuita para probar IronPDF en su proyecto o vea las opciones de licencia para encontrar el plan que se ajuste a su implementación.

¿Listo para ver qué más puedes hacer? Explore la colección completa de tutoriales de Node.js aquí: HTML a PDF en Node.js

Preguntas Frecuentes

¿Qué requisitos previos necesito para rellenar formularios PDF en Node.js?

Necesitas Node.js 18 o superior, una clave de licencia de IronPDF (se ofrece una prueba gratuita), y el binario IronPdfEngine. El motor está incluido en el paquete @ironsoftware/ironpdf y se descarga automáticamente durante la instalación.

¿Cómo se instala IronPDF for Node.js?

Ejecuta npm install @ironsoftware/ironpdf en tu directorio de proyecto. El comando instala el paquete y sus binarios específicos de plataforma para Windows, Linux y macOS. Se incluyen declaraciones de tipo para TypeScript.

¿Cómo descubro los nombres de los campos en un formulario PDF?

Llama a await pdf.getFormFieldNames() después de cargar el PDF con PdfDocument.fromFile(). El método devuelve un arreglo de todos los nombres de campo en el documento. Los nombres de los campos PDF son sensibles a mayúsculas, así que usa las cadenas exactas que se devuelven.

¿Qué formato de valor aceptan las casillas de verificación y los botones de opción?

Las casillas de verificación aceptan la cadena "true" para marcar y "false" para desmarcar. Los botones de opción aceptan el valor de exportación de la opción objetivo como una cadena. Usa getFormFieldNames() e inspecciona las propiedades del campo PDF para encontrar el valor de exportación correcto.

¿Cómo evito que un formulario PDF rellenado sea editado?

Llama a await pdf.flattenAllFormFields() después de establecer todos los valores de los campos y antes de saveAs(). Aplanar fusiona los valores de los campos en el contenido de página estático y elimina la capa de formulario interactivo. La operación es irreversible en el archivo guardado.

¿Puedo usar IronPDF for Node.js con TypeScript?

Sí. El paquete @ironsoftware/ironpdf viene con declaraciones de TypeScript (.d.ts files), así que obtienes verificación de tipos completa e IntelliSense en VS Code y otros editores sin instalar un paquete de tipos por separado.

Darrius Serrant
Darrius Serrant
  Chatea con el equipo de ingeniería ahora
Ingeniero de Software Full Stack (WebOps)

Darrius Serrant tiene una licenciatura en Ciencias de la Computación de la Universidad de Miami y trabaja como Ingeniero de Marketing WebOps Full Stack en Iron Software. Atraído por la programación desde joven, vio la computación como algo misterioso y accesible, convirtiéndolo en el ...

Leer más
¿Listo para empezar?
Versión: 2026.5 just released
Still Scrolling Icon

¿Aún desplazándote?

¿Quieres una prueba rápida?
ejecutar una muestra Mira cómo tu HTML se convierte en PDF.