# 创建批发订单（默认只建草稿，auto_confirm=true 才提交审核）

`POST /api/v1/orders` — 需要 token · order:write · 写操作 · 2 点

批发订单

创建批发订单（默认只建草稿，auto_confirm=true 才提交审核）。OMS 账号登录时要有物流信息：shipping 里给 shipping_method_id（见 /shipping-methods）＋ address_id（见 /addresses）；不传则用你 OMS 账号里的默认设置

## 请求体（JSON）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `warehouse_code` **必填** | string | 仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。 |
| `lines` **必填** | array<object> | 明细数组，每项 { sku, quantity }。至少一项；quantity=0 在调整锁单 / 购物车时表示去掉这一行。 (1–1000) |
| `lines[].sku` **必填** | string | SKU / 条码——**具体到颜色和尺码**的那一层，如 OB0021611。查整个款请改用 product_code。 (最长 64) |
| `lines[].quantity` **必填** | integer | 件数，正整数，如 2。锁单调整 / 购物车里传 0 表示去掉这一行。 (0–99999) |
| `note` | string | 备注（选填，最长 500 字）。 (最长 500) |
| `client_order_number` | string | 你自己系统里的订单号（下代发单时传的那个）。 (最长 64) |
| `auto_confirm` | boolean | 是否直接提交（选填）。**不传 = 只保存草稿**，需要人在 ERP 里确认后才生效——这是有意的默认。代发单提交后会立刻配货、无法再修改。 |
| `shipping` | object | 物流信息（用 OMS 账号登录下批发单时必需）。里面：shipping_method_id（发货方式，见 GET /api/v1/shipping-methods）、address_id（收货地址，见 GET /api/v1/addresses）、carrier_id（物流公司，选填）、pickup_at（自取时间，自取方式才填）。整个不传则用你 OMS 账号里的默认设置；默认也没设会报错并指路。 |
| `shipping.shipping_method_id` | string | 发货方式编号，从 GET /api/v1/shipping-methods 取。 (最长 64) |
| `shipping.carrier_id` | string | 物流公司编号（选填），从 GET /api/v1/carriers 取。 (最长 64) |
| `shipping.address_id` | string | 收货地址编号，从 GET /api/v1/addresses 取。地址簿在 OMS 网站「用户 → 偏好设置 → 批发收货地址」里维护。 (最长 64) |
| `shipping.pickup_at` | string | 自取时间（选填，自取方式才用），如 2026-09-10T14:00:00。 (最长 32) |

## 响应

响应信封只看 HTTP 状态码：成功是 2xx，正文 `{ data: … }`（列表另带 `page / page_size / has_more` 或 `total_count`）；失败是 4xx / 5xx，正文 `{ error: { code, message, hint, request_id, doc_url } }`。

响应头: `HTTP/1.1 201 Created`

```json
{
  "data": { "order_id": "SO2026090300123", "channel_code": "100780", "warehouse_code": "AU",
    "status": 0, "lines": [{ "sku": "OB0021611", "quantity": 2 }], "created_date": "2026-09-03" }
}
```

成功响应里没有任何给人看的文字——没有 `code / result / msg`。`error.code` 是唯一该用程序判断的字段，`message` 跟随 `Accept-Language`。

> 写操作请带 `Idempotency-Key` 头（任意唯一串，如 UUID）：网络重试不会重复下单。下单默认只建草稿，由人在 ERP 确认后生效。

## 示例

### curl

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{ "warehouse_code": "AU", "lines": [ { "sku": "OB0021611", "quantity": 2 } ] }'
```

### Python

```python
import requests

r = requests.post(
    "https://connect.everugg.net.au/api/v1/orders",
    headers={"Authorization": "Bearer " + TOKEN, "Idempotency-Key": str(uuid.uuid4())},
    json={
      "warehouse_code": "AU",
      "lines": [
        {
          "sku": "OB0021611",
          "quantity": 2
        }
      ]
    },
)
data = r.json()
r.raise_for_status()  # 4xx/5xx: data["error"]["code"] / ["hint"]
```

### Node

```js
const res = await fetch("https://connect.everugg.net.au/api/v1/orders", {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    "warehouse_code": "AU",
    "lines": [
      {
        "sku": "OB0021611",
        "quantity": 2
      }
    ]
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${data.error?.code}: ${data.error?.message}`)
```

### Java

```java
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.everugg.net.au/api/v1/orders"))
    .header("Authorization", "Bearer " + token)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .POST(HttpRequest.BodyPublishers.ofString("{ \"warehouse_code\": \"AU\", \"lines\": [ { \"sku\": \"OB0021611\", \"quantity\": 2 } ] }"))
    .build();
HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
```

---
Markdown 源: https://connect.everugg.net.au/reference/post-api-v1-orders.md?lang=zh · 网页版: https://connect.everugg.net.au/reference?op=post-api-v1-orders&lang=zh