商城订阅对接#

订阅对接的目标是让 Halo 商城负责售卖、收款、记录周期，接入方负责解释权益、实际交付并回执。Halo 不解释权益的具体含义，也不会自行判定接入方是否已经交付——这两件事通过 Webhook 与履约上报接口交给接入方。

#职责分工

接入方不需要自己实现支付页：店面购买，以及客户中心的续费、变更、取消都由 Halo 提供。

#接入方式

推荐的接入形态是一个独立的外部服务：接收 Halo 的出站 Webhook，并在需要时调用 Halo 的 Console API。这也是当前完整支持订阅业务流程的形态。

#关于 Halo 插件

订阅对接不需要也不支持通过 Halo 插件扩展商城模块：商城与订阅模块当前不提供插件扩展点（extension point），也不会把订单、订阅事件派发给插件。插件可以自行提供 REST API、自定义模型和角色，这是 Halo 的通用能力，但订阅业务流程仍然只能通过上面的两种通道完成。

因此，除为 Halo 增加与订阅无关的自定义功能外，请把接入方实现为独立的外部服务。

#端到端时序

#接入准备

1. 创建专用用户与角色：在控制台新建一个 Halo 用户（建议只用于对接），并绑定角色「订单发货上报」（role-template-report-ecommerce-fulfillments）。
2. 签发个人令牌：用该用户登录用户中心，进入个人令牌创建令牌，只勾选上一步的角色。令牌只在创建时显示一次，请妥善保存。
3. 确认访问地址：Console API 前缀为 https://{host}/apis/console.api.ecommerce.halo.run/v1alpha1，请求头携带 Authorization: Bearer pat_xxx。令牌创建方式见个人中心 / 个人令牌，认证方式说明见 RESTful API 介绍。
4. 配置 Webhook：在控制台 Webhook 中新建配置，填写回调 URL 与密钥，并订阅需要的订阅事件。操作步骤见商城 / Webhook。
5. 记录对接标识：产品线的 productId、档次的 handle、计划的 planId 与 variantId。后续所有对账都依赖这些标识。

#最小闭环

1. 运营在控制台配置 productType=SUBSCRIPTION 的产品线、档次与计划，详见订阅生命周期。
2. 接入方订阅 SUBSCRIPTION_* 事件与 FULFILLMENT_REQUESTED。
3. 客户下单支付后，接入方按 SUBSCRIPTION_CREATED / SUBSCRIPTION_TRIAL_STARTED 载荷中的 effectiveEntitlements 开通权益。
4. 收到 FULFILLMENT_REQUESTED 后完成交付，并调用履约上报接口回执；不上报，订单会一直停留在待发货。
5. 收到 SUBSCRIPTION_CANCELLED / SUBSCRIPTION_EXPIRED 后停用权益；收到 SUBSCRIPTION_PLAN_CHANGED / SUBSCRIPTION_RENEWED 后按新快照刷新。

#本组文档

相关文档：

• 商城 / Webhook
• 商城 / 订单管理
• 商城 / 虚拟交付
• RESTful API 介绍