erpnew/docs/agent_api_settlement.md

Agent API: 开版订单统计

概述

此 API 供 AI Agent 查询开版订单统计数据，按客户分组显示今日和本月订单数量。

认证

使用 X-AGENT-SECRET 请求头进行认证，无需 JWT Token。

端点

GET /api/v1/settlement/plate-orders/summary/

请求头

Header	Value	Required
X-AGENT-SECRET	RCYH_BOT_0083	Yes

查询参数

Parameter	Type	Required	Description
date	string	Yes	统计日期，格式: YYYY-MM-DD

响应格式

{
  "data": [
    {
      "client_id": 1,
      "client_name": "客户名称",
      "plate_order_count": [
        {
          "type": "首版-匹布",
          "today": 5,
          "current_month": 120
        }
      ]
    }
  ]
}

字段说明

Field	Type	Description
client_id	integer	客户ID
client_name	string	客户名称
plate_order_count	array	订单统计数组
plate_order_count[].type	string	订单类型，格式: {版型}-{做货方式}
plate_order_count[].today	integer	今日订单数
plate_order_count[].current_month	integer	本月累计订单数（从月初到查询日期）

订单类型 (type) 可能值

• 首版-匹布: 首版订单，匹布方式
• 首版-做货: 首版订单，做货方式
• 复版-匹布: 复版订单，匹布方式
• 复版-做货: 复版订单，做货方式
• 修改单-匹布: 修改订单，匹布方式
• 修改单-做货: 修改订单，做货方式

错误响应

Status	Response
400	{"error": "缺少 date 参数"}
400	{"error": "日期格式错误，请使用 YYYY-MM-DD 格式"}
403	{"error": "日期不存在"}
401	{"detail": "身份认证信息未提供。"} (secret 错误)

cURL 调用示例

curl -X GET \
  -H "X-AGENT-SECRET: RCYH_BOT_0083" \
  "http://localhost:8100/api/v1/settlement/plate-orders/summary/?date=2026-02-24"

使用场景

1. 查询今日开版统计: 使用当天日期
2. 查询历史日期统计: 使用指定日期
3. 对比不同客户订单量: 遍历 data 数组

注意事项

• 返回数据仅包含有订单的客户（today 或 current_month > 0）
• current_month 统计范围：月初第一天到查询日期
• 此 API 仅限 Agent 调用，普通用户需使用 JWT 认证