API リファレンス

帳票の発行

POST /v1/renders で帳票を発行します。wait 秒（0〜25、既定 25）以内に完了すれば帳票をその場で返却し（200）、完了しない場合は 202 で Render を返して、完了時に Webhook で通知します。wait に 0 を指定した場合と、50 件を超える一括発行は、非同期で処理します。

curl https://api.docrelay.jp/v1/renders \
  -H "Authorization: Bearer $DOCRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv_88" \
  -d '{
    "template": "請求書",
    "format": "pdf",
    "data": { "customer": { "name": "株式会社サンプル" }, "total": 128000 },
    "wait": 10
  }' \
  -o 請求書.pdf

const res = await fetch('https://api.docrelay.jp/v1/renders', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DOCRELAY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'inv_88',
  },
  body: JSON.stringify({
    template: '請求書',
    format: 'pdf',
    data: { customer: { name: '株式会社サンプル' }, total: 128000 },
    wait: 10,
  }),
});
if (res.status === 200) {
  const pdf = Buffer.from(await res.arrayBuffer()); // x-render-id・x-content-sha256 ヘッダーも返却
} else if (res.status === 202) {
  const render = await res.json(); // { id: 'rnd_…', status: 'queued', … } → 完了時に render.succeeded を Webhook で通知
}

type RenderRequest = {
  template: string;          // テンプレートの ID または名前
  version?: number;          // 省略時は本番環境で公開中、テスト環境で最新
  format?: 'pdf' | 'xlsx' | 'docx' | 'csv';  // 省略時は先頭の形式
  data?: object;             // 1 件分のデータ
  items?: object[];          // 1〜1,000 件。zip で返却
  merge?: boolean;           // レイアウトのみ: 1 つの PDF に結合
  wait?: number;             // 秒。0〜25（既定 25）
  keep_for?: number;         // 保存期間（秒。既定 86,400）
  link?: true | { expires_in?: number; max_downloads?: number };  // 有効期限付き URL
  metadata?: Record<string, string>;  // 20 個まで。Webhook にも含める
  csv?: {                    // CSV の書き出し方（format が csv のときだけ）
    newline?: 'crlf' | 'lf';  // 既定 crlf
    trailing_newline?: boolean;  // 最後の行のあとの改行（既定 true）
    bom?: boolean;           // UTF-8 の BOM（既定 true）
    encoding?: 'utf-8' | 'shift_jis';  // 既定 utf-8
    quote?: 'minimal' | 'all';  // minimal は必要なときだけ、all はすべて囲む
  };
};

type Render = {
  id: string;                // rnd_…
  status: 'queued' | 'rendering' | 'succeeded' | 'failed' | 'expired';
  template_id: string; version: number; format: string;
  filename: string; size: number | null; sha256: string | null; item_count: number;
  error: { code: string; message: string } | null;
  ledger: { seq: number } | null;
  link: { url: string; expires_at: number } | null;
  metadata: Record<string, string>;
  created_at: number; completed_at: number | null; expires_at: number | null;
};

• その場で返却するときのヘッダー: content-type、content-disposition（日本語のファイル名に対応）、x-render-id、x-content-sha256。
• Idempotency-Key ヘッダー（任意）を指定すると、24 時間以内の同じキーによる再送には同じ発行結果を返します。
• リクエスト本文は 5MB までです。
• 本番環境の発行は、帳票 1 件ごとに月間発行数に含みます（一括発行は件数分）。テスト環境の発行とプレビューは含みません。
• 応答には Server-Timing（認証・テンプレートの読み込み・フォント・描画などの段ごとの ms）を付けます。X-DocRelay-Timing: cpu を付けると、描画の CPU 時間 cpu も返します。

テンプレート

レイアウト

テンプレートエディターで作成するレイアウトは JSON で表し、PUT /v1/templates/:id/layout で保存できます。長さの単位は mm、原点は用紙の左上です。書き方の説明とサンプルは、MCP の get_layout_guide でも取得できます。

明細テーブルと本文の表

• wrap: true でセルの文字を列の幅で折り返し、行の高さを最も高いセルに合わせます。ページに入らない行は、セルの中の行の単位で次のページに分けます。
• 行のデータの _span（列をまたぐ）・_align（寄せ）・_bold（太字）で、行ごとに見た目を変えられます。
• 列の rich に指定した項目（[{ text, bold?, color?, underline? }]）で、一部の文字だけ太字・色・下線を変えられます。本文の Markdown では **太字**・<u>下線</u> を使えます。
• headerBold（見出しの行の太字）・padding（セルの内側の余白）・lineHeight（セルの行の高さ）を指定できます。
• 本文の表のセルには、段落・箇条書き・表を 1 段まで入れ子にできます（データのブロックのみ）。

そのほかの指定

• follow: { id, gap? }: 表・本文の実際の終わりに合わせて、合計欄などの要素を詰めて置きます。入りきらなければ次のページに送ります。
• repeat: 表と本文以外の要素を、最初のページ・すべてのページ・最後のページのどれに描くかを指定します。
• watermark: { text, size?, color?, opacity?, angle?, tile?, gap? }: すべてのページに半透明の文字を重ねます。tile: true でページ全体にくり返します。
• 差し込み項目: {{a.b}}・{{x | number}}・{{d | date:YYYY年M月D日}}・{{#list}}…{{/list}}・{{^x}}…{{/x}}・{{_page}}・{{_pages}}。
• レイアウトの形式の誤りは 422 invalid で、fields に elements[3].w のような項目ごとの説明を返します。

完了通知（Webhook）

イベントは render.succeeded・render.failed の 2 種類です。本文は { type, data: Render } です。送信先の登録方法は、提供開始時にご案内します。

{
  "type": "render.succeeded",
  "data": {
    "id": "rnd_…", "status": "succeeded", "filename": "invoice_1024.pdf",
    "sha256": "a3f9…", "item_count": 1, "link": null, …
  }
}

保存期間

帳票の保存期間は keep_for（秒）で指定します。既定は 86,400 秒（24 時間）で、上限はプランの保存期間です。保存期間を過ぎた帳票は削除し、発行の記録（ハッシュ値・サイズ・ファイル名）と改ざん検知ログだけを残します。

改ざん検知ログ

ブロックチェーン技術を応用した改ざん検知です。発行した帳票の SHA-256・発行 ID・テンプレートとバージョン・日時を、1 つ前の記録と連結して記録します。差し込んだデータは記録しません。日次ハッシュ（UTC の日単位）を公開します。

type LedgerEntry = {
  seq: number;               // 通し番号
  render_id: string; sha256: string; template_id: string; version: number;
  at: number;
  prev_hash: string;         // 1 つ前の記録の entry_hash
  // prev_hash・seq・sha256・render_id・at を "\n" でつないだ SHA-256
  entry_hash: string;
};
type DailyHead = { date: string; seq: number; entry_hash: string; published_at: number };

API キーのスコープ

GET /v1/whoami は、どのスコープでも呼び出せます。API キーの環境・プロジェクト・組織を返します。

レート制限とエラー

• レート制限は環境単位で、1 分あたりの上限はプランによって異なります（Free 60 回・Starter 300 回・Pro 1,200 回・Business 3,000 回）。すべてのレスポンスに x-ratelimit-limit・x-ratelimit-remaining・x-ratelimit-reset を付けます。上限を超えると 429 rate_limited と retry-after を返します。
• エラーは { error, message, fields?, request_id } の形式で返します。入力の誤りは 422 invalid で、fields に項目ごとの説明を含みます。
• 失敗したリクエストは、管理画面の API ログで 30 日間確認できます。