Ana içeriğe geç
PDF4me APIEntegrasyonlarBilgi BankasıUzantılarAPI Test CihazıBlog

PDF4me JavaScript SDK Başlarken

O pdf4me paket üzerinde npm resmidir TypeScript/JavaScript ESM müşteri için PDF4me REST APISağlar. 18 modül genelinde 106 işlem: Belgelerden içerik dönüştürme, optimize etme, birleştirme, bölme, damgalama ve ayıklama işlemlerini eşzamansız fonksiyonlar ve tür belirtilmiş sonuçlarla gerçekleştirir. Türler paket içerisinde yer alır, bu nedenle TypeScript Projelerin ayrı bir şeye ihtiyacı yoktur. @types düzenlemek.

Paket bilgileri​

AlanDeğer
Paket adıpdf4me
Mevcut sürüm10.0.1 (Yayınlanma tarihi: 14.09.2026)
LisansMIT
Node.js Destek>=22, ilan edildi engines
Modül formatıESM sadece ("type": "module")
TürlerPaketlenmiş (dist/index.d.ts)
Yan etkilerHiçbiri ("sideEffects": false)
Eylemler18 alt yol üzerinden 106 içe aktarma
Çalışma zamanı bağımlılıklarıBeş Microsoft Kiota paketler (soyutlamalar artı JSON(form, metin ve çok parçalı seri hale getiriciler)
Kaynakgithub.com/pdf4me/pdf4me-clientapi-javascript
npmnpmjs.com/package/pdf4me

Önkoşullar​

  • Node.js 22 veya daha yeni.
  • A PDF4me hesap ve API anahtar.
  • Kullanılabilecek bir proje ESM import sözdizimi ("type": "module" sizin package.json, veya .mjs dosyalar).

Alın API Anahtar

Görüntüle npm

Görüntüle GitHub

Düzenlemek​

npm install pdf4me@^10

O ^10 Aralık önemlidir. ^9 bağımlılık aralığı Olumsuz Sürüm 10'u ayrı olarak indirin, çünkü sürüm 10, önemli değişiklikler içeren yeniden yazılmış bir sürümdür. Bakınız. 9.x sürümünden yükseltme altında.

:::uyarı Node.js 22 gereklidir, ancak npm sadece uyarıyor engines beyan eder node: ">=22"ve varsayılan olarak npm Uyumsuzluk durumunda hata yerine uyarı verir. Proje hala çalışıyor. Node.js 18, sürüm 10'u başarıyla kuracak ancak çalışma zamanında hata verecektir. Kontrol edin. node --versionGöndermeden önce. :::

Kayıt defteri yerine kaynak koddan işlem yapmak için şunu çalıştırın: npm install Ve npm run build Paket dizininin içinde, ardından çalıştırın. npm install /absolute/path/to/pdf4me Uygulama dizininizden.

Kimlik doğrulama​

Ayarlarınızı yapın. API Çevredeki anahtar:

export PDF4ME_API_KEY="your-api-key"

İstemci anahtarı şu şekilde gönderir: Authorization: Basic <apiKey> Her istekte başlık eklenir. Kütüphane kimlik bilgilerini kaydetmez veya içeriği belgelemez. Boş bir anahtarla istemci oluşturmak bir hata fırlatır. TypeError Hemen, herhangi bir ağ bağlantısından önce.

Hızlı başlangıç​

Bunu kaydet optimize-pdf.mjs ve bir tane koy input.pdf Aynı çalışma dizininde. Örnek, dosyayı yükler. PDF optimizasyon için kullanılır ve sonucu kaydeder. optimized.pdf.

import { readFile, writeFile } from "node:fs/promises";
import { Pdf4meClient } from "pdf4me";
import { optimize } from "pdf4me/optimize";

const apiKey = process.env.PDF4ME_API_KEY;
if (!apiKey) {
  throw new Error("Set PDF4ME_API_KEY before running this example.");
}

const client = new Pdf4meClient(apiKey);
const data = await readFile("input.pdf");
const result = await optimize(client, data, { docName: "input.pdf" });
await writeFile("optimized.pdf", result);
console.log("Saved optimized.pdf");

Şu komutla çalıştırın:

node optimize-pdf.mjs

Aynı içe aktarma işlemleri burada da çalışır. TypeScript ESM Paket içeriğinde yer alan türlerle projeler.

Dikkat edilmesi gereken üç şey:

  1. Tek müşteri, birçok işlem. new Pdf4meClient(apiKey) Yapılandırmayı tutar. fetch Bağlantı havuzunun sahibi o, bu yüzden bir sorun yok. close() Çağrılacak bir yöntem ve işiniz bittiğinde serbest bırakılacak bir şey yok.
  2. Eylemler, istemci metotları değil, bağımsız fonksiyonlardır. Her biri kendi alt yolundan içe aktarılır (pdf4me/optimize, pdf4me/merge-split, pdf4me/edit) ve şu şekilde adlandırılır: action(client, source, options).
  3. Argümanların sırası sabittir. Önce istemci tarafı, sonra işlem gerçekleştiğinde kaynak içerik ve en sonda bir seçenekler nesnesi olmak üzere yeniden kullanılabilir yapı.

Paket kökünün dışa aktardıkları​

Kök alt yol (pdf4meİstemciyi ve onu destekleyen türleri barındırır. Eylemler asla burada yer almaz.

İhracatTürAmaç
Pdf4meClientsınıfElinde tutuyor API Anahtar ve taşıma ayarları; her eyleme ilk argüman olarak iletilir.
Pdf4meExceptionsınıfHizmet başarısız olduğunda fırlatılır.
Pdf4meTimeoutErrorsınıfBir isteğin veya işin zaman sınırına ulaşıldığında fırlatılır.
Pdf4meClientOptionstipİstemci yapıcı tarafından kabul edilen seçenekler nesnesi
DocumentSourcetipUint8Array | string — kaynak içeriğin kabul görmüş biçimi
DEFAULT_BASE_URLsabithttps://api.pdf4me.com
DEFAULT_TIMEOUTsabit100000
DEFAULT_MAX_WAITsabit300000
DEFAULT_POLL_INTERVALsabit10000

İstekler ve sonuçlar​

Her işlem gönderilir. isAsync: true ve tamamlanmış sonucu bekliyor. Hemen HTTP 200 kişi hemen geri dönüyor. Bir HTTP 202 numaralı işlem bir iş kimliği döndürür ve istemci daha sonra bu kimliği sorgular. GetActionStatus İş bitene kadar. Kodunuz bir tane görüyor. await öyle ya da böyle.

Geçirdiğiniz şey​

DocumentSource dır Uint8Array | stringBu, dört pratik biçimi kapsar:

Kaynak formuNotlar
Uint8Arrayİçerir Node.js Bufferalt sınıfları Uint8ArrayVeriler, büyük belgelerin yığın taşmasını önlemek için sınırlı parçalar halinde base64 kodlamasına tabi tutulur.
base64 dizesiDirekt geçti.
pdf4meblobid://...Daha önce sahip olunan içeriğe yapılan bir referans. PDF4me.
URLBu hizmet, belgeyi kendisi getirir.

Boş içerik yerel olarak reddedilir. TypeError gönderilmek yerine.

Birden fazla girdiye sahip işlemler, sıralı dizileri kabul eder. addAttachmentToPdf istisnadır: bir süre alır. attachments Dosya adlarını içerikle eşleştiren nesne.

Ne karşılığında alırsınız?​

Sonuç türüTipÖrnek
Dosya işlemleriUint8ArrayDoğrudan kabul edildi Node.js writeFile
JSON eylemlerTipli modellerDocMetadata, SplitPdfRes

Modeller ve enum sabitleri hem eylemin kendi modülünden hem de başka bir yerden dışa aktarılır. pdf4me/models Alt yol. Bilinmeyen yanıt alanları saklanır. additionalDatayani daha yeni bir API Bu alan asla sessizce terk edilmez.

İki telefon görüşmesi daha​

import { merge } from "pdf4me/merge-split";
import { stamp, StampAlignX } from "pdf4me/edit";

const merged = await merge(client, [firstPdf, secondPdf]);
const stamped = await stamp(client, merged, {
  text: "DRAFT",
  alignX: StampAlignX.Center,
});

StampAlignX.Center Bu, türü belirtilmiş bir sabittir, bu nedenle editörünüz geçerli değerleri otomatik olarak tamamlar ve tsc İstek gönderilmeden önce yazım hatalarını yakalar.

Seçenekler ve varsayılanlar​

Örneğin, tüm seçenek arayüzleri dışa aktarılır. OptimizeOptionsİki davranış biçimini bilmekte fayda var:

  • Bir seçenek etkinleştirildiğinde varsayılan değerler uygulanır. mevcut olmayanVarsayılan optimizasyon profili şudur: MaxAçık bir şekilde null yapmak Olumsuz Varsayılan bir değer seçin.
  • Her eylem kabul eder extraEk istek alanları olarak serileştirilmiş bir nesne. Kullanın APIKendi alan adlarını kullanın ve işlem seçeneklerinin zaten sağladığı anahtarlardan kaçının.

İstemci yapılandırması​

const client = new Pdf4meClient(apiKey, {
  baseUrl: "https://api.pdf4me.com",
  timeout: 100_000,
  maxWait: 300_000,
  pollInterval: 10_000,
});

:::bilgi Tüm süreler milisaniyedir The Python İstemci aynı ayarlar için saniye cinsinden süre kullanıyor. İki sistem arasında kod aktarımı yapıyorsanız... SDKs, her süre sonunda yeniden ölçeklendirin. :::

SeçenekVarsayılanBu, neyi kaplıyor?
baseUrlhttps://api.pdf4me.comO API Her istek sunucuya gönderilir.
timeout100000 BayanHer bir bireysel istek, içeriğinin okunması da dahil olmak üzere.
maxWait300000 Bayanİlk iş gönderiminden sonra, işlem devam ederkenki durum sorguları da dahil olmak üzere, sorgulama yapılması.
pollInterval10000 BayanDurum kontrolleri arasındaki yedekleme aralığı
fetchglobalThis.fetchTest veya proxy yapılandırması için kullanışlı, özel bir taşıma yöntemi.

Her varsayılan değer aynı zamanda bir sabit olarak da dışa aktarılır (DEFAULT_TIMEOUT ve arkadaşları), böylece sabit bir sayı kodlamak yerine gönderilen değerden ölçeklendirme yapabilirsiniz.

Yapıcı fonksiyon, ilettiğiniz verileri doğrular:

  • baseUrl bir olmalı http: veya https: URL Kimlik bilgisi, sorgu dizesi veya parça olmadan. Bunun dışındaki her şey hata verir. TypeError.
  • timeout, maxWait, Ve pollInterval her biri, en fazla sonlu pozitif milisaniye sayısı olmalıdır. 2147483647Başka her şey bir hataya yol açar. RangeError.

Sayısal ve HTTP-tarih Retry-After Servisten gelen değerler, sorgulama sıklığını kontrol eder; pollInterval Bu yalnızca servis bir yoklama göndermediğinde kullanılır. Bir sonraki yoklama bu tarihten sonra gerçekleşirse maxWait Son teslim tarihine yaklaşıldığında, müşteri kalan bütçeyi tüketmek için beklemek yerine hemen vazgeçiyor.

:::Dikkat Yönlendirmeler reddediliyor İstemci ayarları yapıyor redirect: "error"Eğer trafiği 3xx yanıtı veren bir proxy üzerinden yönlendiriyorsanız, bunu şu şekilde belirtin: baseUrlYönlendirmeye güvenmek yerine, nihai varış noktasında sonuca ulaşılır. :::

Hatalar​

AtıldıNe zaman
Pdf4meExceptionHizmet başarısız oldu. Taşıma işlemleri message, responseStatusCode, traceId, Ve responseHeaders.
Pdf4meTimeoutErrorBir talep zaman sınırı (timeout) veya bir iş zaman sınırı (maxWait) ulaşıldı.
TypeErrorGeçersiz yerel giriş: boş bir değer API anahtar, kötü bir baseUrlveya boş belge içeriği.
RangeErrorKabul edilebilir aralığın dışında bir süre seçeneği.
Sıradan ErrorGövdesinde kullanılabilir hiçbir şey bulunmayan 202 numaralı araç jobIdveya bir JSON Boş sonuç döndüren işlem.
Ağ hatalarıŞuradan yayıldı: fetch değişmedi.

Pdf4meException.message Bu bilgi, hizmetin kendi web sitesinden alınmıştır. message mevcut olduğunda alana geri döner, HTTP Durum metni. Alıntı yap. traceId Destek ekibiyle iletişime geçtiğinizde: servis tarafındaki tam işi belirler.

import { Pdf4meException, Pdf4meTimeoutError } from "pdf4me";
import { optimize } from "pdf4me/optimize";

try {
  const result = await optimize(client, data, { docName: "input.pdf" });
} catch (error) {
  if (error instanceof Pdf4meTimeoutError) {
    // The job exceeded maxWait. Retry, or raise maxWait for large documents.
  } else if (error instanceof Pdf4meException) {
    console.error(error.responseStatusCode, error.traceId);
  } else {
    throw error;
  }
}

18 modül​

Her modülün kendi içe aktarma alt yolu vardır, bu nedenle paket oluşturucular ve düzenleyiciler yalnızca kullandığınızı yükler. Paket ayarları "sideEffects": falseBu özellik, paketleyicilerin kullanılmayan modülleri tamamen kaldırmasına olanak tanır.

Bazı işlemler, adından tahmin edemeyeceğiniz bir modülün içinde yer alıyor — OCR içindedir find-search, PDF/A yaratılış içindedir convert, Ve pdf4me Tek bir köprü bağlantısı eylemi içerir. Aşağıdaki tabloda dışa aktarılan her eylem listelenmiştir, böylece tahmin yürütmenize gerek kalmaz.

İçe aktarma alt yoluEylemlerDışa aktarılan fonksiyonlar
pdf4me/ai-document-extraction14aiDocumentParser, processBankCheque, processBankStatement, processContract, processCreditCard, processHealthCard, processInvoice, processMarriageCertificate, processMortgageDocument, processOrder, processPayStub, processReceipt, processShippingLabel, processTaxDocument
pdf4me/barcode7addBarcode, createBarcode, createSwissQrBill, readBarcodes, readSwissQrBill, createEpcQrCode, readBarcodesFromImage
pdf4me/convert13convertHtmlToPdf, convertJsonToExcel, convertMdToPdf, convertPdfToExcel, convertPdfToPowerpoint, convertPdfToWord, convertToPdf, convertUrlToPdf, convertVisio, convertWordToPdfForm, createPdfA, flattenPdf, linearizePdf
pdf4me/edit7addAttachmentToPdf, addHtmlHeaderFooter, imageStamp, addMargin, addPageNumber, stamp, signPdf
pdf4me/excel1findAndReplaceTextInExcel
pdf4me/extract8classifyDocument, extractAttachmentFromPdf, extractPdfFormData, extractResources, extractTableFromPdf, extractTextByExpression, extractTextFromWord, parseDocument
pdf4me/find-search2findAndReplace, convertOcrPdf
pdf4me/forms2addFormField, fillPdfForm
pdf4me/generate6enableTrackingChangesInWord, generateDocumentSingle, generateDocumentMultiple, getTrackingChangesInWord, replaceTextWithImageInWord, generateDocumentSingleV2
pdf4me/image13addImageWatermarkToImage, addTextWatermarkToImage, compressImage, convertImageFormat, createImages, cropImage, flipImage, getImageMetadata, imageExtractText, removeExifTagsFromImage, resizeImage, rotateImage, rotateImageByExifData
pdf4me/merge-split5merge, mergeOverlay, splitPdf, splitPdfByBarcode, splitByText
pdf4me/optimize1optimize
pdf4me/organize5deleteBlankPages, deletePages, extractPages, rotate, rotatePage
pdf4me/pdf16getPdfMetadata, repairPdf, createHyperlinkAnnotation, deleteHyperlinkAnnotation, digitalSignPdf, extractHyperlinkAnnotation, getDocumentByText, getTextAndCoordinates, getTextByPosition, highlightText, mergeV3, prepareForPrint, replaceTextWithImage, resizePdf, setPdfMetadata, signDocument
pdf4me/pdf4me1updateHyperlinkAnnotation
pdf4me/security2protect, unlock
pdf4me/word2disableTrackingChangesInWord, findAndReplaceTextInWord
pdf4me/zugferd1createZugferdInvoice

Eylem modüllerinin yanında iki alt yol daha bulunur: paket kökü (pdf4me), yukarıda ele alınmıştır ve pdf4me/modelsBu, her modeli ve enum sabitini yeniden dışa aktarır.

Her bir eylemin parametreleri ve yanıt şekli için aşağıdaki bilgilere bakın. PDF4me REST API referans veya oluşturulan tür bildirimlerinde node_modules/pdf4me/dist/.

9.x sürümünden yükseltme​

Sürüm 10 yeniden yazılmış bir sürümdür. 9.x serisinde kalmak için, sabitleyin. pdf4me@^9.10.15.

İki değişiklik tüm arama sitelerini bozuyor.​

Bunları hemen bulacaksınız, çünkü bunlar düzeltilene kadar hiçbir şey derlenmez veya çalışmaz.

1. ESM sadece. require("pdf4me") Artık çözümlenmiyor. Kullanın. import.

2. Bir istemci ve bağımsız eylemler. pdf4me.createClient(key)Tek bir metot nesnesi döndüren yapı, aşağıdakiyle değiştirilir. new Pdf4meClient(key) alt yollardan içe aktarılan ve çağrılan eylem fonksiyonları da dahil action(client, source, options).

// 9.x
const pdf4me = require("pdf4me");
const client = pdf4me.createClient(key);
const result = await client.optimize(/* ... */);

// 10
import { Pdf4meClient } from "pdf4me";
import { optimize } from "pdf4me/optimize";
const client = new Pdf4meClient(key);
const result = await optimize(client, data, { docName: "input.pdf" });

Üç değişiklik derlenip çalıştırılıyor ancak sorun çıkarıyor.​

Bunları elle kontrol etmelisiniz, çünkü yanlış olduklarını size hiçbir şey söylemeyecek.

1. İkili sonuçlar Uint8Array, Olumsuz Buffer. Buffer alt sınıflar Uint8Array, Bu yüzden writeFile Ve arkadaşlar hala çalışıyor. Ama Buffer-Sadece sessizce anlamsız şeyler üreten yöntemler, saçmalık saçmalık ortaya çıkarmaz:

result.toString("base64");              // 9.x: base64.  10: "0,255,65,128"
Buffer.from(result).toString("base64"); // do this instead

2. Her eylem ankete konu olur. Sürüm 10 gönderildi isAsync: true ve iş tamamlanana kadar anketler yapılır, bu nedenle tek gidiş-dönüş olan bir arama artık birkaç saate kadar engellenebilir. maxWait (varsayılan 300000 ms) ve fırlatabilir Pdf4meTimeoutError — 9.x sürümünde bulunmayan bir hata modu.

3. Yönlendirmeler reddedilir. 9.x onları takip etti; sürüm 10 belirledi. redirect: "error"3xx yanıt veren bir proxy üzerinden trafik yönlendiriyorsanız, bunu şu şekilde belirtin: baseUrl nihai varış noktasında.

Ayrıca bilmeye değer​

  • Node.js 22 artık zorunlu ve ilan edildi. engines, Ancak npm Varsayılan olarak yalnızca uyumsuzluk durumunda uyarı verir.
  • Küçük resim oluşturma (createThumbnail / createThumbnails) Ve PDF/A doğrulama (validate / validateDocument) sahip olmak 10. sürüme eşdeğer bir sürüm yokçünkü v2 API Onları ifşa etmiyor.
  • Lisans değişti. ISC ile MIT.

Yeniden adlandırmalar ve diğerlerini de içeren, yöntemden yönteme tam eşleme. integrationConfig Değişim, paketle birlikte gönderilir. Detayları şu adreste okuyabilirsiniz: node_modules/pdf4me/MIGRATION.md Kurulumdan sonra.

Sorun giderme​

Error [ERR_REQUIRE_ESM] veya require() of ES Module ... not supported. Sürüm 10 ESM Sadece. Ekle "type": "module" senin package.jsonGiriş dosyasını yeniden adlandırın. .mjsveya iğne pdf4me@^9.10.15 proje ilerleyemezse CommonJS henüz.

ERR_MODULE_NOT_FOUND için pdf4me/optimize. Alt yol içe aktarımları paket üzerinden çözümlenir. exports Bu da nispeten güncel bir harita gerektirir. Node.js ve paketleyici. Onaylayın. node --version 22 veya daha yeni bir sürüm raporladığınızdan ve alt yolu modüller tablosunda yazıldığı gibi tam olarak içe aktardığınızdan emin olun (örneğin pdf4me/merge-split(tire ile).

Base64 çıktısı şöyle görünür: "0,255,65,128". Siz aradınız .toString("base64") üzerinde Uint8ArrayÖnce paketleyin: Buffer.from(result).toString("base64").

Pdf4meTimeoutError Büyük belgeler üzerinde. İş beklentileri aştı. maxWaitvarsayılan değeri şudur: 300000 Örneğin, istemci tarafında bu sorunu dile getirin. new Pdf4meClient(apiKey, { maxWait: 900_000 })ve onaylayın timeout Yanıt gövdesini okuyabilecek kadar büyük. Her iki değerin de sınırlandırıldığını unutmayın. 2147483647 Bayan

401 numaralı yol Pdf4meException.responseStatusCode. O API Anahtar mevcut ancak reddedildi. Yeniden oluşturun. PDF4me gösterge paneli ve ortam değişkeninin işlem tarafından gerçekten görülebildiğini doğrulayın — set Windows'ta CMD Oturumlar arasında kalıcı değildir, bu nedenle şunu kullanın: setx kalıcı bir değer için.

TypeError: an API key is required. Yapıcı fonksiyon genellikle şu nedenlerden dolayı boş veya yalnızca boşluklardan oluşan bir dize aldı: process.env.PDF4ME_API_KEY Tanımlanmamıştı. Hızlı başlangıç kılavuzunda olduğu gibi, istemciyi oluşturmadan önce değişkeni kontrol edin.

TypeError: document content is empty. O Uint8Array Veya ilettiğiniz dizenin uzunluğu sıfır. Bu yerel bir kontroldür, bu nedenle herhangi bir istek gönderilmemiştir; dosyanın gerçekten başarıyla okunduğunu doğrulayın.

Kurumsal bir proxy'nin arkasında istekler başarısız oluyor. Müşteri ayarlar redirect: "error" ve bir proxy'nin 3xx. Noktasını takip etmeyecektir. baseUrl son varış noktasında veya özel bir tedarik sağlamak fetch Ulaşımınızı sağlayan.

createThumbnail veya validate İhraç edilmiyor. Her ikisi de 10. sürümde kaldırıldı, çünkü v2 API Onları açığa çıkarmaz. Yerine doğrudan takılabilen bir alternatif yok; eğer onlara bağımlıysanız 9.x sürümünde kalın.

Bundan sonra nereye gideceğiz?​

PDF4me REST API referans

PDF4mePythonSDK

Bir sorun bildirin