175 lines
3.3 KiB
Markdown
175 lines
3.3 KiB
Markdown
|
# 备货单公共 API 对接文档
|
|||
|
|
|
|||
|
|
## 基础信息
|
|||
|
|
|
|||
|
|
| 项 | 值 |
|
|||
|
|
|---|---|
|
|||
|
|
| Base URL | `https://your-domain.com` |
|
|||
|
|
| 鉴权方式 | 请求头 `Fdesk-Api-Key` |
|
|||
|
|
| 响应格式 | JSON |
|
|||
|
|
|
|||
|
|
## 鉴权
|
|||
|
|
|
|||
|
|
所有请求必须携带 API Key 请求头：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
Fdesk-Api-Key: <your-api-key>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
缺少或无效时返回：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"status": "fail",
|
|||
|
|
"code": 401,
|
|||
|
|
"message": "无效的 API Key",
|
|||
|
|
"data": []
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 通用响应结构
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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 号筛选，模糊匹配 |
|
|||
|
|
|
|||
|
|
**响应示例**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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 | 否 | 车架号筛选，模糊匹配 |
|
|||
|
|
|
|||
|
|
**响应示例**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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 | 车型名称 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 调用示例
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 查询 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"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
- 两个接口仅返回审批状态为"已通过"（approval_status=2）的备货单数据
|
|||
|
|
- 已删除的备货单不会出现在查询结果中
|
|||
|
|
- 接口为只读，不支持新增、修改、删除操作
|
|||
|
|
- `pi_no` 和 `vin` 筛选参数支持模糊匹配（包含即可）
|