开发者工具¶
For developers 页面提供 API 访问、Webhook 配置、无头模式和高级集成选项。从左侧导航中的 For developers 打开该页面。
在本页上对复选框和 Webhook URL 所做的更改，需点击保存栏中的 Save 才会生效。令牌按钮和 Generate Secret 会立即生效。Enable headless mode 同样需要点击 Save。
Storefront API¶
Storefront API 是一个 JavaScript 接口（window.GiftHeroAPI），用于在您的店面上构建自己的礼品卡选择和购买界面。
- Enable storefront API — 开启后，会在礼品卡商品页面上加载 JavaScript API。该页面上由应用生成的礼品卡界面会被关闭，因此由您的开发人员来构建界面。
- Disable gift card page animation — 在开启 storefront API 后出现。移除应用的动画礼品卡页面，以便您构建自定义礼品卡页面。
该 API 不读取余额。它收集礼品卡的选择（金额、设计、留言、收件人），并将礼品卡添加到购物车中。
完整 API 参考： Storefront API
REST API¶
REST API 让您可以将 Gift Card Hero 与外部系统集成，例如 CRM、分析仪表板、忠诚度平台等。
启用¶
勾选 Enable REST API 并保存。然后点击 Send me access token，Gift Card Hero 会将 API 访问令牌发送到页面上显示的店铺联系人邮箱地址。
您的店铺同一时间只有一个 API 令牌，由所有使用它的集成共享：
- Send me access token 会签发新的令牌。旧令牌会立即失效，因此请用新令牌更新您的集成。若要再次查看令牌，请查找之前的那封邮件。
- Revoke access token 会在不签发新令牌的情况下停用当前令牌。如果令牌可能已泄露，或合作伙伴不再需要访问权限，请使用此选项。
- 关闭 Enable REST API 也会撤销令牌。
详细信息： 管理您的 API 令牌
页面上提供 Postman collection 链接，便于快速探索 API。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} |
获取单张礼品卡 |
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 参考
Webhooks¶
当特定的礼品卡事件发生时，Gift Card Hero 可以向您的服务器发送 HTTP POST 请求。
开启 Enable REST API 后，Webhook 设置会显示在本页上。
设置 Webhook 密钥¶
点击 Generate Secret 创建签名密钥。请立即从横幅中复制——它只会显示一次。在您的服务器上使用该密钥验证传入的负载确实来自 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 元字段中：
- Namespace:
gift_hero - Key:
cards_data
数据按礼品卡代码的最后四个字符进行索引。这样一来，在生成礼品卡期间，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 |
复制该代码片段，并将其集成到您的自定义店面代码库中。
完整设置指南： 无头集成指南
自定义配送¶
此部分仅会出现在使用自行配送选项的店铺中。开启后，Gift Card Hero 将全权负责创建和交付订单中的礼品卡，而不再使用 Shopify 的自动礼品卡配送。
先在 Shopify 中关闭自动配送
在您的 Shopify 结账（订单处理）设置中，选择 Don't fulfill any of the order's line items automatically。该页面链接到 Check settings 以及一份 Shopify 指南。请勿自行为订单配送礼品卡，它们必须保持未配送状态。
徽章显示当前状态（Enabled 或 Disabled）。点击 Enable custom fulfilment 或 Disable custom fulfilment 进行切换。