Appearance
Sugumart Open API 大纲
本文档定义 Sugumart Open API 的章节结构与能力范围。API 面向外部开发者和第三方应用；卖家通过系统浏览器完成注册或登录并取得 Token，以 Bearer Token 调用店铺、商品、订单和物流相关接口。
Base Path: /openapi/v1
HTTP Method: V1 API 仅使用 GET 和 POST。查询操作使用 GET；创建、更新、状态变更及其他写操作统一使用 POST。
章节总览
| 章节 | 模块 | 主要内容 |
|---|---|---|
| 第一章 | 认证与安全 | 浏览器认证、Token 激活、App ID、凭证安全与租户隔离 |
| 第二章 | 店铺配置 | 获取 Sugumart 店铺信息、配置回调通知 |
| 第三章 | 商品管理 | 商品、媒体、SKU、库存、价格与上下架 |
| 第四章 | 订单、物流与仓库 | 订单查询、发货、取消交易确认与露天物流仓配置 |
第一章 认证与安全
介绍 Sugumart Open API 的浏览器认证、访问凭证和权限边界。卖家应用通过系统浏览器完成注册或登录，由本地 loopback 回调取得绑定店铺的 Token，并通过 Bearer Token 访问业务接口。
Token 通过 Authorization Code + PKCE（S256）流程签发；机密客户端必须在服务端使用 client_secret 兑换 Token。Access Token 默认有效期为 90 天；Refresh Token Family 从首次授权起绝对有效 120 天，采用单次轮换、Token Family 重放检测和主动撤销，轮换不延长绝对期限。Token 在卖家完成 KYC 审核与支付绑定后才会激活。
| 编号 | 能力 | Method + Path | 文档 |
|---|---|---|---|
| 1.1 | 获取 Token | 浏览器打开 https://auth.sugumart.com/register | 认证与安全 |
| 1.2 | 接收认证回调 | GET http://127.0.0.1:{port}/callback | 认证与安全 |
| 1.3 | 激活 Token | 卖家完成 KYC 审核与支付绑定 | 认证与安全 |
| 1.4 | 刷新 Token | POST /api/auth/token，grant_type=refresh_token | 认证与安全 |
| 1.5 | 撤销 Token Family | POST /api/auth/revoke | 认证与安全 |
第二章 店铺配置
提供调用方初始化店铺集成所需的基础能力，包括读取当前 Access Token 所绑定的 Sugumart 店铺信息，以及配置 Sugumart 向合作方发送业务事件的回调通知。
2.1 店铺信息
返回当前租户的 Sugumart 店铺基础资料和可用状态，供第三方确认凭证绑定对象并完成店铺映射。
| 编号 | 能力 | Method + Path | 文档 |
|---|---|---|---|
| 2.1.1 | 获取 Sugumart 店铺信息 | GET /openapi/v1/shop/profile | 店铺配置 |
2.2 回调管理
用于获取和设置当前店铺的回调配置。一个店铺只能配置一个回调；再次设置时覆盖当前配置。
| 编号 | 能力 | Method + Path | 文档 |
|---|---|---|---|
| 2.2.1 | 获取回调配置 | GET /openapi/v1/shop/callback | 店铺配置 |
| 2.2.2 | 设置回调配置 | POST /openapi/v1/shop/callback | 店铺配置 |
2.3 回调通知
Sugumart 向店铺唯一回调 URL 推送商品审核、订单和物流状态变化。通知包含商品提交审核、审核通过、审核拒绝，订单创建、更新、取消，以及物流出库、集运仓入库和买家末端签收事件。
| 编号 | 能力 | 事件或机制 | 文档 |
|---|---|---|---|
| 2.3.1 | 通知事件 | 商品审核、订单与物流事件 | 回调通知 |
| 2.3.2 | 请求格式 | Headers、事件信封与事件数据 | 回调通知 |
| 2.3.3 | 订单事件数据 | 订单创建、更新与取消 | 回调通知 |
| 2.3.4 | 物流事件数据 | 发货、入库与签收 | 回调通知 |
| 2.3.5 | 商品审核事件数据 | 提交审核、审核通过与审核拒绝 | 回调通知 |
| 2.3.6 | 签名验证 | HMAC-SHA256 | 回调通知 |
| 2.3.7 | 响应与重试 | 2xx 确认、失败重试 | 回调通知 |
| 2.3.8 | 幂等与一致性 | Event ID 去重、审核版本比较与详情回查 | 回调通知 |
第三章 商品管理
提供商品全生命周期管理能力，包括创建和查询商品、上传商品媒体、配置 SKU、维护库存与价格，以及商品上下架。
商品创建流程分为基本信息、媒体上传、SKU 与详情配置、提交审核四个阶段。商品审核通过后，调用方才能执行上架操作。
SKU UUID id 是更新已有 SKU 的定位依据，SKU 编号 sku 由平台生成并只读。任何曾经上架过的 SKU 均不得删除；停止销售时应保留其 id 并将 status 设置为 false。
3.1 商品查询
提供商品列表与商品详情查询；商品详情包含 SKU 列表。
| 编号 | 能力 | Method + Path | 文档 |
|---|---|---|---|
| 3.1.1 | 商品列表 | GET /openapi/v1/products | 商品管理 |
| 3.1.2 | 商品详情（含 SKU 列表） | GET /openapi/v1/products/{id} | 商品管理 |
3.2 商品创建流程
商品创建分为以下四步，调用方应按顺序完成基本信息、媒体、SKU 与详情配置，并提交审核。
| 编号 | 能力 | Method + Path | 文档 |
|---|---|---|---|
| 3.2.1 | 创建商品（第一步：基本信息） | POST /openapi/v1/products | 商品管理 |
| 3.2.2 | 上传商品媒体, 获取上传图片链接（第二步） | POST /openapi/v1/products/{id}/media/upload | 商品管理 |
| 3.2.3 | 更新商品（第三步：配置 SKU 与详情） | POST /openapi/v1/products/{id} | 商品管理 |
| 3.2.4 | 提交商品审核（第四步） | POST /openapi/v1/products/{id}/submit | 商品管理 |
3.3 商品上下架
| 编号 | 能力 | Method + Path | 文档 |
|---|---|---|---|
| 3.3.1 | 上架商品 | POST /openapi/v1/products/{id}/online | 商品管理 |
| 3.3.2 | 下架商品 | POST /openapi/v1/products/{id}/offline | 商品管理 |
3.4 类目管理
提供平台商品类目数据，供创建和更新商品时选择 class_id。类目按 parent 逐级查询，每次只返回下一层直接子节点；V1 仅开放类目获取，不提供类目创建、更新或删除。
| 编号 | 能力 | Method + Path | 文档 |
|---|---|---|---|
| 3.4.1 | 获取类目列表 | GET /openapi/v1/categories | 类目与商品分类 |
3.5 店铺商品分类
店铺商品分类是店铺用于整理自身商品的分组，与平台商品类目 class_id 分开管理。店铺商品分类提供创建、列表和删除能力。
| 编号 | 能力 | Method + Path | 文档 |
|---|---|---|---|
| 3.5.1 | 创建商品分类 | POST /openapi/v1/product-categories | 类目与商品分类 |
| 3.5.2 | 获取商品分类列表 | GET /openapi/v1/product-categories | 类目与商品分类 |
| 3.5.3 | 删除商品分类 | POST /openapi/v1/product-categories/{id}/delete | 类目与商品分类 |
第四章 订单和物流
将订单处理、履约物流与露天物流仓配置放在同一章，按“选择物流仓 → 读取订单 → 提交发货 → 处理取消交易”的业务流程组织。订单状态变化可通过第二章定义的回调通知同步给合作方。
4.1 订单管理
提供订单列表、订单详情、卖家发货、卖家取消交易及确认买家取消交易。
| 编号 | 能力 | Method + Path | 文档 |
|---|---|---|---|
| 4.1.1 | 查询订单列表 | GET /openapi/v1/orders | 订单、物流与仓库 |
| 4.1.2 | 查询订单详情 | GET /openapi/v1/orders/{order_id} | 订单、物流与仓库 |
| 4.1.3 | 订单出货 | POST /openapi/v1/orders/{order_id}/ship | 订单、物流与仓库 |
| 4.1.4 | 卖家取消交易 | POST /openapi/v1/orders/{order_id}/cancel | 订单、物流与仓库 |
| 4.1.5 | 确认买家取消交易 | POST /openapi/v1/orders/{order_id}/cancel/confirm | 订单、物流与仓库 |
4.2 物流管理
提供可用露天物流仓列表及店铺物流仓设置，订单出货时使用已设置的大陆集运仓。
| 编号 | 能力 | Method + Path | 文档 |
|---|---|---|---|
| 4.2.1 | 获取露天仓库列表 | GET /openapi/v1/warehouses | 订单、物流与仓库 |
| 4.2.2 | 获取当前物流仓 | GET /openapi/v1/warehouses/selection | 订单、物流与仓库 |
| 4.2.3 | 设置物流仓 | POST /openapi/v1/warehouses/selection | 订单、物流与仓库 |
附录 OpenAPI 状态与附加数据
集中维护 OpenAPI 响应、请求筛选和回调通知中使用的状态枚举及附加数据，避免各接口重复定义或出现同一状态含义不一致。附录只描述对外契约，不新增 API Endpoint。
A.1 订单状态
维护订单主状态、商家展示状态、露天订单观察状态、取消交易状态及其中文说明、适用接口和允许执行的后续操作。
| 编号 | 附加数据 | 主要内容 | 参考 |
|---|---|---|---|
| A.1.1 | 订单主状态 | pending_payment、pending、pending_shipment、shipped、delivered、completed、cancelled、refunded、dispute、needs_action | V1 状态附录 |
| A.1.2 | 订单展示状态 | pending_shipment、shipped、delivered、completed 的派生规则 | V1 状态附录 |
| A.1.3 | 露天订单状态 | order_status、respond_status 的原始枚举与映射 | V1 状态附录 |
| A.1.4 | 取消交易状态 | 取消发起方、处理状态与允许操作 | V1 状态附录 |
| A.1.5 | 订单状态时间 | 状态观察时间、最晚发货时间与取消状态时间的来源和语义 | V1 状态附录 |
A.2 商品状态
维护商品生命周期、审核、上下架、SKU 启用和库存相关状态，以及各状态允许执行的商品操作。
| 编号 | 附加数据 | 主要内容 | 参考 |
|---|---|---|---|
| A.2.1 | 商品生命周期状态 | draft、pending_review、rejected、approved、migrated、offline | V1 状态附录 |
| A.2.2 | 商品审核状态 | draft、pending、approved、rejected 及拒绝原因 | V1 状态附录 |
| A.2.3 | SKU 状态 | SKU 启用状态与库存数量 | V1 状态附录 |
A.3 物流状态
维护订单履约、集货单、大陆快递预报单和物流仓相关状态，明确跨境运输到达与买家签收的区别。
| 编号 | 附加数据 | 主要内容 | 参考 |
|---|---|---|---|
| A.3.1 | 集货单状态 | created、shipped、arrived、completed、cancelled、failed、suspended | V1 状态附录 |
| A.3.2 | 大陆快递预报单状态 | created、shipped、arrived、received、cancelled、failed | V1 状态附录 |
| A.3.3 | 露天出货状态 | Unshipped、Shipped、Delay、Cancel 及其本地映射 | V1 状态附录 |
| A.3.4 | 物流仓附加数据 | 仓库用途、地区、能力和物流商关联规则 | V1 状态附录 |
版本变更记录
V1 对外契约的新增、调整、废弃、删除、修复和安全变化集中记录在 V1 OpenAPI Changelog。尚未绑定正式版本号和发布日期的设计保留在 [Unreleased]，不得表述为已经部署。
通用错误码
V1 错误响应、错误码、可重试性和调用方恢复动作集中维护在 V1 OpenAPI 错误码。各 Endpoint 文档保留其可能返回的错误，本错误码文档提供跨模块统一处理规则。