POST /api/orders/import

概述

与后台 「导入订单」 Excel 功能使用同一套业务逻辑（App\Services\OrderImportService），通过 JSON 传入行数据，而非上传文件。适用于系统外部批量同步 Etsy 风格订单行（一行可对应一个订单项；同一 receipt_id 多行表示多商品）。

请求

项目	说明
URL	`https://tiancase.com/api/orders/import`（`APP_URL` 见 `.env`）
Method	`POST`
Content-Type	`application/json`
鉴权	请求头 `X-Api-Key`：在 ERP 后台「API Key」创建的密钥；未携带、无效或已吊销时返回 401。

Body 参数

字段	类型	必填	说明
`account_id`	integer	是	店铺账号 ID，须存在于 `accounts.id`
`rows`	array	是	至少 1 行；每行为 object 或「Excel 列数组」
`excel_format`	boolean	否	默认 `false`。为 `true` 时表示与 Etsy 导出表一致（含表头行）

`excel_format` = `false`（默认）

每行推荐使用 命名字段（见下表「列与 JSON 字段」），与后台 Excel 列含义一致。
若某行是 连续数字下标 0..n 的数组，则按 Etsy 导出列下标 解析（与 Excel 行相同）。
命名字段行必须包含 receipt_id。

`excel_format` = `true`

rows[0] 为表头行，第 3 列（下标 2）必须为 Buyer。
其余行为数据行，每行须为 0 起始下标的列数组，列顺序与 Etsy 导出一致。

命名字段与 Excel 列下标（节选）

列下标	JSON 字段名
1	`title`
3	`quantity`
4	`price`
13	`transaction_id`
14	`listing_id`
15	`sale_date`
16	`shipped_indicator`
17–22	`name`, `first_line`, `second_line`, `city`, `state`, `zip`
23	`country_name`（与 `countries.name` 匹配）
24	`receipt_id`
25	`variations`
28	`payment_method`
32	`sku`

sale_date 按 纽约时区 解析为 UTC 时间戳（与 Excel 导入一致）。

请求示例（命名字段）

{
  "account_id": 7,
  "rows": [
    {
      "receipt_id": "12345",
      "title": "Example",
      "quantity": 1,
      "price": 19.99,
      "transaction_id": "tx1",
      "listing_id": 123,
      "sale_date": "1/15/26",
      "country_name": "United States",
      "name": "Buyer",
      "first_line": "1 Main St",
      "city": "City",
      "state": "ST",
      "zip": "12345"
    }
  ]
}

响应

成功（200）

{
  "success": true,
  "message": "导入完成",
  "data": {
    "new_orders": 10,
    "updated_orders": 2,
    "order_items_inserted": 15
  }
}

校验失败（422）

参数校验失败或 excel_format 下列格式不符时返回 success: false 及说明。

服务器错误（500）

success: false，message 为「导入失败」，并可能包含 error 字段。

机器可读（MCP 风格）

工具名：post_api_orders_import
见 docs/api/mcp/tools.json 或 GET /docs/api/mcp-tools.json

变更记录

2026-04-04：与后台「导入订单」逻辑对齐，改为 JSON rows 入参；详见根级 CHANGELOG.md。