订单 API 指南

该功能目前仅支持越南市场。我们将在未来陆续支持其他市场，请关注最新动态。

订单 API 允许您在淘宝和 1688（阿里巴巴）上创建和管理代购订单。每个订单维护两个独立状态：由淘宝/1688 返回的平台状态（status）和由采购钱包系统管理的 Elim 付款状态（payment_status）。

所有端点需要通过 Authorization: Bearer <token> 请求头或 API Key（X-API-KEY）进行 JWT 认证。

认证指南：Authentication

订单状态

在使用 API 之前，请了解订单的两个状态维度，以避免在向终端用户显示时产生混淆。

平台状态（`status`）

反映订单在淘宝或 1688 上的处理进度。

值	描述	平台
`creating`	订单刚创建，等待平台确认	✅ 淘宝 ✅ 1688
`pending_payment`	平台已创建订单，等待付款	✅ 淘宝 ✅ 1688
`paid`	订单已在平台付款	✅ 淘宝 ✅ 1688
`shipped`	商品已从仓库发出，正在运输	✅ 淘宝 ✅ 1688
`completed`	订单完成，买家已确认收货	✅ 淘宝 ✅ 1688
`cancelled`	订单已取消	✅ 淘宝 ✅ 1688
`unknown`	无法解析平台返回的状态	✅ 淘宝 ✅ 1688

Elim 付款状态（`payment_status`）

反映订单是否已向 Elim 付款。该状态与 status 相互独立 — 一个订单可能处于 status=shipped，但如果出现问题，仍可能是 payment_status=unpaid。

值	描述
`unpaid`	未付款 — 创建订单时的默认状态
`paid`	采购钱包已成功扣款
`refunded`	订单取消后已退款至钱包

请在界面中始终显示 `status` 和 `payment_status` 两个字段。不要将它们合并为单一状态 — 用户需要同时了解订单进度和付款状态。

预览订单

查看详情：预览订单

在创建真实订单之前，调用预览端点以获取预估总金额并检查商品可用性。此步骤不会创建订单，也不会扣款 — 仅返回信息供用户在结账前确认。

频率限制： 20 次 / 60 秒

POST /v1/orders/preview

请求体：

{
  "platform": "alibaba",
  "receiver_address": {
    "name": "阮文A",
    "phone": "02812345678",
    "mobile": "13800138000",
    "address": "广州市天河区体育西路123号",
    "province": "广东省",
    "city": "广州市",
    "area": "天河区"
  },
  "line_items": [
    {
      "mp_id": "734467086498",
      "id": "5578084256927",
      "quantity": 2,
      "price": 15.5
    }
  ]
}

收货地址信息必须是中国境内的有效地址。

`line_items` 字段说明

字段	类型	必填	描述
`mp_id`	string	是	商品 ID — `mp_id`（淘宝）/ `offerId`（1688）
`id`	string	是	SKU ID — `mp_skuid`（淘宝）/ `spec_id`（1688）
`quantity`	number	是	购买数量
`price`	number	否	单价（CNY）— 需要精确预览时必填

处理 `unavailable_items`

响应返回 unavailable_items 数组，包含无法下单的商品（缺货、SKU 错误、已下架）。如果该数组不为空，则不允许创建订单 — 请先让用户处理有问题的商品。

{
  "unavailable_items": [{ "mp_id": "123456", "id": "sku_789", "reason": "out_of_stock" }]
}

可选参数

参数	描述	平台
`remark`	订单附加备注	✅ 淘宝 ✅ 1688
`promotion_id`	促销活动 ID	✅ 淘宝 ✅ 1688

创建订单

查看详情：创建订单

在平台上创建真实订单。请求体与预览相同 — 建议使用预览步骤中已验证的数据来创建订单，以避免偏差。

频率限制： 10 次 / 60 秒

POST /v1/orders

创建成功后，将用户重定向到订单详情页（/orders/ORD...）。不要让用户停留在购物车页面，因为订单已提交至平台。

响应处理

字段	描述
`data.id`	内部 ID，格式为 `ORD0000000001` — 用于所有后续操作
`status`	成功时为 `pending_payment`；出错时为 `unknown`
`data.order_list[]`	来自平台的店铺 + 商品详情 — 用于显示收据

如果响应返回 `status: "unknown"`，请向用户显示警告："订单可能未创建成功 — 请联系客服。" 在这种情况下，不要继续付款流程。

ID 规范： Elim ID 始终采用 ORD + 10 位数字格式（例如：ORD0000000123）。成功创建的订单还会有平台的 order_id。

订单列表

查看详情：订单列表

返回当前用户（通过 JWT 识别）的订单列表。结果支持分页。

频率限制： 30 次 / 60 秒

GET /v1/orders

筛选参数

参数	类型	描述
`page`	number	当前页码 — 默认为 1
`size`	number	每页条数 — 默认为 20
`platform`	string	`taobao` 或 `alibaba` — 不填则返回全部
`status`	OrderStatus	按平台状态筛选
`created_from`	ISO date	起始日期
`created_to`	ISO date	结束日期

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

列表中的 `line_items` 字段是订单创建时的快照。如需获取最新准确的订单信息，请调用 `GET /v1/orders/:id`。

订单详情

查看详情：订单详情

返回订单的完整且最新的信息。

频率限制： 30 次 / 60 秒

GET /v1/orders/:id

传入 ORD... 格式的 ID。

淘宝和 1688 响应格式差异

两个平台返回不同的数据结构 — 需要分别处理：

平台	商品	物流
1688	`products[]`	`logistics.logistics_info[]` — 已内嵌于响应中
淘宝	`line_items[]`	需单独调用 `GET /v1/orders/:packageId/logistic-detail`

platform 字段在列表响应中已提供 — 从列表视图缓存此字段，以便在调用详情前确定渲染哪个组件。

取消订单

查看详情：取消订单

取消处于可取消状态的订单。系统成功取消后，请再次调用 GET /v1/orders/:id 获取最新状态。

频率限制： 10 次 / 60 秒

POST /v1/orders/:id/cancel

条件： 仅当 status 为 creating 或 pending_payment 时才可取消。在其他状态下请禁用取消按钮。

如果订单尚未获得平台订单 ID（平台尚未处理），系统将返回 `{ success: true, message: 'Internal order cancelled, no external order to cancel' }` — 订单已在 Elim API 中取消，但淘宝/1688 上未执行任何操作。

物流追踪

查看详情：物流详情

返回中国境内运输追踪信息。仅适用于淘宝 — 1688 订单的物流信息已通过 logistics.logistics_info[] 内嵌于订单详情响应中。

频率限制： 20 次 / 60 秒

GET /v1/orders/:packageId/logistic-detail

packageId 是整数，从淘宝订单详情响应中获取 — 不是 ORD... 格式的 ID。

订单付款

Elim 充当代购代理：用户通过采购钱包（以 CNY 计价）向 Elim 付款，Elim 在系统外向平台付款。完整流程：

预览 → 创建订单（payment_status=unpaid）→ 确认钱包付款 → payment_status=paid

查看钱包余额

GET /v1/purchasing/wallet

响应： { balance, frozen_balance, available } — available = balance - frozen_balance。

确认付款

POST /v1/purchasing/orders/:id/confirm

系统检查钱包 → 扣款 → 更新 payment_status = paid。

成功响应（200）：

{
  "order_id": "ORD0000000001",
  "goods_amount_cny": 299.0,
  "shipping_fee_cny": 15.0,
  "service_fee_cny": 15.7,
  "total_amount_cny": 329.7,
  "paid_at": "2026-04-13T10:00:00.000Z",
  "balance_after": 1670.3
}

使用 balance_after 更新本地状态中的钱包余额，无需再次调用 GET /v1/purchasing/wallet。

处理余额不足

当钱包余额不足时，系统返回 400，响应体为：

{
  "error": "insufficient_balance",
  "deficit": 50.3,
  "current_balance": 279.4,
  "required": 329.7
}

显示弹窗告知用户需要充值多少 CNY，并引导用户进行充值。充值流程在系统外进行（银行转账）— 管理员确认后手动充值。

服务费

服务费计算公式：max(订单总额 × 费率百分比, 最低费用)。百分比和最低费用由管理员配置。

钱包交易记录

GET /v1/purchasing/wallet/transactions

参数	描述
`page`	页码
`size`	每页条数
`type`	`deposit` / `order_deduction` / `order_refund` / `admin_adjustment`
`date_from`	起始日期（ISO date）
`date_to`	结束日期（ISO date）

汇率

GET /v1/purchasing/exchange-rates

返回 Elim 配置的当前汇率：VND → CNY 和 USD → CNY。在用户充值前向其显示该汇率。

错误处理

HTTP	情况	您的处理方式
`400`	`insufficient_balance`	通知用户钱包余额不足
`400`	平台 ID 格式错误	显示验证错误消息
`401`	JWT 已过期	通知会话过期，提示用户重新登录
`404`	订单不存在	显示订单未找到状态
`429`	频率限制	通知频率限制错误，请用户稍后重试
`502`	淘宝/1688 平台无响应	显示错误消息，请用户重试

所有错误响应遵循 { statusCode, message, error } 格式。消息有时为越南语 — 可以直接向用户显示。