Appearance
V1 OpenAPI 状态附录
本附录集中定义 Sugumart V1 OpenAPI 使用的订单、商品和物流状态。接口响应、请求筛选与回调通知均以本附录为准。
状态值使用英文原文；新增或调整状态时，应同步更新相关接口文档和回调事件说明。
A.1 订单状态
A.1.1 订单主状态 status
| 状态值 | 中文名称 | 说明 |
|---|---|---|
pending_payment | 待付款 | 买家尚未完成付款 |
pending | 待处理 | 订单已建立，等待后续处理 |
pending_shipment | 待出货 | 订单已满足出货条件，等待卖家提交物流资料 |
shipped | 已出货 | 订单已进入运输流程 |
delivered | 已送达 | 已观察到末端送达或签收进度 |
completed | 已完成 | 订单满足平台完成条件 |
cancelled | 已取消 | 取消交易已完成 |
refunded | 已退款 | 订单退款已完成 |
dispute | 争议中 | 订单取消、付款或履约存在争议 |
needs_action | 需要处理 | 订单存在异常，需要卖家或平台处理 |
A.1.2 订单展示状态 view_status
view_status 是根据订单与履约数据计算的展示状态，不是独立持久化字段。
| 状态值 | 中文名称 | 说明 |
|---|---|---|
pending_shipment | 待出货 | 尚未建立有效履约，或上次发货未完成且允许重试 |
shipped | 运送中 | 已提交物流资料，尚未确认买家末端签收 |
delivered | 已签收 | 已观察到买家末端签收，但尚未满足订单完成条件 |
completed | 已完成 | 已确认买家签收并满足订单完成条件 |
物流商返回“到达统仓”只表示跨境运输节点完成，不等于买家签收。
A.1.3 露天订单状态
ruten_order_status
| 状态值 | 中文名称 | 说明 |
|---|---|---|
Unpaid | 尚未付款 | 买家已下单但尚未付款 |
ToBeConfirmed | 待确认 | 等待卖家确认订单或款项 |
ReadyToShip | 待出货 | 订单可以进入出货流程 |
Shipped | 已出货 | 订单已完成露天出货处理 |
InCancel | 取消处理中 | 买卖双方正在处理取消交易 |
Cancelled | 已取消 | 取消交易已完成 |
ruten_respond_status
| 状态值 | 中文名称 | 说明 |
|---|---|---|
ToRespond | 待回复 | 等待卖家处理买家取消申请 |
Approved | 已同意 | 卖家已同意取消交易 |
Rejected | 已拒绝 | 卖家已拒绝取消交易 |
SystemCancelled | 系统已取消 | 露天依规则自动取消交易 |
A.1.4 取消交易状态
cancellation.status 是 Sugumart 对外提供的标准化取消交易状态，不直接等同于露天 ruten_respond_status。
| 状态值 | 中文名称 | 说明 |
|---|---|---|
pending | 已申请 | 卖家取消请求已经提交，等待露天完成处理 |
pending_confirmation | 待确认 | 买家发起取消，等待卖家确认 |
confirmed | 已确认 | 卖家已同意买家取消申请，等待或已经进入露天取消流程 |
rejected | 已拒绝 | 买家取消申请已被拒绝 |
cancelled | 已取消 | 取消交易已经完成 |
failed | 处理失败 | 取消请求未被接受或异步处理失败，需要查询订单详情或人工处理 |
requested_by | 说明 |
|---|---|
buyer | 买家发起取消交易 |
seller | 卖家发起取消交易 |
system | 露天或 Sugumart 依业务规则发起取消 |
A.1.5 订单状态时间
| 对外字段 | 主 DB 字段或计算来源 | 说明 |
|---|---|---|
status_observed_at | rt_order.ruten_status_observed_at | 最近一次观察到露天订单、付款、出货或取消回复状态的时间；不是任意订单字段的更新时间 |
shipment_deadline_at | rt_order.shipment_deadline_at | 当前订单最晚发货时间；不适用或已经无需发货时为 null |
cancellation.status_at | cancellation.requested_at、cancellation.decided_at | 未作出决定时取 requested_at；已确认、拒绝、取消或失败时取 decided_at |
不得使用订单 updated_at 代替 status_observed_at。updated_at 可能因收件资料、履约资料或其他非状态字段变化而更新。
A.2 商品状态
A.2.1 商品生命周期状态 status
| 状态值 | 中文名称 | 说明 |
|---|---|---|
draft | 草稿 | 商品资料仍在编辑 |
pending_review | 审核中 | 商品已提交平台审核 |
rejected | 已拒绝 | 商品审核未通过 |
approved | 已通过 | 商品已通过审核，等待上架 |
migrated | 已上架 | 商品已发布至露天销售渠道 |
offline | 已下架 | 商品已从销售渠道下架 |
A.2.2 商品审核状态 review_status
| 状态值 | 中文名称 | 说明 |
|---|---|---|
draft | 未提交 | 商品尚未提交审核 |
pending | 审核中 | 等待平台审核 |
approved | 已通过 | 平台审核通过 |
rejected | 已拒绝 | 平台审核拒绝；拒绝原因由商品详情返回 |
审核回调事件映射：
review_status | 回调事件 | 说明 |
|---|---|---|
pending | product.review.submitted | 新审核版本已提交并等待平台审核 |
approved | product.review.approved | 当前审核版本通过；商品尚未因此自动上架 |
rejected | product.review.rejected | 当前审核版本拒绝；事件与商品详情返回拒绝原因 |
每次重新提交审核都会生成递增的 review_version。回调接收方应先按 product_id 比较 review_version，避免旧审核版本覆盖新版本结果。
A.2.3 SKU 状态
| 字段 | 状态值 | 说明 |
|---|---|---|
status | true | SKU 已启用，可参与销售和库存计算 |
status | false | SKU 已停用，不可正常销售 |
qty | 大于 0 | SKU 有可售库存 |
qty | 0 | SKU 暂无可售库存 |
SKU 标识与删除约定：
id是更新已有 SKU 的唯一定位依据；sku是平台生成并维护的只读编号。- 创建新 SKU 时省略
id，更新已有 SKU 时必须提交其 UUIDid。 - 任何曾经上架过的 SKU 均不得删除，即使商品或 SKU 当前已经下架；停止销售时将
status设置为false。 - 只有从未上架的 SKU 才能从商品的完整
skus列表中移除并删除。 - 是否曾经上架由平台历史发布记录决定，不由当前
status单独决定。
A.3 物流状态
A.3.1 履约状态 fulfillment.status
| 状态值 | 中文名称 | 说明 |
|---|---|---|
created | 已建立 | 履约已创建，等待物流商推进 |
shipped | 已出货 | 包裹已从集运仓出库 |
arrived | 已到达 | 包裹已到达跨境运输目的节点 |
completed | 已完成 | 履约流程正常结束 |
cancelled | 已取消 | 履约已取消 |
failed | 失败 | 履约创建或处理失败 |
suspended | 已暂停 | 履约因异常暂停，等待人工处理 |
A.3.2 大陆快递状态 drop_order.status
| 状态值 | 中文名称 | 说明 |
|---|---|---|
created | 已建立 | 大陆快递预报单已创建 |
shipped | 已发出 | 包裹已交由大陆快递运输 |
arrived | 已到达 | 包裹已到达目标物流节点 |
received | 已入库 | 集运仓已签收并入库 |
cancelled | 已取消 | 大陆快递预报单已取消 |
failed | 失败 | 预报或物流处理失败 |
A.3.3 露天出货状态 ruten_shipping_status
| 状态值 | 中文名称 | 说明 |
|---|---|---|
Unshipped | 尚未出货 | 尚未完成露天出货处理 |
Shipped | 已出货 | 已完成露天出货处理 |
Delay | 延迟出货 | 出货时间超过预期 |
Cancel | 无法出货 | 订单无法完成出货 |
A.3.4 物流仓附加数据
| 字段 | 类型 | 说明 |
|---|---|---|
role | string | 仓库用途：consolidation（大陆集运仓）或 return（台湾退货仓） |
status | string | 仓库状态；V1 可选仓库固定返回 active |
logistics_company_code | string | 物流公司代码；同一店铺选择的物流仓必须属于同一物流商 |
supports_consolidation | boolean | 是否支持集运 |
supports_stocking | boolean | 是否支持备货 |
supports_return | boolean | 是否支持退货 |
province | string | 仓库地区；大陆集运仓为 大陆，台湾退货仓为 台湾 |
使用约定
- 未在本附录定义的状态不得作为 V1 OpenAPI 的正式枚举返回。
- 新状态上线前必须补充中文名称、业务含义、允许操作和兼容策略。
- 调用方应保留未知状态的可见错误处理，不应将未知值自动映射为现有状态。
- 回调通知中的状态值与查询接口保持一致，不另外定义同义枚举。