如何在 Taobao/1688 上创建与管理订单

何时使用本指南

当您需要让用户通过 Elimapi 从 Taobao/1688 代购产品时使用——从预览订单、创建订单、跟踪订单到使用购物钱包支付。

注意： 此功能目前仅支持越南市场。其他市场将在后续补充。

完整参考（状态、端点、参数、错误码）：订单 API 参考

前提条件

• API 身份验证信息（JWT 或 API Key）— 参见身份验证 API 请求
• 产品 ID 和 SKU ID — 从产品搜索获取
• 有效的中国收货地址

整体流程

Preview → Tạo đơn (payment_status=unpaid) → Xác nhận thanh toán ví → payment_status=paid

每个订单都有两个独立的状态：status（平台）和 payment_status（Elim 钱包）。在界面中始终同时显示两者——不要合并成一个。

第 1 步 — 预览订单

调用预览以获取预估总金额并检查商品状况。此步骤不会创建订单，也不会扣款。

POST /v1/orders/preview

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

必须检查 unavailable_items： 如果该数组非空，则不允许创建订单——先让用户处理有问题的商品（缺货、SKU 错误、停售）。

收货地址必须是有效的中国地址。

第 2 步 — 创建订单

使用第 1 步预览中已校验的数据（body 完全相同）创建真实订单：

POST /v1/orders

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

响应处理：

[!WARNING] 如果响应返回 status: "unknown"，显示警告”订单可能尚未创建——请联系支持。“不要继续支付流程。

第 3 步 — 查询订单

订单列表（分页，通过 JWT 识别用户）：

GET /v1/orders?page=1&size=20&platform=taobao&status=paid

过滤参数：page、size、platform（taobao/alibaba）、status、created_from、created_to。

列表中的 line_items 是创建时的快照。如需最新数据，请调用订单详情。

订单详情：

GET /v1/orders/:id

注意两个平台之间的差异：

缓存列表响应中的 platform 字段，以便在调用详情前渲染正确的组件。

第 4 步 — 取消订单（如需要）

POST /v1/orders/:id/cancel

条件： 仅当 status 为 creating 或 pending_payment 时才能取消。其他状态下禁用取消按钮。取消后，再次调用 GET /v1/orders/:id 以获取最新状态。

如果订单尚未有平台订单 ID，系统返回 { success: true, message: 'Internal order cancelled, no external order to cancel' } — 订单已在 Elim 取消，但未在 Taobao/1688 上执行任何操作。

第 5 步 — 支付订单

Elim 充当代购代理：用户通过购物钱包（单位为 CNY）向 Elim 支付，Elim 再向平台支付。

1. 查看钱包余额： GET /v1/purchasing/wallet → { balance, frozen_balance, available }
2. 确认支付： POST /v1/purchasing/orders/:id/confirm → 系统检查钱包、扣除金额、更新 payment_status = paid。
3. 使用响应中的 balance_after 更新钱包余额，无需再次调用。
4. 如果钱包余额不足，系统返回 400 并附带 { error: "insufficient_balance", deficit, current_balance, required } — 显示模态框，告知缺少多少 CNY 并指导充值。

验证结果

• 预览返回的总金额与预期一致，且 unavailable_items 为空。
• 创建订单返回 data.id（格式 ORD...）且 status = pending_payment。
• 确认支付返回 payment_status = paid 并附带 balance_after。
• 订单详情正确显示 status 和 payment_status。

处理常见错误

相关链接

• 参考： 订单 API 参考 — 完整的状态、参数、错误码
• 身份验证： 身份验证 API 请求