POST /api/pdf/batch
100件のPDFを1回のAPIコールで
リクエストは即座に batch_id を返し、ジョブキュー上で並列処理。ポーリングまたは batch.completed Webhook で完了を検知できます。月次の請求書発行や大量チケット生成に最適です。
この機能の主なポイント
1
即時レスポンス + 非同期処理
POST すると 201 Created と batch_id がすぐ返ります。クライアントはタイムアウトを心配せず、別のリクエストに移れます。
2
ステータスは2つの取得方法
GET /api/pdf/batch/ でポーリングするか、Webhook で batch.completed イベントを受信するか選べます。
3
失敗は自動リトライ
各アイテムは tries=2 で再実行されます。失敗したアイテムだけ error_message と共に返されるので部分再送が容易です。
使う場合 vs 使わない場合
| バッチAPIを使う | 1件ずつ呼ぶ | |
|---|---|---|
| 100件のリクエスト時間 | 1回のAPIコール、即座に201 | 100回の同期コール、合計数分 |
| クライアント側の制御 | batch_idだけ保持、後で確認 | 並列度・順序・リトライを自前管理 |
| エラー時 | 失敗アイテムだけ取り出して再実行 | 途中失敗で全体の再実行設計が必要 |
| 推奨ボリューム | 10件以上、特に夜間バッチ | 1〜数件のリアルタイム生成 |
実装例
// Submit up to 100 PDFs in one call → 201 Created with batch_id
const res = await fetch("/api/pdf/batch", {
method: "POST",
headers: { "Authorization": `Bearer ${API_KEY}` },
body: JSON.stringify({
items: orders.map(o => ({
type: "html",
html: renderInvoice(o),
expiration_hours: 72,
})),
}),
});
const { data: { batch_id } } = await res.json();
// Either poll for status...
const status = await fetch(`/api/pdf/batch/${batch_id}`, {
headers: { "Authorization": `Bearer ${API_KEY}` },
}).then(r => r.json());
// ...or subscribe to the batch.completed webhook event.