订单查询 API - Shulex Intelli Custom Ticket Open API

Shulex VOC 通过调用你提供的 HTTP 接口同步订单数据。你需要按本文档规范实现订单查询接口，部署后将接口地址与鉴权 Token 配置到 Shulex 平台。

接口规范

请求方法：POST
路径：{baseUrl}/orders
Content-Type：application/json
鉴权：每次请求 Header 携带 Authorization: Bearer {Token}（Token 由 Shulex 生成并提供）

请求参数（Request Body JSON）

字段	类型	必填	说明
`page`	Integer	是	页码，从 1 开始
`pageSize`	Integer	是	每页条数，建议支持最大 200
`createTimeStart`	String	否	创建时间起点，ISO 8601，如 `2024-01-01T00:00:00Z`
`createTimeEnd`	String	否	创建时间终点，ISO 8601
`lastUpdateTimeStart`	String	否	最后更新时间起点，ISO 8601
`lastUpdateTimeEnd`	String	否	最后更新时间终点，ISO 8601
`orderNumber`	String	否	指定单号查询，传入后只返回该订单

查询场景

场景	传参方式
增量同步（按更新时间）	`lastUpdateTimeStart` + `lastUpdateTimeEnd` + 分页
历史全量（按创建时间）	`createTimeStart` + `createTimeEnd` + 分页
单笔订单查询	`orderNumber`
全量无过滤	仅 `page` + `pageSize`

响应格式

外层包装结构

字段	类型	必填	说明
`data`	Array<Order>	是	当前页订单列表
`page`	Integer	是	当前页码
`pageSize`	Integer	是	每页条数
`hasNextPage`	Boolean	是	是否还有下一页，`false` 时停止翻页

Order Object（订单对象）

字段	类型	必填	说明
`orderNumber`	String	是	订单唯一标识，用作幂等键
`externalOrderId`	String	否	外部系统订单 ID
`buyerName`	String	否	买家姓名
`buyerEmail`	String	否	买家邮箱
`purchaseTime`	String	否	下单时间，ISO 8601
`status`	String	否	订单状态，如 `PENDING`、`SHIPPED`、`DELIVERED`、`CANCELLED`
`totalAmount`	Number	否	订单总金额
`currency`	String	否	币种，如 `USD`、`CNY`
`shippingAddress`	String	否	收货地址
`trackingNumber`	String	否	物流单号
`orderLines`	Array<OrderLine>	否	订单行列表

Order Line（订单行对象）

字段	类型	必填	说明
`itemId`	String	是	行项目唯一 ID，用于与物流发货行关联
`sellerSku`	String	是	卖家 SKU
`productName`	String	是	商品名称
`title`	String	是	商品标题（展示用）
`imageUrl`	String	是	商品图片 URL
`quantity`	Integer	是	购买数量
`unitPrice`	Number	否	单价
`currency`	String	否	行级币种
`asin`	String	否	平台商品编码（如 Amazon ASIN）
`productId`	String	否	内部商品 ID

完整响应示例

{
  "page": 1,
  "pageSize": 10,
  "hasNextPage": true,
  "data": [
    {
      "orderNumber": "ORD-100001",
      "externalOrderId": "EXT-98765",
      "buyerName": "John Doe",
      "buyerEmail": "john.doe@example.com",
      "purchaseTime": "2024-01-15T08:30:00Z",
      "status": "SHIPPED",
      "totalAmount": 299.99,
      "currency": "USD",
      "shippingAddress": "123 Main St, New York, NY 10001, USA",
      "trackingNumber": "1Z999AA10123456784",
      "orderLines": [
        {
          "itemId": "ITEM-001",
          "sellerSku": "SKU-WIDGET-BLUE-L",
          "productName": "Blue Widget Large",
          "title": "Premium Blue Widget - Large Size",
          "imageUrl": "https://cdn.example.com/products/blue-widget-l.jpg",
          "quantity": 2,
          "unitPrice": 99.99,
          "currency": "USD"
        }
      ]
    }
  ]
}

请求示例

curl -X POST https://your-api.example.com/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -d '{
    "page": 1,
    "pageSize": 50,
    "createTimeStart": "2024-01-01T00:00:00Z",
    "createTimeEnd": "2024-01-31T23:59:59Z"
  }'

接入步骤

实现接口

按本文档规范实现 POST {baseUrl}/orders 接口。

部署上线

部署到公网可访问地址。

在 Shulex 配置

填入连接信息

填入 Base URL 与 生成的 Token。

测试连接

点击 Test Connection 验证连通性与字段规范。

启用同步

连接成功后配置自动同步任务。

注意事项

hasNextPage 必须正确实现，Shulex 依赖此字段判断是否继续翻页。
orderNumber 作为幂等键，相同订单号重复同步不产生重复数据。
时间字段统一使用 UTC + ISO 8601 格式（yyyy-MM-ddTHH:mm:ssZ）。
建议单页响应时间 < 5s，每页数据量不超过 200 条。

Documentation Index

​接口规范

​请求参数（Request Body JSON）

​查询场景

​响应格式

​外层包装结构

​Order Object（订单对象）

​Order Line（订单行对象）

​完整响应示例

​请求示例

​接入步骤

​注意事项