@pdf123/sdk: PDF123 TypeScript SDK'sı

SDK'yı nasıl kurarım?#

Paketi paket yöneticinizle kurun. Node 20.3 veya üstü, Bun ya da bir bundler gerekir. TypeScript türleri pakete dahildir; @types/node gerekmez.

npm install @pdf123/sdk

bun add @pdf123/sdk ve pnpm add @pdf123/sdk da aynı şekilde çalışır.

İki PDF'yi nasıl birleştiririm?#

Bir istemci oluşturun, merge aracını iki dosya üzerinde çalıştırın ve sonucu kaydedin. Seçenek verilmezse istemci genel API ile anonim olarak konuşur.

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

Sonuç; baytları data içinde, contentType değerini, sunucunun verdiği filename adını ve rapor döndüren araçlar için json alanını taşır. Aynı işlem web sitesinde PDF birleştir olarak da bulunur.

Hangi giriş noktasını içe aktarmalıyım?#

Tarayıcılarda ve uç (edge) çalışma zamanlarında kök girişten içe aktarın; node girişini yalnızca dosya okuduğunuz veya yazdığınız yerde ekleyin.

İstemcide hangi yöntemler var?#

Katalog yardımcıları sade işlevlerdir: TOOLS tüm araçları listeler, getTool(id) bir aracın alanlarını, varsayılanlarını ve kabul ettiği dosya türlerini verir; toolGroup, toolSummary, matchesQuery ve suggestTools araç seçiciler kurmaya yardımcı olur. Komut satırı aynı kataloğu pdfx list ve pdfx describe ile yazdırır.

Bir araca seçenekleri nasıl veririm?#

params araç başına türlüdür. Yalnızca o aracın alanlarını kabul eder ve seçim alanları yalnızca izin verilen değerleri alır. Sayı alanları en küçük ve en büyük değere göre, dosya ise kabul edilen türlere göre, herhangi bir şey yüklenmeden önce denetlenir. Sunucunun gerek duyduğu varsayılanlar doldurulur.

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

Boş bir dize "ayarlanmadı" anlamına gelir; bu durumda varsayılan geçerli olur. Her seçeneğin ne yaptığı için Filigran ekle sayfasına bakın.

Çok sayıda dosyayı nasıl işlerim?#

runBatch, Sıkıştır, Döndür veya Koru gibi tek dosyalı bir aracı her girdi üzerinde aynı seçeneklerle çalıştırır. Varsayılan olarak aynı anda iki dosya işler. Bozuk bir dosya diğerlerini asla durdurmaz.

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), bir işçi onu alana kadar okunmayan tembel bir kaynaktır; bu sayede çok sayıdaki büyük dosya hiçbir zaman aynı anda bellekte durmaz.
• onResult her sonucu tamamlandığı anda alır. Sonucu orada kaydedin; 100 dosyanın 50'sinde iptal ederseniz ilk 49 korunur. retainData: false ile dönen dizi baytları tutmaz.
• Her çağrı timeoutMs ve iptal için bir signal kabul eder.
• idempotencyKey, her dosya için <key>:<index> biçimine dönüşür.

Filtre araçları (kimliği filter- ile başlayanlar), koşulları sağlanmadığında hata fırlatmak yerine matched: false ile tamamlanır. Toplu işlemde böyle bir dosya yine de ok sayılır.

Araçları tek istekte nasıl zincirlerim?#

pipeline, bir adım listesi ve bir ya da daha fazla girdi gönderir. Sunucu her adımın çıktısını sonraki adıma verir.

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

Pipeline'lar run ile aynı parola seçeneklerini kabul eder.

Şifreli PDF'lerle nasıl çalışırım?#

Şifreli bir girdiyi önce açmak için run çağrısına password verin. Kilit açma ve araç tek istekte çalışır. Birleştir gibi birden çok dosya alan araçlarda her girdi için bir değer içeren passwords verin; açık dosya için boş dize kullanın. Her dosyanın kilidi ayrı ayrı açılır.

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

Toplu işlemde passwordFor(file, index) her girdi için parolayı döndürür. Korumayı kalıcı olarak kaldırmak için Parolayı kaldır aracını kullanın.

Hatalar nasıl işler?#

Başarısızlıklar Pdf123Error fırlatır. Bu hatada status (yanıt yoksa undefined), code, password_required gibi ayrıntılı nedeni veren reason ve sunucunun sorun ayrıntılarını içeren problem bulunur; varsa hint de burada yer alır. Doğrulama hataları, herhangi bir şey yüklenmeden önce fırlatılır.

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

Sunucu kodları Hata kodları sayfasında listelenir. İstemci şu kendi kodlarını ekler:

saveResult bir dizinin içindeki hiçbir dosyanın üzerine yazmaz. Bir yola yazılıp yazılamayacağını yüklemeden önce öğrenmek için önce checkOutput(output, { several }) çağırın.

Hangi TypeScript ve modül ayarları çalışır?#

Türler, @pdf123/sdk/node alt yolu dahil, moduleResolution ayarlarından nodenext, node16, bundler ve eski node10 altında çözümlenir. Paket bir ES modülüdür; bu yüzden import her yerde çalışır. CommonJS'ten require("@pdf123/sdk") Node 22.12 veya üstünde çalışır, Node 20'de kullanılamaz.

İstemciyi nasıl yapılandırırım?#

new Pdf123Client() ortamı asla okumaz. @pdf123/sdk/node içindeki clientFromEnv() iki değişkeni okur ve sizin verdiğiniz seçenekler önceliklidir. Anahtar X-API-KEY başlığı olarak gönderilir; bkz. Kimlik doğrulama.

Kendi sunucunuzu kullanmak için baseUrl değerini adresine ayarlayın; örneğin http://localhost:8080. Bkz. Self-host.

SDK'yı tarayıcıda kullanabilir miyim?#

Evet. Kök giriş @pdf123/sdk yalnızca fetch gerektirir ve Node bağımlılığı yoktur. Dosya yardımcıları node girişinde olduğundan FileInput nesnelerini bir File ya da Uint8Array üzerinden kendiniz oluşturun. Başkalarının okuyabileceği tarayıcı koduna API anahtarı koymayın.

İlgili sayfalar#

• REST API ve kimlik doğrulamayı anlatan Geliştiriciler genel bakış
• Bu SDK üzerine kurulu pdfx komut satırı
• Yapay zekâ ajanları için MCP sunucuları
• Swagger UI ve OpenAPI belgesi
• Araç sayfaları: Birleştir, Böl, Sıkıştır, OCR, Koru

SSS#

SDK'nın API anahtarına ihtiyacı var mı?#

Hayır. Seçeneksiz oluşturulan bir istemci genel API'yi anonim olarak çağırır. X-API-KEY başlığını göndermek için apiKey verin.

SDK hangi Node sürümünü gerektirir?#

Node 20.3 veya üstü ya da Bun. Kök giriş yalnızca fetch gerektirir; bu yüzden tarayıcılarda ve bundler'larda da çalışır.

SDK'dan daha yeni bir araca nasıl ulaşırım?#

client.call kullanın. Bir araç kimliği, general/merge-pdfs gibi bir işlem kimliği ya da bir /api/... yolu ile dosyaları ve alanları alır. Yerelde hiçbir şey doğrulanmaz ve varsayılan atanmaz.

Ne kadar büyük dosya yükleyebilirim?#

Toplamı 95 MB'ı aşan girdiler otomatik olarak parçalı yükleme API'sinden geçer. Tek bir doğrudan istek gövdesi 100 MiB ile sınırlıdır.

Tablosu olmayan bir PDF için çağrım neden hata fırlattı?#

pdf-to-csv ve pdf-to-xlsx gibi araçlar, PDF'de algılanabilir tablo yoksa içeriksiz yanıt verir. SDK boş dosya döndürmek yerine no_content kodlu Pdf123Error fırlatır. Boş sonuç sizin için kabul edilebilirse bu kodu denetleyin.