テンプレート一覧を取得

テンプレートとは

テンプレートは、選択したコードで保存されるドキュメントデザインです。編集を続ける下書きと、本番生成に使用する公開済みバージョンが同時に存在します。保存だけでは公開されないため、未完成の変更が顧客に届くことはありません。

ワークスペース内のテンプレートと、公開済みのバージョン番号を返します。生成時には、テンプレートのコードを指定します。

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

[
  {
    "templateId": "tpl_eca4c9985ad74913902f0469469936a1",
    "code": "invoice",
    "name": "法人向け請求書",
    "version": 5,
    "publishedVersion": 1,
    "publishedAt": "2026-08-23T08:23:21+00:00"
  }
]

ページ番号の書式

ページ番号要素のcontentは書式です。{{ page }}は現在のページ、{{ pages }}は総ページ数になります。“{{ page }} / {{ pages }}”と入力すると、“3 / 12”と印刷されます。PDFではページカウンター、WordではPAGE/NUMPAGESフィールドコードを使い、ページの追加に応じて自動更新します。プレースホルダーが含まれない場合、contentは無視され、ページ番号のみを表示します。

バージョンの保存

保存時には、編集中と認識しているバージョンを指定します。その間にほかの人が保存していた場合は、409と現在のバージョンが返されるため、黙って上書きされることはありません。

curl -X POST https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "code": "invoice",
        "name": "法人向け請求書",
        "saveMode": "manual",
        "expectedVersion": 5,
        "changeReason": "ロゴを右余白へ移動しました。",
        "definition": {
          "page": { "size": "A4", "orientation": "portrait" },
          "elements": [
            { "type": "text", "text": "法人向け請求書", "fontSize": 24 }
          ]
        }
      }'

HTTP/1.1 409 Conflict

{
  "type": "https://pdfgine.dev/problems/template-conflict",
  "templateCode": "invoice",
  "currentVersion": 6,
  "currentDraftRevision": 0
}

expectedVersionは任意ですが、指定を推奨します。指定しない場合は最後の書き込みが優先され、前の変更が記録を残さず消えてしまいます。

よくある問題

• 409は、何も確認せず再試行するエラーではありません。currentVersionを読み取り、新しい定義に変更を重ねてから、再度保存してください。
• 保存と公開は異なります。下書きを公開するまで、本番生成には最後に公開したバージョンが使用されます。
• 一覧では最大200件のテンプレートが返されます。続きがある場合は、rel="next"付きのLinkヘッダーを使用してください。最初のページがライブラリ全体だと判断しないでください。
• 読み取りにはtemplates:read、保存にはtemplates:writeが必要です。読み取り専用キーで保存しようとすると、401ではなく403が返されます。
• ほかのすべての呼び出しは、コードでテンプレートを特定します。テンプレート名は自由に変更できますが、コードを変更すると新しいテンプレートになります。