開発者向けツール¶
For developers ページでは、API アクセス、Webhook の設定、ヘッドレスモード、高度な連携オプションを利用できます。左のナビゲーションで For developers を開いてください。
このページでチェックボックスや Webhook の URL を変更した場合は、保存バーの Save をクリックすると反映されます。トークンのボタンと Generate Secret はすぐに動作します。Enable headless mode は Save が必要です。
ストアフロント API¶
ストアフロント API は、ストアフロントにギフトカードの選択と購入の画面を独自に構築するための JavaScript インターフェース（window.GiftHeroAPI）です。
- Enable storefront API — ギフトカードの商品ページで JavaScript API を読み込むには、オンにします。そのページでは、アプリが生成するギフトカードの画面がオフになるため、開発者が画面を構築します。
- Disable gift card page animation — ストアフロント API をオンにすると表示されます。アプリのアニメーション付きギフトカードページを非表示にし、独自のギフトカードページを構築できるようにします。
この API は残高を読み取りません。ギフトカードの選択内容（金額、デザイン、メッセージ、受取人）を収集し、カートに追加します。
API リファレンス（全体）: ストアフロント API
REST API¶
REST API を使うと、Gift Card Hero を CRM、分析ダッシュボード、ロイヤルティプラットフォームなどの外部システムと連携できます。
有効化¶
Enable REST API にチェックを入れて保存します。その後 Send me access token をクリックすると、このページに表示されているストアの連絡先メールアドレスに、API アクセストークンが送信されます。
ストアで使用できる API トークンは1つだけで、それを使うすべての連携で共有されます。
- Send me access token は新しいトークンを発行します。以前のトークンは直ちに使えなくなるため、連携先のトークンも新しいものに更新してください。トークンを再確認するには、以前のメールを探してください。
- Revoke access token は、新しいトークンを発行せずに現在のトークンを無効にします。トークンが漏えいした可能性がある場合や、パートナーがアクセスを必要としなくなった場合に使用します。
- Enable REST API をオフにすると、トークンも取り消されます。
詳細: API トークンの管理
このページには、API をすばやく試せる Postman collection のリンクもあります。Show available API endpoints を押すと、主要なエンドポイントの一覧がこのページに表示されます。
利用可能なエンドポイント¶
| メソッド | エンドポイント | 説明 |
|---|---|---|
POST |
/api/external/gift-cards |
ギフトカードを作成 |
POST |
/api/external/gift-cards/{id}/disable |
ギフトカードを無効化 |
GET |
/api/external/gift-cards |
ギフトカードの一覧（ステータスで絞り込み可能） |
GET |
/api/external/gift-cards/{id} |
ギフトカードを1件取得 |
GET |
/api/external/gift-cards/search?query=... |
ギフトカードを検索（例: last_characters:mnop） |
PUT |
/api/external/gift-cards/{id} |
ギフトカードを更新 |
PUT |
/api/external/gift-cards/{id}/balance |
ギフトカードの残高を更新 |
POST |
/api/external/gift-cards/{id}/redeem |
POS またはレジアプリからギフトカードを利用（利用通知を送信し、店舗を記録） |
GET |
/api/external/gift-cards/transactions |
取引付きのギフトカード（ページ分割） |
POST |
/api/external/gift-cards/assign-to-order |
独自のギフトカードコードを注文に割り当て |
API リファレンス（全体）: REST API リファレンス
Webhook¶
Gift Card Hero は、特定のギフトカードのイベントが発生すると、お使いのサーバーに HTTP POST リクエストを送信できます。
Webhook の設定は、Enable REST API がオンのときにこのページに表示されます。
Webhook シークレットの設定¶
Generate Secret をクリックして署名用のシークレットを作成します。バナーからすぐにコピーしてください。表示されるのは1回だけです。サーバーでこのシークレットを使い、受信したペイロードが Gift Card Hero から送られたものであることを検証します。署名は X-GiftHero-Signature ヘッダーで送信されます（HMAC-SHA256）。
シークレットが漏えいした場合などは、Regenerate Secret をクリックしてシークレットを更新します。古いシークレットは直ちに使えなくなるため、サーバーも新しいシークレットに更新してください。
Webhook のエンドポイント¶
これらの Webhook の種類ごとに、サーバーの URL を設定します。
| ページの項目 | 送信されるタイミング |
|---|---|
| Order with gift card webhook URL | 注文のギフトカードを Gift Card Hero が処理したとき |
| Gift card payment webhook URL | ギフトカードで支払われた注文が作成されたとき |
| Gift card balance webhook URL | 現在は送信されません（連携ガイドを参照） |
各項目にエンドポイントの URL を入力して保存します。新規または変更した URL は https:// で始まり、インターネットからアクセスできる必要があります。プライベートネットワークのアドレスは、保存時に拒否されます。
連携ガイド（全体）: Webhook 連携ガイド
カスタムコードエディター¶
Shopify テーマを直接変更せずに、Gift Card Hero のストアフロントのコンポーネントに CSS を追加できます。
Open custom code editor をクリックします。Settings の Custom code タブが開きます。
CSS は、ギフトカードの商品ページ、ギフトカードページ、物理ギフトカードや任意金額のギフトカード商品のページに追加されます。ストアの他のページには追加されません。ギフトカードビルダーとギフトカードページの見た目を調整するために使用します。変更を適用するには、保存バーの Save をクリックします。
CSS のみ
エディターで受け付けるのは CSS のみです。</style を含む CSS は、保存時に拒否されます。この変更より前にストア用に設定されたカスタム JavaScript は引き続き動作しますが、ここでは編集できなくなります。変更するには、サポートにお問い合わせください。
ギフトカードのデータをメタフィールドに保存¶
Save a gift card data to a metafield にチェックを入れると、各ギフトカードのデータ（デザイン、メッセージ、送信者）が、ショップの Shopify メタフィールドに保存されます。
- ネームスペース:
gift_hero - キー:
cards_data
データは、ギフトカードコードの末尾4文字でキー付けされます。これにより、ギフトカードの生成時に Shopify のメールテンプレートや、独自の Liquid テンプレートでデータを利用できます。
Disable gift card page animation for templates with suffix — テンプレートのサフィックスが設定されたギフトカードについて、アプリのギフトカードページをオフにします（REST API の template_suffix を参照）。その場合は、代わりに独自のテンプレートが表示されます。
ヘッドレスモード¶
標準の Shopify テーマシステムを使わない、カスタムまたはヘッドレスの Shopify ストアフロントでは、ヘッドレスモードを有効にします。
Enable headless mode をクリックします（ステータスバッジが Enabled に変わります）。プレースホルダーの値を含むコードスニペットが表示されるので、ストアの値に置き換えてください。
| プレースホルダー | 置き換える値 |
|---|---|
[MONEY_FORMAT] |
ストアの金額フォーマットの文字列 |
[PRODUCT_ID] |
ギフトカード商品の Shopify の数値 ID |
[MYSHOPIFY_DOMAIN] |
ストアの .myshopify.com ドメイン |
[ADD_TO_CART_CALLBACK] |
独自のカートに追加する JavaScript 関数 |
[LOCALE] |
翻訳のロケールコード（例: en、fr）。初期値は en です |
スニペットをコピーし、カスタムストアフロントのコードベースに組み込みます。
セットアップガイド（全体）: ヘッドレス連携ガイド
カスタムフルフィルメント¶
このセクションは、セルフフルフィルメントのオプションを使用しているストアにのみ表示されます。このオプションを使うと、Shopify の自動ギフトカード配送ではなく、Gift Card Hero が注文のギフトカードの作成と配送をすべて担当します。
先に Shopify の自動フルフィルメントをオフにする
Shopify のチェックアウト（注文処理）の設定で、Don't fulfill any of the order's line items automatically を選択します。ページには Check settings と Shopify のガイドへのリンクがあります。注文のギフトカードを自分でフルフィルしないでください。ギフトカードは未フルフィルのままにしておく必要があります。
バッジには現在のステータス（Enabled または Disabled）が表示されます。切り替えるには Enable custom fulfilment または Disable custom fulfilment をクリックします。