製品・APIガイド

キューによる生成

キューを使うべき場面

直接生成エンドポイントはドキュメントの準備ができると応答します。呼び出し元が待機できる場合には、最も簡単な方法です。長いドキュメント、一度に大量の生成、長時間接続を維持できないWebリクエストでは、キューを使用してください。queueIdを含むレスポンスがすぐに返され、その後も処理が続きます。

長いドキュメントや一括処理は、リクエストをキューに入れてください。レスポンスはすぐに返り、statusUrlでジョブを追跡できます。

キューの順序

キューの優先度はプランで決まり、別々のキューになるわけではありません。優先度に応じて、ジョブがより早く到着したものとして扱われます。これには2つの効果があります。優先度の高いジョブは同時にキューに入ったジョブより先に処理され、待機中のジョブが無期限に待たされることはありません。最悪の場合の待ち時間も計算でき、現在の設定値では、Freeのジョブは最大54分待ち、Maxのジョブには待ち時間がありません。

リクエスト

curl -X POST https://api.pdfgine.com/api/v1/documents/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateCode": "invoice", "format": "pdf", "data": { } }'

レスポンス

{
  "queueId": "queue_ea464b42458e4768ab26d59a88f3291d",
  "status": "queued",
  "statusUrl": "/api/v1/async-jobs/queue_ea464b42...",
  "documentId": null,
  "createdAt": "2026-08-28T13:23:45+00:00"
}

キューによる生成

curl https://api.pdfgine.com/api/v1/async-jobs/queue_ea464b42... \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

リクエストにwebhookUrlを追加すると、ジョブの完了時に署名付き通知が配信されるため、ポーリングする必要がありません。

完了したジョブの状態

statusUrlでジョブを確認してください。実行中のstatusはqueuedまたはrunningで、完了するとdocumentIdとresultに値が設定されます。

レスポンス

{
  "queueId": "queue_ea464b42458e4768ab26d59a88f3291d",
  "status": "succeeded",
  "attemptCount": 1,
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "result": {
    "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
    "pageCount": 12
  },
  "failureCode": null,
  "createdAt": "2026-08-28T13:23:45+00:00",
  "completedAt": "2026-08-28T13:23:52+00:00"
}

失敗したジョブはstatusがfailedとなり、理由を示すfailureCodeが返されます。同じコードの一覧は、エラーページに掲載されています。

よくある問題

キューは、ドキュメントなしでqueueIdを含む202を返します。ジョブ完了までdocumentIdはnullのままです。すぐに読み取り、nullを失敗と扱うのが最もよくある誤りです。
毎秒ポーリングすると、レート制限を無駄に消費します。数秒おきに確認するか、webhookUrlを送信し、ポーリングを行わないようにしてください。
statusがfailedのジョブは、保留中ではなく終了済みです。failureCodeを読み、入力を修正してください。ジョブが自動で再開することはありません。
Webhook通知には署名があります。信頼する前に、Webhookのページにある手順で署名を検証してください。また、2xxを返さないと、通知が再配信されます。
キューでの生成も、直接生成と同じページ数を消費します。キューが変えるのは処理のタイミングであり、費用ではありません。