dps_etag/files/电子标签标准化接口文档.md

# 电子标签标准化接口文档

> 版本号：R1.0
>
> 更新时间：2024年9月3日



## 版本控制

| 版本号 | 更新时间     | 更新人 | 更新内容 | 备注 |
| ------ | ------------ | ------ | -------- | ---- |
| R1.0   | 2024年9月3日 | 葛林强 | 初版     |      |







## 接口详情

### 统一返回

| 参数键     | 参数名称 | 数据类型 | 长度 | 是否允许空值 | 备注                           |
| ---------- | -------- | -------- | ---- | ------------ | ------------------------------ |
| code       | 响应代码 | int32    | 4    | 否           | 0 - 成功<br />非0 - 失败       |
| msg        | 响应信息 | string   | 128  | 否           |                                |
| returnData | 返回信息 | object   |      | 是           | 下述若存在返回信息均套用此键值 |





### 1、上位系统 向 DPS 发送亮灯任务

> 客户端：上位系统
>
> 服务端：DPS
>
> 请求方式：POST
>
> 数据类型：application/json
>
> 接口地址：http://{ip}:{port}/api/wms/dpsTask

**请求参数**

| 参数键    | 参数名称 | 数据类型 | 长度 | 是否允许空值 | 备注                               |
| --------- | -------- | -------- | ---- | ------------ | ---------------------------------- |
| taskGroup | 任务组   | string   | 64   | 否           | 每次发送的任务组不允许重复         |
| taskType  | 任务类型 | int32    | 4    | 否           | 1 - 拣选任务<br />2 - 存取任务     |
| vehicleNo | 载具号   | string   | 32   | 否           |                                    |
| areaId    | 区域标识 | string   | 40   | 否           | 同一个区域号只能存在一个波次的任务 |
| taskData  | 任务详情 | list     |      | 否           | 任务列表，单次请求最大支持50条     |
|           |          |          |      |              |                                    |
| taskId    | 任务标识 | string   | 64   | 否           | 表示唯一任务，不允许重复，主键     |
| location  | 点位     | string   | 32   | 否           | 需要点亮的点位                     |
| goodsId   | 物料编号 | string   | 64   | 是           |                                    |
| goodsName | 物料名称 | string   | 64   | 是           |                                    |
| showNum   | 数量     | int16    | 2    | 否           | 需要点亮的数量                     |

```json
{
    "taskGroup":"123123123123",
    "taskType":1,
    "vehicleNo":"BOX123",
    "areaId":"abc",
    "taskData":[
        {
            "taskId":"sdfsdfs123",
            "location":"1-1-1",
            "goodsId":"1001",
            "goodsName":"手榴弹",
            "showNum":100
        },
        {
            "taskId":"sdfsdfs123",
            "location":"1-1-1",
            "goodsId":"1002",
            "goodsName":"迫击炮弹",
            "showNum":500
        }
    ]
}
```

**响应参数**

```json
{
    "code":0,
    "msg":"操作成功"
}
```



### 2、DPS 向上位系统反馈任务状态

> 客户端：DPS
>
> 服务端：上位系统
>
> 请求方式：POST
>
> 数据类型：application/json
>
> 接口地址：http://{ip}:{port}/api/dps/uploadTaskStatus

<u>注意：在请求失败情况下（http响应码不为 2xx）DPS会重复发送 5 次，若请求成功（http请求码为 2xx）DPS 将不再发送，若 5 次均失败则DPS也不再发送</u>

**请求参数**

| 参数键     | 参数名称 | 数据类型 | 长度 | 是否允许空值 | 备注                      |
| ---------- | -------- | -------- | ---- | ------------ | ------------------------- |
| taskId     | 任务标识 | string   | 64   | 否           | 上位系统发送到DPS的任务号 |
| taskStatus | 任务状态 | int      | 4    | 否           | 100 - 任务完成            |
| confirmNum | 确认数量 | int      | 4    | 否           | 按下确认按钮时的数量      |

```json
{
    "taskId":"12312312312",
    "taskStatus":100,
    "confirmNum":60
}
```

**响应参数**

```json
{
    "code":0,
    "msg":"操作成功"
}
```



### 3、上位系统向DPS查询任务状态

> 客户端：上位系统
>
> 服务端：DPS
>
> 请求方式：GET
>
> 数据类型：application/json
>
> 接口地址：http://{ip}:{port}/api/wms/dpsTask/{taskId}

<u>注意：DPS 只保存最近 10 天的数据，超出时间范围内的任务标识将不会返回数据</u>

**请求参数**

| 参数键 | 参数名称 | 数据类型 | 长度 | 是否允许空值 | 备注                      |
| ------ | -------- | -------- | ---- | ------------ | ------------------------- |
| taskId | 任务标识 | string   | 64   | 否           | 上位系统发送到DPS的任务号 |

**响应参数**

| 参数键      | 参数名称 | 数据类型 | 长度 | 是否允许空值 | 备注                                                         |
| ----------- | -------- | -------- | ---- | ------------ | ------------------------------------------------------------ |
| taskId      | 任务标识 | string   | 64   | 否           | 上位系统发送到DPS的任务号                                    |
| taskStatus  | 任务状态 | int      | 4    | 否           | 0 - 待点亮<br />1 - 正在点亮<br />2 - 已经确认<br />3 - 已经熄灭<br />9 - 点亮异常 |
| lightTime   | 点亮时间 | string   | 32   | 是           | yyyy-MM-dd HH:mm:ss                                          |
| confirmTime | 确认时间 | string   | 32   | 是           | yyyy-MM-dd HH:mm:ss                                          |
| offTime     | 熄灭时间 | string   | 32   | 是           | yyyy-MM-dd HH:mm:ss                                          |
| remark      | 备注     | string   | 128  | 是           |                                                              |

```json
{
    "code":0,
    "msg":"查询成功",
    "returnData":{
        "taskId":"12334534534",
        "taskStatus":3,
        "lightTime":"2024-06-02 13:45:10",
        "confirmTime":"2024-06-02 13:45:20",
        "offTime":"2024-06-02 13:45:21",
        "remark":"设备上报完成"
    }
}
```





### 4、上位系统要求 DPS 取消任务

>客户端：上位系统
>
>服务端：DPS
>
>请求方式：DELETE
>
>数据类型：application/json
>
>接口地址：http://{ip}:{port}/api/wms/dpsTask/{taskId}

**请求参数**

| 参数键 | 参数名称 | 数据类型 | 长度 | 是否允许空值 | 备注                      |
| ------ | -------- | -------- | ---- | ------------ | ------------------------- |
| taskId | 任务标识 | string   | 64   | 否           | 上位系统发送到DPS的任务号 |

**响应参数**

```json
{
    "code":0,
    "msg":"操作成功"
}
```