@pdf123/sdk: l'SDK TypeScript di PDF123

Come installo l'SDK?#

Installa il pacchetto con il tuo gestore di pacchetti. Servono Node 20.3 o successivo, Bun o un bundler. I tipi TypeScript sono inclusi e @types/node non serve.

npm install @pdf123/sdk

bun add @pdf123/sdk e pnpm add @pdf123/sdk funzionano allo stesso modo.

Come unisco due PDF?#

Crea un client, esegui lo strumento merge su due file e salva il risultato. Senza opzioni il client usa l'API pubblica in modo anonimo.

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

Il risultato contiene i byte in data, il contentType, il filename indicato dal server e json per gli strumenti che restituiscono un rapporto. La stessa operazione è disponibile sul sito web come Unisci PDF.

Quale punto di ingresso devo importare?#

Importa dal punto di ingresso principale nei browser e nei runtime edge, e aggiungi quello node solo dove leggi o scrivi file.

Quali metodi ha il client?#

Gli helper del catalogo sono semplici funzioni: TOOLS elenca tutti gli strumenti, getTool(id) restituisce i campi, i valori predefiniti e i tipi di file accettati da uno strumento, mentre toolGroup, toolSummary, matchesQuery e suggestTools aiutano a costruire selettori di strumenti. La riga di comando stampa lo stesso catalogo con pdfx list e pdfx describe.

Come passo le opzioni a uno strumento?#

params è tipizzato per ogni strumento. Accetta solo i campi di quello strumento, e i campi a scelta accettano solo i valori consentiti. I campi numerici vengono confrontati con il loro minimo e massimo, e un file viene confrontato con i tipi accettati, prima di caricare qualsiasi cosa. I valori predefiniti richiesti dal server vengono inseriti automaticamente.

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 stringa vuota significa "non impostato", quindi vale il valore predefinito. Vedi Aggiungi filigrana per sapere cosa fa ogni opzione.

Come elaboro molti file?#

runBatch esegue uno strumento a file singolo, come Comprimi, Ruota o Proteggi, su ogni input con le stesse opzioni. Per impostazione predefinita elabora due file alla volta. Un file difettoso non ferma mai gli altri.

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) è una sorgente pigra, letta solo quando un worker la prende in carico, così tanti file grandi non occupano mai la memoria insieme.
• onResult riceve ogni risultato appena è pronto. Salvalo lì, e un annullamento al file 50 di 100 conserva i primi 49. Con retainData: false l'array restituito non conserva i byte.
• Ogni chiamata accetta timeoutMs e un signal per annullarla.
• idempotencyKey diventa <key>:<index> per ogni file.

Gli strumenti di filtro (id che iniziano con filter-) restituiscono matched: false invece di generare un errore quando la loro condizione non è soddisfatta. In un lotto, un file del genere conta comunque come ok.

Come concateno gli strumenti in una sola richiesta?#

pipeline invia un elenco di passaggi e uno o più input. Il server passa l'output di ogni passaggio a quello successivo.

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

Le pipeline accettano le stesse opzioni per le password di run.

Come lavoro con i PDF cifrati?#

Passa password a run per aprire prima un input cifrato. Lo sblocco e lo strumento vengono eseguiti in una sola richiesta. Per gli strumenti che accettano più file, come Unisci, passa passwords con una voce per ogni input, usando una stringa vuota per un file aperto. Ogni file viene sbloccato separatamente.

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

Per un lotto, passwordFor(file, index) restituisce la password di ogni input. Per rimuovere la protezione in modo permanente, usa lo strumento Sblocca.

Come funzionano gli errori?#

I fallimenti generano Pdf123Error. Ha status (undefined quando non c'è stata risposta), code, reason per la causa più precisa, come password_required, e problem con i dettagli del problema forniti dal server, che includono hint quando c'è. Gli errori di validazione vengono generati prima di caricare qualsiasi cosa.

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

I codici del server sono elencati in Codici di errore. Il client aggiunge questi codici propri:

saveResult non sovrascrive mai un file all'interno di una cartella. Chiama prima checkOutput(output, { several }) per sapere, prima del caricamento, se un percorso è scrivibile.

Quali impostazioni di TypeScript e dei moduli funzionano?#

I tipi vengono risolti con le impostazioni moduleResolution nodenext, node16, bundler e con il più vecchio node10, compreso il sottopercorso @pdf123/sdk/node. Il pacchetto è un modulo ES, quindi import funziona ovunque. require("@pdf123/sdk") da CommonJS funziona su Node 22.12 o successivo e non è disponibile su Node 20.

Come configuro il client?#

new Pdf123Client() non legge mai l'ambiente. clientFromEnv() di @pdf123/sdk/node legge le due variabili, e le opzioni che passi hanno la precedenza. La chiave viene inviata nell'header X-API-KEY; vedi Autenticazione.

Per usare il tuo server, imposta baseUrl sul suo indirizzo, per esempio http://localhost:8080. Vedi Self-host.

Posso usare l'SDK in un browser?#

Sì. Il punto di ingresso principale @pdf123/sdk richiede solo fetch e non ha dipendenze da Node. Costruisci tu gli oggetti FileInput a partire da un File o da un Uint8Array, perché gli helper per i file si trovano nel punto di ingresso node. Non includere una chiave API nel codice del browser, che altri possono leggere.

Pagine correlate#

• Panoramica per sviluppatori con l'API REST e l'autenticazione
• Riga di comando pdfx, costruita su questo SDK
• Server MCP per agenti IA
• Swagger UI e il documento OpenAPI
• Pagine degli strumenti: Unisci, Dividi, Comprimi, OCR, Proteggi

FAQ#

L'SDK richiede una chiave API?#

No. Un client creato senza opzioni chiama l'API pubblica in modo anonimo. Passa apiKey per inviare l'header X-API-KEY.

Quale versione di Node richiede l'SDK?#

Node 20.3 o successivo, oppure Bun. Il punto di ingresso principale richiede solo fetch, quindi funziona anche nei browser e nei bundler.

Come ottengo uno strumento più recente dell'SDK?#

Usa client.call. Accetta un id di strumento, un id di operazione come general/merge-pdfs o un percorso /api/..., insieme a file e campi. In locale non viene validato né precompilato nulla.

Che dimensione possono avere i file che carico?#

Gli input che superano 95 MB in totale passano automaticamente dall'API di caricamento a blocchi. Il corpo di una singola richiesta diretta è limitato a 100 MiB.

Perché la mia chiamata ha generato un errore per un PDF senza tabelle?#

Strumenti come pdf-to-csv e pdf-to-xlsx rispondono senza contenuto quando il PDF non ha tabelle rilevabili. L'SDK genera Pdf123Error con il codice no_content invece di restituire un file vuoto. Controlla quel codice se un risultato vuoto è accettabile.