Sugumart OpenAPI V1

Appearance

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
日常处理：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 浏览结果。

返回当前店铺的订单摘要，固定按 created_at DESC, id DESC 排列。id 是创建时间相同时的稳定第二排序键；V1 不提供自定义排序参数。

Query Parameters ​

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

Response (200 OK) ​

字段类型说明
ordersOrderSummary[]当前页订单摘要
countnumber符合筛选条件的订单总数
limitnumber本次分页大小
offsetnumber本次分页偏移量

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",
        "total_amount": "1280.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 ​

Statuscode说明
400validation_error查询参数、状态或时间范围无效
401unauthorizedAccess Token 无效或已过期

4.1.2 查询订单详情 ​

GET /openapi/v1/orders/{order_id}

返回订单商品、金额、收件信息、取消交易和当前履约资料。调用出货或取消接口前，应以本接口返回的 available_actions 判断当前允许操作。

Path Parameters ​

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

Response (200 OK) ​

字段类型说明
orderOrderDetail订单完整详情

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": "1280.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"
        }
      ],
      "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 ​

Statuscode说明
401unauthorizedAccess Token 无效或已过期
404order_not_found订单不存在或不属于当前店铺

4.1.3 订单出货 ​

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

为待出货订单登记一个大陆快递单号并建立跨境履约。Sugumart 自动从订单、SKU 和店铺配置取得集运仓、末端配送、收件人、发件人、商品、重量及申报金额。

前置条件 ​

  • available_actions 包含 ship。
  • 店铺已设置有效的大陆集运仓和默认大陆发件地址。
  • 订单收件人与清关资料完整。
  • 每个订单商品已关联有效 SKU，且具备物流商要求的重量及申报资料。
  • 一个订单在 V1 中只建立一个有效履约，并只接受一个大陆快递单号。

Path Parameters ​

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

Request Body ​

字段类型必填说明
tracking_numberstring是大陆快递单号，去除首尾空格后长度 1-100
carrier_codestring否大陆快递公司代码。Sugumart 优先根据单号识别；无法识别时必须提供
json
{
  "tracking_number": "SF123456789CN"
}

Response (201 Created) ​

字段类型说明
orderOrderDetail已刷新状态和可用操作的订单
fulfillmentFulfillment创建后的履约资料

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",
      "tracking_number": "SF123456789CN",
      "carrier_code": "SF",
      "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"
    }
  }
}

同一订单以同一个 tracking_number 重试时返回 200 OK 和现有结果；使用不同单号重复出货返回 409。

Error Responses ​

Statuscode说明
400validation_error快递单号或承运商代码格式无效
400carrier_required无法识别快递公司，必须提供 carrier_code
401unauthorizedAccess Token 无效或已过期
404order_not_found订单不存在或不属于当前店铺
409order_not_shippable当前订单状态不允许出货
409fulfillment_already_exists订单已使用其他快递单号建立有效履约
422shipment_configuration_incomplete物流仓、默认发件地址或物流商配置不完整；data.missing_fields 返回缺失项
422order_shipment_data_incomplete订单、清关、SKU 重量或申报资料不完整；data.missing_fields 返回缺失项
503shipment_provider_error物流商暂时不可用或拒绝建立集货单

4.1.4 卖家取消交易 ​

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

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

Path Parameters ​

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

Request Body ​

字段类型必填说明
reason_codestring是item_defective_or_lost、buyer_unreachable、cancelled_by_agreement、seller_out_of_stock 或 other
reasonstring条件必填reason_code=other 时必填，去除首尾空格后长度 1-100；其他原因可省略
json
{
  "reason_code": "seller_out_of_stock"
}

Response (200 OK) ​

字段类型说明
orderOrderDetail提交取消请求后的最新订单
cancellationCancellation当前取消交易资料

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"
    }
  }
}

相同取消原因的重复请求返回当前结果，不重复向露天提交。

Error Responses ​

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

4.1.5 确认买家取消交易 ​

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

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

Path Parameters ​

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

Request Body ​

无请求体。

Response (200 OK) ​

字段类型说明
orderOrderDetail确认后的最新订单
cancellationCancellation确认后的取消交易资料

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 ​

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

4.2 物流管理 ​

4.2.1 获取露天仓库列表 ​

GET /openapi/v1/warehouses

返回当前店铺可以选择的有效物流仓。列表只包含已启用、未删除且已关联可用物流商的仓库，固定按 code ASC 排列；V1 不提供自定义排序参数。

Query Parameters ​

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

Response (200 OK) ​

字段类型说明
warehousesWarehouse[]当前页可选仓库
countnumber符合条件的仓库总数
limitnumber本次分页大小
offsetnumber本次分页偏移量

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
  }
}

Error Responses ​

Statuscode说明
400validation_error分页参数或 role 无效
401unauthorizedAccess Token 无效或已过期

4.2.2 获取当前物流仓 ​

GET /openapi/v1/warehouses/selection

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

Response (200 OK) ​

字段类型说明
selectionWarehouseSelection当前店铺物流仓设置

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 ​

Statuscode说明
401unauthorizedAccess Token 无效或已过期
404shop_not_found当前 Token 未绑定可用店铺

4.2.3 设置物流仓 ​

POST /openapi/v1/warehouses/selection

更新当前店铺的大陆集运仓或台湾退货仓。请求采用局部更新语义：省略字段表示保持不变，传 null 表示清空对应设置；至少必须传入一个字段。

Request Body ​

字段类型必填说明
consolidation_warehouse_codestring | null否大陆集运仓 code；必须支持 consolidation；null 表示清空
return_warehouse_codestring | null否台湾退货仓 code；必须支持 return；null 表示清空
json
{
  "consolidation_warehouse_code": "20089",
  "return_warehouse_code": "20090"
}

选择规则：

  • 集运仓必须位于大陆并支持集运；退货仓必须位于台湾并支持退货。
  • 仓库必须启用、未删除且已关联可用物流商。
  • 两个非空仓库必须属于同一物流商。
  • 清空大陆集运仓后，新的订单出货请求将被拒绝；不影响已经建立的履约。

Response (200 OK) ​

字段类型说明
selectionWarehouseSelection更新后的完整设置

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 ​

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

公共响应对象 ​

OrderSummary ​

字段类型说明
idstring(uuid)Sugumart 订单 ID
ruten_order_idstring露天订单号
statusstring订单主状态，见V1 状态附录
view_statusstring商家展示状态，见V1 状态附录
buyer_namestring | null买家名称
recipient_namestring | null收件人名称
item_countnumber订单商品明细种类数，非负整数
quantitynumber商品购买总数量，非负整数
currencystringISO 4217 币种代码
total_amountstring | null订单总额，currency 主单位 decimal string，固定 2 位小数
cancellationCancellation | null当前取消交易；不存在时为 null
active_fulfillmentFulfillmentSummary | null当前有效履约；未出货时为 null
available_actionsstring[]当前可执行操作：ship、cancel、confirm_cancellation
status_observed_atstring | null最近一次观察到露天订单、付款、出货或取消回复状态的时间，ISO 8601 UTC；尚无外部状态观察记录时为 null。该字段不表示每次本地字段更新的时间
shipment_deadline_atstring | null当前订单最晚发货时间，ISO 8601 UTC；不适用、尚未计算或订单已无需发货时为 null
created_atstring订单创建时间，ISO 8601 UTC
updated_atstring订单最近更新时间，ISO 8601 UTC

OrderDetail ​

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

字段类型说明
ruten_order_statusstring | null最近观察到的露天订单状态
ruten_pay_statusstring | null最近观察到的露天付款状态
ruten_shipping_statusstring | null最近观察到的露天出货状态
ruten_respond_statusstring | null最近观察到的露天取消回复状态
buyer_phonestring | null买家联系电话
buyer_emailstring | null买家电子邮件
recipient_phonestring | null收件人联系电话
shipping_addressShippingAddress结构化收件及清关资料
itemsOrderItem[]订单商品明细
product_amountstring | null商品金额，currency 主单位 decimal string，固定 2 位小数
shipping_amountstring | null运费，currency 主单位 decimal string，固定 2 位小数
fulfillmentFulfillment | null当前有效履约完整资料
paid_atstring | null付款时间，ISO 8601 UTC
cancelled_atstring | null取消完成时间，ISO 8601 UTC
completed_atstring | null订单完成时间，ISO 8601 UTC

ShippingAddress ​

字段类型说明
namestring | null收件人姓名
phonestring | null收件人联系电话
postal_codestring | null邮政编码
citystring | null城市或县市
districtstring | null行政区
address_1string | null主要地址
address_2string | null补充地址
country_codestring | nullISO 3166-1 alpha-2 国家或地区代码
identity_namestring | null清关实名姓名；无资料时为 null
identity_number_maskedstring | null脱敏后的清关证件号码；不返回完整证件号

OrderItem ​

字段类型说明
idstring(uuid)订单商品明细 ID
ruten_item_idstring露天商品 ID
product_idstring(uuid) | null匹配到的 Sugumart 商品 ID
sku_idstring(uuid) | null匹配到的 Sugumart SKU ID
skustring | nullSKU 编号快照
spec_namestring | null规格名称快照
item_namestring商品名称快照
image_urlstring | null商品主图 URL
quantitynumber购买数量，正整数
currencystringISO 4217 币种代码
unit_pricestring | null单价，currency 主单位 decimal string，固定 2 位小数
product_amountstring | null商品小计，currency 主单位 decimal string，固定 2 位小数

Cancellation ​

字段类型说明
requested_bystringbuyer、seller 或 system
statusstringpending、pending_confirmation、confirmed、rejected、cancelled 或 failed
reason_codestring | null取消原因代码
reasonstring | null取消原因补充说明
requested_atstring取消申请时间，ISO 8601 UTC
decided_atstring | null确认、拒绝或系统完成处理的时间，ISO 8601 UTC
status_atstring当前取消状态生效时间，ISO 8601 UTC；未作出决定时等于 requested_at，已确认、拒绝、取消或失败时等于 decided_at

FulfillmentSummary ​

字段类型说明
idstring(uuid)履约 ID
fulfillment_nostringSugumart 集货单号
statusstring履约状态，见V1 状态附录
tracking_numberstring大陆快递单号
carrier_codestring大陆快递公司代码
warehouse_codestring建立履约时使用的大陆集运仓 code
created_atstring履约创建时间，ISO 8601 UTC
updated_atstring履约最近更新时间，ISO 8601 UTC

Fulfillment ​

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

字段类型说明
external_order_codestring | null物流商集货单号；尚未取得时为 null
deliverer_codestring | null从露天订单取得的台湾末端承运商代码
drop_order_statusstring大陆快递状态，见V1 状态附录
warehouse_received_atstring | null集运仓签收入库时间，ISO 8601 UTC
shipped_atstring | null集运仓出库时间，ISO 8601 UTC
delivered_atstring | null买家末端签收时间，ISO 8601 UTC
completed_atstring | null履约完成时间，ISO 8601 UTC

Warehouse ​

字段类型说明
codestring仓库 code，设置物流仓时使用
namestring仓库名称
rolestring[]支持用途：consolidation、return
logistics_company_codestring物流公司代码
logistics_company_namestring物流公司名称
addressWarehouseAddress仓库地址

WarehouseAddress ​

字段类型说明
contact_namestring | null联系人
phonestring | null联系电话
provincestring | null省份或地区
citystring | null城市
districtstring | null行政区
address_1string详细地址
postal_codestring | null邮政编码
country_codestringISO 3166-1 alpha-2 国家或地区代码

WarehouseSelection ​

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

SelectedWarehouse ​

字段类型说明
codestring已保存的仓库 code
namestring | null当前仓库名称；仓库不可用时仍保留 code，名称可能为 null
validboolean当前是否仍可用于对应业务
invalid_reasonstring | null无效原因代码；有效时为 null

通用错误格式 ​

错误响应遵循 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 位小数。
  • 所有时间均为 ISO 8601 UTC；调用方可转换为店铺时区展示，但不得改变原始时间含义。
  • 集运仓入库、集运仓出库和买家签收是不同物流节点，不得互相替代。
  • 写请求超时后先查询订单详情，再决定是否重试。