> ## Documentation Index
> Fetch the complete documentation index at: https://beaver.voc.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 订单查询 API

> Shulex VOC → 你的系统：拉取订单数据的接口规范

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               |

## 完整响应示例

```json theme={null}
{
  "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"
        }
      ]
    }
  ]
}
```

## 请求示例

```bash theme={null}
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"
  }'
```

## 接入步骤

<Steps>
  <Step title="实现接口">
    按本文档规范实现 `POST {baseUrl}/orders` 接口。
  </Step>

  <Step title="部署上线">
    部署到公网可访问地址。
  </Step>

  <Step title="在 Shulex 配置">
    登录 Shulex VOC → 集成 → **Custom Order Data** → 点击 **Connect**。
  </Step>

  <Step title="填入连接信息">
    填入 **Base URL** 与 **生成的 Token**。
  </Step>

  <Step title="测试连接">
    点击 **Test Connection** 验证连通性与字段规范。
  </Step>

  <Step title="启用同步">
    连接成功后配置自动同步任务。
  </Step>
</Steps>

## 注意事项

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