@pdf123/sdk: l'SDK de TypeScript de PDF123

Com instal·lo l'SDK?#

Instal·la el paquet amb el teu gestor de paquets. Cal Node 20.3 o superior, Bun o un empaquetador. Els tipus de TypeScript hi van inclosos i no cal @types/node.

npm install @pdf123/sdk

bun add @pdf123/sdk i pnpm add @pdf123/sdk funcionen igual.

Com uneixo dos PDF?#

Crea un client, executa l'eina merge amb dos fitxers i desa el resultat. Sense opcions, el client es comunica amb l'API pública de manera anònima.

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

El resultat conté els bytes a data, el contentType, el filename del servidor i json per a les eines que retornen un informe. La mateixa operació està disponible al lloc web com a Uneix PDF.

Quin punt d'entrada he d'importar?#

Importa des del punt d'entrada arrel als navegadors i als entorns d'execució edge, i afegeix el punt d'entrada node només allà on llegeixis o escriguis fitxers.

Quins mètodes té el client?#

Les funcions auxiliars del catàleg són funcions simples: TOOLS llista totes les eines, getTool(id) retorna els camps, els valors per defecte i els tipus de fitxer acceptats d'una eina, i toolGroup, toolSummary, matchesQuery i suggestTools ajuden a construir selectors d'eines. La línia d'ordres imprimeix el mateix catàleg amb pdfx list i pdfx describe.

Com passo opcions a una eina?#

params està tipat per eina. Només accepta els camps d'aquella eina, i els camps d'elecció només accepten els valors permesos. Els camps numèrics es comproven amb el seu mínim i màxim, i el fitxer amb els tipus acceptats, abans de pujar res. Els valors per defecte que necessita el servidor s'omplen sols.

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

Una cadena buida vol dir «sense definir», de manera que s'aplica el valor per defecte. Consulta Afegeix marca d'aigua per saber què fa cada opció.

Com processo molts fitxers?#

runBatch executa una eina d'un sol fitxer, com ara Comprimeix, Gira o Protegeix, sobre cada entrada amb les mateixes opcions. Per defecte processa dos fitxers alhora. Un fitxer defectuós no atura mai els altres.

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) és una font mandrosa que només es llegeix quan un procés de treball la pren, de manera que molts fitxers grans no ocupen mai la memòria alhora.
• onResult rep cada resultat quan s'acaba. Desa'l allà, i si cancel·les al fitxer 50 de 100 es conserven els 49 primers. Amb retainData: false, la matriu retornada no conserva els bytes.
• Qualsevol crida accepta timeoutMs i un signal per cancel·lar-la.
• idempotencyKey esdevé <key>:<index> per a cada fitxer.

Les eines de filtre (identificadors que comencen per filter-) resolen amb matched: false en lloc de llançar un error quan no es compleix la seva condició. En un lot, aquest fitxer compta igualment com a ok.

Com encadeno eines en una sola petició?#

pipeline envia una llista de passos i una o més entrades. El servidor passa la sortida de cada pas al següent.

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

Els pipelines accepten les mateixes opcions de contrasenya que run.

Com treballo amb PDF xifrats?#

Passa password a run per obrir primer una entrada xifrada. El desbloqueig i l'eina s'executen en una sola petició. Per a les eines que accepten diversos fitxers, com Uneix, passa passwords amb una entrada per fitxer, amb una cadena buida per a un fitxer obert. Cada fitxer es desbloqueja per separat.

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

En un lot, passwordFor(file, index) retorna la contrasenya de cada entrada. Per treure la protecció de manera permanent, fes servir l'eina Desbloqueja.

Com funcionen els errors?#

Els errors llancen Pdf123Error. Té status (undefined si no hi va haver resposta), code, reason per a la causa detallada, com ara password_required, i problem amb els detalls del problema del servidor, que inclouen hint quan n'hi ha. Els errors de validació es llancen abans de pujar res.

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

Els codis del servidor són a Codis d'error. El client hi afegeix aquests codis propis:

saveResult mai no sobreescriu un fitxer dins d'un directori. Crida primer checkOutput(output, { several }) per saber abans de pujar res si es pot escriure en una ruta.

Quina configuració de TypeScript i de mòduls funciona?#

Els tipus es resolen amb els valors de moduleResolution nodenext, node16, bundler i l'antic node10, inclosa la subruta @pdf123/sdk/node. El paquet és un mòdul ES, de manera que import funciona a tot arreu. require("@pdf123/sdk") des de CommonJS funciona a Node 22.12 o superior i no està disponible a Node 20.

Com configuro el client?#

new Pdf123Client() no llegeix mai l'entorn. clientFromEnv() de @pdf123/sdk/node llegeix les dues variables, i les opcions que passis tenen prioritat. La clau s'envia com a capçalera X-API-KEY; consulta Autenticació.

Per fer servir el teu propi servidor, defineix baseUrl amb la seva adreça, per exemple http://localhost:8080. Consulta Autoallotjament.

Puc fer servir l'SDK en un navegador?#

Sí. El punt d'entrada arrel @pdf123/sdk només necessita fetch i no té dependències de Node. Construeix tu mateix els objectes FileInput a partir d'un File o d'un Uint8Array, perquè les funcions auxiliars de fitxers són al punt d'entrada node. No incloguis una clau d'API en codi de navegador que altres persones puguin llegir.

Pàgines relacionades#

• Visió general per a desenvolupadors amb l'API REST i l'autenticació
• Línia d'ordres pdfx, construïda sobre aquest SDK
• Servidors MCP per a agents d'IA
• Swagger UI i el document OpenAPI
• Pàgines d'eines: Uneix, Parteix, Comprimeix, OCR, Protegeix

FAQ#

L'SDK necessita una clau d'API?#

No. Un client creat sense opcions crida l'API pública de manera anònima. Passa apiKey per enviar la capçalera X-API-KEY.

Quina versió de Node necessita l'SDK?#

Node 20.3 o superior, o Bun. El punt d'entrada arrel només necessita fetch, així que també funciona en navegadors i empaquetadors.

Com obtinc una eina més nova que l'SDK?#

Fes servir client.call. Accepta un identificador d'eina, un identificador d'operació com general/merge-pdfs o una ruta /api/..., a més de fitxers i camps. En local no es valida ni s'omple res per defecte.

Quina mida de fitxer puc pujar?#

Les entrades de més de 95 MB en total passen automàticament per l'API de pujada per fragments. El cos d'una sola petició directa està limitat a 100 MiB.

Per què la meva crida ha llançat un error amb un PDF sense taules?#

Eines com pdf-to-csv i pdf-to-xlsx responen sense contingut quan el PDF no té cap taula detectable. L'SDK llança Pdf123Error amb el codi no_content en lloc de retornar un fitxer buit. Comprova aquest codi si un resultat buit és acceptable.