データ形式

データをどの形式で送信する必要があるかを、ここで確認できます。PDFgineは受け取った値をそのまま印刷するのではなく、テンプレートで指定された書式をドキュメントの言語で適用します。

原則は1つです。データは未加工で受け取り、PDFgineが書式を設定します。書式付きの値を送信すると、ある言語では正しくても、別の言語では誤って表示されます。

書式は3か所で指定できます。表の列と集計行の"format"フィールド、単一の値を出力する要素の"dataRules.formatter"、複数のフィールドを結合するテキスト内のformat_date関数とformat_money関数です。

{
  "issueDate": "2026-09-06",
  "currency": "USD",
  "lineItems": [
    { "name": "企業Webサイト", "quantity": 1, "unitPrice": 24000, "total": 24000 }
  ]
}

// テンプレート側：
// 表の列：   "format": { "kind": "currency", "currency": "USD", "decimals": 2 }
// 日付の列：    "format": { "kind": "date", "dateStyle": "short" }
// テキスト要素：   "{{ referenceNo }} · {{ format_date issueDate }}"

IBAN、電話番号、納税者番号も正規化した形式で送信します。IBANには空白を含めず、電話番号はE.164形式（+442071838750）を使用します。桁区切りは表示用の書式であり、データには含めません。

ダウンロードされるドキュメントの名前

ダウンロードするドキュメントの名前は"{document type} - {counterparty} - {reference no}"になります。3つの部分は、送信データのdocument.title、customer、referenceNoから取得します。不足する部分は省略し、どの値からも使用可能な名前を作れない場合は、quote-doc_94812af2.pdfのように、ドキュメントの識別情報を使用します。

Content-Disposition: attachment;
  filename="Quote - Müller og Søn ApS - QUO-2026-0042.pdf";
  filename*=UTF-8''Quote%20-%20M%C3%BCller%20og%20S%C3%B8n%20ApS%20-%20QUO-2026-0042.pdf

同じヘッダーに、名前が2回記述されます。拡張フィールドではドキュメントの言語を保持し、従来のフィールドには拡張形式を読めないクライアント向けの、読みやすいASCII表記を格納します。ファイルシステムで使用できない文字（スラッシュ、バックスラッシュ、コロン、アスタリスク、疑問符、引用符、小なり記号、大なり記号、縦線）と制御文字を除去し、どのファイルシステムでも扱える長さに制限します。

画像

テンプレートの画像要素は、データフィールドにバインドできます。その場合、画像ソースはリクエストとともに届きます。使用できる形式は、アップロード済みアセットのID（ast_… — 繰り返し使うロゴ、印影、署名向け。一度アップロードすれば、以後はIDのみを送信）と、インライン画像（data:image/png;base64,… — 1回限りの画像向け）の2つです。フィールドがない、または空の場合は、テンプレート自体の画像を使用します。値が存在しても使用できない場合、リクエストは422で拒否され、応答に該当データフィールド名が示されます。

{
  "templateCode": "invoice",
  "format": "pdf",
  "data": {
    "logo": "ast_9f1c7b1f0f6b4f5f9f0a0d1e2c3b4a59",
    "signature": "data:image/png;base64,iVBORw0KGgo..."
  }
}

制限：インライン画像はPNG、JPEG、WebPに対応し、1画像あたり最大2 MB、1ドキュメント内の合計は最大6 MBです。アップロードするアセットは最大10 MBです。一時的な画像には、アセットのアップロード時にexpiresInMinutes（1分～7日）を指定してください。有効期限が切れたアセットは自動的に削除されます。

アセット

ロゴ、署名、フォントは一度アップロードし、IDで参照します。アップロード方法、上限、フォントで許可される利用方法は、専用ページで説明しています。

よくある問題

• 書式付きの値は、受け取ったとおりに印刷されます。"1.234,56"は、ある言語では正しく、別の言語では誤って表示され、後から書式設定で修正することはできません。
• 日付はISO 8601で送信してください。地域固有の形式はテキストとして扱われ、書式設定、並び替え、翻訳が行われません。
• 金額の中に通貨を含めないでください。数値を送信し、列の書式設定でISOコードを追加してください。
• 比率は100を基準に送信します。18%なら18です。0.18を送信すると、0.18パーセントと表示されます。
• 条件はJSONの真偽値を読み取ります。文字列の"false"は空でないテキストのため、値があるものとして扱われます。