订单接口

POST /orders

创建采购单。系统从 API 用户钱包自动扣款，支付与履约异步执行。

请求体

字段	类型	必填	说明
sku_id	number	是	商品接口返回的 skus[].id
quantity	number	是	数量，至少为 1
manual_form_data	object	人工商品必填	人工交付表单数据

自动交付商品的推荐请求只包含 sku_id 和 quantity。Python、Go 示例对外接收 sku_code + quantity，并在内部自动将 sku_code 转换为 sku_id。

{
  "sku_id": 11,
  "quantity": 1
}

成功响应

{
  "ok": true,
  "order_id": 101,
  "order_no": "DJ20260301120000ABCD",
  "status": "paid",
  "amount": "9.90",
  "currency": "CNY"
}

创建错误

错误码	HTTP	说明
bad_request	400	参数无效
invalid_callback_url	400	回调 URL 非法
sku_unavailable	400	SKU 不存在或已禁用
product_unavailable	400	商品不可用
insufficient_balance	402	钱包余额不足
insufficient_stock	409	库存不足
payment_failed	200	支付失败，响应 ok: false

GET /orders/:id

查询订单状态和交付数据。

{
  "ok": true,
  "order_id": 101,
  "order_no": "DJ20260301120000ABCD",
  "status": "completed",
  "amount": "9.90",
  "currency": "CNY",
  "items": [
    {
      "product_id": 1,
      "sku_id": 11,
      "title": { "zh-CN": "示例商品" },
      "quantity": 1,
      "unit_price": "9.90",
      "total_price": "9.90",
      "fulfillment_type": "auto"
    }
  ],
  "fulfillment": {
    "type": "auto",
    "status": "delivered",
    "payload": "account-1\naccount-2",
    "delivery_data": null,
    "delivered_at": "2026-03-01T12:01:00Z"
  }
}

Fulfillment 字段

字段	类型	说明
type	string	auto 或 manual
status	string	交付状态，完成时为 delivered
payload	string	实际购买数据，以 \n 分隔；一行一条数据
delivery_data	object	结构化交付数据，可能为 null
delivered_at	string	ISO 8601 交付时间

fulfillment.payload 就是购买得到的数据。多件商品使用 \n 分隔，每一行是一条购买数据：

data-1\ndata-2\ndata-3

解析 JSON 后应按换行拆成 data-1、data-2、data-3 三条。下载的 test.py 同时识别真实换行、文本形式的 \n 和 \r\n，过滤空行后写入 TXT，每行一条。

POST /orders/:id/cancel

取消仍允许取消的订单。请求体为空。

{
  "ok": true,
  "order_id": 101,
  "order_no": "DJ20260301120000ABCD",
  "status": "canceled"
}

错误码	HTTP	说明
order_not_found	404	订单不存在
cancel_not_allowed	409	当前状态不可取消

取消顺序

本地取消或退款前必须先请求上游取消。如果上游返回 cancel_not_allowed，本地也必须拒绝取消，避免已经交付后仍退款。