PDF4me JavaScript SDK はじめる
の pdf4me パッケージ npm 公式 TypeScript/JavaScript ESM クライアント PDF4me REST API. それは提供する 18のモジュールにわたる106のアクション: 非同期関数と型付き結果を使用して、ドキュメントからコンテンツを変換、最適化、マージ、分割、スタンプ、抽出します。型はパッケージ内に同梱されているため、 TypeScript プロジェクトには別個のものは必要ありません @types インストール。
パッケージ情報
| 分野 | 価値 |
|---|---|
| パッケージ名 | pdf4me |
| 現在のバージョン | 10.0.1 （公開日：2026年9月14日） |
| ライセンス | MIT |
| Node.js サポート | >=22宣言された engines |
| モジュール形式 | ESM のみ （"type": "module"） |
| 種類 | バンドル（dist/index.d.ts） |
| 副作用 | なし （"sideEffects": false） |
| 行動 | 18個のインポートサブパスにわたる106個の |
| 実行時依存関係 | マイクロソフトの5つの Kiota パッケージ（抽象化と JSON（フォーム、テキスト、マルチパートシリアライザー） |
| npm | npmjs.com/package/pdf4me |
前提条件
- Node.js 22歳以下。
- A PDF4me アカウントと API 鍵。
- 使用できるプロジェクト ESM
import構文（"type": "module"あなたのpackage.json、 または.mjsファイル)。
インストール
- npm
- pnpm
- Yarn
npm install pdf4me@^10
pnpm add pdf4me@^10
yarn add pdf4me@^10
の ^10 範囲が重要です。 ^9 依存範囲は ない バージョン10は互換性のない変更を含む全面的な書き換えであるため、バージョン10を単独で入手してください。 9.xからのアップグレード 下に。
engines 宣言する node: ">=22"デフォルトでは npm 不一致が発生した場合、エラーではなく警告を発します。プロジェクトはまだ実行中です。 Node.js 18はバージョン10を正常にインストールしますが、実行時に失敗します。確認してください。 node --version発送前に。
レジストリではなくソースチェックアウトから作業するには、以下を実行します。 npm install そして npm run build パッケージディレクトリ内で、次に実行します。 npm install /absolute/path/to/pdf4me アプリケーションディレクトリから。
認証する
設定する API 環境における鍵：
- Bash / Zsh
- PowerShell
- Windows CMD
export PDF4ME_API_KEY="your-api-key"
$env:PDF4ME_API_KEY = "your-api-key"
set PDF4ME_API_KEY=your-api-key
クライアントはキーを Authorization: Basic <apiKey> すべてのリクエストにヘッダーを追加します。ライブラリは認証情報やドキュメントの内容をログに記録しません。空のキーでクライアントを構築すると、 TypeError ネットワークへの通話を行う直前に。
クイックスタート
これを保存 optimize-pdf.mjs そして input.pdf 同じ作業ディレクトリに。この例では、 PDF 最適化のために、結果を次のように保存します 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");
実行方法：
node optimize-pdf.mjs
同じインポートが機能する TypeScript ESM パッケージに含まれる型を持つプロジェクト。
注目すべき3つの点：
- 顧客一人につき、多くの案件が発生する。
new Pdf4meClient(apiKey)設定を保持します。fetch接続プールを所有しているので、close()呼び出しを行うメソッドであり、終了時に解放するものは何もありません。 - アクションは独立した関数であり、クライアントメソッドではありません。 それぞれが独自のサブパスからインポートされます（
pdf4me/optimize、pdf4me/merge-split、pdf4me/edit）と呼ばれ、action(client, source, options)。 - 引数の順序は固定されています。 再利用可能なクライアントが最初に渡され、次にアクションが実行された際にソースコンテンツが渡され、最後にオプションオブジェクトが渡される。
パッケージルートがエクスポートするもの
ルートサブパス（pdf4me）はクライアントとそのサポートタイプを格納します。アクションはここには存在しません。
| 輸出 | 親切 | 目的 |
|---|---|---|
Pdf4meClient | クラス | 保持する API キーとトランスポートの設定。すべてのアクションの最初の引数として渡されます。 |
Pdf4meException | クラス | サービスが失敗を返したときにスローされます |
Pdf4meTimeoutError | クラス | リクエストまたはジョブの制限時間に達したときにスローされます。 |
Pdf4meClientOptions | タイプ | クライアントコンストラクタが受け入れるオプションオブジェクト |
DocumentSource | タイプ | Uint8Array | string — ソースコンテンツの受け入れられた形式 |
DEFAULT_BASE_URL | const | https://api.pdf4me.com |
DEFAULT_TIMEOUT | const | 100000 |
DEFAULT_MAX_WAIT | const | 300000 |
DEFAULT_POLL_INTERVAL | const | 10000 |
リクエストと結果
すべてのアクションが送信します isAsync: true そして、完了した結果を待ちます。 HTTP 200件の返品がすぐに返ってくる。 HTTP 202 はジョブ ID を返し、クライアントはそれをポーリングします。 GetActionStatus ジョブが完了するまで。あなたのコードは1つを見ます await どちらにしても。
通過するもの
DocumentSource は Uint8Array | stringこれは、以下の4つの実用的な形態を網羅しています。
| ソースフォーム | 注記 |
|---|---|
Uint8Array | 含まれる Node.js Bufferサブクラス Uint8ArrayバイトはBase64エンコードされ、大きなドキュメントがスタックオーバーフローしないように、境界付きチャンクに分割されます。 |
| base64文字列 | そのまま通過した。 |
pdf4meblobid://... | 既に保持されているコンテンツへの参照 PDF4me。 |
| URL | このサービスはドキュメント自体を取得します。 |
空のコンテンツはローカルで拒否されます TypeError 送られるのではなく。
複数の入力を受け付けるアクションは、順序付き配列を受け入れます。 addAttachmentToPdf 例外は、 attachments オブジェクトマッピング：ファイル名とコンテンツのマッピング。
返ってくるもの
| 結果の種類 | タイプ | 例 |
|---|---|---|
| ファイル操作 | Uint8Array | 直接受け入れました Node.js writeFile |
| JSON アクション | 型付きモデル | DocMetadata、 SplitPdfRes |
モデルと列挙定数は、アクションのモジュールと pdf4me/models サブパス。不明な応答フィールドは保持されます。 additionalDataより新しい API このフィールドは決して黙って削除されることはありません。
さらに2件の電話
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 は型付き定数なので、エディタは有効な値を自動補完し、 tsc リクエストが送信される前に、入力ミスを検出します。
オプションとデフォルト設定
すべてのオプションインターフェースがエクスポートされます。例えば OptimizeOptions知っておくべき行動が2つあります。
- オプションが 不在デフォルトの最適化プロファイルは
Max明示的なnullする ない デフォルトを選択してください。 - すべての行動は受け入れる
extra追加のリクエストフィールドとしてシリアル化されたオブジェクト。 API独自のフィールド名を使用し、アクションオプションですでに提供されているキーは使用しないでください。
クライアント構成
const client = new Pdf4meClient(apiKey, {
baseUrl: "https://api.pdf4me.com",
timeout: 100_000,
maxWait: 300_000,
pollInterval: 10_000,
});
| オプション | デフォルト | それが何を覆うのか |
|---|---|---|
baseUrl | https://api.pdf4me.com | の API ホストにすべてのリクエストが送信されます |
timeout | 100000 MS | 個々のリクエストには、その本文を読むことを含めて、 |
maxWait | 300000 MS | 最初の求人応募後のアンケート調査（進行中のステータス確認依頼を含む） |
pollInterval | 10000 MS | ステータスチェック間のフォールバックギャップ |
fetch | globalThis.fetch | テストやプロキシ設定に役立つカスタムトランスポート |
各デフォルト値は定数としてもエクスポートされます（DEFAULT_TIMEOUT （そして友人たち）なので、数値をハードコーディングするのではなく、出荷された値からスケーリングできます。
コンストラクタは渡された値を検証します。
baseUrlでなければならないhttp:またはhttps:URL 認証情報、クエリ文字列、フラグメントなし。それ以外の場合は、TypeError。timeout、maxWait、 そしてpollIntervalそれぞれは、以下の値以下の正の有限ミリ秒でなければならない。2147483647それ以外のものはすべてRangeError。
数値と HTTP-日付 Retry-After サービスからの値によってポーリングの頻度が制御されます。 pollInterval サービスが送信しない場合にのみ使用されます。次のポーリングが maxWait 締め切りが迫ると、クライアントは残りの予算を使い切る前に、すぐに諦めてしまう。
:::注意 リダイレクトは拒否されます
クライアント設定 redirect: "error"3xx を返すプロキシ経由でトラフィックをルーティングする場合は、 baseUrlリダイレクトが実行されるのを待つのではなく、最終目的地で処理する。
:::
エラー
| 投げられた | いつ |
|---|---|
Pdf4meException | サービスが失敗を返しました。 message、 responseStatusCode、 traceId、 そして responseHeaders。 |
Pdf4meTimeoutError | リクエスト時間制限（timeout）またはジョブの時間制限（maxWaitに到達しました。 |
TypeError | 無効なローカル入力: 空白 API キー、悪い baseUrlまたは、ドキュメントの内容が空です。 |
RangeError | 許容範囲外の期間オプション。 |
普通 Error | 202号機は、使用可能な jobIdまたは JSON 空の結果を返したアクション。 |
| ネットワークエラー | 伝播元 fetch 変更なし。 |
Pdf4meException.message サービス自身の情報から引用 message 存在する場合はフィールドに戻り、 HTTP ステータステキスト。引用 traceId サポートに問い合わせると、サービス側で具体的にどのような作業が行われたかが特定されます。
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個のモジュール
各モジュールは独自のインポートサブパスなので、バンドラーやエディタは使用するものだけをロードします。パッケージセット "sideEffects": falseこれにより、バンドラーは使用されていないモジュールを完全に削除できるようになります。
名前からは想像できないようなモジュールにいくつかのアクションが含まれています。 OCR は find-search、 PDF/A 創造は convert、 そして pdf4me 単一のハイパーリンクアクションを保持します。以下の表にエクスポートされたすべてのアクションを一覧表示しているので、推測する必要はありません。
| サブパスをインポートします | 行動 | エクスポートされた関数 |
|---|---|---|
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 |
アクション モジュールの横にはさらに 2 つのサブ パスがあります: パッケージ ルート (pdf4me）上記で説明したとおり、 pdf4me/modelsこれは、すべてのモデルと列挙定数を再エクスポートします。
各アクションのパラメータと応答形状については、以下を参照してください。 PDF4me REST API 参照 または生成された型宣言 node_modules/pdf4me/dist/。
9.xからのアップグレード
バージョン10は書き直しです。9.x系を維持するには、ピン留めしてください。 pdf4me@^9.10.15。
2つの変更で全ての通話サイトが壊れる
これらの問題はすぐに見つかるでしょう。なぜなら、それらが修正されるまでは、何もコンパイルも実行もできないからです。
1. ESM のみ。 require("pdf4me") 解決されなくなりました。 import。
2. クライアントとスタンドアロンアクション。 pdf4me.createClient(key)メソッドの単一オブジェクトを返す は、 に置き換えられます。 new Pdf4meClient(key) サブパスからインポートされ、呼び出されたアクション関数 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" });
3つの変更はコンパイルおよび実行されるが、正しく動作しない
これらは手作業で確認する必要があるものです。なぜなら、それらが間違っていることを教えてくれるものは何もないからです。
1. バイナリ結果は Uint8Array、 ない Buffer。 Buffer サブクラス Uint8Array、 それで writeFile そして友人たちは今も働いている。しかし Buffer-メソッドは例外をスローする代わりに、静かに意味不明な結果を生成します。
result.toString("base64"); // 9.x: base64. 10: "0,255,65,128"
Buffer.from(result).toString("base64"); // do this instead
2. すべての行動は世論調査に反映される。 バージョン10の送信 isAsync: true そしてジョブが完了するまでポーリングを行うため、1回の往復で済むはずだった通話が最大でブロックされる可能性があります。 maxWait （デフォルト 300000 ms) をスローする Pdf4meTimeoutError — 9.xには存在しなかった障害モード。
3. リダイレクトは拒否されます。 9.x がそれに続き、バージョン 10 では redirect: "error"3xx に応答するプロキシ経由でトラフィックをルーティングする場合は、 baseUrl 最終目的地にて。
知っておくと良いこと
- Node.js 22 は現在必要とされ、宣言されています
engines、 しかし npm デフォルトでは、不一致の場合のみ警告を発します。 - サムネイル作成（
createThumbnail/createThumbnails） そして PDF/A 検証（validate/validateDocument） 持っている バージョン10に相当するものはありませんv2 は API それらを暴露しない。 - ライセンスが変更されました ISC に MIT。
メソッドごとの完全なマッピング（名前の変更や integrationConfig 交換品はパッケージに同梱されています。詳細は以下をご覧ください。 node_modules/pdf4me/MIGRATION.md インストール後。
トラブルシューティング
Error [ERR_REQUIRE_ESM] または require() of ES Module ... not supported。 バージョン10は ESM のみ。追加 "type": "module" あなたの package.jsonエントリ ファイルの名前を次のように変更します。 .mjsまたはピン留め pdf4me@^9.10.15 プロジェクトが開始できない場合 CommonJS まだ。
ERR_MODULE_NOT_FOUND のために pdf4me/optimize。 サブパスのインポートはパッケージを通じて解決されます exports 比較的最新の地図が必要です Node.js バンドラーも確認します。 node --version レポート22以降、モジュールテーブルに記述されているとおりにサブパスをインポートしていることを確認してください（例： pdf4me/merge-split（ハイフン付き）。
Base64出力は次のようになります。 "0,255,65,128"。 電話がかかってきた .toString("base64") で Uint8Arrayまず包んでください。 Buffer.from(result).toString("base64")。
Pdf4meTimeoutError 大きな文書の場合。 その仕事は期待を上回った。 maxWaitデフォルトでは 300000 ms。たとえば、クライアント側でそれを引き上げます。 new Pdf4meClient(apiKey, { maxWait: 900_000 })確認します timeout レスポンスボディを読み取るには、まだ十分な大きさです。両方の値は、 2147483647 MS。
401 Pdf4meException.responseStatusCode。 の API キーは存在しますが拒否されました。 PDF4me ダッシュボード そして、環境変数が実際にプロセスから認識されていることを確認します。 set Windowsで CMD セッション間で保持されないため、 setx 永続的な価値のために。
TypeError: an API key is required。 コンストラクタが空の文字列または空白のみの文字列を受け取ったのは、通常は process.env.PDF4ME_API_KEY 変数が未定義でした。クイックスタートと同様に、クライアントを構築する前に変数を確認してください。
TypeError: document content is empty。 の Uint8Array または、渡された文字列の長さがゼロです。これはローカルチェックなので、リクエストは送信されません。ファイルが実際に正常に読み込まれたことを確認してください。
企業プロキシの背後でリクエストが失敗します。 クライアントが設定する redirect: "error" プロキシの3xxポイントには従いません。 baseUrl 最終目的地で、またはカスタム fetch あなたの輸送を手配してくれる会社です。
createThumbnail または validate エクスポートされません。 両方ともバージョン10で削除されました。 API それらは公開されません。代替となるものは存在しません。それらに依存している場合は、9.x を使い続けてください。