アプリとバックエンド業務フロー向けの Shopify PDF API
Shopify アプリやバックエンドの業務フローから gPdf を呼び出し、マッピング済みの Shopify データをもとに注文PDF、請求書、納品書、返品書類、ラベルを生成します。
/api/v1/pdf/render Shopify アプリや EC バックエンドで、注文、顧客、商品、フルフィルメント、返品のデータを gPdf の JSON またはテンプレートデータにマッピングし、公式の Shopify App Store 連携を名乗らずに、再現性のある PDF を返します。
この API が合う場合
- 外部 API を呼び出せる Shopify アプリ、非公開バックエンド、またはフルフィルメント業務フローを構築している場合。
- アプリがすでに Shopify の注文、フルフィルメント、顧客、商品のデータを受け取っている場合。
- 請求書、納品書、返品書類、倉庫ラベル、PDF 添付が必要な場合。
- 事業者ごとの文書レイアウトに、template_id を軸にした安定した呼び出し契約が必要な場合。
置き換えないもの
- gPdf が公式の Shopify アプリ、または Shopify App Store 掲載アプリであることを期待している場合。
- gPdf に事業者ストアへのインストール、OAuth の処理、Webhook の直接購読を任せたい場合。
- gPdf に配送料金、送料の購入、在庫管理、事業者向け UI 機能を求めている場合。
呼び出す endpoint
/api/v1/pdf/render
JSON Render がこのワークフローの標準パスです。
/api/v1/template-render
関連 API パス、テンプレート契約、または機能確認が必要な場合に使います。
最小リクエスト
POST /api/v1/template-render - アプリバックエンドが、マッピング済みの Shopify 注文データを公開テンプレートへ送る。
{
"template_id": "packing_list",
"data": [
{
"order_number": "#1042",
"customer_name": "Example Buyer",
"ship_to": "1200 Market St, San Francisco, CA",
"items": [
{ "sku": "TSHIRT-BLK-M", "name": "Black T-shirt", "quantity": 2 },
{ "sku": "MUG-WHT", "name": "White mug", "quantity": 1 }
]
}
]
}
gPdf が担当すること
- アプリバックエンドがマッピングした Shopify 由来の JSON から PDF を生成すること。
- 事業者やブランド固有の文書レイアウト向けの Template Render。
- バーコード、QR コード、表、合計、画像、ラベル、納品書の構造。
- 公開 gPdf API を通じたステートレスな PDF 生成。
自社システムが担当すること
- Shopify アプリのコード、OAuth、Webhook、事業者向け UI、Shopify App Store での配布。
- 注文、フルフィルメント、顧客、返品、商品、税のデータのマッピング。
- 事業者ごとの設定、テンプレートの選択、配信、保存、リトライ。
本番前チェックリスト
- Shopify の認証情報と gPdf の API トークンは、ブラウザコードではなくバックエンドに保つ。
- Shopify のデータを、明示的なレンダリング用データまたはテンプレートデータスキーマにマッピングする。
- 事業者固有のレイアウトは、承認後に Template Render を使う。
- 生成した PDF または元データを、事業者の業務フローに従って保存する。
- この統合が、公式の gPdf Shopify アプリではなく、自社アプリが gPdf を呼び出すものであることを明記する。
対応範囲の境界
- 存在しない限り、公式の Shopify アプリをうたわないでください。
- gPdf は Shopify の OAuth、アプリのインストール、Webhook、事業者設定を実行しません。
- Shopify データのマッピングと EC の業務ルールは呼び出し側が管理します。
統合モデル
明確な Shopify 統合モデルは、バックエンド同士の連携です。自社アプリが Shopify データを受け取るか取得し、それを gPdf の DocumentRequest またはテンプレートデータオブジェクトにマッピングし、gPdf を呼び出し、事業者の業務フローに従って PDF を返すか保存します。
これにより、外部に説明する製品境界が正確に保たれます。gPdf は、Shopify アプリが呼び出せる PDF 生成 API です。別のアプリ製品が存在しない限り、公式の Shopify アプリではありません。
Template Render は事業者ごとのレイアウトに合う
EC の PDF はしばしば事業者固有になります。ブランディング、明細テーブル、返品手順、ラベルブロック、ギフトメモ、多言語テキストなどです。Template Render を使えば、アプリはそれらのレイアウトを公開テンプレートとして管理しながら、マッピング済みの注文データだけを送れます。
プラットフォームのロジックはアプリに保つ
OAuth、Webhook、事業者設定、フルフィルメントの状態、在庫、返品ルール、Shopify App Store での配布は、自社の Shopify アプリにとどまります。gPdf は最終的なレンダリング用データを受け取り、PDF を生成すべきです。
FAQ
- gPdf は公式の Shopify アプリですか？
- いいえ。このページは gPdf を呼び出すアプリやバックエンド向けです。その製品が存在しない限り、gPdf を公式の Shopify App Store 連携として提示しないでください。
- gPdf の API 呼び出しはどこで行うべきですか？
- Shopify の認証情報と gPdf の API トークンが保護されている、自社のバックエンドまたはアプリサーバーから gPdf を呼び出します。
- Shopify の PDF は JSON Render と Template Render のどちらを使うべきですか？
- カスタム生成のレイアウトには JSON Render を使います。事業者やブランドのレイアウトが承認され、呼び出し側がデータだけを送ればよいときは Template Render を使います。
- gPdf は Shopify の Webhook を処理しますか？
- いいえ。Webhook を受け取り、データをマッピングし、いつレンダリングするかを決めるのは自社アプリです。gPdf は受け取った PDF リクエストに対して PDF を生成するだけです。