fdesk/docs/public-stock-api.md

备货单公共 API 对接文档

基础信息

项	值
Base URL	https://your-domain.com
鉴权方式	请求头 Fdesk-Api-Key
响应格式	JSON

鉴权

所有请求必须携带 API Key 请求头：

Fdesk-Api-Key: <your-api-key>

缺少或无效时返回：

{
  "status": "fail",
  "code": 401,
  "message": "无效的 API Key",
  "data": []
}

通用响应结构

{
  "status": "success | fail",
  "code": 200,
  "message": "描述信息",
  "data": {}
}

code	含义
200	成功
400	查询失败
401	API Key 无效或缺失

---

接口列表

1. PI 号列表

查询已审批通过的备货单 PI 号，含关联的车架号和车型。

请求

GET /common/public/pi/list

参数

参数	类型	必填	说明
page	int	否	页码，默认 1
page_size	int	否	每页条数，默认 20，最大 200
pi_no	string	否	PI 号筛选，模糊匹配

响应示例

{
  "status": "success",
  "code": 200,
  "message": "请求成功",
  "data": {
    "total": 150,
    "per_page": 20,
    "current_page": 1,
    "data": [
      {
        "pi_no": "PI20250601001",
        "vins": ["LSVAU2A39N2123456", "LSVAU2A39N2123457"],
        "model_names": ["BYD Song Plus DM-i", "BYD Seal"]
      }
    ]
  }
}

字段说明

字段	类型	说明
pi_no	string	备货单 PI 号
vins	string[]	该 PI 下所有车架号
model_names	string[]	该 PI 下所有车型名称（与 vins 一一对应）

---

2. VIN 号列表

查询已审批通过的备货单车架号及对应车型。

请求

GET /common/public/vin/list

参数

参数	类型	必填	说明
page	int	否	页码，默认 1
page_size	int	否	每页条数，默认 20，最大 200
vin	string	否	车架号筛选，模糊匹配

响应示例

{
  "status": "success",
  "code": 200,
  "message": "请求成功",
  "data": {
    "total": 500,
    "per_page": 20,
    "current_page": 1,
    "data": [
      {
        "vin": "LSVAU2A39N2123456",
        "model_name": "BYD Song Plus DM-i"
      }
    ]
  }
}

字段说明

字段	类型	说明
vin	string	车架号
model_name	string	车型名称

---

3. 业务人员列表

查询业务人员（角色 role_id=2，在职），全量返回。

请求

GET /common/public/staff/list

参数

参数	类型	必填	说明
keyword	string	否	关键词，模糊匹配姓名/编号/电话/邮箱

响应示例

{
  "status": "success",
  "code": 200,
  "message": "请求成功",
  "data": [
    {
      "id": 17,
      "name": "张三",
      "sn": "S0017",
      "phone": "13800138000",
      "email": "zhangsan@example.com"
    }
  ]
}

字段说明

字段	类型	说明
id	int	用户ID
name	string	姓名
sn	string	编号
phone	string	电话
email	string	邮箱

---

调用示例

# 查询 PI 列表（第一页，每页10条）
curl -H "Fdesk-Api-Key: your-api-key" \
  "https://your-domain.com/common/public/pi/list?page=1&page_size=10"

# 按 PI 号搜索
curl -H "Fdesk-Api-Key: your-api-key" \
  "https://your-domain.com/common/public/pi/list?pi_no=PI202506"

# 查询 VIN 列表（第一页，每页50条）
curl -H "Fdesk-Api-Key: your-api-key" \
  "https://your-domain.com/common/public/vin/list?page=1&page_size=50"

# 按 VIN 号搜索
curl -H "Fdesk-Api-Key: your-api-key" \
  "https://your-domain.com/common/public/vin/list?vin=LSVAU2A3"

# 查询业务人员列表
curl -H "Fdesk-Api-Key: your-api-key" \
  "https://your-domain.com/common/public/staff/list?page=1&page_size=50"

注意事项

• 两个接口仅返回审批状态为"已通过"（approval_status=2）的备货单数据
• 已删除的备货单不会出现在查询结果中
• 接口为只读，不支持新增、修改、删除操作
• pi_no 和 vin 筛选参数支持模糊匹配（包含即可）