轻量工单接口文档V1.0

1. 概述

1.1 文档目的

本文是轻量工单接口文档使用指南文档，其目的是指导第三方系统的开发及维护人员如何使用相关接口接入轻量工单。

1.2 名词说明

名词	说明
任务类型	临时报事时选择的类型，例如安全类、环境卫生类、维修类等
临时工单流程	临时工单的任务流，里面设置了工作的任务节点，并且在节点中设置了对应的接单人员和管理人员，用于接单或者对工单进行分配；
周期工单流程	周期性的任务流，里面设置了工作的任务节点，并且在节点中设置了对应的接单人员和管理人员，用于接单或者对工单进行分配；
工作组	里面包含了对应的工作人员，可以分为接单组、管理组等，工作组可配置到临时、周期工单流程中，用于接单、管理等操作；
SOP	SOP的英文全称（Standard Operating Procedure），标准做单步骤，临时、周期工单流程中可配置不同的做单步骤，让做单人员按照标准执行；

2. 系统交互图介绍

2.1 工单状态机图

工单状态机图，展现工单从创建到关闭的整个生命周期中，状态是如何根据事件（或操作）发生变化的。工单操作包括创建、接单、完工、验收、驳回、作废、取消、挂起、恢复、评价，工单状态包括待领取、进行中、待验收、待评价、已完成、已挂起、已作废、已取消8个状态，具体状态见附录5.1工单状态说明。

2.2 三方系统对接方式

2.2.1 http回调对接方式

第三方应用系统提交报事后，轻量工单会异步处理报事事件，处理结果将通过第三方应用系统提供的回调接口返回处理结果，报事对应工单状态发生变更时，轻量工单将通过回调接口把相关变化信息推送给第三方应用系统。在此，提供回调接口封装规范，第三方应用系统对接轻量工单时，需提供回调接口地址，由轻量工单进行回调。第三方应用系统认证签名信息，同下API接口算法。

回调接口定义：

请求方式：POST
请求地址：http://域名/callback/order

请求头参数

参数	类型	说明
Authorization	string	认证信息，格式：{appId}:{sign}，例如：d9cmxqqg8bwepv38:abc123
Date	string	时间类型，例如：Mon,30 Mar 2026 10:30:00 GMT
Content-Type	string	媒体类型的数据格式，例如：application/json

请求体数据示例：

json

{
  "type": 1,
  "description": "工单创建",
  "data": {
    "taskSpecId": "TASK202411050001",
    "taskTypeCode": "INSPECT_TYPE_01",
    "taskTypeName": "设备巡检",
    "operationCode": "create",
    "operationName": "发起报单",
    "lastStatusCode": "Unassigned",
    "lastStatusName": "待领取",
    "statusCode": "Unassigned",
    "statusName": "待领取",
    "modelKey": "PROC_FLOW_INSPECT_V2_001",
    "name": "11月第1周配电房巡检",
    "orderType": 1,
    "projectCode": "P0006",
    "planStartTime": "2024-11-01 09:00:00",
    "planEndTime": "2024-11-07 18:00:00",
    "actualStartTime": null,
    "actualEndTime": null,
    "createTime": "2024-10-31 10:00:00",
    "updateTime": "2024-11-01 08:45:00"
  }
}

请求体参数说明：

参数	类型	说明
type	integer	1 工单创建；2 工单状态；
description	string	操作描述信息
data	array[object]	承载数据对象

其中data承载数据对象如下

返回值key	返回值名称	返回值类型	最大长度	返回值描述
taskSpecId	工单id	string	32	工单id
taskTypeCode	任务类型编码	string	32	任务类型编码
taskTypeName	任务类型名称	string	32	任务类型名称
operationCode	操作编码	string	32	操作编码（如：create）
operationName	操作名称	string	32	操作名称（如：发起报单）
lastStatusCode	上一个状态编码	string	32	上一个状态编码
lastStatusName	上一个状态名称	string	32	上一个状态名称
statusCode	状态编码	string	32	状态编码：待领取Unassigned，进行中Accepted，待验收TobeReviewed，待评价TobeEvaluated，已评价Evaluated，已完成Completed，已挂起Holding，已作废Retired，已撤销Canceled，AI验收通过AIReviewed，AI验收不通过AIReviewReject
statusName	状态名称	string	32	状态名称
modelKey	流程唯一编码	string	64	流程唯一编码
name	工单名称	string	32	工单名称
orderType	工单类型	integer	-	临时性工单-1，周期性工单-2
projectCode	项目编码	string	32	项目编码
planStartTime	计划开始时间	date	64	yyyy-MM-dd HH:mm:ss
planEndTime	计划结束时间	date	64	yyyy-MM-dd HH:mm:ss
actualStartTime	实际开始时间	date	64	yyyy-MM-dd HH:mm:ss
actualEndTime	实际结束时间	date	64	yyyy-MM-dd HH:mm:ss
createTime	派发时间	date	64	yyyy-MM-dd HH:mm:ss
updateTime	修改时间	date	64	yyyy-MM-dd HH:mm:ss

示例代码

java

@Data
public class WorkOrderOperationDto {
    @ApiModelProperty(value = "工单ID")
    private String taskSpecId;
    @ApiModelProperty(value = "任务类型编码")
    private String taskTypeCode;
    @ApiModelProperty(value = "任务类型名称")
    private String taskTypeName;
    @ApiModelProperty(value = "操作编码")
    private String operationCode;
    @ApiModelProperty(value = "操作名称")
    private String operationName;
    @ApiModelProperty(value = "上一个状态编码")
    private String lastStatusCode;
    @ApiModelProperty(value = "上一个状态名称")
    private String lastStatusName;
    @ApiModelProperty(value = "状态编码")
    private String statusCode;
    @ApiModelProperty(value = "状态名称")
    private String statusName;
    @ApiModelProperty(value = "第三方单号")
    private String orderCode;
    @ApiModelProperty(value = "appId,用于区分当前操作来自哪个业务方")
    private String appId;
    @ApiModelProperty(value = "处理类型：人工：userClick，系统：system[可能是流程定时器]")
    private String dealType;
    @ApiModelProperty(value = "流程编码")
    private String modelKey;
    @ApiModelProperty(value = "工单名称")
    private String name;
    @ApiModelProperty(value = "计划开始时间")
    private Date planStartTime;
    @ApiModelProperty(value = "计划结束时间")
    private Date planEndTime;
    @ApiModelProperty(value = "实际开始时间")
    private Date actualStartTime;
    @ApiModelProperty(value = "实际结束时间")
    private Date actualEndTime;
}

2.2.2 mq订阅对接方式

什么时候广播消息？当工单状态发生变化时（详细见图2.1工单状态机图），会广播消息。
广播消息内容：所有数据类型消息体同上http返回data内容一致。
轻量工单如何对接mq信息？三方应用提供Rabbitmq对应的账号、密码、地址、vhost信息，轻量工单进行mq信息配置。

其中约定如下：

创建工单，消费者端接收工单状态回调路由键 order_create_sync；
工单操作，消费者端接收工单状态回调路由键 order_status_sync；
交换机Exchange的名字为应用appId + "_order"，例如：ioc_order。
队列由三方应用自己定义队列Queue名字，并绑定交换机、路由键、队列的关系。

工单状态变更回调内容data详情如下（结构同HTTP回调的data，此处不再重复列出）

2.3 工单系统接口调用时序图

场景1：临时工单报单时序图

场景2：临时工单工单操作时序图

3. 前置准备/步骤

3.1 申请appId和appSecret

线下找对接人申请appId和appSecret（对appId和appSecret信息进行保密，不要随意泄漏）
appId：应用的唯一标识。
appSecret：appId对应的密钥，访问用户资源时用来验证应用的合法性。

3.2 申请请求域名

具体环境域名线下找对接人提供，同门户。
请求域名：https://xxx

3.3 接口使用说明

所有接口请求均需携带签名信息，用于身份验证和请求合法性校验。签名通过请求头（Header）传递。

注意：每个接口在请求时都要携带最新的签名信息。

3.3.1 签名算法

3.3.1.1 请求头参数

请求头示例：

Authorization: clientId:sign
Date: Tue, 31 Mar 2026 06:16:41 GMT
Content-Type: application/json

3.3.1.2 签名生成步骤

步骤一：构建待签名字符串

{HTTP方法}\n{Content-Type}\n{Date}\n{路径资源}

参数说明：

HTTP方法：大写，如 POST、GET
Content-Type：请求体类型，无请求体时为空字符串
Date：GMT 格式的时间字符串
路径资源：URL 中的路径部分（不含域名和参数）

示例：

POST\napplication/json\nMon,30 Mar 2026 10:30:00 GMT\n/api/open/smartpark-workflow/v2/workorder

步骤二：HmacSHA1加密

使用 HmacSHA1 算法对步骤一生成的字符串进行加密，密钥为 clientSecret。

加密结果 = HmacSHA1(待签名字符串, clientSecret)

步骤三：Base64编码

将加密结果进行 Base64 编码。

base64Hash = Base64(加密结果)

步骤四：截取签名值

取 Base64 编码结果的第6到第15位字符（索引5~14，共10位）。

sign = base64Hash.substring(5,15)

步骤五：组装Authorization

Authorization = clientId + ":" + sign

3.3.1.3 签名代码示例

java

import com.alibaba.fastjson.JSONObject;
import lombok.SneakyThrows;
import lombok.extern.slf4j.Slf4j;
import org.apache.http.entity.ContentType;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.util.StringUtils;
import org.springframework.web.client.*;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Base64;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;

@Slf4j
public class OpenApiClientAuth {

    private OpenApiClientAuth() {
    }

    public static final String AUTHORIZATION = "Authorization";
    public static final String CONTENT_TYPE = "Content-Type";
    public static final String DATE = "Date";
    public static final DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter
            .ofPattern("EEE, dd MMM yyyy HH:mm:ss zzz", Locale.ENGLISH);

    @SneakyThrows
    public static Map<String, String> getSignHeaders(final String httpMethod,
                                                      final String url,
                                                      final String clientId,
                                                      final String clientSecret,
                                                      final String body) {
        // 实现省略，具体逻辑参照上述步骤
        // ...
        return headers;
    }
}

4. 接口正文

4.1 任务类型查询

此接口用于获取所有任务类型清单，并区分临时和周期。

4.1.1 请求方式与接口定义

请求方式：GET
请求路径：/api/open/smartpark-workflow/v2/taskTypeTree

4.1.2 请求参数

参数key	参数名称	参数类型	长度	是否必填	参数描述
projectCode	项目编码	string	64	是	数据编码
dataType	数据分类	integer	-	是	任务类型数据分类，1表示临时性任务类型，2表示周期性任务类型

4.1.3 返回参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
code	状态码	integer	-	状态码
msg	返回消息	string	-	返回的描述消息
success	是否成功	boolean	-	是否成功
data	承载数据	array[object]	-	承载数据

其中承载数据data数组内对象参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
createTime	创建时间	string	64	记录创建时间，格式YYYY-MM-DD HH:mm:ss
updateTime	更新时间	string	64	记录最后更新时间，格式YYYY-MM-DD HH:mm:ss
status	状态	integer	-	1启用，0禁用
isDeleted	是否逻辑删除	integer	-	0未删除，1删除
tenantId	租户id	string	64	租户id，"000000"表示系统级或公共数据
dataType	数据类型	integer	-	1临时任务类型，2周期任务类型
dataTypeName	数据类型中文描述	string	64	数据类型的中文描述
code	任务类型编码	string	32	该任务类型的编码，全局唯一
codePath	任务类型编码的完整路径	string	1024	以逗号分隔的路径
name	任务类型的名称	string	255	任务类型的名称
parentCode	父级节点的编码	string	32	父级节点编码
sort	排序序号	integer	-	排序序号
type	类型扩展字段	integer	-	默认为0
remark	备注信息	string	512	备注信息
children	子级任务类型列表	array[object]	-	结构同本节点

4.1.4 请求示例

请求头 (Request Headers)

http

Date: Tue, 31 Mar 2026 06:16:41 GMT
Content-Type: application/json
Authorization: clientId:{sign}

请求体 (Request Body) 注意：GET请求通常没有请求体，参数通过URL传递

GET /api/open/smartpark-workflow/v2/taskTypeTree?dataType=1&projectCode=P0006

响应体 (Response Body)

json

{
  "code": 200,
  "success": true,
  "data": [{
    "createTime": "2025-01-01 08:00:00",
    "updateTime": "2026-03-19 16:21:57",
    "status": 1,
    "isDeleted": 0,
    "tenantId": "000000",
    "dataType": 1,
    "dataTypeName": "报事任务类型",
    "code": "aqzx",
    "codePath": "aqzx",
    "name": "安全秩序报事",
    "parentCode": "0",
    "sort": 1,
    "type": 0,
    "remark": "安全秩序报事",
    "children": [{
      "createTime": "2025-01-01 08:00:00",
      "updateTime": "2025-01-01 08:00:00",
      "status": 1,
      "isDeleted": 0,
      "tenantId": "000000",
      "dataType": 1,
      "dataTypeName": "报事任务类型",
      "code": "aqzx_2",
      "codePath": "aqzx,aqzx_2",
      "name": "交通管理",
      "parentCode": "aqzx",
      "sort": 3,
      "type": 0,
      "remark": "交通管理",
      "children": []
    }]
  }]
}

4.2 项目信息查询接口

此接口用于查询项目信息数据。

4.2.1 请求方式与接口定义

请求方式：GET
请求路径：/api/open/smartpark-workflow/v2/location/getProject

4.2.2 请求参数

参数key	参数名称	参数类型	长度	是否必填	参数描述
projectCode	项目编码	string	64	是	项目编码

4.2.3 返回参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
code	状态码	integer	-	状态码
msg	返回消息	string	-	返回的描述消息
success	是否成功	boolean	-	是否成功
data	承载数据	object	-	承载数据

其中data对象参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
projectCode	项目编码	string	64	项目编码
projectName	项目名称	string	128	项目名称

4.2.4 请求示例

请求头 (Request Headers)

http

Date: Tue, 31 Mar 2026 06:16:41 GMT
Content-Type: application/json
Authorization: clientId:{sign}

请求体 (Request Body) 注意：GET请求通常没有请求体，参数通过URL传递

GET /api/open/smartpark-workflow/v2/location/getProject?projectCode=P0473

响应体 (Response Body)

json

{
  "code": 200,
  "success": true,
  "msg": "查询成功",
  "data": {
    "projectCode": "P0006",
    "projectName": "xxx项目"
  }
}

失败响应示例

json

{
  "code": 401,
  "success": false,
  "msg": "认证失败，请提供有效的访问令牌",
  "data": null
}

4.3 根据位置编码查询位置子集接口

此接口用于查询位置子集数据。

4.3.1 请求方式与接口定义

请求方式：GET
请求路径：/api/open/smartpark-workflow/v2/location/getChildrenByCode

4.3.2 请求参数

参数key	参数名称	参数类型	长度	是否必填	参数描述
projectCode	项目编码	string	64	是	数据编码
parentCode	父级编码	string	64	是	父级编码，层级结构：项目->楼栋->单元->楼层->空间；或项目->围合->楼层->空间；获取楼栋层级数据时填写项目编码

4.3.3 返回参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
msg	返回消息	string	-	返回的描述消息
success	是否成功	boolean	-	是否成功
code	状态码	integer	-	状态码
data	数据列表	array[object]	-	承载数据

其中data数组内对象参数（部分主要字段）

返回值key	返回值名称	返回值类型	最大长度	返回值描述
name	空间名称	string	128	空间名称
code	空间编码	string	64	空间编码
businessCode	业务编码	string		业务编码
serialNumber	序列号	string	32	序列号
isPublic	是否公共区域	string	32	1-是，-1-否
publicSpaceType	公共空间类型编码	string	32	公共空间类型编码
publicSpaceTypeValue	公共空间类型值	string	64	公共空间类型值
projectCode	项目编码	string	64	项目编码
projectName	项目名称	string	128	项目名称
enclosureCode	园区/地块编码	string	64	园区/地块编码
enclosureName	园区/地块名称	string	128	园区/地块名称
buildingCode	楼栋编码	string	64	楼栋编码
buildingName	楼栋名称	string	128	楼栋名称
unitCode	单元编码	string	64	单元编码
unitName	单元名称	string	128	单元名称
floorCode	楼层编码	string	64	楼层编码
floorName	楼层名称	string	128	楼层名称
...	...	...	...	...

4.3.4 请求示例

请求头 (Request Headers)

http

Date: Tue, 31 Mar 2026 06:16:41 GMT
Content-Type: application/json
Authorization: clientId:{sign}

请求体 (Request Body) 注意：GET请求通常没有请求体，参数通过URL传递

GET /api/open/smartpark-workflow/v2/location/getChildrenByCode?projectCode=P0006&parentCode=P0006B0001F0002

响应体 (Response Body)

json

{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": 13,
      "name": "湿式报警阀室",
      "code": "P0006B0001F00020002",
      "businessCode": null,
      "serialNumber": "",
      "isPublic": "1",
      "publicSpaceType": "PzXfsbBif",
      "publicSpaceTypeValue": "公区_消防设备房_报警阀间（泡沫罐设备间）",
      "projectCode": "P0006",
      "projectName": null,
      "enclosureCode": "",
      "enclosureName": null,
      "buildingCode": "P0006B0001",
      "buildingName": null,
      "unitCode": "",
      "unitName": null,
      "floorCode": "P0006B0001F0002",
      "floorName": null,
      "orgCode": "",
      "orgCodeValue": null,
      "type": null,
      "propertyType": null,
      "manageType": "",
      "manageTypeValue": null,
      "businessDistribution": "",
      "businessDistributionValue": null,
      "houseType": "",
      "houseTypeValue": null,
      "buildingArea": "0",
      "rentableArea": "0",
      "rentalStandard": "",
      "typeValue": null,
      "rightsDuration": null,
      "propertyChargeArea": null,
      "height": null,
      "remark": null,
      "status": 1
    }
  ]
}

4.4 设备查询接口

此接口用于查询设备信息。

4.4.1 请求方式与接口定义

请求方式：POST
请求路径：/api/open/smartpark-workflow/v2/getEquipmentList

4.4.2 请求参数

参数key	参数名称	参数类型	长度	是否必填	参数描述
projectCode	项目编码	string	64	是	项目编码
status	数据状态	integer	-	是	数据状态，1：有效，0：失效
linkNode	链路查询参数	object	-	否	链路查询参数

linkNode对象参数

参数名	类型	长度	描述
code	string		位置编码
dataType	string	16	数据类型：project, building, enclosure, unit, floor, property

4.4.3 返回参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
msg	返回消息	string	-	返回的描述消息
success	是否成功	boolean	-	是否成功
code	状态码	integer	-	状态码
data	数据列表	array[object]	-	承载数据

其中data数组内对象参数（部分主要字段）

参数名	类型	说明
id	integer	设备ID
code	string	设备编码
name	string	设备名称
type	string	设备类型编码
typeValue	string	设备类型名称
productType	string	产品类型编码
productTypeValue	string	产品类型名称
installationDate	string	安装日期（yyyy-MM-dd）
serialNumber	string	序列号
projectCode	string	项目编码
projectName	string	项目名称
buildingCode	string	楼栋编码
buildingName	string	楼栋名称
enclosureCode	string	围栏编码
enclosureName	string	围栏名称
unitCode	string	单元编码
unitName	string	单元名称
floorCode	string	楼层编码
floorName	string	楼层名称
propertyCode	string	资产位置编码
propertyName	string	资产位置名称
brand	string	品牌
specification	string	规格型号
longitude	string	经度
latitude	string	纬度
iot	integer	是否IoT设备（1：是）

4.4.4 请求示例

请求头 (Request Headers)

http

Date: Tue, 31 Mar 2026 06:16:41 GMT
Content-Type: application/json
Authorization: clientId:{sign}

请求体 (Request Body)

json

{
  "status": 1,
  "linkNode": {
    "code": "P0006B0001F0002",
    "dataType": "floor"
  },
  "projectCode": "P0006"
}

响应体 (Response Body)

json

{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": 5332,
      "code": "IOTPR000001100142",
      "name": "F座B1层后厨热水机房",
      "type": "iotPR0000011",
      "typeValue": "标准摄像头V2",
      "productType": null,
      "productTypeValue": "IOT品类",
      "equipmentStatusStr": null,
      "equipmentStatus": null,
      "maintenanceCycleStr": null,
      "maintenanceCycle": null,
      "installationDate": "2026-01-30",
      "warrantyExpiryDate": null,
      "serialNumber": "11010801011180000001_11010801011320000014",
      "projectCode": "P0006",
      "projectName": "xxx项目",
      "buildingCode": "P0006B0001",
      "buildingName": "A楼",
      "enclosureCode": null,
      "enclosureName": null,
      "unitCode": "set2Null",
      "unitName": null,
      "floorCode": "P0006B0001F0002",
      "floorName": "1层",
      "propertyCode": "P0006B0001F00020002",
      "propertyName": "湿式报警阀室",
      "brand": null,
      "specification": null,
      "manufactureCompany": null,
      "manufactureCompanyTel": null,
      "commissioningDate": null,
      "takeoverStatusStr": null,
      "takeoverStatus": null,
      "controlArea": null,
      "unit": null,
      "responsible": null,
      "responsiblePhone": null
    }
  ]
}

4.5 文件上传接口

此接口用于文件上传。当前暂不支持

4.5.1 请求方式与接口定义

请求方式：POST
请求路径：/api/open/smartpark-workflow/v2/file/upload
Content-Type: multipart/form-data

4.5.2 请求参数

参数key	参数名称	参数类型	长度	是否必填	参数描述
file	上传文件	File	-	是	需要上传的文件，若是图片文件，支持常见图片格式（如PNG、JPG）

4.5.3 返回参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
msg	返回消息	string	-	返回的描述消息
success	是否成功	boolean	-	是否成功
code	状态码	integer	-	状态码
data	数据列表	array[object]	-	承载数据

其中data数组内对象参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
fileUri	获取文件uri	string	128	文件的相对统一资源标识符

4.5.4 请求示例

请求头 (Request Headers)

http

Date: Tue, 31 Mar 2026 06:16:41 GMT
Authorization: clientId:{sign}
Content-Type: multipart/form-data; boundary=WebKitFormBoundaryLKVGYZsJwkbnnnhgh

示例请求

POST /api/open/smartpark-workflow/v2/file/upload HTTP/1.1
Host: xxx.icloudcity.com
Content-Type: multipart/form-data; boundary=WebKitFormBoundaryLKVGYZsJwkbnnnhgh

--WebKitFormBoundaryLKVGYZsJwkbnnnhgh
Content-Disposition: form-data; name="file"; filename="Gemini_Generated_Image_4wxkzm4wxkzm4wxk.png"
Content-Type: image/png

[文件二进制数据]
--WebKitFormBoundaryLKVGYZsJwkbnnnhgh--

响应体 (Response Body)

json

{
  "code": 200,
  "success": true,
  "data": {
    "fileUri": "202603/355533dc7df7f40482185deb943a213b/Gemini_Generated_Image_4wxkzm4wxkzm4wxk.png"
  },
  "msg": "操作成功"
}

4.6 文件地址获取接口

此接口用于获取文件地址。

4.6.1 请求方式与接口定义

请求方式：GET
请求路径：/api/open/smartpark-workflow/v2/file/getFileUrl

4.6.2 请求参数

参数key	参数名称	参数类型	长度	是否必填	参数描述
fileName	文件相对Uri地址	string	128	是	文件相对Uri地址

4.6.3 返回参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
msg	返回消息	string	-	返回的描述消息
success	是否成功	boolean	-	是否成功
code	状态码	integer	-	状态码
data	数据列表	array[object]	-	承载数据

其中data数组内对象参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
fileName	文件相对访问URI	string	128	文件相对访问URI
fileLink	文件完整访问URL	string	1024	文件完整访问URL

4.6.4 请求示例

请求头 (Request Headers)

http

Date: Tue, 31 Mar 2026 06:16:41 GMT
Content-Type: application/json
Authorization: clientId:{sign}

请求体 (Request Body) 注意：GET请求通常没有请求体，参数通过URL传递

GET /api/open/smartpark-workflow/v2/file/getFileUrl?fileName=202603%2F355533dc7df7f40482185deb943a213b%2FGemini_Generated_Image_4wxkzm4wxkzm4wxk.png

响应体 (Response Body)

json

{
  "code": 200,
  "success": true,
  "data": {
    "fileName": "202603/355533dc7df7f40482185deb943a213b/Gemini_Generated_Image_4wxkzm4wxkzm4wxk.png",
    "fileLink": "https://xxx/spup/202603/355533dc7df7f40482185deb943a213b/Gemini_Generated_Image_4wxkzm4wxkzm4wxk.png?X-Amz-Algorithm=AWSAH-MAC-SHA256&X-Amz-Credential=..."
  },
  "msg": "操作成功"
}

4.7 创建工单接口

此接口用于创建工单。

4.7.1 请求方式与接口定义

请求方式：POST
请求路径：/api/open/smartpark-workflow/v2/workorder

4.7.2 请求参数

请求结构为JSON结构，参数如下：

参数key	参数名称	参数类型	长度	是否必填	参数描述
projectCode	项目编码	string	64	是	数据编码
taskTypeCode	任务类型code	string	32	是	任务类型code
description	报事描述	string	3000	是	描述，最大长度3000
attachmentUrls	报事图片链接地址	array	1024	否	最多支持10个图片全链接地址
taskReporterId	报事人id	long	-	是	报事人id
taskReporter	报事人姓名	string	32	是	报事人姓名
requestedByPhone	报事人电话	string	32	是	报事人手机号码
isValet	是否代客报事	integer	-	是	1是，2否
taskValetReportPhone	代客报事人电话	string	32	否	代客报事时必填
taskValetReporter	代客报事人	string	32	否	代客报事时必填
locationId	工作位置id	string	64	是	工作位置id
assetId	设备id	string	64	否	设备id

4.7.3 返回参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
code	状态码	integer	-	状态码
data	承载数据	object	-	承载数据
- procInstId	工单Id	string	32	工单Id
msg	返回消息	string	-	返回的描述消息
success	是否成功	boolean	-	是否成功

4.7.4 请求示例

请求头 (Request Headers)

http

Date: Tue, 31 Mar 2026 06:16:41 GMT
Content-Type: application/json
Authorization: clientId:{sign}

请求体 (Request Body)

json

{
  "projectCode": "P0473",
  "taskTypeCode": "aqzx",
  "requestedByPhone": "19926451599",
  "description": "创建工单报事OpenAPI20260330",
  "locationId": "P0473",
  "assetId": "IOTPR00001539091",
  "attachmentUrls": [
    "https://xxxxxx/2023/0130/5cf317dafb8241c68bb15eee7705252f.jpg"
  ]
}

响应体 (Response Body)

json

{
  "code": 200,
  "success": true,
  "data": {
    "procInstId": "2026033108583108854"
  },
  "msg": "创建成功"
}

失败响应示例

json

{
  "code": 400,
  "success": false,
  "msg": "参数错误"
}

4.8 接单并开始工作接口

根据工单编码、项目编码和人员信息，接单并开始工作。

4.8.1 请求方式与接口定义

请求方式：POST
请求路径：/api/open/smartpark-workflow/v2/acceptAndStart

4.8.2 请求参数

参数key	参数名称	参数类型	长度	是否必填	参数描述
procInstId	工单id	string	32	是	工单id
projectCode	项目编码	string	64	是	项目编码
userCode	用户编号	string	32	是	当前操作用户的编号

4.8.3 返回参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
code	状态码	integer	-	状态码
success	是否成功	boolean	-	是否成功
data	承载数据	object	-	承载数据
- procInstId	工单Id	string	32	工单Id
msg	返回消息	string	-	返回消息

4.8.4 请求示例

请求头 (Request Headers)

http

Date: Tue, 31 Mar 2026 06:16:41 GMT
Content-Type: application/json
Authorization: clientId:{sign}

请求体 (Request Body)

json

{
  "procInstId": "2026033013355492217",
  "projectCode": "P0473",
  "userCode": "UUUU00641190"
}

响应体 (Response Body)

json

{
  "code": 200,
  "success": true,
  "data": {
    "procInstId": "2026033108583108854"
  },
  "msg": "操作成功"
}

失败响应示例

json

{
  "code": 400,
  "success": false,
  "data": { "procInstId": "2026033108583108854" },
  "msg": "工单状态异常"
}

4.9 工单完工接口

根据工单编码和项目编码，完成当前工单工作。

4.9.1 请求方式与接口定义

请求方式：POST
请求路径：/api/open/smartpark-workflow/v2/completeWork

4.9.2 请求参数

参数key	参数名称	参数类型	长度	是否必填	参数描述
procInstId	工单id	string	32	是	工单id
projectCode	项目编码	string	64	是	项目编码
userCode	用户编码	string	-	是	用户编码
comment	完工备注/描述	string	128	否	完工备注/描述
completeImg	完工证明图片列表	string	-	否	完工证明图片列表（JSON字符串格式）
sopValue	SOP执行的具体数据内容	object	-	否	当临时或周期工单不存在sop,则可不填，若带有sop,则是必填项

completeImg JSON字符串格式

参数key	参数名称	参数类型	长度	是否必填	参数描述
name	图片文件名称key	string	32	是	图片文件名称key
value	图片文件的uri地址	string	64	是	图片文件的uri地址

sopValue对象结构

参数key	参数名称	参数类型	长度	是否必填	参数描述
procInstId	子流程或关联流程实例ID	string	32	是	子流程或关联流程实例ID
instStatusCode	流程状态码	string	64	是	流程状态码（如：Accepted已接受）
sopFormValueList	sop具体执行步骤数组	array	-	是	包含SOP每一个步骤的具体执行信息

sopFormValueList数组项说明

参数key	参数名称	参数类型	长度	是否必填	参数描述
procInstId	流程实例ID	string	32	是	流程实例ID
equipSpaceNumber	设备空间层级/类型标识	integer	-	是	设备空间层级/类型标识
equipspaceCode	设备空间编码	string	32	是	设备空间编码
equipspaceName	设备空间名称	string	32	是	设备空间名称

4.9.3 返回参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
code	状态码	integer	-	状态码
data	承载数据	object	-	承载数据
- procInstId	工单Id	string	32	工单Id
msg	返回消息	string	-	返回的描述消息
success	是否成功	boolean	-	是否成功

4.9.4 请求示例

请求头 (Request Headers)

http

Date: Tue, 31 Mar 2026 06:16:41 GMT
Content-Type: application/json
Authorization: clientId:{sign}

请求体 (Request Body)

json

{
  "procInstId": "2026033116411236163",
  "sopValue": {
    "procInstId": "57f5ffd4-2cdd-11f1-bb0e-0255ac1001de",
    "instStatusCode": "Accepted",
    "sopFormValueList": [{
      "procInstId": "57f5ffd4-2cdd-11f1-bb0e-0255ac1001de",
      "equipSpace": 2,
      "equipspaceCode": "BUILDING4",
      "equipspaceName": "小米D栋",
      "formKey": "SOP_177336859631386",
      "stepCode": "SOP_177336859631386_1",
      "sopFormExSteps": [
        { "key": "singleCheck", "value": "1" },
        { "key": "sopImg", "value": "[{\"name\":\"202603/3e17537f00ed9512d638aaed8417177b/Gemini_Generated_Image_4wxkzm4wxkzm4wxk.png\"}]" }
      ]
    }]
  }
}

响应体 (Response Body)

json

{
  "code": 200,
  "success": true,
  "data": {
    "procInstId": "2026033116411236163"
  },
  "msg": "完工操作成功"
}

4.10 工单列表查询接口

此接口用于查询工单列表。支持使用工单id、工单创建时间范围、接单人、创建工单人、任务类型（是否包含子级任务类型）、工单类型(临时工单/周期工单)、工单状态过滤多条件高级查询。

4.10.1 请求方式与接口定义

请求方式：GET/POST，推荐使用POST
请求路径：/api/open/smartpark-workflow/v2/queryOrder

4.10.2 请求参数

参数key	参数名称	参数类型	长度	是否必填	参数描述
procInstId	工单id	string	32	是	工单id
projectCode	项目编码	string	64	是	项目编码
taskTypeCode	任务类型	string	32	否	任务类型（是否包含子级任务类型）
orderType	工单类型	int	-	否	临时工单1/周期工单2
current	当前第几页	int	-	否	默认第一页
size	每页多少条记录	int	-	否	默认10条，最大200条
handlerUserMobile	接单人手机号码	string	32	否	接单人手机号码
taskReporterCode	创建工单人code	string	32	否	创建工单人code
instPlanStartTime	流程实例计划开始时间	string	32	否	yyyy-MM-dd HH:mm:ss
instPlanEndTime	流程实例计划结束时间	string	32	否	yyyy-MM-dd HH:mm:ss
taskAssignmentStatusCode	工单状态	string	32	否	待领取Unassigned，进行中Accepted，待验收TobeReviewed，待评价TobeEvaluated，已评价Evaluated，已完成Completed，已挂起Holding，已作废Retired，已撤销Canceled，AI验收通过AIReviewed，AI验收不通过AIReviewReject

4.10.3 返回参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
code	状态码	integer	-	状态码
success	是否成功	boolean	-	是否成功
msg	返回消息	string	-	返回消息
data	承载数据	array[object]	-	承载数据

其中data数组内对象参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
records	工单列表数据数组集合	array	-	工单列表数据数组集合
total	总记录条数	int	-	总记录条数
size	每页记录数	int	-	每页记录数
current	当前页面	int	-	当前页面
pages	总页面数	int	-	总页面数

其中records列表项详细字段（部分）

返回值key	返回值名称	返回值类型	长度	返回值描述
id	工单唯一标识ID	string	32	工单唯一标识ID
tenantId	租户ID	string	32	租户ID
projectCode	项目编码	string	32	项目编码
projectName	项目名称	string	32	项目名称
taskName	任务名称	string	32	任务名称
taskImg	任务关联图片	string	text	JSON字符串格式，含name和url
orderType	工单类型	int	-	1-临时工单，2-周期工单
taskContent	任务描述/报事内容	string	128	任务描述
distributeTime	派发时间	string	32	yyyy-MM-dd HH:mm:ss
taskLocationId	任务位置ID	string	32	任务位置ID
taskLocationName	任务位置全路径名称	string	64	全路径名称
instStatusCode	工单状态编码	string	32	见请求参数枚举值
instStatusName	工单状态名称	string	32	如：待领取、进行中等
createUserName	创建人姓名及手机号	string	32	创建人姓名及手机号
instPlanStartTime	计划开始时间	string	32	计划开始时间
instPlanEndTime	计划结束时间	string	32	计划结束时间
instStartTime	实际开始时间	string	32	实际开始时间
instEndTime	实际完成时间	string	32	实际完成时间
...	...	...	...	...

4.10.4 请求示例

请求头 (Request Headers)

http

Date: Tue, 31 Mar 2026 06:16:41 GMT
Content-Type: application/json
Authorization: clientId:{sign}

请求体 (Request Body)

json

{
  "instStatusCodes": ["Unassigned"],
  "current": 1,
  "size": 10,
  "startDistributeTime": "2025-12-31 00:00:00",
  "endDistributeTime": "2026-03-31 23:59:59",
  "projectCode": "P0473"
}

响应体 (Response Body)（省略示例，结构与文档一致）

4.11 工单详情查询接口

此接口用于查询工单详情。

4.11.1 请求方式与接口定义

请求方式：GET
请求路径：/api/open/smartpark-workflow/v2/details

4.11.2 请求参数

参数key	参数名称	参数类型	长度	是否必填	参数描述
procInstId	工单id	string	32	是	工单id
projectCode	项目编码	string	64	是	项目编码

4.11.3 返回参数

返回值key	返回值名称	返回值类型	最大长度	返回值描述
code	状态码	integer	-	状态码
success	是否成功	boolean	-	是否成功
msg	返回消息	string	-	返回消息
data	承载数据	array[object]	-	承载数据

其中data数组内对象参数（部分主要字段）

返回值key	返回值名称	返回值类型	最大长度	返回值描述
taskSpecId	工单id	string	32	工单id
projectCode	项目code	string	32	项目code
projectName	项目名	string	32	项目名
taskName	任务名称	string	32	任务名称
taskContent	任务内容	string	256	任务内容
taskDescription	任务内容	string	256	任务内容
instStatusCode	流程实例状态code	string	32	流程实例状态code
instStatusName	流程实例状态名	string	32	流程实例状态名
taskReporter	创建人	string	16	创建人
requestedByPhone	报事人电话	string	32	报事人电话
taskFullLocationName	作业位置全路径名	string	32	作业位置全路径名
createTime	创建时间	string	64	yyyy-MM-dd HH:mm:ss
files	工单相关文件	array	-	工单相关文件
lstTaskComment	历史进度记录	array	-	历史进度记录
procInfo	流程信息	array[object]	-	流程信息

files对象数组结构

返回值key	返回值名称	返回值类型	最大长度	返回值描述
fileName	文件名称	string	32	文件名称
url	文件URL	string	64	文件URL

lstTaskComment数组结构

返回值key	返回值名称	返回值类型	最大长度	返回值描述
commentDesc	进度描述	string	128	进度描述
operationPeopleName	操作人	string	32	操作人
operationTime	操作时间	integer	-	操作时间

procInfo数组结构

返回值key	返回值名称	返回值类型	最大长度	返回值描述
name	节点名称	string	16	如：待领取、进行中、待验收
id	节点ID	string	32	节点ID
processStatus	流程状态编码	string	32	流程状态编码
assignee	指派人/组信息	array	-	指派人/组信息

4.11.4 请求示例

请求头 (Request Headers)

http

Date: Tue, 31 Mar 2026 06:16:41 GMT
Content-Type: application/json
Authorization: clientId:{sign}

请求体 (Request Body) 注意：GET请求通常没有请求体，参数通过URL传递

GET /api/open/smartpark-workflow/v2/details?procInstId=2026032609191248176&projectCode=P0006

响应体 (Response Body)（省略示例，结构与文档一致）

5. 附录

5.1 工单状态说明

编码	工单流程状态	说明
Unassigned	待领取	工单创建成功后，还未被接单人接单
Accepted	进行中	工单被接单人接单后，且还未提交完工
TobeReviewed	待验收	接单人提交完工后，还未被管理员验收
TobeEvaluated	待评价	工单被管理员验收通过后，还未被报单人评价
Completed	已完成	工单已经完成最后流程，代表整个流程已经完结
Retired	已作废	管理人员将该工单作废后，状态为已作废
Canceled	已取消	报单人撤销自己创建的工单后，状态为已取消
Holding	已挂起	工单做单过程中，临时挂起，待满足条件后恢复工单继续进行

5.2 状态码清单

5.2.1 HTTP状态码

HTTP状态码	描述
200	操作成功
400	请求不合法，包体格式错误
403	禁止访问
404	请求失败
500	服务器内部错误
501	服务未实现
502	网关错误，服务不可用
503	服务不可用
504	后端服务不可用或者处理超时

轻量工单接口文档V1.0 ​

1. 概述 ​

1.1 文档目的 ​

1.2 名词说明 ​

2. 系统交互图介绍 ​

2.1 工单状态机图 ​

2.2 三方系统对接方式 ​

2.2.1 http回调对接方式 ​

2.2.2 mq订阅对接方式 ​

2.3 工单系统接口调用时序图 ​

3. 前置准备/步骤 ​

3.1 申请appId和appSecret ​

3.2 申请请求域名 ​

3.3 接口使用说明 ​

3.3.1 签名算法 ​

3.3.1.1 请求头参数 ​

3.3.1.2 签名生成步骤 ​

3.3.1.3 签名代码示例 ​

4. 接口正文 ​

4.1 任务类型查询 ​

4.1.1 请求方式与接口定义 ​

4.1.2 请求参数 ​

4.1.3 返回参数 ​

4.1.4 请求示例 ​

4.2 项目信息查询接口 ​

4.2.1 请求方式与接口定义 ​

4.2.2 请求参数 ​

4.2.3 返回参数 ​

4.2.4 请求示例 ​

4.3 根据位置编码查询位置子集接口 ​

4.3.1 请求方式与接口定义 ​

4.3.2 请求参数 ​

4.3.3 返回参数 ​

4.3.4 请求示例 ​

4.4 设备查询接口 ​

4.4.1 请求方式与接口定义 ​

4.4.2 请求参数 ​

4.4.3 返回参数 ​

4.4.4 请求示例 ​

4.5 文件上传接口 ​

4.5.1 请求方式与接口定义 ​

4.5.2 请求参数 ​

4.5.3 返回参数 ​

4.5.4 请求示例 ​

4.6 文件地址获取接口 ​

4.6.1 请求方式与接口定义 ​

4.6.2 请求参数 ​

4.6.3 返回参数 ​

4.6.4 请求示例 ​

4.7 创建工单接口 ​

4.7.1 请求方式与接口定义 ​

4.7.2 请求参数 ​

4.7.3 返回参数 ​

4.7.4 请求示例 ​

4.8 接单并开始工作接口 ​

4.8.1 请求方式与接口定义 ​

4.8.2 请求参数 ​

4.8.3 返回参数 ​

4.8.4 请求示例 ​

4.9 工单完工接口 ​

4.9.1 请求方式与接口定义 ​

4.9.2 请求参数 ​

4.9.3 返回参数 ​

4.9.4 请求示例 ​

4.10 工单列表查询接口 ​

4.10.1 请求方式与接口定义 ​

4.10.2 请求参数 ​

4.10.3 返回参数 ​

4.10.4 请求示例 ​

4.11 工单详情查询接口 ​

4.11.1 请求方式与接口定义 ​

4.11.2 请求参数 ​

4.11.3 返回参数 ​

4.11.4 请求示例 ​

5. 附录 ​

5.1 工单状态说明 ​

5.2 状态码清单 ​

5.2.1 HTTP状态码 ​

轻量工单接口文档V1.0

1. 概述

1.1 文档目的

1.2 名词说明

2. 系统交互图介绍

2.1 工单状态机图

2.2 三方系统对接方式

2.2.1 http回调对接方式

2.2.2 mq订阅对接方式

2.3 工单系统接口调用时序图

3. 前置准备/步骤

3.1 申请appId和appSecret

3.2 申请请求域名

3.3 接口使用说明

3.3.1 签名算法

3.3.1.1 请求头参数

3.3.1.2 签名生成步骤

3.3.1.3 签名代码示例

4. 接口正文

4.1 任务类型查询

4.1.1 请求方式与接口定义

4.1.2 请求参数

4.1.3 返回参数

4.1.4 请求示例

4.2 项目信息查询接口

4.2.1 请求方式与接口定义

4.2.2 请求参数

4.2.3 返回参数

4.2.4 请求示例

4.3 根据位置编码查询位置子集接口

4.3.1 请求方式与接口定义

4.3.2 请求参数

4.3.3 返回参数

4.3.4 请求示例

4.4 设备查询接口

4.4.1 请求方式与接口定义

4.4.2 请求参数

4.4.3 返回参数

4.4.4 请求示例

4.5 文件上传接口

4.5.1 请求方式与接口定义

4.5.2 请求参数

4.5.3 返回参数

4.5.4 请求示例

4.6 文件地址获取接口

4.6.1 请求方式与接口定义

4.6.2 请求参数

4.6.3 返回参数

4.6.4 请求示例

4.7 创建工单接口

4.7.1 请求方式与接口定义

4.7.2 请求参数

4.7.3 返回参数

4.7.4 请求示例

4.8 接单并开始工作接口

4.8.1 请求方式与接口定义

4.8.2 请求参数

4.8.3 返回参数

4.8.4 请求示例

4.9 工单完工接口

4.9.1 请求方式与接口定义

4.9.2 请求参数

4.9.3 返回参数

4.9.4 请求示例

4.10 工单列表查询接口

4.10.1 请求方式与接口定义

4.10.2 请求参数

4.10.3 返回参数

4.10.4 请求示例

4.11 工单详情查询接口

4.11.1 请求方式与接口定义

4.11.2 请求参数

4.11.3 返回参数

4.11.4 请求示例

5. 附录

5.1 工单状态说明

5.2 状态码清单

5.2.1 HTTP状态码