# 创建代发订单：一单一个 SKU；收件人（澳新地址要 state / city / postal_code）；shipping normal / express；auto_confirm=true 才提交配货（提交后不能改）

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

代发订单

## 请求体（JSON）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `warehouse_code` **必填** | string | 仓库编码：AU（澳洲（全部仓合计），合计视图）、AUSYD2（悉尼主仓（Rosehill））、AUSYD1（悉尼配件仓）、CN（中国（全部仓合计），合计视图）、CHNZJ1（中国镇江仓）。AU / CN 是公司级合计视图，其余是真实仓；完整清单看 GET /api/v1/warehouses。 |
| `sku` **必填** | string | SKU / 条码——**具体到颜色和尺码**的那一层，如 OB0021611。查整个款请改用 product_code。 (最长 64) |
| `quantity` **必填** | integer | 件数，正整数，如 2。锁单调整 / 购物车里传 0 表示去掉这一行。 (1–99999) |
| `recipient` **必填** | object | 收件人对象 { name, phone, address, country_code, state, city, postal_code }。country_code 用 AU / CN / NZ；寄澳洲、新西兰时 state / city / postal_code 必填。跨境件电话请带国际区号（如 +61…），地址请含门牌——地址不全是派送失败最常见的原因。 |
| `recipient.name` **必填** | string | 收件人姓名，写全名（快递面单上打印的就是它）。 (最长 128) |
| `recipient.phone` **必填** | string | 收件人电话。跨境件请带国际区号（如 +61…），否则清关和派送可能联系不上。 (最长 64) |
| `recipient.address` **必填** | string | 收件地址，请含门牌。地址不全是派送失败最常见的原因。 (最长 512) |
| `recipient.country_code` **必填** | string | 收件国家：AU 澳洲 / CN 中国 / NZ 新西兰（代发只支持这三国）。 |
| `recipient.state` | string | 州 / 省，如 NSW。寄澳洲、新西兰时必填。 (最长 64) |
| `recipient.city` | string | 城市，如 Sydney。寄澳洲、新西兰时必填。 (最长 128) |
| `recipient.postal_code` | string | 邮编，如 2000。寄澳洲、新西兰时必填。 (最长 16) |
| `sender` | object | 发件人对象 { name, phone }（选填），印在面单上的寄件人。 |
| `sender.name` | string | 收件人姓名，写全名（快递面单上打印的就是它）。 (最长 128) |
| `sender.phone` | string | 收件人电话。跨境件请带国际区号（如 +61…），否则清关和派送可能联系不上。 (最长 64) |
| `shipping_method` | string | 运输方式：normal 普通（默认）/ express 特快 / ems 邮政EMS。 |
| `auto_confirm` | boolean | 是否直接提交（选填）。**不传 = 只保存草稿**，需要人在 ERP 里确认后才生效——这是有意的默认。代发单提交后会立刻配货、无法再修改。 |
| `client_order_number` | string | 你自己系统里的订单号（下代发单时传的那个）。 (最长 64) |
| `note` | string | 备注（选填，最长 500 字）。 (最长 500) |

## 响应

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

```json
{
  "data": { … }
}
```

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

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

## 示例

### curl

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/dropship-orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{ "warehouse_code": "AU", "sku": "OB0021611", "quantity": 2, "recipient": { "name": "Jane Smith", "phone": "+61 400 000 000", "address": "1 Example St, Sydney NSW 2000", "country_code": "AU" } }'
```

### Python

```python
import requests

r = requests.post(
    "https://connect.everugg.net.au/api/v1/dropship-orders",
    headers={"Authorization": "Bearer " + TOKEN, "Idempotency-Key": str(uuid.uuid4())},
    json={
      "warehouse_code": "AU",
      "sku": "OB0021611",
      "quantity": 2,
      "recipient": {
        "name": "Jane Smith",
        "phone": "+61 400 000 000",
        "address": "1 Example St, Sydney NSW 2000",
        "country_code": "AU"
      }
    },
)
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/dropship-orders", {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    "warehouse_code": "AU",
    "sku": "OB0021611",
    "quantity": 2,
    "recipient": {
      "name": "Jane Smith",
      "phone": "+61 400 000 000",
      "address": "1 Example St, Sydney NSW 2000",
      "country_code": "AU"
    }
  }),
})
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/dropship-orders"))
    .header("Authorization", "Bearer " + token)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .POST(HttpRequest.BodyPublishers.ofString("{ \"warehouse_code\": \"AU\", \"sku\": \"OB0021611\", \"quantity\": 2, \"recipient\": { \"name\": \"Jane Smith\", \"phone\": \"+61 400 000 000\", \"address\": \"1 Example St, Sydney NSW 2000\", \"country_code\": \"AU\" } }"))
    .build();
HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
```

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