@pdf123/sdk : le SDK TypeScript de PDF123

Comment installer le SDK ?#

Installez le paquet avec votre gestionnaire de paquets. Node 20.3 ou plus récent, Bun ou un bundler est requis. Les types TypeScript sont inclus et @types/node n'est pas nécessaire.

npm install @pdf123/sdk

bun add @pdf123/sdk et pnpm add @pdf123/sdk fonctionnent de la même façon.

Comment fusionner deux PDF ?#

Créez un client, lancez l'outil merge sur deux fichiers et enregistrez le résultat. Sans option, le client appelle l'API publique de façon anonyme.

import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const result = await client.run("merge", {
  input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
const path = await saveResult(result, { output: "merged.pdf" });
console.log(path);

Le résultat contient les octets dans data, le contentType, le filename du serveur et json pour les outils qui renvoient un rapport. La même opération existe sous le nom Fusionner des PDF sur le site.

Quel point d'entrée importer ?#

Importez depuis le point d'entrée racine dans les navigateurs et les environnements edge, et n'ajoutez le point d'entrée node que là où vous lisez ou écrivez des fichiers.

Quelles méthodes le client propose-t-il ?#

Les utilitaires du catalogue sont de simples fonctions : TOOLS liste tous les outils, getTool(id) renvoie les champs, les valeurs par défaut et les types de fichiers acceptés d'un outil, et toolGroup, toolSummary, matchesQuery et suggestTools aident à construire des sélecteurs d'outils. La ligne de commande affiche le même catalogue avec pdfx list et pdfx describe.

Comment passer des options à un outil ?#

params est typé pour chaque outil. Il n'accepte que les champs de cet outil, et les champs à choix n'acceptent que leurs valeurs autorisées. Les champs numériques sont comparés à leur minimum et à leur maximum, et un fichier au type accepté, avant tout envoi. Les valeurs par défaut dont le serveur a besoin sont renseignées.

const marked = await client.run("watermark", {
  input: await readFileInput("a.pdf"),
  params: { watermarkText: "DRAFT", fontSize: 40, rotation: -45 },
});
await saveResult(marked, { output: "draft.pdf" });

Une chaîne vide signifie « non défini », donc la valeur par défaut s'applique. Voir Filigrane PDF pour le rôle de chaque option.

Comment traiter de nombreux fichiers ?#

runBatch lance un outil à fichier unique, comme Compresser, Pivoter ou Protéger, sur chaque entrée avec les mêmes options. Il traite deux fichiers à la fois par défaut. Un fichier défectueux n'arrête jamais les autres.

import { fileSource, saveResult } from "@pdf123/sdk/node";

const controller = new AbortController();
const entries = await client.runBatch("compress", [fileSource("a.pdf"), fileSource("b.pdf")], {
  concurrency: 2,
  signal: controller.signal,
  onResult: async (entry, index) => {
    if (entry.ok) await saveResult(entry.result, { output: "compressed/" });
  },
});
console.log(entries.map((entry) => entry.ok));

• fileSource(path) est une source paresseuse, lue seulement quand un worker la prend en charge : de nombreux gros fichiers ne se retrouvent donc jamais ensemble en mémoire.
• onResult reçoit chaque résultat dès qu'il est prêt. Enregistrez-le à cet endroit : une annulation au fichier 50 sur 100 conserve les 49 premiers. Avec retainData: false, le tableau renvoyé ne garde pas les octets.
• Tout appel accepte timeoutMs et un signal pour l'annuler.
• idempotencyKey devient <key>:<index> pour chaque fichier.

Les outils de filtre (identifiants commençant par filter-) se terminent avec matched: false au lieu de lever une exception lorsque leur condition n'est pas remplie. Dans un lot, un tel fichier compte quand même comme ok.

Comment enchaîner des outils en une seule requête ?#

pipeline envoie une liste d'étapes et une ou plusieurs entrées. Le serveur transmet la sortie de chaque étape à la suivante.

const piped = await client.pipeline(
  [{ tool: "merge" }, { tool: "watermark", params: { watermarkText: "DRAFT" } }, { tool: "compress" }],
  [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
);
await saveResult(piped, { output: "out.pdf" });

Les pipelines acceptent les mêmes options de mot de passe que run.

Comment traiter les PDF chiffrés ?#

Passez password à run pour ouvrir d'abord une entrée chiffrée. Le déverrouillage et l'outil s'exécutent dans une seule requête. Pour les outils qui prennent plusieurs fichiers, comme Fusionner, passez passwords avec une entrée par fichier, en mettant une chaîne vide pour un fichier ouvert. Chaque fichier est déverrouillé séparément.

await client.run("compress", { input: await readFileInput("locked.pdf"), password: "secret" });
await client.run("merge", {
  input: [await readFileInput("locked.pdf"), await readFileInput("open.pdf")],
  passwords: ["secret", ""],
});

Pour un lot, passwordFor(file, index) renvoie le mot de passe de chaque entrée. Pour retirer définitivement la protection, utilisez l'outil Déverrouiller.

Comment fonctionnent les erreurs ?#

Les échecs lèvent Pdf123Error. Elle expose status (undefined s'il n'y a pas eu de réponse), code, reason pour la cause précise comme password_required, et problem avec le détail du problème renvoyé par le serveur, qui inclut hint quand il y en a un. Les erreurs de validation sont levées avant tout envoi.

import { Pdf123Error } from "@pdf123/sdk";

try {
  await client.run("compress", { input: await readFileInput("locked.pdf") });
} catch (error) {
  if (error instanceof Pdf123Error) {
    console.error(error.status, error.code, error.reason, error.problem?.hint);
  } else {
    throw error;
  }
}

Les codes du serveur sont listés dans Codes d'erreur. Le client ajoute ses propres codes :

saveResult n'écrase jamais un fichier situé dans un répertoire. Appelez d'abord checkOutput(output, { several }) pour savoir, avant l'envoi, si un chemin est accessible en écriture.

Quels réglages TypeScript et modules fonctionnent ?#

Les types se résolvent avec les réglages moduleResolution nodenext, node16, bundler et l'ancien node10, y compris pour le sous-chemin @pdf123/sdk/node. Le paquet est un module ES : import fonctionne partout. require("@pdf123/sdk") depuis CommonJS fonctionne à partir de Node 22.12 et n'est pas disponible sur Node 20.

Comment configurer le client ?#

new Pdf123Client() ne lit jamais l'environnement. clientFromEnv() de @pdf123/sdk/node lit les deux variables, et les options que vous passez l'emportent. La clé est envoyée dans l'en-tête X-API-KEY ; voir Authentification.

Pour utiliser votre propre serveur, définissez baseUrl sur son adresse, par exemple http://localhost:8080. Voir Auto-hébergement.

Puis-je utiliser le SDK dans un navigateur ?#

Oui. Le point d'entrée racine @pdf123/sdk n'a besoin que de fetch et n'a aucune dépendance à Node. Construisez vous-même les objets FileInput à partir d'un File ou d'un Uint8Array, car les utilitaires de fichiers se trouvent dans le point d'entrée node. N'intégrez pas de clé d'API dans du code de navigateur que d'autres personnes peuvent lire.

Pages associées#

• Présentation pour développeurs avec l'API REST et l'authentification
• Ligne de commande pdfx, construite sur ce SDK
• Serveurs MCP pour les agents IA
• Swagger UI et le document OpenAPI
• Pages d'outils : Fusionner, Diviser, Compresser, OCR, Protéger

FAQ#

Le SDK exige-t-il une clé d'API ?#

Non. Un client créé sans option appelle l'API publique de façon anonyme. Passez apiKey pour envoyer l'en-tête X-API-KEY.

Quelle version de Node le SDK exige-t-il ?#

Node 20.3 ou version ultérieure, ou Bun. Le point d'entrée racine n'a besoin que de fetch : il fonctionne donc aussi dans les navigateurs et les bundlers.

Comment utiliser un outil plus récent que le SDK ?#

Utilisez client.call. Elle prend un identifiant d'outil, un identifiant d'opération comme general/merge-pdfs ou un chemin /api/..., ainsi que des fichiers et des champs. Rien n'est validé ni complété par défaut en local.

Quelle taille de fichier puis-je envoyer ?#

Les entrées de plus de 95 Mo au total passent automatiquement par l'API d'envoi par morceaux. Le corps d'une requête directe est limité à 100 MiB.

Pourquoi mon appel a-t-il levé une exception pour un PDF sans tableau ?#

Des outils comme pdf-to-csv et pdf-to-xlsx répondent sans contenu quand le PDF ne contient aucun tableau détectable. Le SDK lève alors Pdf123Error avec le code no_content au lieu de renvoyer un fichier vide. Vérifiez ce code si un résultat vide est acceptable pour vous.