@pdf123/sdk: de TypeScript-SDK van PDF123

Hoe installeer ik de SDK?#

Installeer het pakket met je pakketbeheerder. Node 20.3 of nieuwer, Bun of een bundler is vereist. TypeScript-typen zijn meegeleverd en @types/node is niet nodig.

npm install @pdf123/sdk

bun add @pdf123/sdk en pnpm add @pdf123/sdk werken op dezelfde manier.

Hoe voeg ik twee PDF's samen?#

Maak een client, voer de tool merge uit op twee bestanden en sla het resultaat op. Zonder opties praat de client anoniem met de openbare API.

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

Het resultaat bevat de bytes in data, het contentType, de filename van de server en json voor tools die een rapport teruggeven. Dezelfde bewerking is op de website beschikbaar als PDF samenvoegen.

Welk toegangspunt moet ik importeren?#

Importeer in browsers en edge-runtimes vanuit het hoofdtoegangspunt, en voeg het node-toegangspunt alleen toe waar je bestanden leest of schrijft.

Welke methoden heeft de client?#

Catalogushulpfuncties zijn gewone functies: TOOLS toont alle tools, getTool(id) geeft de velden, standaardwaarden en geaccepteerde bestandstypen van één tool terug, en toolGroup, toolSummary, matchesQuery en suggestTools helpen bij het bouwen van toolkiezers. De opdrachtregel toont dezelfde catalogus met pdfx list en pdfx describe.

Hoe geef ik opties door aan een tool?#

params is per tool getypeerd. Het accepteert alleen de velden van die tool, en keuzevelden accepteren alleen hun toegestane waarden. Getalvelden worden gecontroleerd op hun minimum en maximum, en een bestand wordt gecontroleerd op de geaccepteerde typen, voordat er iets wordt geüpload. Standaardwaarden die de server nodig heeft, worden ingevuld.

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

Een lege tekenreeks betekent "niet ingesteld", dus dan geldt de standaardwaarde. Zie PDF van een watermerk voorzien voor wat elke optie doet.

Hoe verwerk ik veel bestanden?#

runBatch voert een tool voor één bestand, zoals Comprimeren, Roteren of Beveiligen, uit op elke invoer met dezelfde opties. Standaard worden twee bestanden tegelijk verwerkt. Eén slecht bestand stopt de andere nooit.

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) is een luie bron die pas wordt gelezen wanneer een worker hem oppakt, zodat veel grote bestanden nooit tegelijk in het geheugen staan.
• onResult ontvangt elk resultaat zodra het klaar is. Sla het daar op, dan blijven bij een annulering bij bestand 50 van 100 de eerste 49 behouden. Met retainData: false bewaart de teruggegeven array de bytes niet.
• Elke aanroep accepteert timeoutMs en een signal om hem te annuleren.
• idempotencyKey wordt voor elk bestand <key>:<index>.

Filtertools (id's die met filter- beginnen) leveren matched: false op in plaats van een fout te geven wanneer hun voorwaarde niet geldt. In een batch telt zo'n bestand nog steeds als ok.

Hoe koppel ik tools in één verzoek?#

pipeline stuurt een lijst met stappen en een of meer invoerbestanden. De server geeft de uitvoer van elke stap door aan de volgende.

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

Pipelines accepteren dezelfde wachtwoordopties als run.

Hoe werk ik met versleutelde PDF's?#

Geef password mee aan run om een versleutelde invoer eerst te openen. Het ontgrendelen en de tool worden in één verzoek uitgevoerd. Geef voor tools die meerdere bestanden nemen, zoals Samenvoegen, passwords mee met één item per invoer, en gebruik een lege tekenreeks voor een open bestand. Elk bestand wordt apart ontgrendeld.

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", ""],
});

Voor een batch geeft passwordFor(file, index) het wachtwoord voor elke invoer terug. Gebruik de tool Ontgrendelen om de beveiliging blijvend te verwijderen.

Hoe werken fouten?#

Fouten gooien Pdf123Error. Die heeft status (undefined als er geen antwoord was), code, reason voor de fijnmazige oorzaak zoals password_required, en problem met de probleemdetails van de server, waaronder hint als die er is. Validatiefouten worden gegooid voordat er iets wordt geüpload.

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

Servercodes staan op Foutcodes. De client voegt deze eigen codes toe:

saveResult overschrijft nooit een bestand in een map. Roep eerst checkOutput(output, { several }) aan om vóór het uploaden te weten of een pad beschrijfbaar is.

Welke TypeScript- en module-instellingen werken?#

De typen worden opgelost onder de moduleResolution-instellingen nodenext, node16, bundler en de oudere node10, inclusief het subpad @pdf123/sdk/node. Het pakket is een ES-module, dus import werkt overal. require("@pdf123/sdk") vanuit CommonJS werkt op Node 22.12 of nieuwer en is niet beschikbaar op Node 20.

Hoe configureer ik de client?#

new Pdf123Client() leest de omgeving nooit. clientFromEnv() uit @pdf123/sdk/node leest de twee variabelen, en opties die je zelf meegeeft gaan voor. De sleutel wordt verstuurd als de header X-API-KEY; zie Authenticatie.

Stel baseUrl in op het adres van je eigen server om die te gebruiken, bijvoorbeeld http://localhost:8080. Zie Self-host.

Kan ik de SDK in een browser gebruiken?#

Ja. Het hoofdtoegangspunt @pdf123/sdk heeft alleen fetch nodig en heeft geen Node-afhankelijkheden. Bouw FileInput-objecten zelf op basis van een File of een Uint8Array, want de bestandshulpfuncties zitten in het node-toegangspunt. Lever geen API-sleutel mee in browsercode die anderen kunnen lezen.

Gerelateerde pagina's#

• Overzicht voor ontwikkelaars met de REST API en authenticatie
• pdfx-opdrachtregel, gebouwd op deze SDK
• MCP-servers voor AI-agents
• Swagger UI en het OpenAPI-document
• Toolpagina's: Samenvoegen, Splitsen, Comprimeren, OCR, Beveiligen

FAQ#

Heeft de SDK een API-sleutel nodig?#

Nee. Een client die zonder opties is gemaakt, roept de openbare API anoniem aan. Geef apiKey mee om de header X-API-KEY te versturen.

Welke Node-versie heeft de SDK nodig?#

Node 20.3 of nieuwer, of Bun. Het hoofdtoegangspunt heeft alleen fetch nodig, dus het draait ook in browsers en bundlers.

Hoe krijg ik een tool die nieuwer is dan de SDK?#

Gebruik client.call. Die neemt een tool-id, een bewerkings-id zoals general/merge-pdfs of een /api/...-pad, plus bestanden en velden. Er wordt lokaal niets gevalideerd en geen standaardwaarde ingevuld.

Hoe groot mag een bestand zijn dat ik upload?#

Invoer van in totaal meer dan 95 MB gaat automatisch via de upload-API in delen. De body van één direct verzoek is beperkt tot 100 MiB.

Waarom gaf mijn aanroep een fout voor een PDF zonder tabellen?#

Tools zoals pdf-to-csv en pdf-to-xlsx antwoorden zonder inhoud als de PDF geen herkenbare tabel bevat. De SDK gooit dan Pdf123Error met de code no_content in plaats van een leeg bestand terug te geven. Controleer die code als een leeg resultaat acceptabel is.