erpnew/docs/api_v2_ai_api.md

API v2 Agent 接口

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

鉴权方式

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

示例：

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

---

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

API v2 Agent 接口文档

本文档面向 AI Agent 及外部自动化调用方，描述 /api/v2/ai/ 前缀下的所有接口。

基本约定

• Base URL: /api/v2/ai
• 认证：所有接口使用固定 API Key，通过 Authorization 请求头直接传入，无 Bearer 前缀
• 多商户隔离：每个接口均需传入 merchant_id 查询参数，后端以此确定数据范围

认证方式

Authorization: <AGENT_ACCESS_KEY>

AGENT_ACCESS_KEY 由后端部署时通过同名环境变量配置。未配置时所有请求均返回 401。

---

数据结构

TransportVehicle

{
  "id": 1,
  "merchant_id": 10,
  "name": "大卡车",
  "license_plate": "粤A12345",
  "material_capacities": [
    {"id": 1, "material_name": "坯布", "capacity": 500},
    {"id": 2, "material_name": "成品", "capacity": 300}
  ],
  "created_at": "2026-04-01T08:00:00+08:00",
  "updated_at": "2026-04-01T08:00:00+08:00"
}

Shipment

{
  "id": 100,
  "merchant_id": 10,
  "customer": 5,
  "customer_name": "客户A",
  "fabric": "棉布 40S",
  "order_description": "滚筒预警",
  "shipment_date": "2026-04-14",
  "address": "广州市天河区",
  "contact_name": "张三",
  "contact_phone": "13800000000",
  "area": "华东",
  "remark": "备注",
  "status": "pending",
  "status_display": "待出货",
  "external_id": null,
  "geo_coordinates": {"lat": 23.1291, "lng": 113.2644},
  "delivery_id": null,
  "delivery": null,
  "sales_items": [
    {
      "id": 201,
      "name": "销售品甲",
      "quantity": "50.00",
      "unit": 1,
      "unit_display": "件",
      "position": "A-01",
      "remark": "",
      "printing_job_id": 88,
      "printing_job_width": "150cm"
    }
  ],
  "created_at": "2026-04-14T10:00:00+08:00",
  "updated_at": "2026-04-14T10:00:00+08:00"
}

MesDevice

{
  "id": 1,
  "merchant": 10,
  "category": {
    "id": 2,
    "merchant": 10,
    "name": "打印机",
    "created_at": "2026-05-01T08:00:00+08:00",
    "updated_at": "2026-05-01T08:00:00+08:00"
  },
  "name": "A-01",
  "peak_capacity": 120,
  "capacity_unit": 1,
  "capacity_unit_label": "米",
  "extra": {"capacity": {"per_hour": 120}},
  "created_at": "2026-05-01T08:00:00+08:00",
  "updated_at": "2026-05-01T08:00:00+08:00"
}

MesProductionAssignment

{
  "id": 100,
  "merchant": 10,
  "device": {
    "id": 1,
    "merchant": 10,
    "category": {
      "id": 2,
      "merchant": 10,
      "name": "打印机",
      "created_at": "2026-05-01T08:00:00+08:00",
      "updated_at": "2026-05-01T08:00:00+08:00"
    },
    "name": "A-01",
    "peak_capacity": 120,
    "capacity_unit": 1,
    "capacity_unit_label": "米",
    "extra": null,
    "created_at": "2026-05-01T08:00:00+08:00",
    "updated_at": "2026-05-01T08:00:00+08:00"
  },
  "content_type": 45,
  "object_id": 9001,
  "assigner": {"id": 20, "name": "张三", "merchant_id": 10},
  "assignee": {"id": 21, "name": "李四", "merchant_id": 10},
  "production_quantity": 300,
  "status": 2,
  "status_label": "已发布",
  "extra": {"batch": "A1"},
  "created_at": "2026-05-02T10:00:00+08:00",
  "updated_at": "2026-05-02T10:00:00+08:00"
}

---

运输车辆列表

• URL: /api/v2/ai/transport-vehicles/
• Method: GET

查询参数：

参数	类型	必填	说明
merchant_id	int	是	商户 ID
limit	int	否	分页每页数量
offset	int	否	分页偏移量

说明：

• material_capacities 表示该车辆对不同物料的最大装载量
• 只返回 merchant_id 对应商户的车辆

响应为分页结构，results 中每条为 TransportVehicle。

运输车辆详情

• URL: /api/v2/ai/transport-vehicles/<license_plate>/
• Method: GET

路径参数：

参数	说明
license_plate	车牌号码

查询参数：

参数	类型	必填	说明
merchant_id	int	是	商户 ID

说明：

• 同一商户内 license_plate 唯一
• 不同商户可能存在相同车牌号，merchant_id 是必须的
• 车辆不存在时返回 404

未出货出货单列表

• URL: /api/v2/ai/shipments/unshipped/
• Method: GET

查询参数：

参数	类型	必填	说明
merchant_id	int	是	商户 ID
area	string	是	地区筛选，精确匹配
limit	int	否	分页每页数量
offset	int	否	分页偏移量

说明：

• “未出货”定义：delivery 为空，即尚未关联送货单
• delivery_id 未关联时返回 null
• 结果按 created_at 降序排列
• 只返回 merchant_id 对应商户的数据

响应为分页结构，results 中每条为 Shipment。

MES 设备列表

• URL: /api/v2/ai/mes/devices/
• Method: GET

查询参数：

参数	类型	必填	说明
merchant_id	int	是	商户 ID
limit	int	否	分页每页数量
offset	int	否	分页偏移量

说明：

• 使用与其他 agent API 相同的 AGENT_ACCESS_KEY 鉴权，不走 JWT
• 返回当前商户下全部 MES 设备
• 每条设备记录都带完整的设备分类信息

响应为分页结构，results 中每条为 MesDevice。

MES 生产安排列表

• URL: /api/v2/ai/mes/production-assignments/
• Method: GET

查询参数：

参数	类型	必填	说明
merchant_id	int	是	商户 ID
start_date	date	是	开始日期，格式 YYYY-MM-DD
end_date	date	是	结束日期，格式 YYYY-MM-DD
device_id	int	否	设备 ID，可选筛选
status	int	否	生产安排状态，可选筛选
limit	int	否	分页每页数量
offset	int	否	分页偏移量

说明：

• 当前模型没有单独的“计划生产日期”字段
• 因此该接口当前按 created_at 所在日期做范围过滤
• 也就是“查询指定日期范围内创建的生产安排”
• device_id 和 status 都是可选筛选条件

状态值：

值	显示值
1	Draft
2	已发布
3	已接收
4	已取消
5	已完工

响应为分页结构，results 中每条为 MesProductionAssignment。