請求・財務
EC と SaaS 決済向けの領収書PDF API
注文、決済、税、返金のデータから、QR コード、バーコード、PDF/A 設定、繰り返し使えるテンプレート出力を備えた領収書PDFを生成します。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 対象システム EC バックエンド / 課金バックエンド / SaaS プラットフォーム / POS エクスポートサービス
解決する業務課題
確定済みの注文、決済、返金、税のデータを、メール送信、保存、印刷、または顧客アカウントへの添付ができる領収書PDFに変換します。各呼び出し側が PDF 描画コードを抱える必要はありません。
この API が合う場合
- 自社システム側で、すでに決済状態、領収書番号、税明細行、顧客データを管理している場合。
- メール、アカウント履歴、サポート業務、監査エクスポート向けの領収書PDFが必要な場合。
- 照会、返金、受け取りのフロー向けに、領収書の中に QR コードやバーコードを入れたい場合。
- レイアウトが承認されたあと、安定した領収書テンプレートが必要な場合。
置き換えないもの
- 決済処理や返金の実行が必要な場合。gPdf は領収書を生成します。資金移動は自社の決済システムが担います。
- 法的な電子インボイスのパッケージングが必要な場合。Factur-X や ZUGFeRD の出力には E-Invoice Render エンドポイントを使います。
- POS ハードウェアの制御やキャッシュドロワーのロジックが必要な場合。
呼び出す endpoint
/api/v1/pdf/render
JSON Render がこのワークフローの標準パスです。
/api/v1/template-render
関連 API パス、テンプレート契約、または機能確認が必要な場合に使います。
最小リクエスト
POST /api/v1/pdf/render - 照会用 QR コード付きのコンパクトな領収書。
{
"pages": [
{
"size": "a6",
"elements": [
{
"type": "text",
"x": 10,
"y": 12,
"content": "Receipt R-2026-1001",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 10,
"y": 28,
"content": "Order total: $82.40\nPaid by card ending 4242\nTax: $6.10",
"style": { "font_size": 10, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "qrcode",
"content": "https://example.com/receipts/R-2026-1001",
"x": 10,
"y": 58,
"width": 28,
"height": 28
}
]
}
]
}
gPdf が担当すること
- JSON Render の送信データから領収書ページを生成すること。
- テキスト、合計、明細行、QR コード、バーコード、メタデータ、任意の PDF/A 設定。
- 同じ領収書レイアウトを再利用するときの Template Render へのバインド。
- バイナリ PDF 出力。失敗時は共通の gPdf エラーエンベロープを返します。
自社システムが担当すること
- 支払いのオーソリ、キャプチャ、返金、税計算、領収書の採番。
- 顧客の識別、注文の状態、通貨の書式、保持ポリシー。
- メール配信、アカウントへの保存、重複領収書の処理。
本番前チェックリスト
- 安定した領収書番号を使い、レンダリングごとに X-Request-Id を渡す。
- 領収書を元データから再生成するか、初回生成後に保存するかを決める。
- 長い品名、返金、割引、複数の税明細行、金額ゼロの注文をテストする。
- サポートと財務のチームがレイアウトを承認したら Template Render へ切り替える。
- 支払いと税の判断は、レンダリングリクエストの外側に保つ。
対応範囲の境界
- gPdf は決済を処理せず、税を計算せず、返金を実行しません。
- 領収書PDFは、自動的に法的な電子インボイスになるわけではありません。
- 業務上の正本は自社システム側にあります。gPdf はその内容を PDF として表現します。
領収書PDFはレンダリングの出力
これは独立した決済や POS のエンドポイントではありません。自社の EC、課金、または POS バックエンドが「領収書が存在する」と判断し、その領収書の内容を DocumentRequest として、または公開テンプレート向けのデータとして gPdf に送ります。
レンダリング層は、同じ入力から同じ出力を返せる状態に保つべきです。サポート担当が同じ領収書を再度要求した場合、自社システムは元データを再送して再生成するか、保持ポリシーに従って以前に保存した PDF を返すかを選べます。
繰り返し使う領収書のテンプレート経路
領収書のレイアウトは、たいてい早く安定します。デザインが承認されたら、テンプレートを公開し、領収書のフィールドを渡して POST /api/v1/template-render を呼び出します。これにより、決済システムはデータに集中でき、レイアウト管理を 1 か所に集約できます。
FAQ
- gPdf は領収書の合計を計算できますか？
- いいえ。合計、割引、税、返金の状態は、自社の決済またはコマースシステムが管理します。gPdf は送られた値を PDF に出力します。
- 領収書は JSON Render と Template Render のどちらを使うべきですか？
- レイアウトを設計している間は JSON Render を使います。領収書のレイアウトとフィールド仕様が安定したら Template Render を使います。
- 領収書に QR コードを入れられますか？
- はい。gPdf は PDF 出力で QR コードのバーコード要素をサポートします。QR コードに符号化する URL や値は自社システム側で管理します。
- これは電子インボイス API と同じですか？
- いいえ。通常の領収書PDFは JSON Render または Template Render を使います。Factur-X と ZUGFeRD のパッケージングは E-Invoice Render エンドポイントを使います。