V1 订单和物流 API

本章定义订单查询、订单出货、取消交易处理，以及店铺物流仓配置。所有数据均按 Access Token 绑定的卖家租户隔离。

Base Path: /openapi/v1

Authentication: 除特别说明外，均需传入 Authorization: Bearer <access_token>。

设计原则

order_id 是 Sugumart 订单 ID；ruten_order_id 是露天订单号。
调用方只提交当前业务动作新增的信息。订单、收件人、商品、金额和末端配送资料由 Sugumart 根据订单快照取得。
订单出货使用店铺当前设置的大陆集运仓，并以卖家大陆退货仓中唯一的主要仓作为寄件地址；出货请求不能临时覆盖这两个仓库。
写请求以订单当前状态为前置条件。重复请求不得重复建立履约或重复处理取消交易。
露天或物流商的异步结果通过订单详情和第二章业务通知确认。

处理流程

text

首次配置：GET /warehouses → POST /warehouses/selection
          POST /warehouses/seller-returns（设置主要大陆退货仓）
日常处理：GET /orders → GET /orders/{order_id}
              ├─ POST /orders/{order_id}/ship
              ├─ POST /orders/{order_id}/cancel
              └─ POST /orders/{order_id}/cancel/confirm

4.1 订单管理

4.1.1 查询订单列表

GET /openapi/v1/orders

本接口定位为人工查询和订单处理页面使用，不提供增量同步语义。调用方可按订单状态、创建时间或关键字筛选，并使用 limit、offset 浏览结果。

返回当前店铺的订单摘要，包括主状态为 pending（待实名）的订单；可显式传入 status=pending 单独筛选，分页 count 使用相同条件。待实名订单的 available_actions 不包含 ship，符合取消条件时仍可包含 cancel。结果固定按 created_at DESC, id DESC 排列。id 是创建时间相同时的稳定第二排序键；V1 不提供自定义排序参数。

Query Parameters

字段	类型	必填	说明
`limit`	number	否	每页数量，默认 `20`，范围 `1-100`
`offset`	number	否	偏移量，默认 `0`，必须为非负整数
`q`	string	否	精确或模糊搜索 Sugumart 订单 ID、露天订单号、商品名称或 SKU
`status`	string	否	订单主状态；多个值使用半角逗号分隔，枚举见V1 状态附录
`view_status`	string	否	商家展示状态；多个值使用半角逗号分隔，枚举见V1 状态附录
`cancellation_pending`	boolean	否	`true` 时仅返回等待卖家确认的买家取消申请
`created_from`	string	否	创建时间下界，ISO 8601 UTC，包含边界
`created_to`	string	否	创建时间上界，ISO 8601 UTC，包含边界；不得早于 `created_from`

Response (200 OK)

字段	类型	说明
`orders`	OrderSummary[]	当前页订单摘要
`count`	number	符合筛选条件的订单总数
`limit`	number	本次分页大小
`offset`	number	本次分页偏移量

Response Example

json

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "d2e925a7-b767-407b-8624-c61388ab24b3",
        "ruten_order_id": "24080412345678",
        "status": "pending_shipment",
        "view_status": "pending_shipment",
        "buyer_name": "林小姐",
        "recipient_name": "林怡君",
        "item_count": 1,
        "quantity": 1,
        "currency": "TWD",
        "product_amount": "1200.00",
        "shipping_amount": "80.00",
        "total_amount": "1000.00",
        "cancellation": null,
        "active_fulfillment": null,
        "available_actions": [
          "ship",
          "cancel"
        ],
        "status_observed_at": "2026-08-04T03:09:55.000Z",
        "shipment_deadline_at": "2026-08-06T03:09:55.000Z",
        "created_at": "2026-08-04T02:15:00.000Z",
        "updated_at": "2026-08-04T03:10:00.000Z"
      }
    ],
    "count": 1,
    "limit": 20,
    "offset": 0
  }
}

Error Responses

Status	code	说明
400	`validation_error`	查询参数、状态或时间范围无效
401	`unauthorized`	Access Token 无效或已过期

4.1.2 查询订单详情

GET /openapi/v1/orders/{order_id}

返回订单商品、金额、收件信息、取消交易和当前履约资料。调用出货或取消接口前，应以本接口返回的 available_actions 判断当前允许操作。ruten_payload 是订单同步时保存在 Sugumart 数据库内的露天详情快照，不会在查询时实时请求露天。

Path Parameters

字段	类型	必填	说明
`order_id`	string(uuid)	是	Sugumart 订单 ID

Response (200 OK)

字段	类型	说明
`order`	OrderDetail	订单完整详情

Response Example

json

{
  "success": true,
  "data": {
    "order": {
      "id": "d2e925a7-b767-407b-8624-c61388ab24b3",
      "ruten_order_id": "24080412345678",
      "status": "pending_shipment",
      "view_status": "pending_shipment",
      "currency": "TWD",
      "product_amount": "1200.00",
      "shipping_amount": "80.00",
      "total_amount": "1000.00",
      "recipient_name": "林怡君",
      "recipient_phone": "0912345678",
      "shipping_address": {
        "name": "林怡君",
        "phone": "0912345678",
        "city": "台北市",
        "district": "中山区",
        "address_1": "南京东路三段 100 号",
        "country_code": "TW",
        "identity_name": "林怡君",
        "identity_number_masked": "A1******89"
      },
      "items": [
        {
          "id": "58dff493-4174-4896-825d-8bc36f8bbc39",
          "ruten_item_id": "22408041234567",
          "sku": "BAG-BLK-20",
          "spec_name": "黑色 / 20L",
          "item_name": "轻量防泼水通勤背包",
          "quantity": 1,
          "currency": "TWD",
          "unit_price": "1200.00",
          "product_amount": "1200.00"
        }
      ],
      "ruten_payload": {
        "order_id": "24080412345678"
      },
      "cancellation": null,
      "fulfillment": null,
      "available_actions": [
        "ship",
        "cancel"
      ],
      "status_observed_at": "2026-08-04T03:09:55.000Z",
      "shipment_deadline_at": "2026-08-06T03:09:55.000Z",
      "created_at": "2026-08-04T02:15:00.000Z",
      "updated_at": "2026-08-04T03:10:00.000Z"
    }
  }
}

Error Responses

Status	code	说明
401	`unauthorized`	Access Token 无效或已过期
404	`order_not_found`	订单不存在或不属于当前店铺

4.1.3 订单出货

POST /openapi/v1/orders/{order_id}/ship

为待出货订单登记一个或多个大陆快递单号并建立跨境履约。Sugumart 自动从订单、SKU 和店铺配置取得集运仓、末端配送、收件人、发件人、商品、重量及申报金额。提交给物流商的 total_value 按 product_amount 计算，cod_value 按 product_amount + shipping_amount 计算；任一金额缺失时拒绝出货，不使用已经扣除露天卖家折扣、优惠及露币的 total_amount。

前置条件

available_actions 包含 ship。
店铺已设置有效的大陆集运仓，并至少设置一个卖家大陆退货仓且唯一标记一个主要仓。
订单收件人与清关资料完整。
每个订单商品已关联有效 SKU，且具备物流商要求的重量及申报资料。
订单必须具备有效的 product_amount 和 shipping_amount；任一金额缺失时拒绝出货，不以 total_amount 或固定运费回退值替代。
一个订单在 V1 中只建立一个有效履约，该履约可关联多个大陆快递单号；本接口不支持按商品数量拆包或分批发货。

Path Parameters

字段	类型	必填	说明
`order_id`	string(uuid)	是	Sugumart 订单 ID

Request Body

字段	类型	必填	说明
`drop_orders`	ShipmentPackage[]	条件必填	推荐的新格式；至少一个包裹，每项分别指定单号与快递公司。不能与 `tracking_number` 或顶层 `carrier_code` 混用
`tracking_number`	string	条件必填	兼容单号字段；未提供 `drop_orders` 时必填。去除首尾空格后长度 `1-100`，不接受 `null` 或空字符串
`transport_mode`	string	否	跨境运输方式：`sea` 海运、`sea_express` 海快、`air` 空运；新发货省略默认海运，不接受 `null` 或空字符串
`carrier_code`	string	否	仅用于旧格式的统一大陆快递公司代码，去除首尾空格后长度 `1-64`，不接受 `null` 或空字符串；提供时用于全部旧格式单号，省略时逐条识别

ShipmentPackage 字段：

字段	类型	必填	说明
`tracking_number`	string	是	大陆快递单号；去除首尾空格后长度 `1-100`，不接受 `null` 或空字符串
`carrier_code`	string	是	该单号的快递公司代码；去除首尾空格后长度 `1-64`，不接受 `null` 或空字符串。例如顺丰 `SFExpress`、京东 `JD`；当前按字符串校验，不作枚举限制

新格式按包裹保存并向物流商传递各自的快递公司。包裹对象不接受未知字段；单号去除首尾空格后若重复，返回 400 validation_error，即使两项的公司不同也不允许重复。carrier_code=OTHER 会继续尝试自动识别，不能用于强制关闭识别。

未提供 drop_orders 时，必须提供单号字段 tracking_number。多包裹统一使用 drop_orders，不再提供独立的单号数组；未知请求字段返回 400 validation_error。

兼容说明：旧文档要求无法识别快递公司时必须提供 carrier_code，当前实现采用 OTHER，不会仅因无法识别而返回 carrier_required。新接入请使用 drop_orders 为每个单号分别指定公司。旧格式仍支持省略顶层 carrier_code 自动识别；无法识别时使用 OTHER。

同一订单使用顺丰和京东的请求示例（新格式）：

json

{
  "drop_orders": [
    { "tracking_number": "SF1234567890123", "carrier_code": "SFExpress" },
    { "tracking_number": "JD1234567890123", "carrier_code": "JD" }
  ],
  "transport_mode": "air"
}

兼容的单号请求示例：

json

{
  "tracking_number": "SF123456789CN",
  "transport_mode": "air"
}

Response (201 Created)

字段	类型	说明
`order`	OrderDetail	已刷新状态和可用操作的订单
`fulfillment`	Fulfillment	创建后的履约资料

Response Example

json

{
  "success": true,
  "data": {
    "order": {
      "id": "d2e925a7-b767-407b-8624-c61388ab24b3",
      "ruten_order_id": "24080412345678",
      "status": "shipped",
      "view_status": "shipped",
      "available_actions": []
    },
    "fulfillment": {
      "id": "97e78f56-6f67-474b-91cd-3669461ec54d",
      "fulfillment_no": "SGM202608040001",
      "status": "created",
      "drop_orders": [
        {
          "id": "11111111-1111-4111-8111-111111111111",
          "tracking_number": "SF123456789CN",
          "carrier_code": "SF",
          "status": "created",
          "warehouse_received_at": null
        },
        {
          "id": "22222222-2222-4222-8222-222222222222",
          "tracking_number": "SF987654321CN",
          "carrier_code": "SF",
          "status": "created",
          "warehouse_received_at": null
        }
      ],
      "tracking_number": "SF123456789CN",
      "carrier_code": "SF",
      "transport_mode": "air",
      "warehouse_code": "20089",
      "external_order_code": "WMS2408040098",
      "drop_order_status": "created",
      "warehouse_received_at": null,
      "shipped_at": null,
      "delivered_at": null,
      "created_at": "2026-08-04T08:50:00.000Z",
      "updated_at": "2026-08-04T08:50:00.000Z"
    }
  }
}

多单号响应与重试

订单列表的 active_fulfillment、订单详情的 active_fulfillment / fulfillment，以及发货响应的 order 内履约对象和 data.fulfillment 均通过 drop_orders 返回包裹资料，包含当前履约全部未软删除的大陆包裹，包含状态为 cancelled 或 failed 的包裹。包裹按创建时间升序、同一创建时间按包裹 ID 升序排列，不保证与提交数组顺序一致。

原有 tracking_number、carrier_code、drop_order_status 和 warehouse_received_at 保留，分别对应 drop_orders[0] 的单号、公司、状态和入库时间，仅用于兼容旧客户端，不代表全部包裹的状态。履约存在但无包裹时，drop_orders 为 []，上述兼容字段为 null；没有有效履约时，履约对象仍为 null。

旧文档曾约定相同单号重试返回 200 OK，当前实现尚未提供这一幂等保证；成功返回 201 Created。订单状态不允许出货时返回 409 order_not_shippable；订单仍可出货但已有不可重试的有效履约时返回 409 fulfillment_already_exists，不以单号是否相同区分。

仅当订单仍可出货，且已有履约处于 created、已生成集货单号但尚未取得物流商集货单号时，支持继续提交物流商；此时不可修改已保存的运输方式。请求超时或失败后应先查询订单及履约状态，不要将重复提交视为追加单号或分批发货。

Error Responses

Status	code	说明
400	`validation_error`	缺少包裹或单号字段、数组为空、单号或快递公司格式无效、新格式缺少公司、包裹单号重复、新旧字段混用或包含未知字段
400	`transport_mode_not_supported`	集货仓所属物流商未开通所选运输方式；提交前查询仓库的 `transport_modes`
409	`transport_mode_conflict`	已有本地履约重试不能修改已保存的运输方式
400	`carrier_required`	旧契约错误码；当前实现对无法识别的快递公司使用 `OTHER`，不会仅因此返回本错误
401	`unauthorized`	Access Token 无效或已过期
404	`order_not_found`	订单不存在或不属于当前店铺
409	`order_not_shippable`	当前订单状态不允许出货
409	`fulfillment_already_exists`	订单已有不可重试的有效履约，与本次单号是否相同无关
422	`shipment_configuration_incomplete`	物流仓、卖家主要大陆退货仓或物流商配置不完整；`data.missing_fields` 返回缺失项，其中缺少主要退货仓时包含 `seller_return_warehouse`
422	`order_shipment_data_incomplete`	订单、清关、SKU 重量或申报资料不完整；`data.missing_fields` 返回缺失项
503	`shipment_provider_error`	物流商暂时不可用或拒绝建立集货单

4.1.4 卖家取消交易

POST /openapi/v1/orders/{order_id}/cancel

由卖家主动向露天申请取消交易。该操作不会删除 Sugumart 订单；已经进入有效履约的订单不能通过本接口取消。

调用成功表示露天已经接受取消申请或订单已经完成取消；调用方应读取响应的 cancellation.status，并通过订单详情或回调继续确认最终状态。

Path Parameters

字段	类型	必填	说明
`order_id`	string(uuid)	是	Sugumart 订单 ID

Request Body

字段	类型	必填	说明
`reason_code`	string	是	`item_defective_or_lost`、`buyer_unreachable`、`cancelled_by_agreement`、`seller_out_of_stock` 或 `other`
`reason`	string	条件必填	`reason_code=other` 时必填；提供时去除首尾空格后长度 `1-100`。服务端自动转换为台湾繁体，转换后仍须为 `1-100` 字；其他原因可省略，使用对应的繁体原因文案

json

{
  "reason_code": "seller_out_of_stock"
}

选择 other 时必须填写文字，例如：

json

{
  "reason_code": "other",
  "reason": "買家要求更換商品，協議取消後重新下單"
}

也可传入简体文字，服务端会统一转换为台湾繁体后保存并提交露天。其他类型如提供 reason，也会转换；不提供时使用该类型的繁体说明。空字符串、纯空白、非字符串及超长文字均返回 400 validation_error。

Response (200 OK)

字段	类型	说明
`order`	OrderDetail	提交取消请求后的最新订单
`cancellation`	Cancellation	当前取消交易资料

Response Example

json

{
  "success": true,
  "data": {
    "order": {
      "id": "d2e925a7-b767-407b-8624-c61388ab24b3",
      "ruten_order_id": "24080412345678",
      "status": "pending",
      "available_actions": []
    },
    "cancellation": {
      "requested_by": "seller",
      "status": "pending",
      "reason_code": "seller_out_of_stock",
      "reason": null,
      "requested_at": "2026-08-04T09:00:00.000Z",
      "decided_at": null,
      "status_at": "2026-08-04T09:00:00.000Z"
    }
  }
}

相同取消原因的重复请求返回当前结果，不重复向露天提交；订单已有不同原因的处理中申请时返回 409 cancellation_conflict。

Error Responses

Status	code	说明
400	`validation_error`	取消原因无效或缺少 `reason`
401	`unauthorized`	Access Token 无效或已过期
404	`order_not_found`	订单不存在或不属于当前店铺
409	`order_not_cancellable`	当前订单状态不允许卖家取消
409	`fulfillment_already_exists`	订单已经进入有效履约
409	`cancellation_conflict`	已存在内容不同或由买家发起的取消交易
502	`ruten_provider_error`	露天未接受取消请求

4.1.5 确认买家取消交易

POST /openapi/v1/orders/{order_id}/cancel/confirm

同意买家发起的取消交易。仅当 cancellation.requested_by=buyer 且 cancellation.status=pending_confirmation 时允许调用。已付款订单的款项处理由露天取消流程完成，本接口不单独发起退款。

Path Parameters

字段	类型	必填	说明
`order_id`	string(uuid)	是	Sugumart 订单 ID

Request Body

无请求体。

Response (200 OK)

字段	类型	说明
`order`	OrderDetail	确认后的最新订单
`cancellation`	Cancellation	确认后的取消交易资料

Response Example

json

{
  "success": true,
  "data": {
    "order": {
      "id": "d2e925a7-b767-407b-8624-c61388ab24b3",
      "ruten_order_id": "24080412345678",
      "status": "cancelled",
      "available_actions": []
    },
    "cancellation": {
      "requested_by": "buyer",
      "status": "cancelled",
      "reason_code": "cancelled_by_agreement",
      "reason": null,
      "requested_at": "2026-08-04T08:40:00.000Z",
      "decided_at": "2026-08-04T09:05:00.000Z",
      "status_at": "2026-08-04T09:05:00.000Z"
    }
  }
}

已确认成功的重复请求返回当前结果，不重复向露天提交。

Error Responses

Status	code	说明
401	`unauthorized`	Access Token 无效或已过期
404	`order_not_found`	订单不存在或不属于当前店铺
409	`cancellation_not_pending`	当前没有等待卖家确认的买家取消申请
409	`cancellation_already_rejected`	该取消申请已经被拒绝，不能再确认
502	`ruten_provider_error`	露天未接受确认请求

4.2 物流管理

4.2.1 获取露天仓库列表

GET /openapi/v1/warehouses

返回当前店铺可以选择的有效物流仓。列表只包含已启用、未删除且已关联可用物流商的仓库，固定按 code ASC 排列；V1 不提供自定义排序参数。同时返回按物流商分组的 logistics_companies，供配置页面先选择物流商，再分别选择该物流商下的集运仓与退货仓。

物流商即使只提供一种仓库也会出现在分组中：缺少的一侧返回空数组；同一用途有多个仓库时全部返回，由调用方选择一个，不因缺仓或多仓排除物流商。

Query Parameters

字段	类型	必填	说明
`limit`	number	否	每页数量，默认 `20`，范围 `1-100`
`offset`	number	否	偏移量，默认 `0`，必须为非负整数
`role`	string	否	`consolidation`（大陆集运仓）或 `return`（台湾退货仓）

Response (200 OK)

字段	类型	说明
`warehouses`	Warehouse[]	当前页可选仓库
`count`	number	符合条件的仓库总数
`limit`	number	本次分页大小
`offset`	number	本次分页偏移量
`logistics_companies`	LogisticsCompanyWarehouses[]	按物流商分组的全部可选仓库，不受当前页 `limit`、`offset` 影响
`logistics_company_count`	number	可选物流商数量

Response Example

json

{
  "success": true,
  "data": {
    "warehouses": [
      {
        "code": "20089",
        "name": "深圳集运仓",
        "role": [
          "consolidation"
        ],
        "logistics_company_code": "SUGU_LOGISTICS",
        "logistics_company_name": "Sugumart 跨境物流",
        "address": {
          "contact_name": "集运仓收货组",
          "phone": "0755-88886666",
          "province": "广东省",
          "city": "深圳市",
          "district": "宝安区",
          "address_1": "航城街道示例物流园 2 栋",
          "postal_code": "518100",
          "country_code": "CN"
        }
      }
    ],
    "count": 1,
    "limit": 20,
    "offset": 0,
    "logistics_companies": [
      {
        "logistics_company_code": "SUGU_LOGISTICS",
        "logistics_company_name": "Sugumart 跨境物流",
        "consolidation_warehouses": [
          {
            "code": "20089",
            "name": "深圳集运仓",
            "role": ["consolidation"],
            "logistics_company_code": "SUGU_LOGISTICS",
            "logistics_company_name": "Sugumart 跨境物流",
            "address": {
              "contact_name": "集运仓收货组",
              "phone": "0755-88886666",
              "province": "广东省",
              "city": "深圳市",
              "district": "宝安区",
              "address_1": "航城街道示例物流园 2 栋",
              "postal_code": "518100",
              "country_code": "CN"
            }
          }
        ],
        "return_warehouses": []
      }
    ],
    "logistics_company_count": 1
  }
}

Error Responses

Status	code	说明
400	`validation_error`	分页参数或 `role` 无效
401	`unauthorized`	Access Token 无效或已过期

4.2.2 获取当前物流仓

GET /openapi/v1/warehouses/selection

返回当前店铺的物流仓设置及有效性。已选仓库后来被停用或不再满足规则时，仍返回其 code，并将对应 valid 设为 false，避免把错误配置静默表现为“从未设置”。

Response (200 OK)

字段	类型	说明
`selection`	WarehouseSelection	当前店铺物流仓设置

Response Example

json

{
  "success": true,
  "data": {
    "selection": {
      "consolidation_warehouse": {
        "code": "20089",
        "name": "深圳集运仓",
        "valid": true,
        "invalid_reason": null
      },
      "return_warehouse": {
        "code": "20090",
        "name": "新北退货仓",
        "valid": true,
        "invalid_reason": null
      },
      "logistics_company_code": "SUGU_LOGISTICS",
      "updated_at": "2026-08-04T06:00:00.000Z"
    }
  }
}

Error Responses

Status	code	说明
401	`unauthorized`	Access Token 无效或已过期
404	`shop_not_found`	当前 Token 未绑定可用店铺

4.2.3 设置物流仓

POST /openapi/v1/warehouses/selection

更新当前店铺选定的大陆集运仓或台湾退货仓。请求采用局部更新语义：省略字段表示保持不变，传 null 表示清空对应设置；至少必须传入一个字段。logistics_company_code 是兼容字段，用于校验本次选择或一次清空两个仓库；服务端以仓库所属物流商为准，不单独持久化该字段。

Request Body

字段	类型	必填	说明
`logistics_company_code`	string \| null	否	当前选定物流商；`null` 会同时清空集运仓和退货仓
`consolidation_warehouse_code`	string \| null	否	大陆集运仓 code；必须支持 `consolidation`；`null` 表示清空
`return_warehouse_code`	string \| null	否	台湾退货仓 code；必须支持 `return`；`null` 表示清空

json

{
  "logistics_company_code": "SUGU_LOGISTICS",
  "consolidation_warehouse_code": "20089",
  "return_warehouse_code": "20090"
}

选择规则：

集运仓必须位于大陆并支持集运；退货仓必须位于台湾并支持退货。
仓库必须启用、未删除且已关联可用物流商。
两个非空仓库必须属于请求选择的同一物流商；不能跨物流商配对。
物流商可缺少集运仓或退货仓，缺少的一侧保持 null；同一用途存在多个仓库时由调用方选择其中一个。
清空大陆集运仓后，新的订单出货请求将被拒绝；不影响已经建立的履约。
清空台湾退货仓不会阻止订单出货，但需要退货仓的后续业务不可执行。

Response (200 OK)

字段	类型	说明
`selection`	WarehouseSelection	更新后的完整设置

Response Example

json

{
  "success": true,
  "data": {
    "selection": {
      "consolidation_warehouse": {
        "code": "20089",
        "name": "深圳集运仓",
        "valid": true,
        "invalid_reason": null
      },
      "return_warehouse": {
        "code": "20090",
        "name": "新北退货仓",
        "valid": true,
        "invalid_reason": null
      },
      "logistics_company_code": "SUGU_LOGISTICS",
      "updated_at": "2026-08-04T09:10:00.000Z"
    }
  }
}

使用与当前设置相同的值重复请求时，返回当前结果且不产生额外副作用。

Error Responses

Status	code	说明
400	`validation_error`	未提供更新字段或字段格式无效
401	`unauthorized`	Access Token 无效或已过期
404	`warehouse_not_found`	指定仓库不存在或当前店铺不可见
409	`warehouse_unavailable`	指定仓库已停用、删除或物流商不可用
409	`warehouse_role_mismatch`	仓库地区或能力不符合指定用途
409	`warehouse_provider_mismatch`	两个仓库不属于同一物流商

4.2.4 获取卖家大陆退货仓

GET /openapi/v1/warehouses/seller-returns

返回当前店铺维护的卖家大陆退货仓。该资源与物流商提供的台湾退货仓不同；其中恰好一个 is_primary=true，作为订单出货和 WMS 集货单的寄件地址。兼容旧数据时，如尚未保存主要标记，响应会将列表第一项标记为主要。

Response (200 OK)

json

{
  "success": true,
  "data": {
    "warehouses": [
      {
        "id": "65bdb75c-59cb-4fe9-8a84-eaf46d6d05be",
        "label": "义乌退货仓",
        "first_name": "小明",
        "last_name": "陈",
        "company": "示例商贸",
        "address_1": "稠城街道示例路 8 号",
        "address_2": null,
        "city": "义乌市",
        "province": "浙江省",
        "country_code": "CN",
        "postal_code": "322000",
        "phone": "13800000000",
        "identity_number_masked": "12********34",
        "identity_name": "陈小明",
        "identity_phone": "13800000000",
        "is_primary": true
      }
    ]
  }
}

4.2.5 替换卖家大陆退货仓

POST /openapi/v1/warehouses/seller-returns

使用完整列表替换当前店铺的全部卖家大陆退货仓，不影响历史大陆发货仓等其他内部地址。请求必须包含 1-5 个仓库，并且恰好一个 is_primary=true；重复提交同一完整列表可安全重试。

id 可省略，由服务端生成；更新已有仓库时应回传其 id。identity_number 是只写敏感字段：GET 仅返回脱敏值；更新同一 id 且省略该字段时保留原值，传入字符串时替换原值。

Request Body

字段	类型	必填	说明
`warehouses`	SellerReturnWarehouseInput[]	是	完整退货仓列表，`1-5` 项
`warehouses[].id`	string	否	已有仓库 ID；同一请求内不得重复
`warehouses[].label`	string	是	仓库名称，`1-50` 字
`warehouses[].first_name`	string	是	联系人名字，`1-20` 字
`warehouses[].last_name`	string	否	联系人姓氏，最长 20 字，默认空字符串
`warehouses[].company`	string	否	公司名称，最长 100 字，默认空字符串
`warehouses[].address_1`	string	是	详细地址，`1-200` 字
`warehouses[].address_2`	string	否	补充地址，最长 200 字，默认空字符串
`warehouses[].city`	string	是	城市，`1-50` 字
`warehouses[].province`	string	否	省份，最长 50 字，默认空字符串
`warehouses[].country_code`	string	是	国家或地区代码，`1-8` 字符，保存时转为大写
`warehouses[].postal_code`	string	否	邮政编码，最长 20 字，默认空字符串
`warehouses[].phone`	string	是	仓库联系电话，`1-30` 字
`warehouses[].identity_number`	string	否	证件号码，最长 64 字；同 ID 更新时省略表示保留
`warehouses[].identity_name`	string	否	实名姓名，最长 50 字，默认空字符串
`warehouses[].identity_phone`	string	否	实名电话，最长 30 字，默认空字符串
`warehouses[].is_primary`	boolean	是	是否为主要退货仓；整个列表必须恰好一个 `true`

json

{
  "warehouses": [
    {
      "id": "65bdb75c-59cb-4fe9-8a84-eaf46d6d05be",
      "label": "义乌退货仓",
      "first_name": "小明",
      "last_name": "陈",
      "company": "示例商贸",
      "address_1": "稠城街道示例路 8 号",
      "address_2": "",
      "city": "义乌市",
      "province": "浙江省",
      "country_code": "CN",
      "postal_code": "322000",
      "phone": "13800000000",
      "identity_name": "陈小明",
      "identity_phone": "13800000000",
      "is_primary": true
    }
  ]
}

成功时返回 200 OK，data.warehouses 与 4.2.4 相同。

Error Responses

Status	code	说明
400	`validation_error`	列表数量、字段格式、ID 唯一性或主要仓数量不符合要求；`data.fields` 返回字段错误
401	`invalid_token`	Access Token 无效或已过期
404	`shop_not_found`	当前 Token 未绑定可用店铺

公共响应对象

OrderSummary

字段	类型	说明
`id`	string(uuid)	Sugumart 订单 ID
`ruten_order_id`	string	露天订单号
`status`	string	订单主状态，见V1 状态附录
`view_status`	string	商家展示状态，见V1 状态附录
`buyer_name`	string \| null	买家名称
`recipient_name`	string \| null	收件人名称
`item_count`	number	订单商品明细种类数，非负整数
`quantity`	number	商品购买总数量，非负整数
`currency`	string	ISO 4217 币种代码
`product_amount`	string \| null	商品金额，来源为露天 `checkout_info.item_amount`；`currency` 主单位 decimal string，固定 2 位小数
`shipping_amount`	string \| null	露天原始物流费，来源为 `checkout_info.original_shipping_fee`；`currency` 主单位 decimal string，固定 2 位小数
`total_amount`	string \| null	买家实际支付金额，即扣除露天卖家折扣、优惠及露币后的金额；`currency` 主单位 decimal string，固定 2 位小数
`cancellation`	Cancellation \| null	当前取消交易；不存在时为 `null`
`active_fulfillment`	FulfillmentSummary \| null	当前有效履约；未出货时为 `null`
`available_actions`	string[]	当前可执行操作：`ship`、`cancel`、`confirm_cancellation`；`status=pending` 时不返回 `ship`
`status_observed_at`	string \| null	最近一次观察到露天订单、付款、出货或取消回复状态的时间，ISO 8601 UTC；尚无外部状态观察记录时为 `null`。该字段不表示每次本地字段更新的时间
`shipment_deadline_at`	string \| null	兼容历史发货截止时间，ISO 8601 UTC；新分流订单为 `null`，且不再触发自动取消或发货阻断
`created_at`	string	订单创建时间，ISO 8601 UTC
`updated_at`	string	订单最近更新时间，ISO 8601 UTC

OrderDetail

OrderDetail 包含 OrderSummary 的全部字段，并增加以下字段：

字段	类型	说明
`ruten_order_status`	string \| null	最近观察到的露天订单状态
`ruten_pay_status`	string \| null	最近观察到的露天付款状态
`ruten_shipping_status`	string \| null	最近观察到的露天出货状态
`ruten_respond_status`	string \| null	最近观察到的露天取消回复状态
`buyer_phone`	string \| null	买家联系电话
`buyer_email`	string \| null	买家电子邮件
`recipient_phone`	string \| null	收件人联系电话
`shipping_address`	ShippingAddress	结构化收件及清关资料
`items`	OrderItem[]	订单商品明细
`fulfillment`	Fulfillment \| null	当前有效履约完整资料
`ruten_payload`	RutenPayload	订单同步时保存的露天订单详情脱敏快照；无快照时为空对象。当前格式及示例见下文；该字段不是稳定的 V1 结构化契约
`paid_at`	string \| null	付款时间，ISO 8601 UTC
`cancelled_at`	string \| null	取消完成时间，ISO 8601 UTC
`completed_at`	string \| null	订单完成时间，ISO 8601 UTC

RutenPayload

ruten_payload 是 Sugumart 同步订单时保存的露天订单详情快照，不会在查询订单详情时实时请求露天。它用于第三方系统排查来源资料或读取尚未纳入 OrderDetail 稳定字段的露天信息。

当前快照经过脱敏处理：收件人姓名、电话、地址、超商门市及买家电子邮件等直接个人资料以 ********** 返回。买家露天账号、订单号、商品与付款物流状态等业务识别资料仍会保留。调用方仍应将整个对象视为敏感业务资料，限制访问、日志记录与保存期限。

字段	类型	说明
`item_list`	object[]	露天订单商品明细；价格为 TWD 主单位整数，数量为正整数
`order_info`	object	露天订单编号、买家账号、状态和建立时间等资料
`cancel_info`	object \| null	露天取消交易资料；没有取消记录时为 `null`
`payment_info`	object	付款方式、金额、付款状态和相关时间
`checkout_info`	object	商品、运费、优惠券与订单收入的结账金额资料；金额为 TWD 主单位整数
`shipping_info`	object	配送方式、出货状态、包裹和已脱敏收件资料

其中 create_time、seller_confirm_time、pay_time、transfer_time、pause_refund_time 与 ship_time 等露天原始时间字段使用 Unix timestamp（秒），尚未发生时为 null。这些字段不会转换成 V1 稳定字段所采用的 ISO 8601 格式。

以下为当前脱敏数据格式的完整示例：

json

{
  "item_list": [
    {
      "item_id": "22551750576184",
      "spec_id": "255124234615055",
      "custom_no": "5159848223715",
      "item_name": "卡諾 倉鼠窩躲避屋【選物家】芝吱多居室 倉鼠躲避窩 偷窺屋 倉鼠窩 倉鼠別墅 倉鼠木屋 倉鼠玩具 卡諾官方 B005",
      "spec_name": "M 芝吱單居室-奶酪黃",
      "discount_price": 218,
      "original_price": 218,
      "quantity_purchased": 2
    },
    {
      "item_id": "22551750576184",
      "spec_id": "255124234615044",
      "custom_no": "5035565310791",
      "item_name": "卡諾 倉鼠窩躲避屋【選物家】芝吱多居室 倉鼠躲避窩 偷窺屋 倉鼠窩 倉鼠別墅 倉鼠木屋 倉鼠玩具 卡諾官方 B005",
      "spec_name": "M 芝吱多居室-奶酪黃",
      "discount_price": 298,
      "original_price": 298,
      "quantity_purchased": 1
    }
  ],
  "order_info": {
    "buyer_id": "rutentest1187",
    "order_id": "26070761963177",
    "buyer_email": "**********",
    "create_time": 1783418124,
    "msg_to_buyer": null,
    "order_status": "ReadyToShip",
    "msg_to_seller": null,
    "seller_confirm_time": 1783418142
  },
  "cancel_info": null,
  "payment_info": {
    "account": "iw",
    "pay_way": "FMB2C_COD",
    "pay_time": null,
    "pay_amount": null,
    "pay_status": "Unpaid",
    "pay_way_text": "全家取貨付款",
    "transfer_time": null,
    "notify_pay_info": null,
    "pause_refund_time": null
  },
  "checkout_info": {
    "rpoint": 0,
    "item_amount": 734,
    "order_income": 734,
    "total_amount": 734,
    "coupon_from_ruten": 0,
    "coupon_from_seller": 0,
    "use_shipping_coupon": false,
    "original_shipping_fee": 0,
    "is_total_amount_edited": false,
    "buyer_paid_shipping_fee": 0
  },
  "shipping_info": {
    "ship_way": "FMB2C_COD",
    "ship_time": null,
    "package_info": [],
    "receiver_info": {
      "receiver_name": "**********",
      "receiver_phone": "**********",
      "receiver_mobile": "**********",
      "receiver_address": "**********",
      "receiver_store_name": "**********"
    },
    "ship_way_text": "全家取貨付款",
    "shipping_status": "Unshipped"
  }
}

上述结构记录的是当前露天上游快照格式。露天新增、删除或调整嵌套字段时，ruten_payload 可能随之变化；第三方的稳定业务逻辑应优先使用 OrderDetail 的结构化字段。

ShippingAddress

字段	类型	说明
`name`	string \| null	收件人姓名
`phone`	string \| null	收件人联系电话
`postal_code`	string \| null	邮政编码
`city`	string \| null	城市或县市
`district`	string \| null	行政区
`address_1`	string \| null	主要地址
`address_2`	string \| null	补充地址
`country_code`	string \| null	ISO 3166-1 alpha-2 国家或地区代码
`identity_name`	string \| null	清关实名姓名；无资料时为 `null`
`identity_number_masked`	string \| null	脱敏后的清关证件号码；不返回完整证件号

OrderItem

字段	类型	说明
`id`	string(uuid)	订单商品明细 ID
`ruten_item_id`	string	露天商品 ID
`product_id`	string(uuid) \| null	匹配到的 Sugumart 商品 ID
`sku_id`	string(uuid) \| null	匹配到的 Sugumart SKU ID
`sku`	string \| null	SKU 编号快照
`spec_name`	string \| null	规格名称快照
`item_name`	string	商品名称快照
`image_url`	string \| null	商品主图 URL
`quantity`	number	购买数量，正整数
`currency`	string	ISO 4217 币种代码
`unit_price`	string \| null	单价，`currency` 主单位 decimal string，固定 2 位小数
`product_amount`	string \| null	商品小计，`currency` 主单位 decimal string，固定 2 位小数

Cancellation

字段	类型	说明
`requested_by`	string	`buyer`、`seller` 或 `system`
`status`	string	`pending`、`pending_confirmation`、`confirmed`、`rejected`、`cancelled` 或 `failed`
`reason_code`	string \| null	取消原因代码
`reason`	string \| null	取消原因补充说明
`requested_at`	string	取消申请时间，ISO 8601 UTC
`decided_at`	string \| null	确认、拒绝或系统完成处理的时间，ISO 8601 UTC
`status_at`	string	当前取消状态生效时间，ISO 8601 UTC；未作出决定时等于 `requested_at`，已确认、拒绝、取消或失败时等于 `decided_at`

FulfillmentSummary

drop_orders 返回当前履约全部未软删除的大陆包裹，按创建时间及 ID 升序排列；旧单号字段只表示数组首条。履约存在但没有包裹时数组为 []，没有有效履约时整个对象为 null。

字段	类型	说明
`id`	string(uuid)	履约 ID
`fulfillment_no`	string	Sugumart 集货单号
`status`	string	履约状态，见V1 状态附录
`drop_orders`	DropOrder[]	大陆包裹列表，见下表；无包裹时为 `[]`
`tracking_number`	string \| null	兼容字段，等于 `drop_orders[0].tracking_number`；无包裹时为 `null`
`carrier_code`	string \| null	兼容字段，等于 `drop_orders[0].carrier_code`；无包裹时为 `null`
`warehouse_code`	string	建立履约时使用的大陆集运仓 code
`transport_mode`	string	已保存的跨境运输方式：`sea` / `sea_express` / `air`；历史记录为 `sea`
`created_at`	string	履约创建时间，ISO 8601 UTC
`updated_at`	string	履约最近更新时间，ISO 8601 UTC

DropOrder

每项代表一个大陆包裹，不包含商品与包裹的数量分配。

字段	类型	说明
`id`	string(uuid)	大陆包裹 ID
`tracking_number`	string	该包裹的大陆快递单号
`carrier_code`	string	该包裹的大陆快递公司代码
`status`	string	该包裹状态：`created`、`shipped`、`arrived`、`received`、`cancelled`、`failed`；来源为 `rt_shipment_drop_order.status`
`warehouse_received_at`	string \| null	该包裹的集运仓签收入库时间，ISO 8601 UTC；尚未入库为 `null`

Fulfillment

Fulfillment 包含 FulfillmentSummary 的全部字段，并增加以下字段：

字段	类型	说明
`external_order_code`	string \| null	物流商集货单号；尚未取得时为 `null`
`deliverer_code`	string \| null	从露天订单取得的台湾末端承运商代码
`drop_order_status`	string \| null	兼容字段，等于 `drop_orders[0].status`；无包裹时为 `null`
`warehouse_received_at`	string \| null	兼容字段，等于 `drop_orders[0].warehouse_received_at`；无包裹或首条尚未入库时为 `null`，ISO 8601 UTC
`shipped_at`	string \| null	集运仓出库时间，ISO 8601 UTC
`delivered_at`	string \| null	买家末端签收时间，ISO 8601 UTC
`completed_at`	string \| null	履约完成时间，ISO 8601 UTC

Warehouse

字段	类型	说明
`code`	string	仓库 code，设置物流仓时使用
`name`	string	仓库名称
`role`	string[]	支持用途：`consolidation`、`return`
`logistics_company_code`	string	物流公司代码
`logistics_company_name`	string	物流公司名称
`transport_modes`	string[]	物流公司支持的方式，至少包含 `sea`；其他可选值 `sea_express`、`air`
`address`	WarehouseAddress	仓库地址

WarehouseAddress

字段	类型	说明
`contact_name`	string \| null	联系人
`phone`	string \| null	联系电话
`province`	string \| null	省份或地区
`city`	string \| null	城市
`district`	string \| null	行政区
`address_1`	string	详细地址
`postal_code`	string \| null	邮政编码
`country_code`	string	ISO 3166-1 alpha-2 国家或地区代码

LogisticsCompanyWarehouses

字段	类型	说明
`logistics_company_code`	string	物流公司代码
`logistics_company_name`	string \| null	物流公司名称
`transport_modes`	string[]	仓库所属物流商支持的方式：`sea` / `sea_express` / `air`，至少包含 `sea`
`consolidation_warehouses`	Warehouse[]	该物流商可选大陆集运仓，可为空或包含多个仓库
`return_warehouses`	Warehouse[]	该物流商可选台湾退货仓，可为空或包含多个仓库

WarehouseSelection

字段	类型	说明
`consolidation_warehouse`	SelectedWarehouse \| null	当前大陆集运仓；从未设置或已清空时为 `null`
`return_warehouse`	SelectedWarehouse \| null	当前台湾退货仓；从未设置或已清空时为 `null`
`logistics_company_code`	string \| null	当前选择所属物流公司代码；均未设置时为 `null`
`updated_at`	string \| null	最近设置时间，ISO 8601 UTC；从未设置时为 `null`

SelectedWarehouse

字段	类型	说明
`code`	string	已保存的仓库 code
`name`	string \| null	当前仓库名称；仓库不可用时仍保留 code，名称可能为 `null`
`valid`	boolean	当前是否仍可用于对应业务
`invalid_reason`	string \| null	无效原因代码；有效时为 `null`

SellerReturnWarehouse

字段	类型	说明
`id`	string	店铺内地址 ID；更新时原样回传
`label`	string	仓库名称，最长 50 字
`first_name` / `last_name`	string / string \| null	联系人名字与姓氏
`company`	string \| null	公司名称
`address_1` / `address_2`	string / string \| null	详细地址
`city` / `province`	string / string \| null	城市与省份
`country_code`	string	国家或地区代码，保存时转为大写
`postal_code`	string \| null	邮政编码
`phone`	string	仓库联系电话
`identity_number_masked`	string \| null	脱敏证件号码，仅响应返回
`identity_name` / `identity_phone`	string \| null	实名资料
`is_primary`	boolean	是否为唯一主要退货仓；主要仓用作 WMS 寄件地址

通用错误格式

错误响应遵循 V1 统一信封；request_id 仅在请求携带 X-SGM-Request-Id 时返回，需要指出缺失资料时可在 data 中增加结构化字段。

json

{
  "success": false,
  "code": "order_shipment_data_incomplete",
  "message": "Shipment data is incomplete",
  "data": {
    "missing_fields": ["items[0].weight"]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

注意事项

available_actions 由订单、取消交易和履约状态计算，不是独立持久化字段。
金额均使用 JSON string，单位为对应 currency 的主单位，固定 2 位小数。
product_amount + shipping_amount 表示商品及原始物流费合计；发货时物流商 total_value 使用 product_amount，cod_value 使用该合计。订单 total_amount 表示扣除露天卖家折扣、优惠及露币后的买家实际支付金额，不可替代前述金额。
所有时间均为 ISO 8601 UTC；调用方可转换为店铺时区展示，但不得改变原始时间含义。
集运仓入库、集运仓出库和买家签收是不同物流节点，不得互相替代。
写请求超时后先查询订单详情，再决定是否重试。
ruten_payload 是数据库快照，不保证与露天当前状态实时一致；稳定业务逻辑应优先使用订单的结构化字段。

运输方式兼容规则

运输方式只记录于平台履约、跨境运输事实及财务快照，本次不改变向物流商 WMS 传递的 shipping_way=EXPRESS。新请求未传 transport_mode 时默认海运；本地失败重试未传时沿用首次保存值，显式改变时返回 409 transport_mode_conflict。配置变更不影响历史运输及原方式重试；运输方式非法返回 400 validation_error，未开通返回 400 transport_mode_not_supported。

V1 订单和物流 API ​

设计原则 ​

处理流程 ​

4.1 订单管理 ​

4.1.1 查询订单列表 ​

Query Parameters ​

Response (200 OK) ​

Response Example ​

Error Responses ​

4.1.2 查询订单详情 ​

Path Parameters ​

Response (200 OK) ​

Response Example ​

Error Responses ​

4.1.3 订单出货 ​

前置条件 ​

Path Parameters ​

Request Body ​

Response (201 Created) ​

Response Example ​

多单号响应与重试 ​

Error Responses ​

4.1.4 卖家取消交易 ​

Path Parameters ​

Request Body ​

Response (200 OK) ​

Response Example ​

Error Responses ​

4.1.5 确认买家取消交易 ​

Path Parameters ​

Request Body ​

Response (200 OK) ​

Response Example ​

Error Responses ​

4.2 物流管理 ​

4.2.1 获取露天仓库列表 ​

Query Parameters ​

Response (200 OK) ​

Response Example ​

Error Responses ​

4.2.2 获取当前物流仓 ​

Response (200 OK) ​

Response Example ​

Error Responses ​

4.2.3 设置物流仓 ​

Request Body ​

Response (200 OK) ​

Response Example ​

Error Responses ​

4.2.4 获取卖家大陆退货仓 ​

Response (200 OK) ​

4.2.5 替换卖家大陆退货仓 ​

Request Body ​

Error Responses ​

公共响应对象 ​

OrderSummary ​

OrderDetail ​

RutenPayload ​

ShippingAddress ​

OrderItem ​

Cancellation ​

FulfillmentSummary ​

DropOrder ​

Fulfillment ​

Warehouse ​

WarehouseAddress ​

LogisticsCompanyWarehouses ​

WarehouseSelection ​

SelectedWarehouse ​

SellerReturnWarehouse ​

通用错误格式 ​

注意事项 ​

运输方式兼容规则 ​

V1 订单和物流 API

设计原则

处理流程

4.1 订单管理

4.1.1 查询订单列表

Query Parameters

Response (200 OK)

Response Example

Error Responses

4.1.2 查询订单详情

Path Parameters

Response (200 OK)

Response Example

Error Responses

4.1.3 订单出货

前置条件

Path Parameters

Request Body

Response (201 Created)

Response Example

多单号响应与重试

Error Responses

4.1.4 卖家取消交易

Path Parameters

Request Body

Response (200 OK)

Response Example

Error Responses

4.1.5 确认买家取消交易

Path Parameters

Request Body

Response (200 OK)

Response Example

Error Responses

4.2 物流管理

4.2.1 获取露天仓库列表

Query Parameters

Response (200 OK)

Response Example

Error Responses

4.2.2 获取当前物流仓

Response (200 OK)

Response Example

Error Responses

4.2.3 设置物流仓

Request Body

Response (200 OK)

Response Example

Error Responses

4.2.4 获取卖家大陆退货仓

Response (200 OK)

4.2.5 替换卖家大陆退货仓

Request Body

Error Responses

公共响应对象

OrderSummary

OrderDetail

RutenPayload

ShippingAddress

OrderItem

Cancellation

FulfillmentSummary

DropOrder

Fulfillment

Warehouse

WarehouseAddress

LogisticsCompanyWarehouses

WarehouseSelection

SelectedWarehouse

SellerReturnWarehouse

通用错误格式

注意事项

运输方式兼容规则