Sugumart OpenAPI V1

Appearance

V1 OpenAPI Changelog ​

本文记录 Sugumart OpenAPI V1 对外契约的变化，包括 Endpoint、请求字段、响应字段、状态枚举、错误码和回调事件。仅记录外部开发者可观察到的变化，不记录内部重构、数据库迁移或不影响契约的实现调整。

V1 的 Base Path 固定为 /openapi/v1，业务接口仅使用 GET 和 POST。完整接口入口见 V1 Open API，状态枚举见 V1 状态附录。

2026-08-12 ​

  • Redirect URI 登记与授权回调明确支持 HTTP 和 HTTPS；生产环境仍建议使用 HTTPS，HTTP 可用于 localhost 本地联调。
  • 新增可在 localhost:4000 运行的 Node.js Authorization Code + PKCE 示例。
  • 浏览器授权升级为 Authorization Code + PKCE（S256），回调不再携带 Bearer Token。
  • 开放应用新增仅显示一次并可轮换的 client_secret；Token 交换必须同时校验授权码、精确回调地址、Client Secret 与 PKCE verifier。
  • POST /api/auth/token 新增 refresh_token grant；Access Token 默认有效期为 90 天，Refresh Token Family 从首次授权起绝对有效 120 天，轮换不延长期限。
  • Refresh Token 采用单次轮换和 Token Family 重放检测；新增 POST /api/auth/revoke 主动撤销端点。

兼容性约定 ​

向后兼容变化 ​

以下变化通常可在 V1 内发布：

  • 新增 Endpoint。
  • 请求体新增可选字段，且省略时保持原有行为。
  • 响应对象新增字段。
  • 新增错误码、回调事件或状态枚举值。
  • 放宽字段长度、数量或筛选范围，且不改变现有值的含义。

调用方必须忽略无法识别的响应字段；遇到未知枚举值或回调事件时，应记录可见错误并保留原始值，不得自动映射为已知值。回调接收端对未知事件仍应在安全持久化后返回 2xx，避免平台无意义重复投递。

破坏性变化 ​

以下变化不会直接加入已发布的 V1 契约，原则上需要新的主版本路径：

  • 删除或重命名 Endpoint、请求字段、响应字段或回调事件。
  • 将可选字段改为必填字段，或将可为空字段改为不可为空。
  • 改变字段类型、单位、精度、时区或业务语义。
  • 收紧现有字段限制，导致原本合法的请求被拒绝。
  • 删除枚举值，或改变已有枚举值、错误码的含义。
  • 改变签名原文、认证方式、分页语义或写操作的幂等规则。

废弃策略 ​

  • 计划废弃的能力会先在本文件标记为 Deprecated，并在对应接口文档中注明替代方案和停止支持日期。
  • 非紧急废弃从公告到停止支持至少保留 90 个自然日。
  • 废弃期内原契约继续可用；停止支持后若会造成破坏性变化，应通过新的主版本实施。
  • 因已确认安全风险必须缩短周期时，会单独说明风险、影响范围和迁移方式。

变更分类 ​

分类说明
Added新增 Endpoint、字段、枚举、回调事件或文档能力
Changed调整既有契约行为或字段语义
Deprecated已声明废弃但仍可使用的能力
Removed已停止支持的能力；V1 原则上不直接执行破坏性删除
Fixed修正文档歧义、示例错误或契约描述不一致
Security与认证、授权、签名或敏感数据保护相关的变化

[Unreleased] ​

以下内容已经进入 V1 文档设计，但尚未在本文件中绑定正式版本号和发布日期。是否已经部署应以平台发布公告和实际环境为准。

Added ​

  • 实现 GET /openapi/v1/shop/profile，按 Bearer Token 返回其唯一绑定店铺的基础资料，并执行初始化与暂停状态检查。

  • 新增独立 Auth Web 浏览器认证页、7 天浏览器会话和 GET /auth/tokeninfo Token 信息接口。

  • 新增 ISV 开放应用登记、Redirect URI 精确白名单、应用启停和新注册店铺来源归因；未携带 App ID 时只允许 loopback 回调。

  • 新增商品审核回调事件：product.review.submitted、product.review.approved 和 product.review.rejected；事件通过 review_version 处理重复提交和乱序通知。

  • 新增订单与物流回调事件：订单创建、更新、取消，以及集运仓入库、出库和买家末端签收。

  • 新增店铺唯一回调 URL 的获取与设置接口；同一 URL 接收全部 V1 通知。

  • 新增平台类目逐级查询，以及店铺商品分类的创建、列表和删除接口。

  • 新增商品四阶段流程：创建基本信息、取得媒体上传地址、配置详情与 SKU、提交审核。

  • 新增订单人工查询、订单详情、订单出货、卖家取消交易和确认买家取消交易接口。

  • 新增可用露天仓库列表、当前物流仓和物流仓设置接口。

  • 新增请求追踪支持：请求携带 X-SGM-Request-Id 时，响应返回 X-Request-Id Header，并在统一响应信封中返回相同的 request_id。

  • 新增 V1 状态附录，集中维护订单、商品、SKU、履约、物流和仓库状态。

  • 新增统一错误码文档，集中说明 HTTP 状态、可重试性、错误 data 和调用方恢复动作。

Changed ​

  • OpenAPI Token 首版默认有效期为 90 天并由平台配置；修改卖家密码后，既有 Token 与浏览器认证会话同时失效。

  • V1 OpenAPI 改为独立统一响应契约：成功返回 { success: true, data }，失败返回 { success: false, code, message, data? }；不再沿用 Seller/Admin API 的直返格式。

  • request_id 调整为仅在请求携带 X-SGM-Request-Id 时返回，并与响应 Header X-Request-Id 保持一致。

  • 结构化错误辅助信息由旧 details 字段调整为统一信封内的 data 字段。

  • 认证方式由 API Key + Secret 换取固定 30 天 Access Token，调整为系统浏览器注册/登录、本地 loopback 回调取得动态有效期 Token；新 Token 需完成 KYC 审核和支付绑定后激活。

  • 新增 ISV 可选 app_id 的来源统计与 Webhook 自动配置语义，并明确 App ID 不参与认证。

  • V1 Base Path 统一为 /openapi/v1，并约定业务接口仅使用 GET 和 POST。

  • 平台类目改为通过 parent=g_class 一级一级查询直接子节点；商品只能选择 selectable=true 的末级类目。

  • 商品主图、详情图、海报图和 SKU 图分别定义数量、格式、文件大小、原始尺寸及建议尺寸。

  • SKU 编号 sku 改为平台生成的只读编号；更新已有 SKU 时必须使用 SKU UUID id 定位。

  • 商品图片列表和 SKU 列表采用完整替换语义；省略列表字段时保持原值不变。

  • 曾经上架过的 SKU 不允许删除，只能通过 status=false 停用；只有从未上架的 SKU 可以从完整列表中移除。

  • 订单列表定位为人工查询接口，支持创建时间、状态和关键字筛选，不提供增量同步语义。

  • 商品、平台类目、店铺商品分类、订单和仓库列表定义稳定排序及第二排序键，避免相同主排序值导致分页顺序不确定。

  • 订单出货请求由调用方提供大陆快递单号；其他履约资料由平台根据订单、SKU 和店铺物流配置取得。

  • 明确已上传商品图片通常长期保留，平台不会因未关联、移除引用或商品下架自动清理；V1 不提供图片删除接口。

Removed ​

  • 移除订单列表的 updated_from 增量同步参数。
  • 移除商品批量上下架和批量更新 SKU 能力。
  • 移除商品品牌、副标题、short_description、attributes、spec_groups、海关编码、运费设定、币种、所在地和二手商品等不属于当前系统契约的输入字段。
  • 移除回调配置的多 URL、创建、更新、轮换等独立模块；每个店铺只维护一个回调配置。

Fixed ​

  • 区分订单状态观察时间、最晚发货时间、取消状态时间和普通 updated_at，避免把资源更新时间误认为业务状态发生时间。
  • 明确 SKU 编号即使由调用方提交也不会覆盖平台编号。
  • 明确商品审核通过不表示商品已经上架，仍需调用商品上架接口。

发布记录模板 ​

正式发布时，将 [Unreleased] 中已上线的条目移动到带版本号和日期的章节：

markdown
## [1.0.0] - 2026-08-05

### Added

- 新增示例能力。

版本日期使用 YYYY-MM-DD，表示该契约在生产环境开始对外可用的日期。仅完成文档设计但尚未部署的变化必须继续保留在 [Unreleased]。