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 的访问凭证和权限边界。公开应用通过系统浏览器完成 Authorization Code + PKCE 授权；固定绑定单一店铺的私有应用通过 Client Credentials 取得 Token。两类 Token 均通过 Bearer Token 访问同一套业务接口。
OAuth redirect_uri 是浏览器授权回调，与第二章由 Sugumart 服务端 POST 的业务通知 URL 分开配置。
Token 通过 Authorization Code + PKCE（S256）流程签发；机密客户端必须在服务端使用 client_secret 兑换 Token。Access Token 默认有效期为 90 天；Refresh Token Family 从首次授权起绝对有效 120 天，采用单次轮换、Token Family 重放检测和主动撤销，轮换不延长绝对期限。Token 在卖家完成 KYC 审核后激活；Payoneer 绑定状态不阻断 OpenAPI。
| 编号 | 能力 | Method + Path | 开发状态 | 文档 |
|---|---|---|---|---|
| 1.1 | 发起浏览器授权 | 浏览器打开 https://auth.sugumart.com/register | 已完成 | 认证与安全 |
| 1.2 | 接收授权回调 | GET {redirect_uri} | 已完成 | 认证与安全 |
| 1.3 | 兑换 Token | POST /api/auth/token，grant_type=authorization_code | 已完成 | 认证与安全 |
| 1.4 | 刷新 Token | POST /api/auth/token，grant_type=refresh_token | 已完成 | 认证与安全 |
| 1.5 | 撤销 Token Family | POST /api/auth/revoke | 已完成 | 认证与安全 |
| 1.6 | 查询 Token 信息 | GET /auth/tokeninfo | 已完成 | 认证与安全 |
| 1.7 | 私有应用兑换 Token | POST /api/auth/token，grant_type=client_credentials | 已完成 | 认证与安全 |
第二章 店铺配置
提供调用方初始化店铺集成所需的基础能力，包括读取当前 Access Token 所绑定的 Sugumart 店铺信息，以及配置 Sugumart 向合作方发送业务通知。
2.1 店铺信息
返回当前租户的 Sugumart 店铺基础资料和可用状态，供第三方确认凭证绑定对象并完成店铺映射。
| 编号 | 能力 | Method + Path | 开发状态 | 文档 |
|---|---|---|---|---|
| 2.1.1 | 获取 Sugumart 店铺信息 | GET /openapi/v1/shop/profile | 已完成 | 店铺配置 |
2.2 业务通知管理
用于获取和设置当前 Sugumart tenant 的业务通知配置。一个 tenant 只能配置一个通知 URL；多个开放应用访问同一 tenant 时共享该配置。
| 编号 | 能力 | Method + Path | 开发状态 | 文档 |
|---|---|---|---|---|
| 2.2.1 | 获取业务通知配置 | GET /openapi/v1/shop/callback | 已完成 | 店铺配置 |
| 2.2.2 | 设置业务通知配置 | POST /openapi/v1/shop/callback | 已完成 | 店铺配置 |
| 2.2.3 | 查看业务通知签名 Secret | POST /openapi/v1/shop/callback/reveal-secret | 已完成 | 店铺配置 |
2.3 业务通知
Sugumart 向店铺唯一业务通知 URL 推送商品审核、订单和物流状态变化。通知支持单条或批量投递，包含商品提交审核、审核通过、审核拒绝，订单创建、更新、取消，以及物流出库、集运仓入库和买家末端签收事件。
| 编号 | 能力 | 事件或机制 | 文档 |
|---|---|---|---|
| 2.3.1 | 通知事件 | 商品审核、订单、物流与批通知事件 | 业务通知 |
| 2.3.2 | 请求格式 | Headers、事件信封与事件数据 | 业务通知 |
| 2.3.3 | 订单事件数据 | 订单创建、更新与取消 | 业务通知 |
| 2.3.4 | 物流事件数据 | 发货、入库与签收 | 业务通知 |
| 2.3.5 | 商品审核事件数据 | 提交审核、审核通过与审核拒绝 | 业务通知 |
| 2.3.6 | 批通知事件 | Notification[] 批量投递 | 业务通知 |
| 2.3.7 | 签名验证 | HMAC-SHA256 | 业务通知 |
| 2.3.8 | 响应与重试 | 2xx 确认、失败重试 | 业务通知 |
| 2.3.9 | 幂等与一致性 | 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.2.5 | 异步整合创建商品 | POST /openapi/v1/product-create-tasks | 已完成 | 商品管理 |
| 3.2.6 | 查询异步创建任务 | GET /openapi/v1/product-create-tasks/{task_id} | 已完成 | 商品管理 |
3.3 商品上下架
| 编号 | 能力 | Method + Path | 开发状态 | 文档 |
|---|---|---|---|---|
| 3.3.1 | 上架商品 | POST /openapi/v1/products/{id}/online | 已完成 | 商品管理 |
| 3.3.2 | 下架商品 | POST /openapi/v1/products/{id}/offline | 已完成 | 商品管理 |
| 3.3.3 | 更新已上架商品 SKU 状态与自有料号 | POST /openapi/v1/products/{id}/skus/spec-info | 已完成 | SKU 更新 |
| 3.3.4 | 更新已上架商品 SKU 价格 | POST /openapi/v1/products/{id}/skus/price | 已完成 | SKU 更新 |
| 3.3.5 | 更新已上架商品 SKU 库存 | POST /openapi/v1/products/{id}/skus/stock | 已完成 | SKU 更新 |
| 3.3.6 | 合并更新已上架商品 SKU | POST /openapi/v1/products/{id}/skus/update-price-quantity-and-status | 已完成 | SKU 更新 |
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} | 已完成 | 类目与商品分类 |
| 3.5.4 | 删除商品分类 | 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 | 已完成 | 订单、物流与仓库 |
| 4.2.4 | 获取卖家大陆退货仓 | GET /openapi/v1/warehouses/seller-returns | 已完成 | 订单、物流与仓库 |
| 4.2.5 | 替换卖家大陆退货仓 | POST /openapi/v1/warehouses/seller-returns | 已完成 | 订单、物流与仓库 |
附录 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 文档保留其可能返回的错误，本错误码文档提供跨模块统一处理规则。