从这里开始

Giftpack API 可让你的后端创建并运行奖励、激励、企业礼品和受赠人自主选择等工作流。你的系统负责管理业务触发条件和客户数据；Giftpack 则负责目录供应情况、受赠体验、履约以及配送进度更新。

生产环境的基础 URL 为：

https://developer.giftpack.ai

如需完整的请求和响应 schema，请参阅 API Reference。本指南可帮助你选择正确的资源系列，并了解资源创建后的状态变化。

选择工作流

资源模型

Smart Gifting 以 campaign 作为项目容器，并以 giftee 表示每位受赠人的生命周期：

Campaign -> Giftee -> Redemption -> Fulfillment -> Delivery

直接目录订单以 marketplace order 作为订单容器，并以 marketplace order receiver 表示每位受赠人的生命周期：

Marketplace Order -> Receiver -> Claim or Selection -> Fulfillment -> Delivery

请勿将 giftee 和 marketplace_order_receiver 视为可互换的资源。即使两者的履约状态看起来相似，其事件名称仍代表不同的订单系列。

请求生命周期

创建和更新请求会返回资源的当前状态。受赠人操作、履约、发货和送达则会异步继续进行。

要构建可靠的集成：

• 保存返回的资源 ID。
• 订阅对应的 Webhook 事件系列。
• 使用 Webhook 事件的 id 作为去重键。
• 当系统检测到事件丢失或延迟时，通过 GET 端点核对资源状态。
• 除非该 API 操作明确说明幂等性约定，否则请勿自动重试会改变状态的请求。

第一个请求

在 Giftpack 创建 API key 后，可通过 Webhook 事件目录验证访问权限：

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

响应会列出 API 当前支持的 Webhook 事件类型。此端点才是事件目录的权威来源，请勿依赖硬编码在客户端中的列表。

后续步骤

1. 存储或使用 API key 前，请先阅读身份验证与安全。
2. 在实施指南中选择一种工作流。
3. 生产环境上线前，先配置并验证 Webhook。
4. 使用 API Reference 查看各端点的必填字段和响应模型。

名词定义

这些定义描述了 Giftpack API 集成中使用的核心领域对象。 在构建工作流之前，理解这些对象之间的关系非常关键。 Giftpack 主要运行在三层模型上：

1. 互动层 (Engagement Layer)
2. 商业层 (Commerce Layer)
3. 供应与运营层 (Supply & Operations Layer)

Recipient
  └─ may belong to Recipient Group
  └─ becomes Giftee when attached to Campaign

Campaign (Engagement Container)
  ├─ defines Redemption rules
  ├─ manages Giftee states
  └─ may generate Fulfillment Orders

Commerce Layer
  ├─ Marketplace Order (direct transaction)
  └─ Swag Order (inventory-based transaction)

Redemption
  ├─ Link-based
  ├─ Email-based
  └─ Transitions state before fulfillment

身份验证与安全

Giftpack 核心 /v1 操作使用限定于工作区的 API key，并通过 X-API-KEY header 发送。API key 只能由可信的服务器端应用程序使用。

访问要求

API key 可在开发者设置中管理。工作区和当前用户必须拥有 Giftpack Open API 功能的访问权限，以及开发者设置所需的权限。

如果无法打开“开发者”页面，请先让工作区管理员确认工作区方案和你的角色，再开始构建集成。

创建并存储 Key

1. 登录 Giftpack。
2. 打开开发者设置。
3. 为目标环境创建 API key。
4. 将 key 存储在服务器端的密钥管理工具中。

绝不要将 API key 放在浏览器 JavaScript、移动应用程序、日志、屏幕截图、客服工单或源代码版本控制中。

测试环境和生产环境应使用不同的凭证。如果 key 可能已经泄露，请立即撤销。

验证请求

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

API key 用于标识工作区。资源授权会在服务器端强制执行，因此即使获得其他工作区的 ID，也不代表能够访问该资源。

环境与传输

• 将生产环境请求发送至 https://developer.giftpack.ai。
• 所有请求都必须使用 HTTPS。
• 将凭证保存在各环境专用的密钥存储中。
• 请勿在本地开发环境中重复使用生产环境的 key。

API Reference 中的部分 connector 操作会使用 bearer token 或提供商专用的身份验证方式。请按照各项操作所列的 security scheme 执行，不要假设 Giftpack API key 能够调用 connector 端点。

运维实践

• 按照组织的安全策略定期轮换凭证。
• 仅允许确有需要的服务访问 key。
• 在请求和错误日志中遮蔽 X-API-KEY。
• 记录操作、资源 ID、HTTP 状态和时间戳，以便支持团队进行诊断。
• Webhook 签名必须独立于 API 请求身份验证进行校验。

公开约定并未承诺所有操作共用统一的速率限制或重试策略。如果各端点提供了相关 header 或 API Reference 说明，请以这些信息为准；规划突发高流量请求前，请先联系 Giftpack。

错误与恢复

Giftpack 操作使用标准 HTTP 状态码。API Reference 所记录的错误响应使用 application/problem+json。

问题响应

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Property email is required but is missing.",
  "instance": "https://developer.giftpack.ai/errors/example",
  "errors": [
    {
      "location": "body.email",
      "message": "The email field is required.",
      "value": null
    }
  ]
}

字段

• type：标识问题类型的 URI，可能为 about:blank。
• title：稳定、易于理解的问题摘要。
• status：此响应对应的 HTTP 状态。
• detail：本次具体失败的说明。
• instance：如有提供，用于标识本次问题实例的 URI。
• errors：可选的字段级错误详情，包含 location、message 和 value。

并非每个错误都保证包含所有字段。解析器应能容忍可选字段缺失，以及未来新增的未知字段。

按状态恢复

各项操作所记录的响应，以 API Reference 为权威来源。

安全重试

GET 请求通常可以使用设有上限的指数退避策略重试。会改变状态的请求则需要更加谨慎：

• POST 或 PATCH 请求超时后，请勿直接重试。
• 先确认该操作是否记录了幂等性，或是否会返回可供核对的资源。
• 开始下一步前，先持久化存储返回的 ID。
• 如果端点支持，请使用自有的业务引用字段。
• 防止多个并发 worker 提交同一项逻辑操作。

传输超时只表示客户端未收到响应，不能证明服务器没有完成该请求。

支持诊断

上报问题时，请提供端点、method、UTC 时间戳、HTTP 状态、相关资源 ID，以及已遮蔽敏感信息的问题响应。绝不要附上 API key 或未经遮蔽的受赠人数据。

Webhook 与异步事件

Webhook 会报告 API 请求返回后发生的受赠人和履约状态转换。请将 Webhook 作为生命周期的主要信号，并使用 GET 操作核对状态。

事件目录

请获取最新目录，不要硬编码旧版列表：

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

当前目录包含两个资源系列。

giftee

Smart Gifting 订单的受赠人生命周期事件，包括通过集成启动的 campaign、定时项目和自动化奖励工作流。

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed
• giftee.cancel
• giftee.resume
• giftee.delete

marketplace_order_receiver

直接通过 Gift Mall 或 Merchandise Catalog 创建、且不属于 Smart Gifting campaign 工作流的订单，其受赠人生命周期事件。

• marketplace_order_receiver.created
• marketplace_order_receiver.launched
• marketplace_order_receiver.shipped
• marketplace_order_receiver.delivered
• marketplace_order_receiver.failed
• marketplace_order_receiver.returned
• marketplace_order_receiver.reviewed
• marketplace_order_receiver.delete

Payload 约定

每次投递的内容都是 JSON object。data 是结构化的资源快照，不是经过转义的 JSON string。

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "type": "giftee.shipped",
  "data": {
    "id": "23e4567-e89b-12d3-a456-426655440000",
    "type": "giftee",
    "email": "recipient@example.com",
    "status": 12,
    "delivery_status": 2,
    "budget": 100,
    "campaign": {
      "id": "323e4567-e89b-12d3-a456-426655440000"
    },
    "recipient": {
      "id": "423e4567-e89b-12d3-a456-426655440000"
    },
    "delivery_tracking_code": "TRACKING-CODE"
  },
  "created_at": "2026-09-01 15:23:33"
}

• id 是持久保留的事件实例 ID，应作为去重键。
• type 用于标识资源系列和状态转换。
• data 捕获事件发生时的资源状态。字段会因资源系列和生命周期阶段而异。
• created_at 是事件发生时间。投递顺序可能与事件发生顺序不同，因此排列状态转换时请使用此值。
• 资源从线上数据中删除后，delete 事件仍会保留最后一次存储的快照。

签名验证

Giftpack 会将原始 request body 的 HMAC-SHA256 digest 以小写十六进制格式放在 X-Giftpack-Signature 中发送。

const crypto = require('crypto');

function verifyGiftpackWebhook(rawBody, signature, secret) {
  if (!signature) return false;

  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const actualBuffer = Buffer.from(signature, 'utf8');
  const expectedBuffer = Buffer.from(expected, 'utf8');

  return (
    actualBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(actualBuffer, expectedBuffer)
  );
}

请在解析或处理 payload 前验证签名。Webhook secret 应存储在服务器端的密钥存储中。

投递与重试行为

• Giftpack 会使用 HTTP POST 发送 JSON body。
• 任何 2xx 响应都表示投递成功。
• 每次请求最长可保持打开 60 秒。
• 投递失败后，会分别在大约 1、5 和 15 分钟后重试；包括首次请求在内，最多尝试投递四次。
• 事件可能重复投递。请以幂等方式处理 id。
• 不保证投递顺序。

验证并可靠接收事件后，请尽快返回 2xx。将耗时工作移至 queue 执行。

事件日志状态

Webhook event 和 request 日志使用以下数值状态：

• -1：失败
• 0：处理中
• 1：成功

事件详情响应包含结构化的 webhook_event_data、尝试次数，以及每次 request record，供故障排查使用。

生产环境检查清单

• 仅订阅你的工作流会产生的事件系列。
• 使用未经修改的 raw body 验证 X-Giftpack-Signature。
• 按事件 id 去重。
• 存储 created_at，并允许事件不按顺序到达。
• 仅在事件已安全接收后返回 2xx。
• 监控进入失败状态的事件。
• 启用生产环境端点前，先使用 dashboard 测试操作。

实施指南

请根据受赠人获得奖励的方式选择对应的资源系列。每个必填字段和响应模型仍以 API Reference 为权威来源。

curl https://developer.giftpack.ai/v1/marketplaceorders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "marketplace_order_name": "September employee rewards",
    "marketplace_order_start_date": "2026-09-01",
    "marketplace_order_end_date": "2026-09-30",
    "marketplace_order_type": "Normal",
    "submit": false,
    "receivers": [
      {
        "member_id": "9a1232aa-238f-421c-82e7-45693d1b25b4",
        "country": "US",
        "gift_message": "Thank you for your contribution.",
        "email_notification": true,
        "sms_notification": false,
        "marketplace_feature": false,
        "donation_feature": false,
        "products": [
          {
            "marketplace_product_id": "961be65a-88d8-4040-8808-843ccf5da624",
            "marketplace_product_variant_id": "961be65a-a96a-412d-b22a-325f07d85647",
            "product_quantity": 1
          }
        ]
      }
    ]
  }'

curl https://developer.giftpack.ai/v1/pointrecipients/MEMBER_ID/points \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "credits": 1,
    "points": 100,
    "expired_at": "2027-09-01",
    "notes": "Annual recognition allocation"
  }'

生产环境上线前

• 根据当前 API Reference 验证必填字段。
• 使用非生产环境的受赠人数据和凭证进行测试。
• 持久化存储每个返回的资源 ID。
• 配置对应的 Webhook 事件系列。
• 验证签名并对事件去重。
• 重试会改变状态的请求前，先定义系统核对超时结果的方式。