PDF4me JavaScript SDK Commencer
Le pdf4me colis sur npm est l'officiel TypeScript/JavaScript ESM client pour le PDF4me REST APIIl fournit 106 actions réparties sur 18 modulesConvertissez, optimisez, fusionnez, divisez, horodatez et extrayez le contenu de documents grâce à des fonctions asynchrones et des résultats typés. Les types sont inclus dans le package. TypeScript Les projets n'ont pas besoin de séparation @types installer.
Informations sur l'emballage
| Champ | Valeur |
|---|---|
| Nom du paquet | pdf4me |
| Version actuelle | 10.0.1 (publié le 14 septembre 2026) |
| Licence | MIT |
| Node.js soutien | >=22, déclaré dans engines |
| Format du module | ESM seulement ("type": "module") |
| Types | Regroupé (dist/index.d.ts) |
| effets secondaires | Aucun ("sideEffects": false) |
| Actes | 106 répartis sur 18 sous-chemins d'importation |
| Dépendances d'exécution | Cinq Microsoft Kiota paquets (abstractions plus le JSON, formulaire, texte et sérialiseurs multiparties) |
| Source | github.com/pdf4me/pdf4me-clientapi-javascript |
| npm | npmjs.com/package/pdf4me |
Prérequis
- Node.js 22 ans ou plus récent.
- UN PDF4me compte et API clé.
- Un projet qui peut utiliser ESM
importsyntaxe ("type": "module"dans votrepackage.json, ou.mjsfichiers).
Installer
- npm
- pnpm
- Yarn
npm install pdf4me@^10
pnpm add pdf4me@^10
yarn add pdf4me@^10
Le ^10 L'étendue des possibilités compte. A ^9 la plage de dépendance pas Téléchargez la version 10 séparément, car il s'agit d'une réécriture complète comportant des changements importants. Voir Mise à niveau depuis la version 9.x ci-dessous.
:::avertissement Node.js 22 est requis, mais npm se contente d'avertir
engines déclare node: ">=22"et par défaut npm Émet un avertissement plutôt qu'une erreur en cas d'incompatibilité. Projet toujours en cours d'exécution. Node.js La version 18 installera correctement la version 10, mais échouera à l'exécution. Vérifiez. node --versionavant l'expédition.
:::
Pour travailler à partir d'une copie de code source plutôt que du registre, exécutez la commande suivante : npm install et npm run build dans le répertoire du paquet, puis exécutez npm install /absolute/path/to/pdf4me depuis le répertoire de votre application.
Authentifier
Configurez votre API clé dans l'environnement :
- 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
Le client envoie la clé sous forme de Authorization: Basic <apiKey> Un en-tête est ajouté à chaque requête. La bibliothèque ne conserve aucune trace des identifiants ni du contenu des documents. La création d'un client sans clé provoque une exception. TypeError immédiatement, avant tout appel réseau.
Démarrage rapide
Enregistrer ceci sous optimize-pdf.mjs et mettre un input.pdf dans le même répertoire de travail. L'exemple télécharge le PDF pour l'optimisation et enregistre le résultat sous 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");
Exécutez-le avec :
node optimize-pdf.mjs
Les mêmes importations fonctionnent dans TypeScript ESM projets, avec des types inclus dans le package.
Trois points à noter :
- Un client, plusieurs actions.
new Pdf4meClient(apiKey)contient la configuration.fetchpossède le pool de connexions, il n'y a donc pas declose()méthode à appeler et rien à libérer une fois terminé. - Les actions sont des fonctions autonomes, et non des méthodes client. Chacun est importé depuis son propre sous-chemin (
pdf4me/optimize,pdf4me/merge-split,pdf4me/edit) et appeléaction(client, source, options). - L'ordre des arguments est fixe. Client réutilisable en premier, contenu source ensuite lorsque l'action en nécessite une, et objet d'options en dernier.
Ce que le paquet racine exporte
Le sous-chemin racine (pdf4me) contient le client et ses types de support. Les actions ne résident jamais ici.
| Exporter | Gentil | But |
|---|---|---|
Pdf4meClient | classe | Détient le API Paramètres de touches et de transport ; transmis comme premier argument à chaque action |
Pdf4meException | classe | Lancé lorsque le service renvoie une erreur |
Pdf4meTimeoutError | classe | Déclenchée lorsqu'une limite de temps pour une requête ou une tâche est atteinte. |
Pdf4meClientOptions | taper | L'objet d'options accepté par le constructeur client |
DocumentSource | taper | Uint8Array | string — la forme acceptée du contenu source |
DEFAULT_BASE_URL | const | https://api.pdf4me.com |
DEFAULT_TIMEOUT | const | 100000 |
DEFAULT_MAX_WAIT | const | 300000 |
DEFAULT_POLL_INTERVAL | const | 10000 |
Demandes et résultats
Chaque action soumet isAsync: true et attend le résultat final. Immédiatement HTTP 200 retours immédiats. Un HTTP 202 renvoie un identifiant de tâche, que le client interroge ensuite à GetActionStatus jusqu'à ce que la tâche soit terminée. Votre code en voit un await de toute façon.
Ce que vous transmettez
DocumentSource est Uint8Array | string, qui couvre quatre formes pratiques :
| Formulaire source | Notes |
|---|---|
Uint8Array | Comprend Node.js Buffer, dont les sous-classes Uint8ArrayLes octets sont encodés en base64 pour vous, par blocs délimités afin que les documents volumineux ne débordent pas la pile. |
| chaîne de base64 | Passé sans encombre. |
pdf4meblobid://... | Une référence à un contenu déjà détenu par PDF4me. |
| URL | Le service récupère lui-même le document. |
Le contenu vide est rejeté localement avec un TypeError plutôt que d'être envoyés.
Les actions à entrées multiples acceptent des tableaux ordonnés. addAttachmentToPdf est l'exception : il faut un attachments Association d'objets entre les noms de fichiers et leur contenu.
Ce que vous récupérez
| Type de résultat | Taper | Exemple |
|---|---|---|
| Actions sur les fichiers | Uint8Array | Accepté directement par Node.js writeFile |
| JSON actions | Modèles typés | DocMetadata, SplitPdfRes |
Les modèles et les constantes d'énumération sont exportés à la fois du module propre à l'action et du pdf4me/models sous-chemin. Les champs de réponse inconnus sont conservés dans additionalData, donc un plus récent API Le domaine n'est jamais abandonné silencieusement.
Deux autres appels
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 est une constante typée, votre éditeur complète donc automatiquement les valeurs autorisées et tsc détecte les fautes de frappe avant même que la requête ne soit envoyée.
Options et valeurs par défaut
Toutes les interfaces d'options sont exportées, par exemple OptimizeOptionsDeux comportements méritent d'être connus :
- Les valeurs par défaut sont appliquées lorsqu'une option est sélectionnée. absentLe profil d'optimisation par défaut est
Max. Un explicitenullfait pas Sélectionnez une valeur par défaut. - Chaque action accepte
extra, un objet sérialisé sous forme de champs de requête supplémentaires. Utilisez le APIUtilisez les noms de champs propres à l'entreprise et évitez les clés déjà fournies par les options d'action.
Configuration du client
const client = new Pdf4meClient(apiKey, {
baseUrl: "https://api.pdf4me.com",
timeout: 100_000,
maxWait: 300_000,
pollInterval: 10_000,
});
Le Python Le client utilise quelques secondes pour les mêmes paramètres. Si vous portez du code entre les deux SDKs, redimensionnez chaque durée.
| Option | Défaut | Ce que cela plafonne |
|---|---|---|
baseUrl | https://api.pdf4me.com | Le API L'hôte envoie chaque requête à |
timeout | 100000 MS | Chaque demande individuelle, y compris la lecture de son corps |
maxWait | 300000 MS | Sondage après la soumission initiale de la tâche, y compris les demandes de statut en cours. |
pollInterval | 10000 MS | L'écart de repli entre les vérifications d'état |
fetch | globalThis.fetch | Un transport personnalisé, utile pour les tests ou la configuration du proxy |
Chaque valeur par défaut est également exportée en tant que constante (DEFAULT_TIMEOUT et amis), vous pouvez donc calculer à partir de la valeur livrée plutôt que de coder en dur un nombre.
Le constructeur valide les données que vous lui transmettez :
baseUrldoit être unhttp:ouhttps:URL sans identifiants, chaîne de requête ni fragment. Tout autre élément génère une erreur.TypeError.timeout,maxWait, etpollIntervaldoit être un nombre fini positif de millisecondes ne dépassant pas2147483647Tout le reste provoque une erreur.RangeError.
Numérique et HTTP-date Retry-After Les valeurs issues du service contrôlent la cadence d'interrogation ; pollInterval n'est utilisé que lorsque le service n'en envoie pas. Si la prochaine interrogation devait avoir lieu après le maxWait Face à l'échéance, le client abandonne immédiatement plutôt que d'épuiser d'abord le budget restant.
Attention : les redirections sont rejetées.
Le client configure redirect: "error"Si vous acheminez le trafic via un proxy qui répond par un code 3xx, pointez baseUrlà destination finale au lieu de compter sur le fait que la redirection soit suivie.
:::
Erreurs
| Jeté | Quand |
|---|---|
Pdf4meException | Le service a renvoyé une erreur. Transports message, responseStatusCode, traceId, et responseHeaders. |
Pdf4meTimeoutError | Un délai de requête (timeout) ou une limite de temps de travail (maxWait) a été atteint. |
TypeError | Entrée locale invalide : un espace vide API clé, une mauvaise baseUrl, ou un contenu de document vide. |
RangeError | Une option de durée hors de la plage acceptée. |
Ordinaire Error | Un 202 dont la carrosserie ne contenait aucune pièce utilisable jobId, ou un JSON action qui a renvoyé un résultat vide. |
| Erreurs réseau | Propagé à partir de fetch inchangé. |
Pdf4meException.message est tiré du propre service message champ lorsqu'il est présent, en revenant au HTTP Texte d'état. Citez le traceId Lorsque vous contactez l'assistance : celle-ci identifie précisément la tâche à effectuer du côté du service.
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;
}
}
Les 18 modules
Chaque module possède son propre sous-chemin d'importation, ce qui permet aux outils de regroupement et aux éditeurs de ne charger que ce que vous utilisez. "sideEffects": false, ce qui permet aux gestionnaires de modules de supprimer complètement les modules inutilisés.
Quelques actions se trouvent dans un module que vous ne devineriez peut-être pas d'après son nom — OCR est dans find-search, PDF/A La création est en convert, et pdf4me Contient une seule action de lien hypertexte. Le tableau ci-dessous répertorie toutes les actions exportées afin que vous n'ayez pas à les deviner.
| Sous-chemin d'importation | Actes | Fonctions exportées |
|---|---|---|
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 |
Deux autres sous-chemins se trouvent à côté des modules d'action : la racine du paquet (pdf4me), déjà mentionné ci-dessus, et pdf4me/models, qui réexporte chaque constante de modèle et d'énumération.
Pour connaître les paramètres et la forme de la réponse de chaque action, voir la section suivante : PDF4me REST API référence ou les déclarations de type générées dans node_modules/pdf4me/dist/.
Mise à niveau depuis la version 9.x
La version 10 est une réécriture. Pour rester sur la branche 9.x, épinglez pdf4me@^9.10.15.
Deux modifications perturbent tous les sites d'appel
Vous les trouverez immédiatement, car rien ne se compile ni ne s'exécute tant qu'ils ne sont pas corrigés.
1. ESM seulement. require("pdf4me") Ne résout plus le problème. Utilisez import.
2. Un client et des actions autonomes. pdf4me.createClient(key), qui renvoyait un seul objet de méthodes, est remplacé par new Pdf4meClient(key) plus les fonctions d'action importées des sous-chemins et appelées comme 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" });
Trois modifications se compilent et s'exécutent, mais présentent un comportement anormal.
Ce sont celles-ci qu'il faut vérifier manuellement, car rien ne vous indiquera qu'elles sont erronées.
1. Les résultats binaires sont Uint8Array, pas Buffer. Buffer sous-classes Uint8Array, donc writeFile et mes amis travaillent toujours. Mais Buffer-Seules les méthodes produisent silencieusement des absurdités au lieu de les lever :
result.toString("base64"); // 9.x: base64. 10: "0,255,65,128"
Buffer.from(result).toString("base64"); // do this instead
2. Chaque action fait l'objet d'un sondage. La version 10 est soumise isAsync: true et effectue des sondages jusqu'à la fin de la tâche, de sorte qu'un appel qui ne nécessitait qu'un aller-retour peut maintenant bloquer pendant une durée pouvant aller jusqu'à maxWait (défaut 300000 ms) et peut lancer Pdf4meTimeoutError — un mode de défaillance que la version 9.x ne présentait pas.
3. Les redirections sont rejetées. La version 9.x leur a succédé ; la version 10 en est un ensemble redirect: "error"Si vous acheminez le trafic via un proxy qui répond à un code 3xx, pointez-le. baseUrl à destination finale.
Il est également bon de le savoir
- Node.js 22 est désormais requis et déclaré dans
engines, mais npm Par défaut, il n'émet qu'un avertissement en cas d'incohérence. - Création de miniatures (
createThumbnail/createThumbnails) et PDF/A validation (validate/validateDocument) avoir aucune version 10 équivalente, car la v2 API ne les expose pas. - La licence a changé de ISC à MIT.
Le mappage complet méthode par méthode, y compris les renommages et le integrationConfig Pièce de rechange, incluse dans le colis. Consultez les informations à ce sujet. node_modules/pdf4me/MIGRATION.md après l'installation.
Dépannage
Error [ERR_REQUIRE_ESM] ou require() of ES Module ... not supported. La version 10 est ESM seulement. Ajouter "type": "module" à votre package.json, renommez le fichier d'entrée en .mjs, ou épingle pdf4me@^9.10.15 si le projet ne peut pas avancer CommonJS encore.
ERR_MODULE_NOT_FOUND pour pdf4me/optimize. Les importations de sous-chemin sont résolues via le package exports carte, ce qui nécessite une carte raisonnablement à jour Node.js et regroupement. Confirmer node --version les rapports 22 ou plus récents, et que vous importez le sous-chemin exactement comme indiqué dans le tableau des modules (par exemple pdf4me/merge-split, avec un trait d'union).
Le résultat Base64 ressemble à "0,255,65,128". Vous avez appelé .toString("base64") sur un Uint8Array. Emballez-le d'abord : Buffer.from(result).toString("base64").
Pdf4meTimeoutError sur des documents volumineux. Le travail a dépassé maxWait, qui par défaut à 300000 Mme, signalez-le au client, par exemple. new Pdf4meClient(apiKey, { maxWait: 900_000 })et confirmer timeout est encore suffisamment grand pour lire le corps de la réponse. Notez que les deux valeurs sont plafonnées à 2147483647 MS.
Un 401 dans Pdf4meException.responseStatusCode. Le API La clé est présente mais rejetée. Régénérez-la dans le PDF4me tableau de bord et vérifiez que la variable d'environnement est bien visible par le processus. set sous Windows CMD ne persiste pas d'une session à l'autre, veuillez donc utiliser setx pour une valeur permanente.
TypeError: an API key is required. Le constructeur a reçu une chaîne vide ou ne contenant que des espaces, généralement parce que process.env.PDF4ME_API_KEY La variable n'était pas définie. Vérifiez-la avant de créer le client, comme le fait le guide de démarrage rapide.
TypeError: document content is empty. Le Uint8Array Il se peut que la chaîne de caractères fournie soit vide. Cette vérification étant locale, aucune requête n'a été envoyée ; assurez-vous simplement que le fichier a bien été lu.
Les requêtes échouent derrière un proxy d'entreprise. Le client fixe redirect: "error" et ne suivra pas les instructions 3xx d'un proxy. Point baseUrl à destination finale, ou fournir un service personnalisé fetch qui gère votre transport.
createThumbnail ou validate n'est pas exporté. Les deux ont été supprimés dans la version 10, car la v2 API ne les expose pas. Il n'existe pas de solution de remplacement directe ; restez sur la version 9.x si vous en avez besoin.