订单 API 参考

概述

本页列出订单模块的状态、端点、参数与错误码。完整流程请见淘宝/1688 下单与支付指南。如何通过 webhook 接收订单更新，另有独立参考页。

适用范围： 已支持多个市场。支付统一以 越南盾、美元或人民币（CNY） 计价——采购钱包以这三种货币之一充值；API 中的余额与订单金额均归一化为统一单位（*_cny）。

Elim 是负责订单执行与支付的技术平台——不做零售，也不直接面向终端客户。你的系统通过采购钱包向 Elim 付款，Elim 再向平台上的卖家付款。因此每笔订单都有两个相互独立的状态——平台状态（status）和与 Elim 的支付状态（payment_status）——外加一个平台侧支付结果指示（platform_payment_status）。

所有端点均需 JWT 认证（Authorization: Bearer <token>）或 API Key（x-api-key）。见API 请求认证。

平台状态（status）

订单在淘宝 / 1688 侧的处理进度。

creating → pending_payment → paid → shipped → completed
                                            ↘ cancelled

Elim 支付状态（payment_status）

用户与 Elim 之间的支付进度。与 status 相互独立。

unpaid → requested → approved → paid → refunded
   ↑         ↓
   └──── rejected

在 requested 状态下，用户可自行撤回申请回到 unpaid（见 cancel-payment-request）。进入 approved 后，只能通过退款回退。

平台支付结果（platform_payment_status）

仅在 Elim 向平台发起支付后才有取值。

界面中请同时显示 status 与 payment_status。platform_payment_status 主要用于出现问题时的诊断。

订单端点

前缀 /v1/orders。限流按秒级时间窗口计。

预览与创建订单——请求体

{
  "platform": "alibaba",
  "receiver_address": {
    "name": "Nguyen Van A",
    "phone": "02812345678",
    "mobile": "13800138000",
    "address": "广州市天河区体育西路123号",
    "province": "广东省",
    "city": "广州市",
    "area": "天河区",
    "town": "天河南街道"
  },
  "line_items": [
    { "product_ref": "734467086498", "sku_ref": "5578084256927", "quantity": 2, "price": 15.5 }
  ],
  "preview_token": "c5f75ec1-9f8d-4bf6-9de2-048d50fef349",
  "idempotency_key": "checkout-2026-08-25-001",
  "remark": "给卖家的备注",
  "promotion_id": "PROMO123"
}

line_items[]

每个元素以 product_ref + sku_ref 组合标识商品，直接取自商品搜索 / 详情。

mp_id + mp_skuid（marketplace ID）组合仍向后兼容接受。

receiver_address

预览响应

{
  "success": true,
  "preview_token": "c5f75ec1-9f8d-4bf6-9de2-048d50fef349",
  "currency": "CNY",
  "total_product_amount": 31.0,
  "total_post_fee": 8.0,
  "total_amount": 39.0,
  "shops": [
    {
      "seller_id": "b2b-2201234567",
      "seller_name": "广州某某贸易有限公司",
      "post_fee": 8.0,
      "shop_amount": 31.0,
      "items": [
        { "product_id": "734467086498", "sku_id": "5578084256927", "quantity": 2, "unit_price": 15.5, "total_price": 31.0 }
      ]
    }
  ],
  "unavailable_items": []
}

创建订单响应

{
  "status": "pending_payment",
  "data": {
    "id": "ORD0000000123",
    "order_list": [
      {
        "success": true,
        "amount": 39.0,
        "post_fee": 8.0,
        "lines": [
          { "sub_id": "E2101234567890", "product_id": "734467086498", "sku_id": "5578084256927", "quantity": 2, "amount": 31.0 }
        ]
      }
    ]
  }
}

新订单始终处于 payment_status = unpaid。

订单列表——筛选参数

GET /v1/orders

响应： { total, page, size, items: OrderListItem[] }。

{
  "total": 1, "page": 1, "size": 20,
  "items": [
    {
      "id": "ORD0000000123",
      "platform": "alibaba",
      "status": "paid",
      "payment_status": "paid",
      "total_amount_cny": 39.0,
      "total_amount": 39.0,
      "products": [
        { "id": "734467086498", "name": "某某商品", "price": 15.5, "quantity": 2, "img_urls": ["https://..."] }
      ],
      "created_at": "2026-04-09T10:30:00.000Z"
    }
  ]
}

列表中的 line_items / products 是下单时的快照。需要最新数据请调用 GET /v1/orders/:id。

订单详情——各平台差异

GET /v1/orders/:id——响应前会自动从平台同步状态。

platform 字段在列表响应中即有——保存下来，在调用详情前用于选择展示方式。

package_id 是整数，取自淘宝订单详情响应，而非 ORD... ID。

取消订单——条件

POST /v1/orders/:id/cancel——仅当 status 为 creating 或 pending_payment 时。

若订单尚无平台订单号：{ "success": true, "message": "Internal order cancelled, no external order to cancel" }。

采购钱包端点

前缀 /v1/purchasing。

GET /v1/purchasing/wallet

{
  "balance": 1670.30,
  "frozen_balance": 286.50,
  "available_balance": 1383.80,
  "total_deposited": 5000.00,
  "total_spent": 3329.70,
  "updated_at": "2026-06-19T00:00:00.000Z"
}

GET /v1/purchasing/wallet/transactions

参数：page、size、type、date_from、date_to。响应：{ total, page, size, items }。

GET /v1/purchasing/exchange-rates

按货币对（VND→CNY、USD→CNY）返回的生效汇率数组：source_currency、target_currency、rate（市场汇率）、markup_percent、effective_rate（Elim 加价后实际适用的汇率）。

订单支付端点

前缀 /v1/purchasing/orders/:id。:id 取 ORD... 形式。

POST …/request-payment

{
  "success": true,
  "order_id": "ORD0000000123",
  "frozen_amount": 286.50,
  "goods_amount_cny": 281.50,
  "shipping_fee_cny": 0,
  "service_fee_cny": 5.00
}

钱包余额不足错误——400：

{
  "error": "insufficient_balance",
  "current_balance": 120.00,
  "available_balance": 90.00,
  "required": 286.50,
  "deficit": 196.50
}

POST …/confirm

{
  "order_id": "ORD0000000123",
  "goods_amount_cny": 281.50,
  "shipping_fee_cny": 0,
  "service_fee_cny": 5.00,
  "total_amount_cny": 286.50,
  "payment_status": "paid",
  "wallet_balance_after": 1383.80
}

用 wallet_balance_after 更新显示余额，无需再次调用 GET /v1/purchasing/wallet。

由 Elim 执行的状态流转

用户不会调用这些操作。列出它们是为了说明 payment_status 将如何变化，以及你何时会收到 payment.updated。

通过 webhook 接收订单更新

注册 webhook，使订单的 status 或 payment_status 每次变化时 Elim 都会回调你的系统——免去持续轮询状态。与订单模块相关的两个事件：

Payload 携带一份订单快照：data.order.id、status、payment_status、platform_payment_status、total_amount_cny、updated_at。处理完成后返回 HTTP 2xx。

注册端点、完整 payload 结构、请求头、HMAC 签名校验以及重试策略：见 Webhook 参考。

错误码

错误响应遵循 { statusCode, message, error } 结构。message 有时为越南语，可直接展示。

ID 约定

• 内部订单 ID： ORD + 10 位数字，例如 ORD0000000123。用于所有端点。
• 平台订单号（order_id）： 由淘宝/1688 签发，仅在订单创建成功后才有。
• package_id： 整数，用于淘宝物流追踪。

相关链接

• 淘宝/1688 下单与支付指南 —— 分步流程
• Webhook 参考 —— 接收 order.updated / payment.updated 更新
• API 请求认证
• 完整 API 参考