PDF4me JavaScript SDK Memulai

Yang pdf4me paket pada npm adalah yang resmi TypeScript/JavaScript ESM klien untuk PDF4me REST APIIni menyediakan 106 tindakan di 18 modulMengonversi, mengoptimalkan, menggabungkan, memisahkan, memberi cap, dan mengekstrak konten dari dokumen dengan fungsi asinkron dan hasil bertipe. Tipe disertakan di dalam paket, jadi TypeScript proyek tidak memerlukan pemisahan @types instal.

Fakta kemasan

Bidang	Nilai
Nama paket	pdf4me
Versi saat ini	10.0.1 (diterbitkan 14 September 2026)
Lisensi	MIT
Node.js mendukung	>=22, dinyatakan dalam engines
Format modul	ESM hanya ("type": "module")
Jenis	Dibundel (dist/index.d.ts)
Efek samping	Tidak ada ("sideEffects": false)
Tindakan	106 melintasi 18 subjalur impor
Ketergantungan saat runtime	Lima Microsoft Kiota paket (abstraksi ditambah JSON(formulir, teks, dan serialisasi multibagian)
Sumber	github.com/pdf4me/pdf4me-clientapi-javascript
npm	npmjs.com/package/pdf4me

Prasyarat

• Node.js 22 tahun atau lebih baru.
• A PDF4me akun dan API kunci.
• Sebuah proyek yang dapat menggunakan ESM import sintaks ("type": "module" di dalam dirimu package.json, atau .mjs berkas).

Dapatkan milikmu API Kunci

Lihat di npm

Lihat di GitHub

Memasang

npm

npm install pdf4me@^10

pnpm

pnpm add pdf4me@^10

Yarn

yarn add pdf4me@^10

Yang ^10 Jangkauan itu penting. A ^9 rentang ketergantungan akan bukan Gunakan versi 10 secara terpisah, karena versi 10 merupakan penulisan ulang dengan perubahan yang signifikan. Lihat Melakukan upgrade dari versi 9.x di bawah.

:::peringatan Node.js 22 diperlukan, tetapi npm hanya memperingatkan engines menyatakan node: ">=22", dan secara default npm Mengeluarkan peringatan alih-alih kesalahan jika terjadi ketidakcocokan. Sebuah proyek masih berjalan. Node.js Versi 18 akan berhasil diinstal pada versi 10, tetapi kemudian gagal saat dijalankan. Periksa node --versionsebelum Anda mengirimkan barang. :::

Untuk bekerja dari source checkout dan bukan dari registry, jalankan perintah berikut: npm install Dan npm run build di dalam direktori paket, lalu jalankan npm install /absolute/path/to/pdf4me dari direktori aplikasi Anda.

Otentikasi

Atur milik Anda API kunci dalam lingkungan:

Bash / Zsh

export PDF4ME_API_KEY="your-api-key"

PowerShell

$env:PDF4ME_API_KEY = "your-api-key"

Windows CMD

set PDF4ME_API_KEY=your-api-key

Klien mengirimkan kunci sebagai sebuah Authorization: Basic <apiKey> Header pada setiap permintaan. Pustaka ini tidak mencatat kredensial atau isi dokumen. Membuat klien dengan kunci kosong akan menimbulkan kesalahan. TypeError segera, sebelum panggilan jaringan apa pun.

Mulai cepat

Simpan ini sebagai optimize-pdf.mjs dan meletakkan sebuah input.pdf di direktori kerja yang sama. Contoh ini mengunggah PDF untuk optimasi dan menyimpan hasilnya sebagai 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");

Jalankan dengan:

node optimize-pdf.mjs

Impor yang sama berlaku di TypeScript ESM proyek, dengan tipe yang termasuk dalam paket.

Tiga hal yang perlu diperhatikan:

1. Satu klien, banyak tindakan. new Pdf4meClient(apiKey) menyimpan konfigurasi. fetch memiliki kumpulan koneksi, jadi tidak ada close() metode yang akan dipanggil dan tidak ada yang perlu dilepaskan setelah selesai.
2. Aksi adalah fungsi mandiri, bukan metode klien. Masing-masing diimpor dari subjalurnya sendiri (pdf4me/optimize, pdf4me/merge-split, pdf4me/edit) dan disebut sebagai action(client, source, options).
3. Urutan argumen sudah tetap. Klien yang dapat digunakan kembali terlebih dahulu, konten sumber berikutnya ketika tindakan tersebut membutuhkannya, dan objek opsi terakhir.

Apa yang diekspor oleh root paket

Subjalur akar (pdf4me) membawa klien dan tipe pendukungnya. Aksi tidak pernah berada di sini.

Ekspor	Baik	Tujuan
Pdf4meClient	kelas	Memegang API Pengaturan kunci dan transportasi; diteruskan sebagai argumen pertama untuk setiap tindakan.
Pdf4meException	kelas	Dilemparkan ketika layanan mengembalikan kegagalan.
Pdf4meTimeoutError	kelas	Dilemparkan ketika batas waktu permintaan atau pekerjaan tercapai.
Pdf4meClientOptions	jenis	Objek opsi yang diterima oleh konstruktor klien.
DocumentSource	jenis	Uint8Array | string — bentuk konten sumber yang diterima
DEFAULT_BASE_URL	konstanta	https://api.pdf4me.com
DEFAULT_TIMEOUT	konstanta	100000
DEFAULT_MAX_WAIT	konstanta	300000
DEFAULT_POLL_INTERVAL	konstanta	10000

Permintaan dan hasil

Setiap tindakan mengirimkan isAsync: true dan menunggu hasil yang lengkap. Segera HTTP 200 kembali langsung. Sebuah HTTP 202 mengembalikan ID pekerjaan, yang kemudian diakses oleh klien. GetActionStatus sampai pekerjaan selesai. Kode Anda melihat satu await Bagaimanapun juga.

Apa yang Anda berikan

DocumentSource adalah Uint8Array | string, yang mencakup empat bentuk praktis:

Sumber formulir	Catatan
Uint8Array	Termasuk Node.js Buffer, yang merupakan subkelas Uint8ArrayByte dienkode base64 untuk Anda, dalam potongan-potongan terbatas sehingga dokumen besar tidak menyebabkan stack overflow.
string base64	Melewatinya tanpa hambatan.
pdf4meblobid://...	Referensi ke konten yang sudah dimiliki oleh PDF4me.
URL	Layanan tersebut mengambil dokumen itu sendiri.

Konten kosong ditolak secara lokal dengan TypeError alih-alih dikirim.

Aksi dengan banyak input menerima array yang terurut. addAttachmentToPdf adalah pengecualian: dibutuhkan sebuah attachments Pemetaan objek antara nama file dan konten.

Apa yang Anda dapatkan kembali

Jenis hasil	Jenis	Contoh
Tindakan berkas	Uint8Array	Diterima langsung oleh Node.js writeFile
JSON tindakan	Model bertipe	DocMetadata, SplitPdfRes

Model dan konstanta enum diekspor baik dari modul aksi itu sendiri maupun dari pdf4me/models subjalur. Kolom respons yang tidak diketahui tetap dipertahankan di additionalData, jadi yang lebih baru API Lapangan tidak pernah ditinggalkan begitu saja.

Dua panggilan lagi

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 adalah konstanta bertipe, jadi editor Anda akan melengkapi nilai-nilai yang valid secara otomatis dan tsc Mendeteksi kesalahan ketik sebelum permintaan dikirim.

Opsi dan pengaturan default

Semua antarmuka opsi diekspor, misalnya OptimizeOptionsAda dua perilaku yang patut diketahui:

• Nilai default diterapkan ketika suatu opsi dipilih. absenProfil optimasi default adalah MaxSebuah pernyataan eksplisit. null melakukan bukan Pilih default.
• Setiap tindakan menerima extra, sebuah objek yang diserialisasi sebagai bidang permintaan tambahan. Gunakan APInama kolomnya sendiri, dan hindari kunci yang sudah disediakan oleh opsi tindakan.

Konfigurasi klien

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

Semua durasi adalah milidetik

The Python Klien menggunakan detik untuk pengaturan yang sama. Jika Anda memindahkan kode di antara keduanya. SDKs, skala ulang setiap durasi.

Pilihan	Bawaan	Apa yang dibatasinya
baseUrl	https://api.pdf4me.com	Yang API host tempat setiap permintaan dikirim
timeout	100000 MS	Setiap permintaan individu, termasuk membaca isi permintaan tersebut.
maxWait	300000 MS	Melakukan polling setelah pengajuan pekerjaan awal, termasuk permintaan status selama proses pengerjaan.
pollInterval	10000 MS	Jeda cadangan antara pemeriksaan status
fetch	globalThis.fetch	Transportasi khusus, berguna untuk pengujian atau konfigurasi proxy.

Setiap nilai default juga diekspor sebagai konstanta (DEFAULT_TIMEOUT dan teman-teman), sehingga Anda dapat melakukan penskalaan dari nilai yang dikirim daripada memasukkan angka secara manual.

Konstruktor memvalidasi apa yang Anda berikan:

• baseUrl haruslah sebuah http: atau https: URL tanpa kredensial, string kueri, atau fragmen. Apa pun selain itu akan menimbulkan kesalahan. TypeError.
• timeout, maxWait, Dan pollInterval masing-masing harus berupa bilangan milidetik positif terbatas yang tidak lebih besar dari 2147483647Apa pun selain itu akan menimbulkan RangeError.

Numerik dan HTTP-tanggal Retry-After nilai dari layanan mengontrol ritme polling; pollInterval Hanya digunakan ketika layanan tidak mengirimkannya. Jika polling berikutnya akan jatuh setelah maxWait Jika tenggat waktu tiba, klien langsung menyerah daripada menunggu sampai anggaran yang tersisa habis terlebih dahulu.

:::peringatan Pengalihan ditolak Klien menetapkan redirect: "error"Jika Anda mengarahkan lalu lintas melalui proxy yang merespons dengan kode 3xx, maka... baseUrldi tujuan akhir, alih-alih mengandalkan pengalihan yang diikuti. :::

Kesalahan

Dilempar	Kapan
Pdf4meException	Layanan tersebut mengembalikan kegagalan. Membawa message, responseStatusCode, traceId, Dan responseHeaders.
Pdf4meTimeoutError	Batas waktu permintaan (timeout) atau batas waktu pekerjaan (maxWait) telah tercapai.
TypeError	Input lokal tidak valid: kosong API kunci, yang buruk baseUrlatau isi dokumen yang kosong.
RangeError	Opsi durasi berada di luar rentang yang diterima.
Biasa Error	Sebuah pesawat 202 yang badannya tidak membawa barang yang dapat digunakan. jobId, atau sebuah JSON tindakan yang menghasilkan hasil kosong.
Kesalahan jaringan	Disebarluaskan dari fetch tidak berubah.

Pdf4meException.message diambil dari layanan itu sendiri message lapangan bila ada, kembali ke HTTP Teks status. Kutip traceId Saat Anda menghubungi dukungan: sistem akan mengidentifikasi masalah spesifik yang perlu ditangani di sisi layanan.

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 modul

Setiap modul memiliki subjalur impornya sendiri, sehingga bundler dan editor hanya memuat apa yang Anda gunakan. Paket tersebut menetapkan "sideEffects": false, yang memungkinkan bundler untuk menghapus modul yang tidak digunakan sepenuhnya.

Beberapa aksi berada dalam modul yang mungkin tidak Anda duga dari namanya — OCR berada di dalam find-search, PDF/A penciptaan ada di dalam convert, Dan pdf4me hanya berisi satu aksi hyperlink. Tabel di bawah ini mencantumkan setiap aksi yang diekspor sehingga Anda tidak perlu menebak-nebak.

Impor subjalur	Tindakan	Fungsi yang diekspor
pdf4me/ai-document-extraction	14	aiDocumentParser, processBankCheque, processBankStatement, processContract, processCreditCard, processHealthCard, processInvoice, processMarriageCertificate, processMortgageDocument, processOrder, processPayStub, processReceipt, processShippingLabel, processTaxDocument
pdf4me/barcode	7	addBarcode, createBarcode, createSwissQrBill, readBarcodes, readSwissQrBill, createEpcQrCode, readBarcodesFromImage
pdf4me/convert	13	convertHtmlToPdf, convertJsonToExcel, convertMdToPdf, convertPdfToExcel, convertPdfToPowerpoint, convertPdfToWord, convertToPdf, convertUrlToPdf, convertVisio, convertWordToPdfForm, createPdfA, flattenPdf, linearizePdf
pdf4me/edit	7	addAttachmentToPdf, addHtmlHeaderFooter, imageStamp, addMargin, addPageNumber, stamp, signPdf
pdf4me/excel	1	findAndReplaceTextInExcel
pdf4me/extract	8	classifyDocument, extractAttachmentFromPdf, extractPdfFormData, extractResources, extractTableFromPdf, extractTextByExpression, extractTextFromWord, parseDocument
pdf4me/find-search	2	findAndReplace, convertOcrPdf
pdf4me/forms	2	addFormField, fillPdfForm
pdf4me/generate	6	enableTrackingChangesInWord, generateDocumentSingle, generateDocumentMultiple, getTrackingChangesInWord, replaceTextWithImageInWord, generateDocumentSingleV2
pdf4me/image	13	addImageWatermarkToImage, addTextWatermarkToImage, compressImage, convertImageFormat, createImages, cropImage, flipImage, getImageMetadata, imageExtractText, removeExifTagsFromImage, resizeImage, rotateImage, rotateImageByExifData
pdf4me/merge-split	5	merge, mergeOverlay, splitPdf, splitPdfByBarcode, splitByText
pdf4me/optimize	1	optimize
pdf4me/organize	5	deleteBlankPages, deletePages, extractPages, rotate, rotatePage
pdf4me/pdf	16	getPdfMetadata, repairPdf, createHyperlinkAnnotation, deleteHyperlinkAnnotation, digitalSignPdf, extractHyperlinkAnnotation, getDocumentByText, getTextAndCoordinates, getTextByPosition, highlightText, mergeV3, prepareForPrint, replaceTextWithImage, resizePdf, setPdfMetadata, signDocument
pdf4me/pdf4me	1	updateHyperlinkAnnotation
pdf4me/security	2	protect, unlock
pdf4me/word	2	disableTrackingChangesInWord, findAndReplaceTextInWord
pdf4me/zugferd	1	createZugferdInvoice

Dua subjalur lagi berada di samping modul aksi: akar paket (pdf4me), yang telah dibahas di atas, dan pdf4me/models, yang mengekspor ulang setiap model dan konstanta enum.

Untuk parameter dan bentuk respons setiap tindakan, lihat PDF4me REST API referensi atau deklarasi tipe yang dihasilkan di node_modules/pdf4me/dist/.

Melakukan upgrade dari versi 9.x

Versi 10 adalah penulisan ulang. Untuk tetap menggunakan versi 9.x, sematkan pdf4me@^9.10.15.

Dua perubahan merusak setiap lokasi panggilan.

Anda akan segera menemukan masalah ini, karena tidak ada yang dapat dikompilasi atau dijalankan sampai masalah tersebut diperbaiki.

1. ESM hanya. require("pdf4me") tidak lagi teratasi. Gunakan import.

2. Klien ditambah tindakan mandiri. pdf4me.createClient(key), yang mengembalikan satu objek metode, digantikan oleh new Pdf4meClient(key) ditambah fungsi aksi yang diimpor dari subjalur dan dipanggil sebagai 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" });

Tiga perubahan berhasil dikompilasi dan dijalankan, tetapi berperilaku tidak wajar.

Inilah angka-angka yang perlu diperiksa secara manual, karena tidak ada yang akan memberi tahu Anda jika angka-angka tersebut salah.

1. Hasil biner adalah Uint8Array, bukan Buffer. Buffer subkelas Uint8Array, Jadi writeFile dan teman-teman masih bekerja. Tapi Buffer-Hanya metode-metode ini yang secara diam-diam menghasilkan omong kosong daripada menimbulkan masalah:

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

2. Setiap tindakan diikutsertakan dalam jajak pendapat. Versi 10 mengirimkan isAsync: true dan melakukan polling hingga pekerjaan selesai, sehingga panggilan yang tadinya hanya satu kali perjalanan pulang pergi sekarang mungkin akan terblokir hingga beberapa kali. maxWait (bawaan 300000 ms) dan bisa melempar Pdf4meTimeoutError — sebuah mode kegagalan yang tidak dimiliki oleh versi 9.x.

3. Pengalihan ditolak. Versi 9.x menyusul; versi 10 menetapkan redirect: "error"Jika Anda mengarahkan lalu lintas melalui proxy yang merespons 3xx, arahkan baseUrl di tujuan akhir.

Hal lain yang perlu diketahui

• Node.js 22 sekarang dipersyaratkan dan dinyatakan dalam engines, Tetapi npm Secara default, hanya memberikan peringatan jika terjadi ketidakcocokan.
• Pembuatan thumbnail (createThumbnail / createThumbnails) Dan PDF/A validasi (validate / validateDocument) memiliki tidak ada versi 10 yang setara, karena v2 API tidak mengekspos mereka.
• Lisensi tersebut berubah dari ISC ke MIT.

Pemetaan lengkap metode demi metode, termasuk penggantian nama dan integrationConfig Penggantian, dikirim bersama paket. Baca selengkapnya di node_modules/pdf4me/MIGRATION.md setelah instalasi.

Penyelesaian Masalah

Error [ERR_REQUIRE_ESM] atau require() of ES Module ... not supported. Versi 10 adalah ESM hanya. Tambahkan "type": "module" untuk Anda package.json, ganti nama file entri menjadi .mjs, atau pin pdf4me@^9.10.15 jika proyek tidak dapat berjalan CommonJS belum.

ERR_MODULE_NOT_FOUND untuk pdf4me/optimize. Impor subjalur diselesaikan melalui paket. exports peta, yang membutuhkan versi yang cukup terkini Node.js dan bundler. Konfirmasi node --version laporan versi 22 atau yang lebih baru, dan bahwa Anda mengimpor subjalur persis seperti yang tertulis dalam tabel modul (misalnya pdf4me/merge-split(dengan tanda hubung).

Output Base64 terlihat seperti ini: "0,255,65,128". Anda menelepon .toString("base64") pada suatu Uint8ArrayBungkus dulu: Buffer.from(result).toString("base64").

Pdf4meTimeoutError pada dokumen berukuran besar. Pekerjaan tersebut melebihi ekspektasi. maxWait, yang secara default menjadi 300000 Misalnya, sampaikan hal itu kepada pihak klien. new Pdf4meClient(apiKey, { maxWait: 900_000 })dan mengkonfirmasi timeout masih cukup besar untuk membaca isi respons. Perhatikan bahwa kedua nilai tersebut dibatasi hingga 2147483647 MS.

Angka 401 di Pdf4meException.responseStatusCode. Yang API Kunci ada tetapi ditolak. Buat ulang di PDF4me dasbor dan pastikan variabel lingkungan tersebut benar-benar terlihat oleh proses tersebut — set di Windows CMD tidak berlaku di seluruh sesi, jadi gunakan setx untuk nilai permanen.

TypeError: an API key is required. Konstruktor menerima string kosong atau hanya berisi spasi, biasanya karena process.env.PDF4ME_API_KEY tidak terdefinisi. Periksa variabel sebelum membuat klien, seperti yang dilakukan panduan memulai cepat.

TypeError: document content is empty. Yang Uint8Array atau string yang Anda berikan memiliki panjang nol. Ini adalah pemeriksaan lokal, jadi tidak ada permintaan yang dikirim — verifikasi apakah file benar-benar berhasil dibaca.

Permintaan gagal karena berada di balik proxy perusahaan. Klien mengatur redirect: "error" dan tidak akan mengikuti 3xx milik proxy. Poin baseUrl di tujuan akhir, atau menyediakan layanan khusus. fetch yang menangani transportasi Anda.

createThumbnail atau validate tidak diekspor. Keduanya dihapus di versi 10, karena v2 API tidak mengeksposnya. Tidak ada pengganti langsung; tetap gunakan versi 9.x jika Anda bergantung padanya.

Ke mana harus pergi selanjutnya?

PDF4me REST API referensi

PDF4mePythonSDK

Laporkan masalah