工单集成 | 文档中心

一、应用场景

1.应用于工单转发记录的查看
2.应用于设备异常转发工单时的模板配置
3.应用于第三方工单系统的对接

二、功能说明

可实现设备出现异常后，将异常信息转发至第三方的工单系统中，并在工单系统完成后，将对应的状态信息回写至平台的对应工单记录中

三、前提条件

1.在平台完成工单系统的配置
2.在平台完成工单模板的配置
3.在第三方工单系统中完成回调信息的配置

四、关键流程

4.1.发起工单

4.2.查询工单

五、API列表

5.1. 工单创建

接口描述

创建工单

请求方式

POST

请求地址

/v3/workorder/system/server/ticket/create

请求头

名称	必填	类型	备注
Access-Token	true	String	企业权限
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
template_id	body	是	String	发送内容模板
content	body	否	String	自定义工单内容(带通配符)
user_id	body	否	String	操作员工
event_id	body	否	String	绑定事件id（事件id与设备id二选一）
device_id	body	是	Integer	触发设备id（事件id与设备id二选一）
event_type	body	是	Integer	@1：人工 @2：自动
title	body	否	String	自定义标题
contacts_name	body	否	String	联系人
contacts_phone	body	否	String	联系人电话
scene_id	body	否	String	场景id
log_id	body	否	String	场景日志id
photos	body	否	Array	图片集（图片传输方式三选一）
photos.value	body	否	byte[]	图片流
photos.url	body	否	String	图片下载url
photos.file_id	body	否	String	物联云平台文件系统文件id

请求示例：

{
    "template_id": "发送内容模板",
    "content": "xxxxxxxxxxxxxxxx",
    "user_id": "操作员工",
    "event_id": "事件id",
    "event_type": 1,
    "photos":[
        {
            "url" : "www.google.com/xxx.png"
        },
        {
            "file_id" : "xxxxxxxxx"
        }
    ]
}

返回参数说明

名称	必填	类型	备注
status	是	int	HTTP状态码
code	否	int	业务错误码
msg	否	String	业务错误信息
data	否	Object	业务响应数据
data.flow_id	是	String	工单流水号
data.is_success	是	int	是否创建成功@1：成功；@2：失败
data.msg	否	String	退款错误消息

返回示例：

{
    "code" : "000000",
    "status" : "200",
    "msg" : "请求成功",
    "data" : {
        "flow_id": "工单流水号",
        "is_success": 1,
        "msg": "失败原因"
    }
}

错误码：

错误码	描述
000000	请求成功
4001005	参数不能为空
4001102	获取企业信息失败
5031001	服务端发生异常
4001103	没有该第三方用户
40001104	第三方配置已停用

5.2. 单个工单查询

接口描述

查询工单接口

请求方式

GET

请求地址

/v3/workorder/system/server/ticket/check/{id}

请求头

名称	必填	类型	备注
Access-Token	true	String	企业权限
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
id	path	true	String	工单id

返回参数说明

名称	必填	类型	备注
status	是	int	HTTP状态码
code	否	int	业务错误码
msg	否	String	业务错误信息
data	否	Object	业务响应数据
data.flow_id	是	String	第三方工单流水号
data.project_id	是	String	项目id
data.corp_id	是	String	企业id
data.event_id	是	String	事件id
data.third_name	是	String	第三方系统名称
data.event_type	是	String	来源（事件类型，@1：人工 @2：自动）
data.urgent	否	Integer	紧急程度
data.content	是	String	内容
data.third_msg	否	String	第三方返回内容
data.deal_user	否	String	处理人
data.deal_time	否	date	处理时间
data.deal_remark	否	String	处理备注
data.deal_pic_url	否	String	处理图片
data.create_ticket_time	否	date	转发时间
data.stauts	是	int	状态码@1：待处理；@2：处理中；@3：已处理；@4：失败；@5：撤销/取消；@9：错误工单
data.created_time	是	date	创建时间
data.updated_time	否	date	更新时间
data.accept_time	否	date	接收工单时间
data.finish_time	否	date	完成工单时间

返回示例：

{
    "responseTime": "2021-10-14T15:40:39.620Z",
    "code": "000000",
    "status": "200",
    "msg": "请求成功",
    "data": {
        "id": "X488785707981078528",
        "status": 1,
        "application": "VideoSecurity",
        "corp_id": "100010b9c424fa00",
        "created_date": "2021-09-10T18:59:53.982Z",
        "create_man": "1206c0c06968e800",
        "updated_date": "2021-09-10T18:59:54.25Z",
        "update_man": "1206c0c06968e800",
        "deleted": false,
        "third_id": "tc488296482240200704",
        "third_name": "物联云平台工单系统",
        "ticket_id": "tc488297794138800128",
        "template_id": "tpc488723393596620800",
        "flow_id": "yzy488785707721031680",
        "event_id": "3b613b3a96b991e5411c6fd0f5",
        "event_type": 1,
        "address": "广东省广州市海珠区琶洲街道都比教育M+Studio创工场",
        "content": "设备名称：公司大门\n事件触发条件：人为抓图-实时监控\n空间位置：广东省广州市海珠区琶洲街道都比教育M+Studio创工场\n详细位置：广东省广州市海珠区琶洲街道都比教育M+Studio创工场\n预警对象姓名：",
        "third_msg": "发起工单成功",
        "create_ticket_time": "2021-09-10T18:59:53.982Z"
    }
}

错误码：

错误码	描述
000000	请求成功

5.3. 查询工单列表

接口描述

查询工单列表

请求方式

POST

请求地址

/v3/workorder/system/server/ticket/list

请求头

名称	必填	类型	备注
Access-Token	true	String	企业权限/外部权限
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
filter	body	false	Array	过滤字段
limit	body	true	Integer	每页数量
offset	body	true	Integer	返回数据指针
order	body	false	Map	排序
query	body	false	Map	查询条件：支持name；id等字段

请求示例：

{
    "order":{
        "create_ticket_time":"desc"
    },
    "limit":10,
    "offset":0
}

返回参数说明

名称	必填	类型	备注
status	是	int	HTTP状态码
code	否	int	业务错误码
msg	否	String	业务错误信息
data	否	Array	业务响应数据
data.id	是	String	工单id
data.flow_id	否	String	第三方工单id（未受理则为空）
data.event_id	否	String	事件id
data.event_type	否	Integer	事件来源（@1：手动；@2：自动）
data.address	否	String	地址
data.device_id	否	String	设备
data.third_name	是	String	第三方系统名称
data.content	是	String	内容
data.deal_user	否	String	处理人
data.deal_pic_url	否	String	处理图片
data.deal_time	否	date	处理时间
data.deal_remark	否	String	处理备注
data.create_ticket_time	否	date	转发时间
data.stauts	是	int	状态码@1：待处理；@2：处理中；@3：已处理；@4：失败；@5：撤销/取消；@9：错误工单

返回示例：

{
	"responseTime": "2021-10-14T15:39:12.275Z",
	"code": "000000",
	"status": "200",
	"msg": "请求成功",
	"data": {
		"list": [
			{
				"id": "X488785707981078528",
				"status": 1,
				"application": "VideoSecurity",
				"corp_id": "100010b9c424fa00",
				"created_date": "2021-09-10T18:59:53.982Z",
				"create_man": "1206c0c06968e800",
				"updated_date": "2021-09-10T18:59:54.25Z",
				"update_man": "1206c0c06968e800",
				"deleted": false,
				"third_id": "tc488296482240200704",
				"third_name": "物联云平台工单系统",
				"ticket_id": "tc488297794138800128",
				"template_id": "tpc488723393596620800",
				"flow_id": "yzy488785707721031680",
				"event_id": "3b613b3a96b991e5411c6fd0f5",
				"event_type": 1,
				"address": "广东省广州市海珠区琶洲街道都比教育M+Studio创工场",
				"device_id": null,
				"content": "设备名称：公司大门\n事件触发条件：人为抓图-实时监控\n空间位置：广东省广州市海珠区琶洲街道都比教育M+Studio创工场\n详细位置：广东省广州市海珠区琶洲街道都比教育M+Studio创工场\n预警对象姓名：",
				"third_msg": "发起工单成功",
				"create_ticket_time": "2021-09-10T18:59:53.982Z"
			}
		],
		"count": 386,
		"current_page": null,
		"per_page": null
	}
}

错误码：

错误码	描述
000000	请求成功

5.4. 工单状态回调

接口描述

第三方工单处理完成回调接口

请求方式

POST

请求地址

/v3/workorder/system/server/third/callback/{type}

请求头

名称	必填	类型	备注
Access-Token	true	String	企业权限
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
type	path	是	String	@招商：UBMS；@微钉：WEIDING；@四格：SIGE；@佳兆业：JZY
is_success	body	是	Integer	是否成功（@1：成功，@0：失败）
third_project_id	body	是	String	第三方项目id
ticket_code	body	是	String	第三方工单编码
ticket_status	body	是	String	工单状态
ticket_deal_user	body	否	String	处理人第三方id
ticket_finish_time	body	否	Date	处理完成时间
ticket_remark	body	否	String	处理备注

请求示例：

{
    "is_success": "1",
    "third_project_id": "111111",
    "ticket_code": "1111",
    "ticket_status": "has_finish",
    .........
}

返回参数说明

名称	必填	类型	备注
status	是	int	HTTP状态码
code	否	int	业务错误码
msg	否	String	业务错误信息
data	否	Object	业务响应数据
data.is_success	是	Integer	是否处理成功（@1：成功；@2：失败）
data.ticket_code	是	String	第三方工单编码

返回示例：

{
    "code" : "000000",
    "status" : "200",
    "msg" : "请求成功",
    "data" : {
    	"is_success": 1,
    	"ticket_code": "11111"
	}
}

错误码：

错误码	描述
000000	请求成功
400	请求字段不合法
4002003	没有对应的工单

上次更新：2024-05-09