Sugumart OpenAPI V1

Appearance

V1 OpenAPI Changelog ​

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

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

2026-09-28：移除冗余单号数组 ​

  • 移除订单发货请求及列表、详情、发货响应履约对象中的 tracking_numbers。多包裹统一使用 drop_orders，保留兼容单号字段 tracking_number。
  • 这是不兼容变更：请求继续传 tracking_numbers 时返回 400 validation_error；读取多单号的客户端应改用 drop_orders[].tracking_number。
  • backend 的 OpenAPI 内部发货接口同步移除该字段。已按 open-gateway → backend 顺序发布至生产，避免旧网关仍转发该字段时被新后端拒绝；同步更新文档站。无新增数据库迁移。

2026-09-28 ​

  • 订单出货新增推荐请求格式 drop_orders: [{ tracking_number, carrier_code }]，同一订单可一次提交顺丰、京东等不同公司的包裹，每项单号及公司均必填。
  • 新格式禁止与旧的 tracking_number、tracking_numbers、顶层 carrier_code 混用；单号去除首尾空格后重复、包裹字段缺失或无效均返回 400 validation_error。
  • 保留旧格式兼容能力及现有履约响应。仍不支持发货后追加包裹或分批发货。
  • backend、open-gateway 及 Admin 多包裹发货已发布生产环境；本次功能无新增数据库迁移。

2026-09-23 ​

  • 订单出货新增 tracking_numbers，支持同一订单的一次履约关联多个大陆快递单号；保留 tracking_number 兼容旧客户端，同时提供时以数组为准，单号去除首尾空格后去重。
  • 明确当前 carrier_code 行为：提供时用于全部单号，省略时逐条识别，无法识别使用 OTHER；旧文档中要求提供公司及返回 carrier_required 的描述与实现不符。
  • 订单列表、详情与发货响应的履约对象新增 tracking_numbers 和 drop_orders，返回全部未软删除大陆包裹及各自的快递公司、状态、入库时间；按创建时间和 ID 升序排列。保留原单号字段，对应数组首条，兼容已有客户端；无包裹时数组为 []，无有效履约时对象仍为 null。
  • 标注重试契约差异：当前实现不保证相同单号重试返回 200 OK；成功返回 201 Created，已有有效履约通常返回冲突，仅支持符合条件的未取得物流商集货单号的履约继续提交。
  • 多单号请求与查询能力已随本次多包裹发货更新发布至生产环境，无新增数据库迁移。

2026-09-21（待发布） ​

  • 商品分类列表及写操作返回的完整分类列表允许 display_sort 超过 100，保留露天返回的正安全整数；创建、修改请求仍限 1–100。需 backend 和 open-gateway 发布后生效。

  • 订单主动取消的文字原因统一转换为台湾繁体后保存并提交露天，预设原因说明也改为繁体。

  • reason_code 仍为必填；仅 other 必须提供 reason，其他类型可省略或补充文字。提供的文字去除首尾空格及转换后均须为 1–100 字。

  • 需 backend 和 open-gateway 发布后生效，无数据库迁移。

2026-09-20（待发布） ​

  • 发货新增可选 transport_mode，支持海运、海快、空运；新发货省略默认海运，履约响应返回已保存值。
  • 仓库与物流公司对象新增 transport_modes；增加未开通方式和重试方式冲突错误。
  • 代码已实现，需数据库迁移及 backend、网关发布后在对应环境生效。

2026-08-20 ​

  • 明确商品规格数量限制：同一商品最多包含 30 个不同 spec_name，每个 spec_name 最多对应 15 个不同 item_name；完整双规格 SKU 列表上限由 30 项放宽至 450 项，并在进入露天审核前执行相同校验。
  • 业务通知开始按固定请求体可靠投递，支持同租户事件自动合批；每轮首次失败后最多重试 3 次，仍失败进入死信。事件发生时未配置或已停用通知的历史事件不会补发。

2026-08-18 ​

  • 调整店铺初始化门槛：KYC 审核通过即可调用 OpenAPI，Payoneer 未绑定不再返回 shop_not_initialized。
  • 统一 Open Gateway 全部成功与错误响应为 V1 信封：成功使用 { success:true, data }，失败使用 { success:false, code, message, data?, request_id? }；Auth 接口不再返回裸响应或 errorCode。
  • 放宽商品主图和 SKU 图片上传上限至 5 MiB（5,242,880 bytes）。
  • 修正商品详情中未完成配置的草稿 SKU：taiwan_sale_price 和 weight 响应允许为 null；SKU 更新请求仍要求填写售价和重量。
  • 修正 SKU 更新的 custom_no 空值兼容，允许按响应原样回传 null。
  • 修正商品全托管说明：ruten_managed_distribution 按 SKU 独立配置，商品级聚合标记仅供平台内部处理，不是 OpenAPI 商品级配置项。
  • 商品创建流程明确区分“有序分步创建”和“整合数据创建”，并将整合创建接口移至商品 API 页面末尾。
  • 实现 POST /openapi/v1/orders/{order_id}/cancel/confirm，卖家可确认买家发起且仍待回复的取消交易；重复确认已取消的同一买家申请不会再次调用露天。
  • 新增零依赖 Node.js 私有应用 Client Credentials 示例，并在文档侧边栏区分公开应用与私有应用示例。
  • 恢复商品 SKU 可选的第二规格字段 item_name；服务端将 spec_name、item_name 分别自动映射为“规格”和“款式”，并在商品响应中分离返回两个字段。此前把第二规格拼入 spec_name 的调用方需要改为分别读取两个字段。
  • 实现 GET /openapi/v1/categories 平台类目逐级查询。
  • 实现店铺商品分类的创建、列表、修改和删除接口；写操作完成后返回刷新后的完整分类列表。

2026-08-17 ​

  • 新增 POST /openapi/v1/product-create-tasks，可一次提交商品基本资料、图片来源与 SKU，并立即取得商品 ID 和异步任务 ID。
  • 新增 GET /openapi/v1/product-create-tasks/{task_id}，用于查询媒体归档、部分成功和失败明细。
  • 异步创建任务支持可选 Idempotency-Key；任务始终保留可由原有商品接口继续修改的草稿，且不会自动提交审核。

2026-08-15 ​

  • 新增 notifications.batch 批通知事件，data 为完整单条通知组成的 Notification[]。
  • 第二章统一使用“业务通知”表述，并移除业务通知字段说明中的“观察”措辞。

2026-08-14 ​

  • 新增 POST /openapi/v1/shop/callback/reveal-secret，允许店铺显式查看当前 Webhook Secret。
  • 回调 URL 支持 HTTP 与 HTTPS；正式环境仍建议使用 HTTPS。
  • 开放应用可配置新注册店铺的默认通知 URL，每个店铺使用独立 Secret。

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] ​

Changed ​

  • 订单出货提交给物流商的 total_value 改为 product_amount，cod_value 改为 product_amount + shipping_amount；任一金额缺失时拒绝出货，不使用固定运费回退值或订单 total_amount。

  • 明确 total_amount 是扣除露天卖家折扣、优惠及露币后的买家实际支付金额；product_amount 是商品金额，shipping_amount 是露天原始物流费。

  • 订单列表重新返回主状态为 pending（待实名）的订单，分页 count 同步包含；支持 status=pending 筛选，且待实名订单的 available_actions 不包含 ship。

  • 已上架商品 SKU 更新新增可选 custom_no（支持 null 清空）；状态/料号、价格、库存改为分别调用露天对应接口，避免一般价格或库存更新重建规格 ID。

  • 商品 SKU 的 custom_no 统一按露天规则校验：非空时只允许 1–100 个 ASCII 可见字符；/ 合法，空格、中文和 ⅓/⅔ 等非 ASCII 字符会返回 validation_error。

  • 订单出货和 WMS 集货单的寄件地址改为卖家主要大陆退货仓；缺少时 shipment_configuration_incomplete.data.missing_fields 返回 seller_return_warehouse。

  • 商品在审核通过但尚未上架时可被平台管理员撤销通过；同一 review_version 可能先产生 product.review.approved、后产生 product.review.rejected，调用方在版本相同时须以较新的 status_at 为准。

  • 在 API 大纲增加“待规划 / 设计中 / 已完成”开发状态，并只展示第三方接入所需的公开认证端点。

  • 新增店铺回调配置、物流仓列表和店铺物流仓选择接口。

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

Added ​

  • 商品提交审核新增 product_main_image_limit_exceeded 错误；历史草稿主图超过 9 张时返回当前数量与上限，调用方需删除多余主图后重试。

  • 订单列表响应新增 product_amount 与 shipping_amount，与订单详情使用相同金额口径。

  • 新增 POST /openapi/v1/products/{id}/skus/spec-info、/price、/stock 三个拆分接口；均以商品 UUID 定位商品，并支持通过 SKU UUID 或露天 spec_id 批量定位 SKU。原合并更新接口继续正式支持。

  • 新增 GET、POST /openapi/v1/warehouses/seller-returns，用于查询并整表替换卖家大陆退货仓；每店必须维护 1-5 个地址且恰好一个主要仓。

  • 新增 POST /openapi/v1/products/{id}/skus/update-price-quantity-and-status，可通过 SKU UUID 或露天 spec_id 批量更新已上架商品的售价、库存与启用状态。

  • 实现商品列表、详情、草稿创建、媒体上传、SKU 更新、提交审核、上架与下架接口。

  • 全托管 SKU 省略供货价时，按售价的 65% 自动计算并四舍五入到 2 位。

  • 新增固定绑定单一店铺的私有应用；私有应用通过 grant_type=client_credentials 取得与公开应用相同格式的 Access Token 和 Refresh Token。

  • Token 信息增加 application_type 与 actor_type，用于区分公开应用的卖家授权和私有应用的服务端凭据。

  • Seller owner 可创建并管理每店唯一的私有应用；停用私有应用会立即撤销其全部 Token Family。

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

  • 新增独立 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 通知。

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

  • 新增店铺商品分类修改接口 POST /openapi/v1/product-categories/{id}，使用完整分类设置替换语义。

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

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

  • 实现订单人工查询、订单详情与订单出货；订单详情增加数据库内露天详情快照 ruten_payload。

  • 实现卖家主动取消订单，并复用 Backend 现有露天取消、库存释放与订单状态同步流程。

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

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

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

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

Changed ​

  • 已发布商品重新提交时先读取露天商品详情，只提交实际变化的商品和 SKU 字段；仅在规格名称或组合结构确实变化时调用规格选项覆盖接口，避免一般修改导致 spec_id 重建。

  • 商品公开 SKU 使用 spec_name 表示第一规格值，并可使用 item_name 表示第二规格值；服务端自动生成最多两层规格结构。

  • 商品售价明确为正整数 TWD，并以固定 2 位小数字符串传输。

  • 公开 API 与回调 JSON 字段统一使用 snake_case；TypeScript 内部的 camelCase 名称不得直接进入公开响应。

  • 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 ​

  • 补充 Authorization Code + PKCE 示例的 invalid_client 排查说明，明确测试/生产 Auth 环境混用、Secret 轮换和应用状态等原因，并区分 unauthorized_client、redirect_uri_not_allowed 与 invalid_grant。

  • 明确商品 SKU 的 spec_name 最多为 20 个文字字符而非 20 个 UTF-8 字节，可完整填写 20 个繁体中文字；该限制与最多 30 个不同第一规格值的数量限制相互独立。

  • 区分订单状态观察时间、历史发货截止时间、取消状态时间和普通 updated_at，避免把资源更新时间误认为业务状态发生时间。

  • 明确 SKU 编号即使由调用方提交也不会覆盖平台编号。

  • 明确商品审核通过不表示商品已经上架，仍需调用商品上架接口。

发布记录模板 ​

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

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

### Added

- 新增示例能力。

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