PDF4me JavaScript SDK Erste Schritte
Der pdf4me Paket auf npm ist der offizielle TypeScript/JavaScript ESM Kunde für den PDF4me REST APIEs bietet 106 Aktionen in 18 Modulen: Konvertieren, optimieren, zusammenführen, aufteilen, stempeln und Inhalte aus Dokumenten extrahieren mit asynchronen Funktionen und typisierten Ergebnissen. Die Typen sind im Paket enthalten, TypeScript Projekte benötigen keine separate @types installieren.
Verpackungsinformationen
| Feld | Wert |
|---|---|
| Paketname | pdf4me |
| Aktuelle Version | 10.0.1 (veröffentlicht am 14.09.2026) |
| Lizenz | MIT |
| Node.js Unterstützung | >=22, erklärt in engines |
| Modulformat | ESM nur ("type": "module") |
| Typen | Gebündelt (dist/index.d.ts) |
| Nebenwirkungen | Keine ("sideEffects": false) |
| Aktionen | 106 über 18 Import-Unterpfade |
| Laufzeitabhängigkeiten | Fünf Microsoft Kiota Pakete (Abstraktionen plus die JSON(Formular-, Text- und Multipart-Serialisierer) |
| Quelle | github.com/pdf4me/pdf4me-clientapi-javascript |
| npm | npmjs.com/package/pdf4me |
Voraussetzungen
- Node.js 22 oder neuer.
- A PDF4me Konto und API Schlüssel.
- Ein Projekt, das verwendet werden kann ESM
importSyntax ("type": "module"in Ihrempackage.json, oder.mjsDateien).
Installieren
- npm
- pnpm
- Yarn
npm install pdf4me@^10
pnpm add pdf4me@^10
yarn add pdf4me@^10
Der ^10 Die Reichweite ist wichtig. ^9 Abhängigkeitsbereich wird nicht Installieren Sie Version 10 separat, da es sich um eine Neuentwicklung mit inkompatiblen Änderungen handelt. Siehe Upgrade von 9.x unten.
:::Warnung Node.js 22 ist erforderlich, aber npm Es werden lediglich Warnungen ausgesprochen.
engines erklärt node: ">=22"und standardmäßig npm Gibt bei einer Abweichung eine Warnung anstelle eines Fehlers aus. Ein noch laufendes Projekt. Node.js Version 10 lässt sich mit Schritt 18 zwar erfolgreich installieren, schlägt dann aber zur Laufzeit fehl. Überprüfen Sie dies. node --versionvor dem Versand.
:::
Um mit einem Quellcode-Checkout anstatt mit der Registry zu arbeiten, führen Sie Folgendes aus: npm install Und npm run build im Paketverzeichnis dann ausführen npm install /absolute/path/to/pdf4me aus Ihrem Anwendungsverzeichnis.
Authentifizieren
Stellen Sie Ihre API Schlüsselelement in der Umwelt:
- 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
Der Client sendet den Schlüssel als Authorization: Basic <apiKey> Bei jeder Anfrage wird ein Header gesendet. Die Bibliothek protokolliert weder Anmeldeinformationen noch Dokumentinhalte. Das Erstellen eines Clients mit einem leeren Schlüssel löst eine Ausnahme aus. TypeError sofort, vor jedem Netzwerkanruf.
Schnellstart
Speichern Sie dies unter optimize-pdf.mjs und setze ein input.pdf im selben Arbeitsverzeichnis. Das Beispiel lädt die Datei hoch. PDF zur Optimierung und speichert das Ergebnis als optimized.pdfDie
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");
Führen Sie es aus mit:
node optimize-pdf.mjs
Die gleichen Importe funktionieren in TypeScript ESM Projekte, wobei die Typen im Paket enthalten sind.
Drei Dinge, die man beachten sollte:
- Ein Kunde, viele Aktionen.
new Pdf4meClient(apiKey)enthält die Konfiguration.fetchbesitzt den Verbindungspool, daher gibt es keinenclose()Methode zum Aufrufen und nichts zum Freigeben, wenn Sie fertig sind. - Aktionen sind eigenständige Funktionen, keine Clientmethoden. Jedes Element wird aus seinem eigenen Unterpfad importiert (
pdf4me/optimize,pdf4me/merge-split,pdf4me/editund genannt alsaction(client, source, options)Die - Die Argumentreihenfolge ist festgelegt. Wiederverwendbarer Client zuerst, Quellinhalt als nächstes, wenn die Aktion eine solche ausführt, und zuletzt ein Optionsobjekt.
Was das Paket-Root-Element exportiert
Der Wurzel-Unterpfad (pdf4me) enthält den Client und seine unterstützenden Typen. Aktionen werden hier niemals ausgeführt.
| Export | Art | Zweck |
|---|---|---|
Pdf4meClient | Klasse | Hält die API Schlüssel- und Transporteinstellungen; werden als erstes Argument an jede Aktion übergeben |
Pdf4meException | Klasse | Wird ausgelöst, wenn der Dienst einen Fehler zurückgibt. |
Pdf4meTimeoutError | Klasse | Wird ausgelöst, wenn ein Zeitlimit für eine Anfrage oder einen Auftrag erreicht ist. |
Pdf4meClientOptions | Typ | Das vom Client-Konstruktor akzeptierte Optionen-Objekt |
DocumentSource | Typ | Uint8Array | string — die akzeptierte Form des Quellinhalts |
DEFAULT_BASE_URL | Konstante | https://api.pdf4me.com |
DEFAULT_TIMEOUT | Konstante | 100000 |
DEFAULT_MAX_WAIT | Konstante | 300000 |
DEFAULT_POLL_INTERVAL | Konstante | 10000 |
Anfragen und Ergebnisse
Jede Aktion wird übermittelt isAsync: true und wartet auf das Endergebnis. Ein sofortiger HTTP 200 Rückgaben sofort. Ein HTTP 202 gibt eine Job-ID zurück, die der Client dann abfragt bei GetActionStatus bis der Job abgeschlossen ist. Ihr Code sieht einen await So oder so.
Was Sie weitergeben
DocumentSource Ist Uint8Array | string, das vier praktische Formen umfasst:
| Quellformular | Anmerkungen |
|---|---|
Uint8Array | Beinhaltet Node.js Bufferwelche Unterklassen Uint8ArrayDie Bytes werden für Sie Base64-kodiert, und zwar in begrenzten Blöcken, damit große Dokumente den Stack nicht überlaufen. |
| Base64-Zeichenkette | Ging direkt durch. |
pdf4meblobid://... | Ein Verweis auf bereits vorhandene Inhalte PDF4meDie |
| URL | Der Dienst ruft das Dokument selbst ab. |
Leere Inhalte werden lokal mit einem Fehler abgelehnt. TypeError anstatt gesendet zu werden.
Aktionen mit mehreren Eingaben akzeptieren geordnete Arrays. addAttachmentToPdf ist die Ausnahme: Es benötigt einen attachments Objektzuordnung von Dateinamen zu Inhalten.
Was Sie zurückbekommen
| Ergebnisart | Typ | Beispiel |
|---|---|---|
| Dateiaktionen | Uint8Array | Direkt akzeptiert von Node.js writeFile |
| JSON Aktionen | Typisierte Modelle | DocMetadata, SplitPdfRes |
Modelle und Enum-Konstanten werden sowohl aus dem eigenen Modul der Aktion als auch aus dem exportiert. pdf4me/models Unterpfad. Unbekannte Antwortfelder werden beibehalten in additionalDataalso ein neueres API Das Spielfeld wird niemals stillschweigend fallen gelassen.
Zwei weitere Anrufe
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 ist eine typisierte Konstante, daher vervollständigt Ihr Editor automatisch die zulässigen Werte und tsc erkennt Tippfehler, bevor die Anfrage überhaupt gesendet wird.
Optionen und Standardeinstellungen
Alle Optionsschnittstellen werden exportiert, zum Beispiel OptimizeOptionsZwei Verhaltensweisen sind es wert, bekannt zu sein:
- Standardwerte werden angewendet, wenn eine Option ausgewählt ist. abwesendDas Standard-Optimierungsprofil ist
MaxEine explizitenulltut nicht Wählen Sie einen Standardwert. - Jede Handlung akzeptiert
extra, ein Objekt, das als zusätzliche Anforderungsfelder serialisiert wird. Verwenden Sie die APIeigene Feldnamen verwenden und Schlüssel vermeiden, die die Aktionsoptionen bereits bereitstellen.
Clientkonfiguration
const client = new Pdf4meClient(apiKey, {
baseUrl: "https://api.pdf4me.com",
timeout: 100_000,
maxWait: 300_000,
pollInterval: 10_000,
});
Die Python Der Client benötigt für dieselben Einstellungen Sekunden. Wenn Sie Code zwischen den beiden Systemen portieren. SDKs, alle Dauer neu skalieren.
| Option | Standard | Was es begrenzt |
|---|---|---|
baseUrl | https://api.pdf4me.com | Der API Jede Anfrage wird an den Host gesendet |
timeout | 100000 MS | Jede einzelne Anfrage, einschließlich des Lesens ihres Inhalts |
maxWait | 300000 MS | Abfragen nach der ersten Auftragsübermittlung, einschließlich Anfragen zum Status während des laufenden Auftrags |
pollInterval | 10000 MS | Die Ausfalllücke zwischen Statusprüfungen |
fetch | globalThis.fetch | Ein benutzerdefinierter Transport, nützlich für Test- oder Proxy-Konfigurationen |
Jeder Standardwert wird auch als Konstante exportiert (DEFAULT_TIMEOUT und Freunde), sodass Sie vom Lieferwert ausgehen können, anstatt eine Zahl fest zu codieren.
Der Konstruktor prüft die übergebenen Daten:
baseUrlmuss einhttp:oderhttps:URL ohne Anmeldeinformationen, Abfragezeichenfolge oder Fragment. Alles andere löst eine Ausnahme aus.TypeErrorDietimeout,maxWait, UndpollIntervalmuss jeweils eine positive, endliche Anzahl von Millisekunden sein, die nicht größer ist als2147483647Alles andere führt zu einem Fehler.RangeErrorDie
Numerisch und HTTP-Datum Retry-After Die vom Dienst bereitgestellten Werte steuern die Abfragefrequenz; pollInterval wird nur verwendet, wenn der Dienst keine Abfrage sendet. Wenn die nächste Abfrage nach dem maxWait Nach Ablauf der Frist gibt der Kunde sofort auf, anstatt erst das restliche Budget aufzubrauchen.
:::Achtung: Weiterleitungen werden abgelehnt
Der Client setzt redirect: "error"Wenn Sie den Datenverkehr über einen Proxy leiten, der mit einer 3xx-Adresse antwortet, weisen Sie darauf hin baseUrlam endgültigen Zielort, anstatt sich darauf zu verlassen, dass der Weiterleitung gefolgt wird.
:::
Fehler
| Geworfen | Wann |
|---|---|
Pdf4meException | Der Dienst meldete einen Fehler. message, responseStatusCode, traceId, Und responseHeadersDie |
Pdf4meTimeoutError | Eine Frist für die Anfrage (timeout) oder eine zeitliche Begrenzung des Auftrags (maxWaitwurde erreicht. |
TypeError | Ungültige lokale Eingabe: ein leerer Eintrag API Schlüssel, ein schlechter baseUrloder leerer Dokumentinhalt. |
RangeError | Eine Laufzeitoption außerhalb des zulässigen Bereichs. |
Normal Error | Eine 202, deren Wanne keine brauchbaren Teile enthielt jobIdoder ein JSON Aktion, die ein leeres Ergebnis lieferte. |
| Netzwerkfehler | Vermehrt von fetch unverändert. |
Pdf4meException.message stammt aus den eigenen Daten des Dienstes. message Feld, falls vorhanden, ansonsten auf das zurückgreifen HTTP Status-Text. Zitieren Sie den traceId Wenn Sie den Support kontaktieren, wird der genaue Vorgang auf der Serviceseite identifiziert.
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;
}
}
Die 18 Module
Jedes Modul hat seinen eigenen Import-Unterpfad, sodass Bundler und Editoren nur das laden, was Sie benötigen. Die Paketeinstellungen "sideEffects": false, wodurch Bundler ungenutzte Module vollständig entfernen können.
Einige Aktionen befinden sich in einem Modul, dessen Name es vielleicht nicht vermuten lässt – OCR ist in find-search, PDF/A Die Schöpfung ist in convert, Und pdf4me Enthält eine einzelne Hyperlink-Aktion. Die folgende Tabelle listet alle exportierten Aktionen auf, sodass Sie nicht raten müssen.
| Unterpfad importieren | Aktionen | Exportierte Funktionen |
|---|---|---|
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 |
Neben den Aktionsmodulen befinden sich zwei weitere Unterpfade: das Paketstammverzeichnis (pdf4me), wie oben beschrieben, und pdf4me/models, wodurch jedes Modell und jede Enum-Konstante erneut exportiert wird.
Die Parameter und die Antwortform jeder Aktion finden Sie unter PDF4me REST API Referenz oder die generierten Typdeklarationen in node_modules/pdf4me/dist/Die
Upgrade von 9.x
Version 10 ist eine Neuentwicklung. Um auf der 9.x-Reihe zu bleiben, pinnen Sie die entsprechende Datei an. pdf4me@^9.10.15Die
Zwei Änderungen führen zu Problemen auf jeder Anrufseite
Sie werden diese Fehler sofort bemerken, denn nichts lässt sich kompilieren oder ausführen, bis sie behoben sind.
1. ESM nur. require("pdf4me") Das Problem lässt sich nicht mehr lösen. Verwenden Sie importDie
2. Ein Client plus eigenständige Aktionen. pdf4me.createClient(key), das ein einzelnes Objekt mit Methoden zurückgab, wird ersetzt durch new Pdf4meClient(key) plus Aktionsfunktionen, die aus Unterpfaden importiert und aufgerufen werden als action(client, source, options)Die
// 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" });
Drei Änderungen lassen sich kompilieren und ausführen, verhalten sich aber fehlerhaft.
Diese müssen manuell überprüft werden, denn nichts wird Ihnen sagen, ob sie falsch sind.
1. Binäre Ergebnisse sind Uint8Array, nicht BufferDie Buffer Unterklassen Uint8Array, Also writeFile Und Freunde arbeiten immer noch. Aber Buffer-nur Methoden erzeugen stillschweigend Unsinn, anstatt eine Fehlermeldung auszulösen:
result.toString("base64"); // 9.x: base64. 10: "0,255,65,128"
Buffer.from(result).toString("base64"); // do this instead
2. Jede Aktion wird befragt. Version 10 reicht ein isAsync: true und Umfragen, bis der Auftrag abgeschlossen ist, sodass ein Anruf, der ursprünglich nur eine Hin- und Rückreise erforderte, nun bis zu maxWait (Standard 300000 ms) und kann werfen Pdf4meTimeoutError — ein Fehlermodus, den Version 9.x nicht hatte.
3. Weiterleitungen werden abgelehnt. Version 9.x folgte ihnen; Version 10 setzt redirect: "error"Wenn Sie den Datenverkehr über einen Proxy leiten, der 3xx-Anfragen beantwortet, weisen Sie darauf hin baseUrl am endgültigen Zielort.
Ebenfalls wissenswert
- Node.js 22 ist nun erforderlich und wird deklariert in
engines, Aber npm Standardmäßig wird nur bei einer Nichtübereinstimmung eine Warnung ausgegeben. - Thumbnail-Erstellung (
createThumbnail/createThumbnails) Und PDF/A Validierung (validate/validateDocument) haben Es gibt keine entsprechende Version 10.weil die v2 API setzt sie nicht aus. - Die Lizenz änderte sich von ISC Zu MITDie
Die vollständige Methoden-für-Methoden-Zuordnung, einschließlich Umbenennungen und der integrationConfig Ersatzteil wird mit dem Paket geliefert. Mehr dazu unter node_modules/pdf4me/MIGRATION.md nach der Installation.
Fehlerbehebung
Error [ERR_REQUIRE_ESM] oder require() of ES Module ... not supportedDie Version 10 ist ESM Nur hinzufügen. "type": "module" zu Ihrem package.json, benennen Sie die Einstiegsdatei um in .mjsoder Anstecknadel pdf4me@^9.10.15 wenn das Projekt nicht vorankommt CommonJS noch.
ERR_MODULE_NOT_FOUND für pdf4me/optimizeDie Subpfad-Importe werden über das Paket aufgelöst exports Karte, die eine einigermaßen aktuelle Node.js und Bundler. Bestätigen node --version Berichte 22 oder neuer, und dass Sie den Unterpfad genau so importieren, wie er in der Modultabelle angegeben ist (zum Beispiel pdf4me/merge-split(mit Bindestrich).
Die Base64-Ausgabe sieht folgendermaßen aus: "0,255,65,128"Die Du hast angerufen .toString("base64") auf einem Uint8ArrayZuerst einwickeln: Buffer.from(result).toString("base64")Die
Pdf4meTimeoutError bei großen Dokumenten. Die Aufgabe wurde übertroffen maxWait, was standardmäßig auf 300000 Frau [Name], sprechen Sie das Thema beim Kunden an, zum Beispiel new Pdf4meClient(apiKey, { maxWait: 900_000 })und bestätigen timeout ist noch groß genug, um den Antworttext zu lesen. Beachten Sie, dass beide Werte auf einen Maximalwert begrenzt sind. 2147483647 MS.
Ein 401 in Pdf4meException.responseStatusCodeDie Der API Der Schlüssel ist vorhanden, wurde aber abgelehnt. Generieren Sie ihn neu. PDF4me Armaturenbrett und bestätigen, dass die Umgebungsvariable für den Prozess tatsächlich sichtbar ist — set unter Windows CMD wird nicht über Sitzungen hinweg gespeichert, daher verwenden Sie setx für einen dauerhaften Wert.
TypeError: an API key is requiredDie Der Konstruktor erhielt eine leere Zeichenkette oder eine Zeichenkette, die nur aus Leerzeichen bestand, normalerweise weil process.env.PDF4ME_API_KEY war nicht definiert. Überprüfen Sie die Variable, bevor Sie den Client erstellen, wie es in der Schnellstartanleitung beschrieben ist.
TypeError: document content is emptyDie Der Uint8Array Oder die übergebene Zeichenkette ist leer. Dies ist eine lokale Prüfung, es wurde also keine Anfrage gesendet – überprüfen Sie, ob die Datei tatsächlich erfolgreich gelesen wurde.
Anfragen schlagen hinter einem Unternehmensproxy fehl. Die Kundensätze redirect: "error" und folgt nicht den 3xx-Protokollen eines Proxys. baseUrl am endgültigen Bestimmungsort oder liefern Sie eine kundenspezifische fetch das kümmert sich um Ihren Transport.
createThumbnail oder validate wird nicht exportiert. Beide wurden in Version 10 entfernt, da die v2 API Sie werden dadurch nicht offengelegt. Es gibt keinen direkten Ersatz; bleiben Sie bei Version 9.x, wenn Sie darauf angewiesen sind.