PDF4me JavaScript SDK Empezando
El pdf4me paquete en npm es el oficial TypeScript/JavaScript ESM cliente para el PDF4me REST APIProporciona 106 acciones en 18 módulos: convierte, optimiza, fusiona, divide, estampa y extrae contenido de documentos con funciones asíncronas y resultados tipados. Los tipos se incluyen dentro del paquete, por lo que TypeScript Los proyectos no necesitan ser separados @types instalar.
Información del paquete
| Campo | Valor |
|---|---|
| Nombre del paquete | pdf4me |
| Versión actual | 10.0.1 (publicado el 14 de septiembre de 2026) |
| Licencia | MIT |
| Node.js apoyo | >=22, declarado en engines |
| Formato del módulo | ESM solo ("type": "module") |
| Tipos | Agrupado (dist/index.d.ts) |
| Efectos secundarios | Ninguno ("sideEffects": false) |
| Comportamiento | 106 en 18 subrutas de importación |
| dependencias de tiempo de ejecución | Cinco Microsoft Kiota paquetes (abstracciones más el JSONserializadores de formulario, texto y multipartes) |
| Fuente | github.com/pdf4me/pdf4me-clientapi-javascript |
| npm | npmjs.com/package/pdf4me |
Requisitos previos
- Node.js 22 años o más reciente.
- A PDF4me cuenta y API llave.
- Un proyecto que puede utilizar ESM
importsintaxis ("type": "module"en tupackage.json, o.mjsarchivos).
Instalar
- npm
- pnpm
- Yarn
npm install pdf4me@^10
pnpm add pdf4me@^10
yarn add pdf4me@^10
El ^10 El rango importa. Un ^9 el rango de dependencia será no Descarga la versión 10 por separado, ya que la versión 10 es una reescritura con cambios incompatibles. Ver Actualización desde la versión 9.x abajo.
:::advertencia Node.js Se requieren 22, pero npm solo advierte
engines declara node: ">=22"y por defecto npm emite una advertencia en lugar de un error en caso de discrepancia. Un proyecto aún en ejecución Node.js 18 instalará la versión 10 correctamente y luego fallará en tiempo de ejecución. Compruebe node --versionantes de realizar el envío.
:::
Para trabajar desde una copia de origen en lugar del registro, ejecute npm install y npm run build dentro del directorio del paquete, luego ejecute npm install /absolute/path/to/pdf4me desde el directorio de su aplicación.
Autenticar
Configura tu API clave en el entorno:
- Bash / Zsh
- PowerShell
- Windows CMD
export PDF4ME_API_KEY="your-api-key"
$env:PDF4ME_API_KEY = "your-api-key"
set PDF4ME_API_KEY=your-api-key
El cliente envía la clave como un Authorization: Basic <apiKey> encabezado en cada solicitud. La biblioteca no registra credenciales ni documenta el contenido. Construir un cliente con una clave en blanco genera un error. TypeError inmediatamente, antes de cualquier llamada de red.
Inicio rápido
Guardar esto como optimize-pdf.mjs y poner un input.pdf en el mismo directorio de trabajo. El ejemplo carga el PDF para optimización y guarda el resultado como optimized.pdf.
import { readFile, writeFile } from "node:fs/promises";
import { Pdf4meClient } from "pdf4me";
import { optimize } from "pdf4me/optimize";
const apiKey = process.env.PDF4ME_API_KEY;
if (!apiKey) {
throw new Error("Set PDF4ME_API_KEY before running this example.");
}
const client = new Pdf4meClient(apiKey);
const data = await readFile("input.pdf");
const result = await optimize(client, data, { docName: "input.pdf" });
await writeFile("optimized.pdf", result);
console.log("Saved optimized.pdf");
Ejecútalo con:
node optimize-pdf.mjs
Las mismas importaciones funcionan en TypeScript ESM proyectos, con tipos incluidos en el paquete.
Tres cosas a tener en cuenta:
- Un cliente, muchas acciones.
new Pdf4meClient(apiKey)mantiene la configuración.fetchposee el grupo de conexiones, por lo que no hayclose()método para llamar y nada que liberar cuando hayas terminado. - Las acciones son funciones independientes, no métodos del cliente. Cada uno se importa desde su propia subruta (
pdf4me/optimize,pdf4me/merge-split,pdf4me/edit) y llamado comoaction(client, source, options). - El orden de los argumentos es fijo. Primero el cliente reutilizable, luego el contenido de origen cuando la acción lo requiera, y por último un objeto de opciones.
Lo que exporta la raíz del paquete
La subruta raíz (pdf4me) contiene al cliente y sus tipos de soporte. Las acciones nunca residen aquí.
| Exportar | Amable | Objetivo |
|---|---|---|
Pdf4meClient | clase | Contiene el API Configuración de teclas y transporte; se pasa como primer argumento a cada acción. |
Pdf4meException | clase | Se lanza cuando el servicio devuelve un error. |
Pdf4meTimeoutError | clase | Se activa cuando se alcanza el límite de tiempo de una solicitud o trabajo. |
Pdf4meClientOptions | tipo | El objeto de opciones aceptado por el constructor del cliente |
DocumentSource | tipo | Uint8Array | string — la forma aceptada del contenido fuente |
DEFAULT_BASE_URL | constante | https://api.pdf4me.com |
DEFAULT_TIMEOUT | constante | 100000 |
DEFAULT_MAX_WAIT | constante | 300000 |
DEFAULT_POLL_INTERVAL | constante | 10000 |
Solicitudes y resultados
Cada acción se somete isAsync: true y espera el resultado final. Una inmediata HTTP 200 devoluciones inmediatamente. Un HTTP 202 devuelve un ID de trabajo, que el cliente luego consulta en GetActionStatus hasta que el trabajo termine. Tu código ve uno await de cualquier manera.
Lo que pasas en
DocumentSource es Uint8Array | string, que abarca cuatro formas prácticas:
| Formulario fuente | Notas |
|---|---|
Uint8Array | Incluye Node.js Buffer, que subclases Uint8ArrayLos bytes se codifican en base64 en bloques delimitados para que los documentos grandes no saturen la pila. |
| cadena base64 | Pasó directamente. |
pdf4meblobid://... | Una referencia al contenido que ya posee PDF4me. |
| URL | El servicio se encarga de obtener el documento. |
El contenido vacío se rechaza localmente con un TypeError en lugar de ser enviados.
Las acciones con múltiples entradas aceptan matrices ordenadas. addAttachmentToPdf es la excepción: se necesita un attachments Objeto que asigna nombres de archivo a contenido.
Lo que recibes a cambio
| Tipo de resultado | Tipo | Ejemplo |
|---|---|---|
| Acciones de archivo | Uint8Array | Aceptado directamente por Node.js writeFile |
| JSON acciones | Modelos tipificados | DocMetadata, SplitPdfRes |
Los modelos y las constantes de enumeración se exportan tanto desde el propio módulo de la acción como desde el pdf4me/models subruta. Los campos de respuesta desconocidos se conservan en additionalData, por lo que un nuevo API El campo nunca se abandona en silencio.
Dos llamadas más
import { merge } from "pdf4me/merge-split";
import { stamp, StampAlignX } from "pdf4me/edit";
const merged = await merge(client, [firstPdf, secondPdf]);
const stamped = await stamp(client, merged, {
text: "DRAFT",
alignX: StampAlignX.Center,
});
StampAlignX.Center es una constante tipificada, por lo que su editor autocompleta los valores válidos y tsc Detecta los errores tipográficos antes de que se envíe la solicitud.
Opciones y valores predeterminados
Todas las interfaces de opciones se exportan, por ejemplo OptimizeOptionsHay dos comportamientos que vale la pena conocer:
- Los valores predeterminados se aplican cuando se selecciona una opción. ausente. El perfil de optimización predeterminado es
Max. Un explícitonullhace no Seleccione una opción predeterminada. - Cada acción acepta
extra, un objeto serializado como campos de solicitud adicionales. Utilice el APInombres de campo propios, y evitar las claves que ya proporcionan las opciones de acción.
Configuración del cliente
const client = new Pdf4meClient(apiKey, {
baseUrl: "https://api.pdf4me.com",
timeout: 100_000,
maxWait: 300_000,
pollInterval: 10_000,
});
| Opción | Por defecto | Lo que limita |
|---|---|---|
baseUrl | https://api.pdf4me.com | El API host al que se envía cada solicitud |
timeout | 100000 EM | Cada solicitud individual, incluyendo la lectura de su cuerpo |
maxWait | 300000 EM | Sondeos posteriores a la presentación inicial del trabajo, incluidas las solicitudes de estado en curso. |
pollInterval | 10000 EM | El intervalo de reserva entre las comprobaciones de estado |
fetch | globalThis.fetch | Un transporte personalizado, útil para pruebas o configuración de proxy. |
Cada valor predeterminado también se exporta como una constante (DEFAULT_TIMEOUT y amigos), de modo que puedas escalar a partir del valor enviado en lugar de codificar un número fijo.
El constructor valida lo que se le pasa:
baseUrldebe ser unhttp:ohttps:URL Sin credenciales, cadena de consulta o fragmento. Cualquier otra cosa genera un error.TypeError.timeout,maxWait, ypollIntervalcada uno debe ser un número finito positivo de milisegundos no mayor que2147483647Cualquier otra cosa lanza unRangeError.
Numérico y HTTP-fecha Retry-After Los valores del servicio controlan la frecuencia de sondeo; pollInterval se utiliza solo cuando el servicio no envía uno. Si la siguiente encuesta llegara más allá del maxWait Ante la fecha límite, el cliente se rinde inmediatamente en lugar de gastar primero el presupuesto restante.
:::precaución: las redirecciones son rechazadas.
El cliente establece redirect: "error". Si enrutas el tráfico a través de un proxy que responde con un 3xx, apunta baseUrlen el destino final en lugar de depender de que se siga la redirección.
:::
Errores
| Lanzado | Cuando |
|---|---|
Pdf4meException | El servicio devolvió un error. message, responseStatusCode, traceId, y responseHeaders. |
Pdf4meTimeoutError | Un límite de tiempo para la solicitud (timeout) o un límite de tiempo de trabajo (maxWait) se alcanzó. |
TypeError | Entrada local no válida: un espacio en blanco API llave, una mala baseUrlo contenido de documento vacío. |
RangeError | Una opción de duración fuera del rango aceptado. |
Común Error | Un 202 cuyo cuerpo no portaba nada utilizable jobId, o un JSON acción que devolvió un resultado vacío. |
| Errores de red | Propagado desde fetch sin cambios. |
Pdf4meException.message se toma del propio servicio message campo cuando esté presente, retrocediendo al HTTP texto de estado. Citar el traceId Cuando te pones en contacto con el servicio de asistencia, se identifica el trabajo exacto que debes realizar.
import { Pdf4meException, Pdf4meTimeoutError } from "pdf4me";
import { optimize } from "pdf4me/optimize";
try {
const result = await optimize(client, data, { docName: "input.pdf" });
} catch (error) {
if (error instanceof Pdf4meTimeoutError) {
// The job exceeded maxWait. Retry, or raise maxWait for large documents.
} else if (error instanceof Pdf4meException) {
console.error(error.responseStatusCode, error.traceId);
} else {
throw error;
}
}
Los 18 módulos
Cada módulo es su propia subruta de importación, por lo que los empaquetadores y editores solo cargan lo que usted utiliza. El conjunto de paquetes "sideEffects": false, lo que permite a los empaquetadores descartar por completo los módulos no utilizados.
Algunas acciones se encuentran en un módulo que tal vez no adivinarías por el nombre: OCR está en find-search, PDF/A la creación está en convert, y pdf4me Contiene una única acción de hipervínculo. La tabla a continuación enumera todas las acciones exportadas para que no tengas que adivinar.
| Subruta de importación | Comportamiento | Funciones exportadas |
|---|---|---|
pdf4me/ai-document-extraction | 14 | aiDocumentParser, processBankCheque, processBankStatement, processContract, processCreditCard, processHealthCard, processInvoice, processMarriageCertificate, processMortgageDocument, processOrder, processPayStub, processReceipt, processShippingLabel, processTaxDocument |
pdf4me/barcode | 7 | addBarcode, createBarcode, createSwissQrBill, readBarcodes, readSwissQrBill, createEpcQrCode, readBarcodesFromImage |
pdf4me/convert | 13 | convertHtmlToPdf, convertJsonToExcel, convertMdToPdf, convertPdfToExcel, convertPdfToPowerpoint, convertPdfToWord, convertToPdf, convertUrlToPdf, convertVisio, convertWordToPdfForm, createPdfA, flattenPdf, linearizePdf |
pdf4me/edit | 7 | addAttachmentToPdf, addHtmlHeaderFooter, imageStamp, addMargin, addPageNumber, stamp, signPdf |
pdf4me/excel | 1 | findAndReplaceTextInExcel |
pdf4me/extract | 8 | classifyDocument, extractAttachmentFromPdf, extractPdfFormData, extractResources, extractTableFromPdf, extractTextByExpression, extractTextFromWord, parseDocument |
pdf4me/find-search | 2 | findAndReplace, convertOcrPdf |
pdf4me/forms | 2 | addFormField, fillPdfForm |
pdf4me/generate | 6 | enableTrackingChangesInWord, generateDocumentSingle, generateDocumentMultiple, getTrackingChangesInWord, replaceTextWithImageInWord, generateDocumentSingleV2 |
pdf4me/image | 13 | addImageWatermarkToImage, addTextWatermarkToImage, compressImage, convertImageFormat, createImages, cropImage, flipImage, getImageMetadata, imageExtractText, removeExifTagsFromImage, resizeImage, rotateImage, rotateImageByExifData |
pdf4me/merge-split | 5 | merge, mergeOverlay, splitPdf, splitPdfByBarcode, splitByText |
pdf4me/optimize | 1 | optimize |
pdf4me/organize | 5 | deleteBlankPages, deletePages, extractPages, rotate, rotatePage |
pdf4me/pdf | 16 | getPdfMetadata, repairPdf, createHyperlinkAnnotation, deleteHyperlinkAnnotation, digitalSignPdf, extractHyperlinkAnnotation, getDocumentByText, getTextAndCoordinates, getTextByPosition, highlightText, mergeV3, prepareForPrint, replaceTextWithImage, resizePdf, setPdfMetadata, signDocument |
pdf4me/pdf4me | 1 | updateHyperlinkAnnotation |
pdf4me/security | 2 | protect, unlock |
pdf4me/word | 2 | disableTrackingChangesInWord, findAndReplaceTextInWord |
pdf4me/zugferd | 1 | createZugferdInvoice |
Dos subrutas más se encuentran junto a los módulos de acción: la raíz del paquete (pdf4me), cubierto anteriormente, y pdf4me/models, que reexporta cada modelo y constante de enumeración.
Para conocer los parámetros y la forma de respuesta de cada acción, consulte la PDF4me REST API referencia o las declaraciones de tipo generadas en node_modules/pdf4me/dist/.
Actualización desde la versión 9.x
La versión 10 es una reescritura. Para permanecer en la línea 9.x, fije pdf4me@^9.10.15.
Dos cambios afectan a todos los sitios de llamadas.
Los detectarás inmediatamente, porque nada compila ni se ejecuta hasta que se solucionen.
1. ESM solo. require("pdf4me") ya no resuelve. Usar import.
2. Un cliente más acciones independientes. pdf4me.createClient(key), que devolvía un único objeto de métodos, se reemplaza por new Pdf4meClient(key) más funciones de acción importadas desde subrutas y llamadas como action(client, source, options).
// 9.x
const pdf4me = require("pdf4me");
const client = pdf4me.createClient(key);
const result = await client.optimize(/* ... */);
// 10
import { Pdf4meClient } from "pdf4me";
import { optimize } from "pdf4me/optimize";
const client = new Pdf4meClient(key);
const result = await optimize(client, data, { docName: "input.pdf" });
Tres cambios se compilan y ejecutan, pero presentan un comportamiento anómalo.
Estos son los que hay que revisar a mano, porque nada te indicará si están mal.
1. Los resultados binarios son Uint8Array, no Buffer. Buffer subclases Uint8Array, entonces writeFile y los amigos todavía trabajan. Pero Buffer-Los métodos exclusivos producen tonterías silenciosamente en lugar de generarlas:
result.toString("base64"); // 9.x: base64. 10: "0,255,65,128"
Buffer.from(result).toString("base64"); // do this instead
2. Cada acción genera encuestas. La versión 10 se envía isAsync: true y encuestas hasta que el trabajo se complete, por lo que una llamada que era un viaje de ida y vuelta ahora puede bloquearse hasta por maxWait (por defecto 300000 ms) y puede lanzar Pdf4meTimeoutError — un modo de fallo que la versión 9.x no tenía.
3. Las redirecciones son rechazadas. 9.x les siguió; la versión 10 establece redirect: "error". Si enrutas el tráfico a través de un proxy que responde con 3xx, apunta baseUrl en el destino final.
También vale la pena saberlo
- Node.js Ahora se requiere y se declara el 22
engines, pero npm Por defecto, solo muestra una advertencia en caso de discrepancia. - Creación de miniaturas (
createThumbnail/createThumbnails) y PDF/A validación (validate/validateDocument) tener no hay equivalente a la versión 10, porque la v2 API no los expone. - La licencia cambió de ISC a MIT.
El mapeo completo método por método, incluyendo los cambios de nombre y el integrationConfig Reemplazo, se envía con el paquete. Léalo en node_modules/pdf4me/MIGRATION.md después de la instalación.
Solución de problemas
Error [ERR_REQUIRE_ESM] o require() of ES Module ... not supported. La versión 10 es ESM solamente. Agregar "type": "module" a tu package.json, cambie el nombre del archivo de entrada a .mjso alfiler pdf4me@^9.10.15 si el proyecto no puede avanzar CommonJS todavía.
ERR_MODULE_NOT_FOUND para pdf4me/optimize. Las importaciones de subrutas se resuelven a través del paquete. exports mapa, que requiere una actualización razonable Node.js y empaquetador. Confirmar node --version informa 22 o más reciente, y que está importando la subruta exactamente como está escrita en la tabla de módulos (por ejemplo pdf4me/merge-split, con un guion).
La salida Base64 se ve así: "0,255,65,128". Me llamaste .toString("base64") en un Uint8ArrayEnvuélvalo primero: Buffer.from(result).toString("base64").
Pdf4meTimeoutError en documentos grandes. El trabajo superó maxWait, que por defecto es 300000 Sra. Plantéelo al cliente, por ejemplo new Pdf4meClient(apiKey, { maxWait: 900_000 })y confirmar timeout sigue siendo lo suficientemente grande como para leer el cuerpo de la respuesta. Tenga en cuenta que ambos valores están limitados a 2147483647 EM.
Un 401 en Pdf4meException.responseStatusCode. El API La clave está presente pero ha sido rechazada. Vuelva a generarla en el PDF4me panel y confirmar que la variable de entorno es realmente visible para el proceso. set en Windows CMD no persiste entre sesiones, por lo que utiliza setx para un valor permanente.
TypeError: an API key is required. El constructor recibió una cadena vacía o solo con espacios en blanco, generalmente porque process.env.PDF4ME_API_KEY No estaba definida. Compruebe la variable antes de construir el cliente, como se hace en la guía de inicio rápido.
TypeError: document content is empty. El Uint8Array o la cadena que proporcionaste tiene longitud cero. Esta es una verificación local, por lo que no se envió ninguna solicitud; verifica que el archivo se haya leído correctamente.
Las solicitudes fallan detrás de un proxy corporativo. El cliente establece redirect: "error" y no seguirá el 3xx de un proxy. Punto baseUrl en el destino final, o proporcionar un personalizado fetch que se encarga de su transporte.
createThumbnail o validate no se exporta. Ambos fueron eliminados en la versión 10, porque la v2 API No los expone. No existe un reemplazo directo; manténgase en la versión 9.x si depende de ellos.