# API v2 Agent 接口

本文档描述 `api/v2/ai/...` 下供内部 agent 调用的简化鉴权接口。

## 鉴权方式

- 使用请求头 `Authorization`
- 直接传入固定密钥
- 不使用 `Bearer` 前缀

示例：

```bash
curl -X GET \
  'https://api.example.com/api/v2/ai/shipments/unshipped/?merchant_id=1&area=华东' \
  -H 'Authorization: your-agent-access-key'
```

配置项：

- [`AGENT_ACCESS_KEY`](/home/f/coding/flower/flower/settings.py)

---

## 查询未进入送货单的出货单

- **URL**: `/api/v2/ai/shipments/unshipped/`
- **Method**: `GET`

### 查询参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `merchant_id` | int | 是 | 商户 ID |
| `area` | string | 是 | 地区，精确匹配 |
| `limit` | int | 否 | 分页大小 |
| `offset` | int | 否 | 分页偏移 |

### 业务定义

这里的“未出货”定义为：

- `Shipment.delivery_id is null`

也就是该出货单尚未进入送货单。

### 响应示例

```json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 101,
      "merchant_id": 1,
      "customer": 12,
      "customer_name": "客户A",
      "shipment_date": "2026-04-14",
      "address": "",
      "contact_name": "张三",
      "contact_phone": "13800000000",
      "area": "华东",
      "remark": "目标记录",
      "status": 1,
      "status_display": "草稿(未发布)",
      "external_id": null,
      "delivery": null,
      "created_at": "2026-04-14T10:00:00Z",
      "updated_at": "2026-04-14T10:00:00Z"
    }
  ]
}
```

### 错误响应

#### 401 Unauthorized

```json
{
  "detail": "AGENT_ACCESS_KEY 无效"
}
```

#### 400 Bad Request

```json
{
  "merchant_id": ["This field is required."]
}
```