文档介绍

Giftpack API 让你能够在全球范围内，以编程方式构建关系驱动赠礼流程（relationship-driven gifting workflows），覆盖礼品、品牌周边（swag）和奖励场景。

你无需单独搭建奖励门户，也不需要手动协调供应商；可以直接在现有企业系统（如 CRM、HRIS、内部运营平台）中编排赠礼事件（gifting events）。API 使你的应用能够以程序化方式触发、管理并监控互动时刻，而 Giftpack 负责履约执行（fulfillment）、可用性、物流与合规。

Giftpack 的结构并非传统电商 API。它不是围绕商品目录和结账交易，而是将赠礼流程（gifting）建模为关系事件。接收人的身份、时间点和业务上下文与所发送的商品一样，都是一等输入。这使集成能够自然映射到真实业务触发点，如入职、周年纪念、成交、留存活动或客户互动里程碑。

API 提供赠礼流程各阶段的生命周期可见性，包括 redemption 状态、fulfillment 进度和配送追踪（delivery tracking）。通过这些端点，你的系统可以衡量效果、自动化后续动作，并将赠礼流程（gifting）纳入报表与运营工作流。

核心概念

在系统层面，Giftpack 遵循如下生命周期模型：

Intent → Campaign → Recipient → Redemption → Fulfillment → Tracking

每个阶段代表互动生命周期中的一次状态迁移：

Intent 定义业务触发或目标。
Campaign 作为互动容器。
Recipient 表示参与活动的对象身份。
Redemption 记录接收人的行为。
Fulfillment 处理运营履约流程。
Tracking 提供后续可见性与分析。

生命周期

业务事件
    │
    ▼
[ Intent ]
    │
    │  (同步 API)
    ▼
[ Campaign Created ]
    │
    │  (同步 API)
    ▼
[ Recipient Attached ]
    │
    │  (同步 API)
    ▼
[ Redemption Link Issued ]
    │
    │  ────── 用户行为（异步） ──────
    ▼
[ Redemption Claimed ]
    │
    │  (Webhook: giftee.preparing)
    ▼
[ Shipment Processing ]
    │
    │  (Webhook: giftee.shipped)
    ▼
[ Tracking / Delivered ]
    │
    │  (Webhook: giftee.delivered / giftee.failed / giftee.returned)
    ▼
[ Final Tracking State ]
    │
    │  (Webhook: giftee.reviewed)
    ●

生命周期前半段通过 API 调用同步发起；后半段通过接收人行为与运营履约事件（fulfillment events）异步推进。集成时应依赖状态字段与 webhook 事件，而不是假设会立即完成。

该模型可一致应用于智能赠礼（smart gifting）AutoMatch™ 活动、商城订单（marketplace orders）、品牌周边流程（swag workflows）及企业自动化场景。尤其在异步与事件驱动环境中，理解该模型是构建可靠集成的关键。

名词定义

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

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

1. 互动层 (Engagement Layer)

该层建模发送方与接收方之间的关系生命周期。它是事件驱动（event-driven）且常常是异步的。

接收人 (Recipient)

可能接收礼品或奖励的真实个体（员工、客户或合作伙伴）。在 API 语义中，Recipient 是 Giftpack 工作区内的持久身份。Recipient 可独立于 Campaign 存在，也可在不同时间参与多个 Campaign。

接收人分组 (Recipient Group)

用于定向与批量分配的逻辑集合。分组是组织结构概念，不代表交易。

活动 (Campaign)

Campaign 表示一次独立的互动意图。

其定义内容包括：

目的（例如 onboarding、retention、milestone）
redemption 时间窗口
预算分配
可参与接收人

Campaign 不是订单。 Campaign 是生命周期容器，redemption 与 fulfillment 事件在其中发生。

受赠状态 (Giftee)

当 Recipient 被附加到 Campaign 时，会成为 Giftee。 Giftee 代表接收人在该 Campaign 中的参与状态。这个区分非常重要：

Recipient = 身份
Giftee = 活动绑定状态

活动模板 (Campaign Template)

定义活动的展示层，包括：

消息内容
品牌元素
邮件内容

模板影响沟通方式，不影响 fulfillment 逻辑。

兑换动作 (Redemption)

Redemption 表示接收人执行领取礼品的动作。可通过以下方式发生：

redemption 链接
redemption 邮件
礼品卡流程（可选）

Redemption 将状态从 “invited” 转为 “claimed”。

兑换链接 (Redemption Link)

允许 Giftee 领取礼品的唯一 URL。

兑换邮件 (Redemption Email)

使用 Campaign Template 发送 redemption 链接的邮件。

2. 商业层 (Commerce Layer)

该层处理交易与 fulfillment 相关操作。它可以独立于 Campaign 工作流运行。

商城商品 (Marketplace Product)

由发送方直接选择的固定精选商品。通常在下单后会立即 fulfilled。

商城订单 (Marketplace Order)

面向一个或多个接收人的直接购买交易。可跳过 Campaign 式 redemption，直接进入 fulfillment。 Marketplace Order ≠ Campaign。

商城订单接收人 (Marketplace Order Receiver)

在 Marketplace Order 中被指定为 fulfillment 目标的接收人。

Swag 商品 (Swag Product)

通过 Giftpack 库存与仓储系统管理的可定制商品。可能需要：

procurement
库存分配
批量 fulfillment

商品 (Product)

Marketplace 或 Swag 目录中的可售容器对象。

商品变体 (Product Variant)

商品的具体可购买配置，例如：

尺寸
颜色
配置

交易始终发生在 Product Variant 层级。

3. 供应与运营层 (Supply & Operations Layer)

该层支撑 fulfillment 与 vendor 管理。对大多数集成来说通常被抽象，但对理解状态流转仍然重要。

采购办公室 (Procurement Office)

负责以下内容的运营层：

vendor onboarding
inventory sourcing
quality control
fulfillment governance

供应商 (Provider)

向 Giftpack 生态提供商品的 vendor。

托管供应商 (Managed Provider)

由 Procurement Office 监督的 Provider，用于目录质量、onboarding 与运营管控。

供应商代码 (Provider Code)

在 API 操作中引用 Provider 的唯一标识符。

关系概览 (Relationship Overview)

以下结构展示了这些实体之间的关系：

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 Integration API 的请求都必须使用有效 API Key 完成认证。

每个端点都强制执行认证，并以 workspace 边界进行访问控制。未授权或认证不正确的请求会在业务逻辑执行前被拒绝。

API 密钥

每个 Giftpack workspace 都可以在 Giftpack 控制台创建一个或多个 API Key。

API Key 用于：

认证 API 请求
标识请求来源 workspace
执行资源级授权
应用使用控制与速率限制

API Key 为 workspace-scoped。无法访问其来源 workspace 之外的资源。

Giftpack 不会在不同 workspace 之间共享 API Key。

安全提示：API Key 可访问 workspace 级资源，请按机密凭证进行管理。

获取 API Key

创建 API Key 步骤：

登录 Giftpack 控制台
进入 Integration Hub → API Keys
在 Giftpack Integration 下生成新的 API Key

API Key 创建后立即生效。系统会记录密钥创建事件以用于审计与追踪。

重要提示：请妥善保管 API Key，不要在 client-side 代码或公开仓库中暴露。

使用 API Key

每次请求都必须在 X-API-KEY header 中携带 API Key。

GET /v1/recipients HTTP/1.1
Host: developer.giftpack.ai
X-API-KEY: YOUR_API_KEY

缺少有效 API Key 的请求将返回认证错误。认证会在请求处理和资源评估前执行。

授权模型

授权在 workspace 级别执行。 API Key 仅可访问：

Recipients
Campaigns
Marketplace Orders
Swag Orders
Credits
Providers
该 workspace 的其他资源

严禁跨 workspace 访问。授权决策在服务端执行，不能通过客户端参数覆盖。

密钥生命周期管理

企业集成应建立完善的密钥生命周期管理机制。

建议实践：

为 staging 与 production 使用不同 API Key
定期轮换 API Key
若怀疑泄露，立即吊销 API Key
避免在不同团队或系统之间共享 API Key

若 API Key 被吊销，后续使用该密钥的请求将被拒绝。

Giftpack 不会自动轮换 API Key。密钥管理由集成方负责。

传输安全

所有 API 请求必须通过 HTTPS。

最低 TLS 版本：TLS 1.2
明文 HTTP 请求会被拒绝

所有传输中的数据均使用行业标准 TLS 加密。

包括：

Recipient 数据
收货/配送信息
订单元数据
认证 headers

Giftpack 不支持不安全传输连接。

速率限制

为确保平台稳定与公平使用，API 请求受速率限制。超限时 API 将返回：

HTTP 状态 429
RATE_LIMIT_EXCEEDED 错误码

集成方应：

实现重试逻辑
使用指数退避（exponential backoff）
避免高频轮询

对于高并发或突发企业负载，请联系 Giftpack 讨论速率配置。

数据隐私与 PII 处理

Giftpack API 可能处理个人可识别信息（PII），包括：

收件人姓名
邮箱地址
收货地址

开发者有责任：

确保数据处理具有合法依据
在适用情况下获得必要的收件人同意
遵守相关法规（如 GDPR、CCPA）
减少不必要的数据存储

Giftpack 仅为执行赠礼与奖励流程处理数据。 Giftpack 不会将收件人数据用于广告或无关画像分析。

日志与审计建议

在企业环境中，建议集成方：

记录 outbound API requests
记录响应码与错误状态
监控异常认证失败
监控异常 rate-limit 事件

Giftpack 内部会记录：

认证尝试
密钥使用情况
安全相关事件

认证错误响应

认证与授权错误采用一致结构。

{
  "error_code": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "action": "Verify your API key and include it in the X-API-KEY header"
}

常见认证相关错误码包括：

UNAUTHORIZED
FORBIDDEN
RATE_LIMIT_EXCEEDED

安全最佳实践

生产环境建议：

将 API Key 存储在安全环境变量中
不要在前端或 client-side 应用中暴露 API Key
不要将 API Key 提交到版本控制
限制内部对 production key 的访问
优先使用 server-to-server 集成

若怀疑 API Key 泄露：

立即吊销该密钥
生成替代密钥
检查近期 API 日志是否存在异常使用

错误处理与状态映射

Giftpack API 使用标准 HTTP 状态码，并返回结构化错误 payload。

所有错误响应都包含机器可读错误码与 request_id。联系支持团队时，请始终提供 request_id。

错误响应格式

所有错误都遵循以下结构：

{
  "error": {
    "code": "invalid_request",
    "message": "Recipient email is required.",
    "request_id": "req_123"
  }
}

字段说明

code – 机器可读错误标识
message – 人类可读错误说明
request_id – 用于调试追踪的唯一请求标识

建议在系统日志中保留 request_id，用于运维排障。

HTTP 状态码

Giftpack 使用标准 HTTP 状态语义：

200 / 201 – 请求成功
400 – 校验失败或请求格式错误
401 – API Key 缺失或无效
403 – 权限不足
404 – 资源不存在
409 – 冲突（如重复资源或状态冲突）
429 – 超出速率限制
5xx – 服务器内部错误

重试指南

并非所有错误都应该重试。

可安全重试

429（超出速率限制）
5xx（服务器错误）

重试时请使用 exponential backoff。避免激进的立即重试。

不要重试

400（校验错误）
401 / 403（认证或权限失败）
404（资源引用无效）
409（业务逻辑冲突）

这些错误通常表示客户端需要先修正后再提交。

异步状态与 HTTP 状态

HTTP 成功并不等于履约完成。

例如：

201 Created 仅表示 campaign 已创建
不表示 redemption 已完成
不表示 shipment 已完成
不表示 delivery 已完成

Giftpack 的多数操作是异步推进的。

要确定生命周期状态，请：

通过 GET 端点查询资源状态
或监听 webhook 事件

请将 HTTP 成功视为“请求已被接受”，而非“业务已完成”。

幂等性考虑

若集成会进行重试，请确保重复请求不会产生非预期副作用。

适用时建议：

使用唯一 external identifier
保存你自己的 request tracking ID
避免对 4xx 进行盲目重试

Giftpack 可能根据端点逻辑拒绝重复创建资源。

速率限制行为

当触发速率限制时：

返回 HTTP 状态 429
延迟后再重试

集成应：

实现 exponential backoff
避免紧密轮询
优先使用 webhook 更新，而不是高频 GET 轮询

支持与诊断

若遇到异常错误：

记录完整错误 payload
记录 request_id
联系 Giftpack 支持时提供 request_id

这将帮助支持团队快速在服务器日志中定位问题。

Webhook 与异步事件

Giftpack 工作流是异步的。

API 成功响应仅表示请求已被接受。 redemption、fulfillment、shipping、delivery 等生命周期更新会通过 webhook 事件通知。

生产集成 必须将 webhook 作为主要状态更新机制。状态端点轮询仅用于对账或恢复。

支持的事件类型

Webhook 事件类型由 Giftpack 控制台直接管理与展示。查看或配置可用事件触发器：

https://giftpack.ai/app/developer/webhooks

控制台 UI 反映当前已支持且可用于生产的事件类型。可用事件应以 UI 为准。

当前支持示例：

giftee.created
giftee.launched
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned
giftee.reviewed

事件可用性会随时间演进。生产配置请始终参考控制台。

Webhook 配置

Webhook 按 workspace 在控制台中配置。每条配置包含：

name
endpoint
event_types
active 开关
workspace 级 secret key

配置示例：

{
  "name": "Giftpack Delivery Updates",
  "endpoint": "https://example.com/webhooks/giftpack",
  "event_types": [
    "giftee.created",
    "giftee.shipped",
    "giftee.delivered"
  ]
}

一个 workspace 可拥有多个 webhook 配置。

投递模型

Webhook 采用 at-least-once delivery 模型。

意味着：

同一事件可能重复投递
投递顺序不保证严格有序
集成端必须实现幂等处理

当你的端点返回任意 2xx HTTP 状态码，即视为投递成功。

非 2xx 响应会触发额外重试。

接收端点约定

你的 webhook 端点必须：

接收 POST + JSON payload
返回 2xx HTTP 状态确认成功
在合理超时窗口内完成响应
安全处理重复事件

确认示例：

HTTP/1.1 200 OK
Content-Type: application/json

{"ok": true}

建议使用 webhook event ID 作为去重键。

事件日志与投递尝试

Giftpack 控制台提供完整 webhook 事件日志。每条事件包含：

事件元数据
原始 payload
投递状态
尝试次数
每次尝试的请求/响应诊断信息

日志状态码：

0 – failed
1 – processing
2 – success

事件详情 API 同时暴露：

Webhook event（逻辑事件）
Webhook event requests（单次投递尝试）

事件详情对象示例：

{
  "webhook_event_id": "wev_01H...",
  "webhook_setting_id": "whs_01H...",
  "webhook_event_type": "giftee.shipped",
  "webhook_event_resource_type": "giftee",
  "webhook_event_resource_id": "gft_01H...",
  "webhook_event_status": 2,
  "webhook_event_attempts": 1,
  "webhook_event_data": "{...raw payload...}",
  "webhook_event_created_at": "2026-02-20T02:00:00.000Z",
  "webhook_event_updated_at": "2026-02-20T02:00:01.000Z"
}

每次尝试记录包含：

目标 endpoint
HTTP 响应状态
响应 headers
响应 body
时间戳

该日志提供完整可追踪性，便于集成排错。

Webhook 测试控制台

Giftpack 在控制台提供内置 Webhook 测试控制台。你可以：

选择 webhook endpoint
选择事件类型
发送模拟事件 payload
查看端点实时响应

可用于：

端到端验证
payload 检查
即时响应诊断

测试响应示例：

{
  "event_data": {
    "type": "giftee.created",
    "resource_type": "giftee",
    "resource_id": "gft_01H..."
  },
  "response_http_status": "200",
  "response_http_headers": {"content-type": "application/json"},
  "response_http_body": "{\"ok\":true}"
}

测试控制台用于生产启用前的开发与验证。

传输要求

虽然当前 UI 可能允许配置 http 或 https，但生产集成应始终使用 HTTPS。

使用 HTTPS 可确保：

传输加密
防止中间人拦截
满足企业安全合规要求

集成最佳实践

为确保 webhook 稳定处理：

使用幂等事件处理
记录所有入站事件
存储事件 ID 进行去重
避免在 webhook handler 中执行长耗时同步逻辑
将重任务下放后台任务
监控投递失败尝试

Webhook 是生命周期更新的权威来源。不要把同步 API 成功响应当作最终业务状态。

Webhook 签名校验

为确保 webhook 事件来自 Giftpack 且未被篡改，每个 webhook 请求都会使用 workspace 专属 secret 进行签名。

生产集成 必须校验 webhook 签名。

签名 Header 格式

每个 webhook 请求都包含：

X-GIFTPACK-SIGNATURE: t=1708459200,v1=abcdef1234567890...

组成部分

t — Unix 时间戳（秒）
v1 — HMAC SHA-256 签名

签名生成方式：

HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

必须使用原始请求体 raw_body，不能做任何改写。

校验流程

校验 webhook 请求步骤：

读取 X-GIFTPACK-SIGNATURE header
解析 timestamp（t）和 signature（v1）
获取原始请求体（JSON 解析前）
计算：

expected_signature = HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

使用 timing-safe comparison 对比 expected_signature 与 v1
如下情况必须拒绝请求：

签名不匹配
时间戳过旧（建议：超过 5 分钟）

防重放攻击

为防止重放攻击：

校验时间戳在可接受窗口内（±300 秒）
存储已处理事件 ID 并拒绝重复
不接受未签名 payload

时间窗口示例：

current_time - timestamp <= 300 seconds

示例（Node.js）

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;

  const elements = signatureHeader.split(',');
  const timestamp = elements.find(e => e.startsWith('t='))?.split('=')[1];
  const signature = elements.find(e => e.startsWith('v1='))?.split('=')[1];

  if (!timestamp || !signature) return false;

  const payload = `${timestamp}.${rawBody}`;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );

  const currentTime = Math.floor(Date.now() / 1000);
  const tolerance = 300; // 5 minutes

  if (Math.abs(currentTime - Number(timestamp)) > tolerance) {
    return false;
  }

  return isValid;
}

Express 示例：

app.post('/webhooks/giftpack',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-giftpack-signature'];
    const isValid = verifySignature(
      req.body.toString(),
      signature,
      process.env.GIFTPACK_WEBHOOK_SECRET
    );

    if (!isValid) {
      return res.status(400).send('Invalid signature');
    }

    const event = JSON.parse(req.body.toString());

    // Process event safely

    res.status(200).json({ ok: true });
});

Secret 管理

Webhook secrets：

每条 webhook 配置唯一
必须安全存储（环境变量）
不应暴露在 client-side 代码中
如怀疑泄露应立即轮换

如 secret 已轮换，请立即更新你的集成。

失败处理

如果签名校验失败：

返回非 2xx HTTP 状态
不处理 payload
记录失败用于安全监控

重复签名失败可能表示：

secret 不一致
endpoint 配置错误
恶意流量

投递模型提醒

Webhook 投递遵循 at-least-once。可能存在重复事件。

按案例构建

Giftpack API 围绕真实业务工作流设计。

与其直接逐个查端点，不如先选择你要实现的业务案例。每个案例都说明：

业务目标
API 调用顺序
预期生命周期
相关 webhook 事件

Webhook 验签与签名处理细节请参考 Webhook 与异步事件 章节。

案例 1：员工表彰活动（Smart Gifting）

业务场景

你希望：

表彰员工
分配预算
让收件人自行选礼
追踪兑换与履约
将最终状态同步回 HRIS 或 CRM

这是基于 Campaign 的 Giftee 流程。

生命周期概览

Create Campaign
      ↓
Add Giftee
      ↓
Generate Redemption Link
      ↓
Recipient Claims
      ↓
Order Processing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

1. 创建 Campaign

POST /v1/campaigns

定义：

预算
时长
目标逻辑
redemption 时间窗口

2. 添加 Giftees

POST /v1/giftees

每个 giftee 代表该 campaign 内的一位收件人。

3. 生成 Redemption Link

POST /v1/campaigns/{campaignId}/giftees/{gifteeId}/redeemlink

share_claim_link

你可以：

通过 Giftpack 发送
通过内部邮件系统发送

1. 获取商品

GET /v1/providers/{providerCode}/products

使用该端点浏览可用商品。如需完整详情：

GET /v1/providers/{providerCode}/products/{productId}

选择：

product_id
product_variant_id

2. 创建 Marketplace Order

POST /v1/marketplaceorders

提供：

product_id
product_variant_id
member_id
quantity
如需要则提供 shipping information

订单会被异步受理并开始履约。

1. 为收件人启用积分功能

POST /v1/pointrecipients/{memberId}/enablepointfeature

该操作允许收件人持有并兑换积分。

2. 发放积分

PATCH /v1/pointrecipients/{memberId}/points

提供：

points
如需可附 allocation metadata

收件人余额会立即更新。

3. 兑换触发 Giftee 生命周期

当收件人兑换积分后：

会创建 giftee 记录
履约开始
生命周期正常推进

文档介绍

核心概念

生命周期

名词定义

接收人 (Recipient)

接收人分组 (Recipient Group)

活动 (Campaign)

受赠状态 (Giftee)

活动模板 (Campaign Template)

兑换动作 (Redemption)

兑换链接 (Redemption Link)

兑换邮件 (Redemption Email)

商城商品 (Marketplace Product)

商城订单 (Marketplace Order)

商城订单接收人 (Marketplace Order Receiver)

Swag 商品 (Swag Product)

商品 (Product)

商品变体 (Product Variant)

采购办公室 (Procurement Office)

供应商 (Provider)

托管供应商 (Managed Provider)

供应商代码 (Provider Code)

关系概览 (Relationship Overview)

认证与安全

API 密钥

获取 API Key

使用 API Key

授权模型

密钥生命周期管理

传输安全

速率限制

数据隐私与 PII 处理

日志与审计建议

认证错误响应

安全最佳实践

错误处理与状态映射

错误响应格式

字段说明

HTTP 状态码

重试指南

异步状态与 HTTP 状态

幂等性考虑

速率限制行为

支持与诊断

Webhook 与异步事件

支持的事件类型

Webhook 配置

投递模型

接收端点约定

事件日志与投递尝试

Webhook 测试控制台

传输要求

集成最佳实践

Webhook 签名校验

签名 Header 格式

校验流程

防重放攻击

Secret 管理

失败处理

投递模型提醒

按案例构建

1. 创建 Campaign

2. 添加 Giftees

3. 生成 Redemption Link

相关 Webhook 事件

1. 获取商品

2. 创建 Marketplace Order

相关 Webhook 事件

1. 为收件人启用积分功能

2. 发放积分

3. 兑换触发 Giftee 生命周期

相关 Webhook 事件