まとめて1ファイルに

支払明細、給与明細、証書、顧客ごとの請求書 —— 同じ様式を、人数のぶんだけ。 Compose PDF はそれを1回の呼び出しで描き、1つのファイルにして返します。 各レコードはそれぞれ独立した文書として組まれます。

何通ほしいかの言い方は2つあり、どちらを使うかはリストを誰が持っているかで決まります。

呼び出し側がリストを持つ場合

data の代わりに dataList(ペイロードの配列)を送ります。各要素がそれぞれ検証され、 1つの文書として描かれ、順番どおりに綴じられます。

curl -X POST https://composepdf.com/v1/canvases/{canvasId}/pdf \
  -H "x-api-key: $COMPOSEPDF_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "dataList": [
        { "customer": { "name": "Acme Inc." },     "items": [ … ] },
        { "customer": { "name": "Brightline LLC" }, "items": [ … ] }
      ] }' \
  --output statements.pdf

スキーマ違反は、それがどのレコードから来たかを名指しします。4番目の行が悪ければ 「不正なリクエスト」ではなく dataList[3].customer.name と読めます。

テンプレートがリストを持つ場合

ペイロードが自然に「リストを内側に持つ1つのオブジェクト」で、そのリストの各要素が 1文書になるべきこともあります。その場合はスタジオでそう伝えます。印刷する文書の下で、 このデータ全体から1通ではなく**〈リスト〉の1行につき1通**を選びます。

これで data オブジェクト1つが展開されます。各文書は自分の行と、リストの外にあるもの すべて —— 対象期間、自社の住所、全通に出る注意書き —— を見ます。両方に同じ名前があれば、 行の側が勝ちます。

**この選択はテンプレートに属し、公開時に凍結されます。**だからこそ、スタジオのプレビューと ブラウザからの書き出しと API は、「このペイロードが何通になるか」について一致します。

返ってくるもの

PDF が1つ。各レコードは独立して改ページされるので、ページ番号は文書ごとです。 2通目の請求書はまたページ1から始まり、3 / 4 はその請求書の3ページ目を意味します。 応答は、描いたレコード数を x-rspdf-records に返します。総ページ数はサーバー側で記録され、 GET /v1/renders/{renderId} の pages で読めます。

注意と制限

• **dataList は1リクエストにつき100レコードまで。**それを超えるリクエストは実行されずに 拒否されます。分割してください。
• data と dataList は排他です。
• **空のリストは拒否されます。**0ページの PDF は答えとして役に立たないので、空の配列は 空のファイルではなくエラーになります。
• **長いジョブは非同期にしてください。**同期リクエストには約25秒のレンダリング予算が あります。Prefer: respond-async を付けるとジョブ id が返るので、用意ができたら ダウンロードします。 レンダリング API を参照してください。
• **非同期ジョブでは暗号化を使えません。**ジョブが待っているあいだパスワードを保存する ことになるためです。