製品・APIガイド

ドキュメントを生成

このエンドポイントの役割

1回の呼び出しで、テンプレートとデータから完成したファイルを生成します。待機中にドキュメントが生成され、レスポンスにはダウンロード先が含まれます。ポーリングは不要です。長いドキュメントや一括処理では、キュー用エンドポイントが同じ処理をバックグラウンドで行います。

テンプレートコードとデータを送信すると、ドキュメントが返されます。レスポンスのダウンロードURLは、ベースアドレスに対する相対URLで、同じAPIキーで取得します。

リクエスト

curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "locale": "ja",
        "purpose": "production",
        "data": {
          "document": { "title": "INV-2026-001" }
        }
      }'

formatフィールドは"pdf"または"docx"を受け付けます。既存クライアント向けの数値も引き続き有効で、1はPDF、2はDOCXです。レスポンスでは形式を数値で返します。

purposeがproductionの場合は利用枠を消費します。テンプレートを試す際はeditor-testを送信してください。この出力は利用枠を消費せず、未公開の下書きの改訂版を使用します。

リクエストからダウンロードまで

上の呼び出しのレスポンスと、ファイル取得の呼び出しを示します。ステータスは202で、リクエストが受け付けられ、ドキュメントの準備ができていることを示します。

レスポンス

HTTP/1.1 202 Accepted
X-PDFgine-Pages: 1
X-PDFgine-Quota-Remaining: 4999

{
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "format": "pdf",
  "templateCode": "invoice",
  "templateVersion": 1,
  "templateVersionSource": "published",
  "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
  "pageCount": 1,
  "quotaRemaining": 4999,
  "meteringBasis": "pdf-equivalent"
}

cURL

curl https://api.pdfgine.com/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -o invoice.pdf

よくある問題

生成は200ではなく202を返します。200以外を失敗と見なすクライアントでは、成功をエラーとして報告してしまいます。
purposeは2つの動作を決めます。productionは公開済みのバージョンを使用し、利用枠を消費します。editor-testは未公開の下書きを使用し、利用枠を消費しません。productionでテストすると、テンプレートの試用に最も多くの費用がかかります。
422はサーバー障害ではありません。本文のerrorsには、テンプレートが要求する各フィールドが示されます。再試行ではなく、送信データを修正してください。
402は、月間ページ利用枠を使い切ったことを示します。到達する前に、X-PDFgine-Quota-Remainingヘッダーで残量を確認できます。
downloadUrlは、APIアドレスに対する相対URLです。絶対URLとして保存すると、アドレス変更時に利用できなくなります。documentIdを保存し、アドレスを組み立ててください。

レスポンス →