PDF4me JavaScript SDK Iniziare

IL pdf4me pacchetto su npm è l'ufficiale TypeScript/JavaScript ESM cliente per il PDF4me REST APIFornisce 106 azioni suddivise in 18 moduli: converti, ottimizza, unisci, dividi, timbra ed estrai contenuti da documenti con funzioni asincrone e risultati tipizzati. I tipi vengono spediti all'interno del pacchetto, quindi TypeScript i progetti non necessitano di essere separati @types installare.

Informazioni sulla confezione

Campo	Valore
Nome del pacchetto	pdf4me
Versione attuale	10.0.1 (pubblicato il 14/09/2026)
Licenza	MIT
Node.js supporto	>=22, dichiarato in engines
Formato modulo	ESM soltanto ("type": "module")
Dimensioni	Raggruppato (dist/index.d.ts)
Effetti collaterali	Nessuno ("sideEffects": false)
Azioni	106 su 18 sottopercorsi di importazione
Dipendenze di runtime	Cinque Microsoft Kiota pacchetti (astrazioni più il JSONserializzatori di moduli, testo e parti multiple)
Fonte	github.com/pdf4me/pdf4me-clientapi-javascript
npm	npmjs.com/package/pdf4me

Prerequisiti

• Node.js 22 anni o successivi.
• UN PDF4me conto e API chiave.
• Un progetto che può utilizzare ESM import sintassi ("type": "module" nel tuo package.json, O .mjs file).

Ottieni il tuo API Chiave

Visualizza su npm

Visualizza su GitHub

Installare

npm

npm install pdf4me@^10

pnpm

pnpm add pdf4me@^10

Yarn

yarn add pdf4me@^10

IL ^10 La portata è importante. A ^9 l'intervallo di dipendenza sarà non scarica la versione 10 separatamente, perché la versione 10 è una riscrittura con modifiche incompatibili. Vedi Aggiornamento dalla versione 9.x sotto.

:::avvertimento Node.js 22 è richiesto, ma npm avverte soltanto engines dichiara node: ">=22"e per impostazione predefinita npm emette un avviso anziché un errore in caso di mancata corrispondenza. Un progetto ancora in esecuzione Node.js 18 installerà correttamente la versione 10 e poi fallirà in fase di esecuzione. Controlla node --versionprima della spedizione. :::

Per lavorare da un checkout del codice sorgente invece che dal registro, eseguire npm install E npm run build all'interno della directory del pacchetto, quindi esegui npm install /absolute/path/to/pdf4me dalla directory della tua applicazione.

Autenticare

Imposta il tuo API chiave nell'ambiente:

Bash / Zsh

export PDF4ME_API_KEY="your-api-key"

PowerShell

$env:PDF4ME_API_KEY = "your-api-key"

Windows CMD

set PDF4ME_API_KEY=your-api-key

Il cliente invia la chiave come un Authorization: Basic <apiKey> intestazione su ogni richiesta. La libreria non registra le credenziali o il contenuto del documento. La creazione di un client con una chiave vuota genera un errore TypeError immediatamente, prima di qualsiasi chiamata di rete.

Avvio rapido

Salva questo come optimize-pdf.mjs e mettere un input.pdf nella stessa directory di lavoro. L'esempio carica il PDF per l'ottimizzazione e salva il risultato come 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");

Eseguilo con:

node optimize-pdf.mjs

Le stesse importazioni funzionano in TypeScript ESM progetti, con tipologie incluse nel pacchetto.

Tre cose da notare:

1. Un cliente, molte azioni. new Pdf4meClient(apiKey) contiene la configurazione. fetch possiede il pool di connessioni, quindi non c'è close() metodo da chiamare e niente da rilasciare al termine.
2. Le azioni sono funzioni autonome, non metodi lato client. Ciascuno viene importato dal proprio sottopercorso (pdf4me/optimize, pdf4me/merge-split, pdf4me/edit) e chiamato come action(client, source, options).
3. L'ordine degli argomenti è fisso. Prima il client riutilizzabile, poi il contenuto sorgente quando l'azione lo richiede, e infine un oggetto opzioni.

Cosa esporta la radice del pacchetto

Il sottopercorso radice (pdf4me) contiene il client e i suoi tipi di supporto. Le azioni non risiedono mai qui.

Esportare	Tipo	Scopo
Pdf4meClient	classe	Contiene il API Impostazioni di tasti e trasporto; passate come primo argomento ad ogni azione
Pdf4meException	classe	Viene generata quando il servizio restituisce un errore
Pdf4meTimeoutError	classe	Viene generata quando viene raggiunto il limite di tempo per una richiesta o un'attività.
Pdf4meClientOptions	tipo	L'oggetto opzioni accettato dal costruttore del client
DocumentSource	tipo	Uint8Array | string — la forma accettata del contenuto sorgente
DEFAULT_BASE_URL	costa	https://api.pdf4me.com
DEFAULT_TIMEOUT	costa	100000
DEFAULT_MAX_WAIT	costa	300000
DEFAULT_POLL_INTERVAL	costa	10000

Richieste e risultati

Ogni azione invia isAsync: true e attende il risultato finale. Un immediato HTTP 200 rendimenti immediati. Un HTTP 202 restituisce un ID lavoro, che il client poi interroga a GetActionStatus fino al termine del lavoro. Il tuo codice ne vede uno await in entrambi i casi.

Ciò che passi

DocumentSource È Uint8Array | stringche comprende quattro forme pratiche:

Forma di origine	Note
Uint8Array	Include Node.js Buffer, che sottoclassi Uint8ArrayI byte vengono codificati in base64, in blocchi delimitati, in modo che i documenti di grandi dimensioni non superino lo stack.
stringa base64	Passato senza problemi.
pdf4meblobid://...	Un riferimento al contenuto già presente PDF4me.
URL	Il servizio recupera autonomamente il documento.

Il contenuto vuoto viene rifiutato localmente con un TypeError piuttosto che essere inviato.

Le azioni con input multipli accettano array ordinati. addAttachmentToPdf è l'eccezione: prende un attachments Mappatura degli oggetti: nomi dei file e relativi contenuti.

Ciò che ricevi indietro

Tipo di risultato	Tipo	Esempio
Azioni sui file	Uint8Array	Accettato direttamente da Node.js writeFile
JSON azioni	Modelli tipizzati	DocMetadata, SplitPdfRes

I modelli e le costanti enum vengono esportati sia dal modulo dell'azione stessa che dal pdf4me/models sottopercorso. I campi di risposta sconosciuti vengono mantenuti in additionalData, quindi un più recente API Il campo non viene mai abbandonato silenziosamente.

Altre due chiamate

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 è una costante tipizzata, quindi il tuo editor completa automaticamente i valori validi e tsc Rileva gli errori di battitura prima ancora che la richiesta venga inviata.

Opzioni e impostazioni predefinite

Tutte le interfacce delle opzioni vengono esportate, ad esempio OptimizeOptionsDue comportamenti meritano di essere conosciuti:

• Le impostazioni predefinite vengono applicate quando è selezionata un'opzione. assenteIl profilo di ottimizzazione predefinito è Max. Un esplicito null fa non selezionare un valore predefinito.
• Ogni azione accetta extra, un oggetto serializzato come campi di richiesta aggiuntivi. Utilizzare il APIi nomi dei campi propri ed evitare le chiavi già fornite dalle opzioni di azione.

Configurazione client

const client = new Pdf4meClient(apiKey, {
  baseUrl: "https://api.pdf4me.com",
  timeout: 100_000,
  maxWait: 300_000,
  pollInterval: 10_000,
});

Tutte le durate sono in millisecondi

Il Python Il client utilizza i secondi per le stesse impostazioni. Se stai trasferendo il codice tra i due SDKs, ridimensiona ogni durata.

Opzione	Predefinito	Cosa copre
baseUrl	https://api.pdf4me.com	IL API ogni richiesta viene inviata all'host
timeout	100000 SM	Ogni singola richiesta, compresa la lettura del suo corpo
maxWait	300000 SM	Sondaggi successivi all'invio iniziale della candidatura, comprese le richieste di stato in corso di elaborazione.
pollInterval	10000 SM	Il divario di fallback tra i controlli di stato
fetch	globalThis.fetch	Un trasporto personalizzato, utile per test o configurazione proxy.

Ogni valore predefinito viene anche esportato come costante (DEFAULT_TIMEOUT e amici), quindi puoi scalare in base al valore spedito anziché inserire un numero fisso.

Il costruttore convalida i dati che gli vengono passati:

• baseUrl deve essere un http: O https: URL senza credenziali, stringa di query o frammento. Qualsiasi altra cosa genera un errore TypeError.
• timeout, maxWait, E pollInterval ciascuno deve essere un numero finito positivo di millisecondi non superiore a 2147483647. Qualsiasi altra cosa lancia un RangeError.

Numerico e HTTP-data Retry-After I valori provenienti dal servizio controllano la cadenza di polling; pollInterval viene utilizzato solo quando il servizio non ne invia uno. Se il prossimo sondaggio dovesse atterrare dopo il maxWait entro la scadenza, il cliente rinuncia immediatamente piuttosto che dormire prima esaurire il budget rimanente.

:::attenzione I reindirizzamenti vengono rifiutati Il client imposta redirect: "error". Se instradi il traffico attraverso un proxy che risponde con un 3xx, punta baseUrlalla destinazione finale invece di fare affidamento sul fatto che il reindirizzamento venga seguito. :::

Errori

Lanciato	Quando
Pdf4meException	Il servizio ha restituito un errore. message, responseStatusCode, traceId, E responseHeaders.
Pdf4meTimeoutError	Un limite di tempo per la richiesta (timeout) o un limite di tempo di lavoro (maxWaitè stato raggiunto.
TypeError	Input locale non valido: un campo vuoto API chiave, una cattiva baseUrl, oppure contenuto del documento vuoto.
RangeError	Un'opzione di durata al di fuori dell'intervallo accettato.
Ordinario Error	Un 202 il cui corpo non trasportava alcun oggetto utilizzabile jobId, o un JSON azione che ha restituito un risultato vuoto.
Errori di rete	Propagato da fetch invariato.

Pdf4meException.message è tratto dal servizio stesso message campo quando presente, ripiegando sul HTTP testo di stato. Cita il traceId Quando contatti l'assistenza: il sistema identifica con precisione l'intervento da effettuare sul lato del servizio.

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;
  }
}

I 18 moduli

Ogni modulo ha il suo sottopercorso di importazione, quindi i bundler e gli editor caricano solo ciò che usi. Il pacchetto imposta "sideEffects": falseche permette ai bundler di eliminare completamente i moduli inutilizzati.

Alcune azioni si trovano in un modulo che potresti non intuire dal nome. OCR è in find-search, PDF/A la creazione è in convert, E pdf4me Contiene una singola azione di collegamento ipertestuale. La tabella seguente elenca tutte le azioni esportate, così non dovrai fare supposizioni.

Percorso di importazione secondario	Azioni	Funzioni esportate
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

Altri due sottopercorsi si trovano accanto ai moduli di azione: la radice del pacchetto (pdf4me), trattato sopra, e pdf4me/models, che riesporta ogni costante del modello e dell'enumerazione.

Per i parametri e la forma di risposta di ciascuna azione, vedere il PDF4me REST API riferimento o le dichiarazioni di tipo generate in node_modules/pdf4me/dist/.

Aggiornamento dalla versione 9.x

La versione 10 è una riscrittura. Per rimanere sulla linea 9.x, blocca pdf4me@^9.10.15.

Due modifiche interrompono ogni call-site

Li individuerai immediatamente, perché finché non vengono corretti, nessun programma si compila o funziona.

1. ESM soltanto. require("pdf4me") non si risolve più. Usa import.

2. Un client più azioni autonome. pdf4me.createClient(key), che restituiva un singolo oggetto di metodi, viene sostituito da new Pdf4meClient(key) più funzioni di azione importate da sottopercorsi e chiamate come 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" });

Tre modifiche vengono compilate ed eseguite, ma non funzionano correttamente.

Questi sono quelli da controllare a mano, perché nulla vi dirà che sono sbagliati.

1. I risultati binari sono Uint8Array, non Buffer. Buffer sottoclassi Uint8Array, COSÌ writeFile e gli amici lavorano ancora. Ma Buffer-solo i metodi producono silenziosamente nonsenso invece di lanciare:

result.toString("base64");              // 9.x: base64.  10: "0,255,65,128"
Buffer.from(result).toString("base64"); // do this instead

2. Ogni azione sonda. La versione 10 viene inviata isAsync: true e sondaggi fino al completamento del lavoro, quindi una chiamata che era un viaggio di andata e ritorno ora potrebbe bloccarsi per un massimo di maxWait (predefinito 300000 ms) e può lanciare Pdf4meTimeoutError — una modalità di errore che la versione 9.x non aveva.

3. I reindirizzamenti vengono rifiutati. La versione 9.x li ha seguiti; la versione 10 li ha impostati redirect: "error". Se instradi il traffico attraverso un proxy che risponde 3xx, punta baseUrl alla destinazione finale.

Da sapere anche

• Node.js 22 è ora richiesto e dichiarato in engines, Ma npm Per impostazione predefinita, avvisa solo in caso di mancata corrispondenza.
• Creazione miniatura (createThumbnail / createThumbnails) E PDF/A convalida (validate / validateDocument) Avere nessuna versione equivalente alla 10, perché la v2 API non li espone.
• La licenza è cambiata da ISC A MIT.

La mappatura completa metodo per metodo, comprese le ridenominazioni e il integrationConfig sostituzione, spedita con il pacco. Leggilo su node_modules/pdf4me/MIGRATION.md dopo l'installazione.

Risoluzione dei problemi

Error [ERR_REQUIRE_ESM] O require() of ES Module ... not supported. La versione 10 è ESM solo. Aggiungi "type": "module" al tuo package.json, rinominare il file di ingresso in .mjs, o spillo pdf4me@^9.10.15 se il progetto non può partire CommonJS Ancora.

ERR_MODULE_NOT_FOUND per pdf4me/optimize. Le importazioni dei sottopercorsi si risolvono tramite il pacchetto exports mappa, che richiede una mappa ragionevolmente aggiornata Node.js e bundler. Conferma node --version segnala 22 o versioni successive e che stai importando il sottopercorso esattamente come è scritto nella tabella dei moduli (ad esempio pdf4me/merge-split(con il trattino).

L'output Base64 ha questo aspetto: "0,255,65,128". Hai chiamato .toString("base64") su un Uint8Array. Avvolgilo prima: Buffer.from(result).toString("base64").

Pdf4meTimeoutError su documenti di grandi dimensioni. Il lavoro è andato oltre maxWait, che di default è 300000 Sig.ra, solleva la questione con il cliente, ad esempio new Pdf4meClient(apiKey, { maxWait: 900_000 })e confermare timeout è ancora abbastanza grande da leggere il corpo della risposta. Nota che entrambi i valori sono limitati a 2147483647 SM.

Un 401 in Pdf4meException.responseStatusCode. IL API La chiave è presente ma rifiutata. Rigenerala nel PDF4me pannello di controllo e confermare che la variabile d'ambiente sia effettivamente visibile al processo — set in Windows CMD non persiste tra le sessioni, quindi usa setx per un valore permanente.

TypeError: an API key is required. Il costruttore ha ricevuto una stringa vuota o composta solo da spazi bianchi, di solito perché process.env.PDF4ME_API_KEY era indefinito. Controlla la variabile prima di creare il client, come fa la guida rapida.

TypeError: document content is empty. IL Uint8Array oppure la stringa passata ha lunghezza zero. Si tratta di un controllo locale, quindi non è stata inviata alcuna richiesta: verifica che il file sia stato effettivamente letto correttamente.

Le richieste falliscono se protette da un proxy aziendale. Il cliente imposta redirect: "error" e non seguirà il 3xx di un proxy. Punto baseUrl alla destinazione finale, oppure fornire un personalizzato fetch che si occupa del vostro trasporto.

createThumbnail O validate non viene esportato. Entrambi sono stati rimossi nella versione 10, perché la v2 API non li espone. Non esiste un sostituto diretto; rimanete alla versione 9.x se ne avete bisogno.

Dove andare dopo?

PDF4me REST API riferimento

PDF4mePythonSDK

Segnala un problema