# 工单系统

工单接口V2版本旨在抽象七鱼客服、客服分组、工单等部分业务操作，为第三方系统和七鱼工单集成提供一定的便利。工单的操作严格按照七鱼工单系统的可操作行为来定义接口。

# 接口鉴权

# 接口协议

接口属性描述了接口的方法、地址和Content-Type，Payload部分描述了接口的协议内容。

# 错误码

参数	参数说明
200	成功
8802	客服没有权限
14001	App Key错误
14002	请求校验失败
14003	时间错误
14004	请求参数错误
14500	内部错误
14100	客服不存在
14101	分类不存在
14102	客服分组不存在
14103	附件个数超出限制
14104	附件大小超出限制
14105	用户不存在
14106	工单不存在
14107	附件大小超出企业总大小限制
14108	工单重复创建
14109	uniqueId超过长度限制
14110	工单模板不存在
14200	不支持的分类类型
16001	服务不可用

附录 [1] 工单状态：1:已提交，5：待申领， 10：处理中，20：已完结， 50：已挂起

# 工单接口对接

该接口用于创建工单时，七鱼系统通过该接口向第三方系统获取用户信息，包括访客VIP级别，访客UID，访客CRM信息等，通过参数eventType进行区分不同场景下的调用。
对接URL配置在七鱼系统中：系统管理》扩展与集成》CRM信息对接》工单对接接口URL

参数eventType类型说明：

参数值	参数说明
1	邮件工单通过邮件收件人地址+发件人地址获取访客CRM信息

七鱼服务器向第三方接口请求信息时，采用密钥安全认证机制，保证第三方系统的信息安全。

# 数据校验

接口鉴权参考通用说明-数据校验 (opens new window)

# 调用说明

本接口只支持POST请求；
本接口请求Content-Type类型为：application/json;charset=utf-8;
本接口返回类型为JSON，同时进行UTF-8编码。

# curl请求样例如下

1.邮件工单通过邮件收件人地址+发件人地址，获取访客用户信息，包括访客VIP级别、访客UID、crm信息

curl -X POST \
  'http://www.xxx.com/api/ticket/crm/info?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
  -H 'content-type: application/json;charset=utf-8' \
  -d '{
    "eventType": 1,
    "sender": "some@163.com",  //发件人邮件地址
    "receiver": "other@163.com"  //收件人邮件地址
  }'

# 响应样例如下

本接口返回的数据中，code返回200代表成功
本接口返回的数据中，message可用于code非200，即响应错误时的说明
result代表返回的数据内容，JSON格式；其中data为String类型，data中字段具体说明参考CRM对接-crm轻量对接-参数说明 (opens new window)

{
  "code": 200,
  "result": {
    "uid": "testUid",
    "viplevel": 3,
    "data": "[
{ \"key\":\"real_name\", \"value\":\"testname122601\" },
{ \"key\":\"mobile_phone\", \"hidden\":true, \"value\":\"14800000000\" },
{ \"key\":\"email\", \"value\":\"14800000000@163.com\" },
{ \"index\":0, \"key\":\"account\", \"label\":\"账号\", \"value\":\"zhangsan\" , \"href\":\"http://example.domain/user/zhangsan\" },
{ \"index\":1, \"key\":\"sex\", \"label\":\"性别\", \"value\":\"先生\" },
{ \"index\":5, \"key\":\"reg_date\", \"label\":\"注册日期\", \"value\":\"2015-11-16\" },
{ \"index\":6, \"key\":\"last_login\", \"label\":\"上次登录时间\", \"value\":\"2015-12-22 15:38:54\" },
{ \"index\":7, \"key\": \"tags\", \"label\": \"标签\", \"value\": \"ceshi,测试一下\" },
{ \"index\":8, \"key\": \"leaderId\", \"value\": \"1001\" }
] ",
},
"message": "返回说明"
}

# 创建工单

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/create?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "title":"工单标题",
  "uid":"someone",
  "uniqueId":"123456789ABCDE",
  "typeId":12345,
  "content":"我有一个问题",
  "userName":"游客1",
  "userMobile":"18888888888",
  "userEmail":"some@163.com",
  "toEmail":"other@163.com",
  "targetStaffId":12345,
  "targetGroupId":12345,
  "staffId":12345,
  "priority": 5,
  "templateId":1234,
  "followerIds":["1001","1003"],
  "attachments":[
    {
      "fileName":"附件1.txt",
      "type":1,
      "payload":"附件BASE64"
    }
  ],
  "properties":[
    {
      "key":"服务器",
      "value":"瘦西湖"
    },
    {
      "key":"玩家ID",
      "value":"12345"
    }
  ],
  "customFields":[
    {
      "id":12345,
      "value":"你好"
    },
    {
      "id":12346,
      "value":"恩"
    },
    {
      "id": 66,
      "value": "619546,619549,619210" //如果是级联自定义字段入参按这个格式拼接，ID的顺序也是级联的顺序
    }
  ]
}

接口参数说明如下：

参数	是否必须	参数说明
title	是	工单标题，不超过100个字符
uid	否	开发者的应用里的用户ID，不超过64个字符(如果没有userMobile则必传)
typeId	否	分类ID，0表示未分类
content	是	工单内容，不超过3000个字符
userName	否	用户姓名，不超过128个字符
userMobile	否	用户联系方式，不超过128个字符(如果没有uid则必传)
userEmail	否	用户联系邮箱，不超过255个字符 (当fromType=8的时候则必传)
toEmail	否	收件人邮箱
targetGroupId	否	指定客服分组ID(开启自动流转请勿传此字段)
staffId	是	托管客服ID (当fromType=8的时候则不是必传)
priority	否	优先级,2=低;5=一般;8=紧急;10=非常紧急
templateId	否	模板ID
connectionId	否	关联会话ID（七鱼在线或呼叫系统的会话ID）
followerIds	否	工单关注人
attachments	否	附件列表
attachments.fileName	是	附件的文件名，不超过128个字符
attachments.type	是	附件的类型，1=文件的Base64，目前仅支持此类型
attachments.payload	是	对应type的内容
customFields	否	自定义字段
customFields.id	是	自定义字段的ID，对应获取工单模板字段接口返回的fieldId字段
customFields.value	是	自定义字段的值 `如果是级联字段，需要按顺序用英文逗号,分割传入子集的ID。看入参示例入参。子集ID从[获取级联字段子字段详细信息]接口获取`
properties	否	附加属性对，json格式，不超过1024个字符
fromType	否	工单类型 8=邮件工单，不传则是普通工单

userMobile和userEmail二者必填其一；
普通工单targetStaffId和targetGroupId二者必填其一，自动流转类型工单则不必满足；
创建工单接口上传附件大小目前限制最多5个附件，总大小不超过50M。

响应

{
  "code":200,
  "message":12345
}

响应码为200时，message内容为工单ID

# 修改工单

修改工单部分属性。

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/modify?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":12345,
  "staffId":123,
  "type": 0,
  "customId":12345,
  "fieldId":12345,
  "value":"值" // 如果是级联字段入参按这个格式拼接，ID的顺序也是级联的顺序"619546,619549"
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID
staffId	是	持有工单的客服ID
type	是	修改类型，0=自定义字段，1=标题，2=优先级，3=分类
customId	是	type=0时，填写自定义字段ID，否则填0
fieldId	是	type=0时，填写自定义字段FieldId，否则填0, 对应获取工单模板字段接口返回的fieldId字段, 暂不支持级联类型自定义字段， customId 和 fieldId 同时存在，以fieldId为准
value	是	新值 `如果是级联字段，需要按顺序用英文逗号,分割传入子集的ID。看入参示例入参。子集ID从[获取级联字段子字段详细信息]接口获取`

响应

{
  "code":200,
  "message": true
}

返回成功或者失败。

响应码为8803时，actionStatus为1表示已提交,5表示已分配待申领(考虑待分配状态) 未受理,10表示已领取/已受理/处理中,20为已完结,25为已驳回,999为已删除

# 批量修改工单

修改工单部分属性。

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/batch/modify?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId": 12345,
  "staffId": 123, //传-1时代表访客补充材料
  "customFields": [
    {
      "id": 12345,
      "fieldId": 12345,
      "value": "你好"
    },
    {
      "id": 12346,
      "fieldId": 12345,
      "value": "恩"
    },
    {
      "id": 12346,
      "fieldId": 12345,
      "value": "619546,619549,619275" //如果是级联字段入参按这个格式拼接，ID的顺序也是级联的顺序，访客补充材料不支持级联字段
    },
    {
      "id": 12346,
      "fieldId": 12345,
      "value": "[{\"fileName\":\"1.jpg\",\"payload\":\"base64code\"}]" //如果是附件字段传附件名称和base64编码，仅访客补充材料支持
    },
    {
      "id": 0,
      "fieldId": 0,
      "value": "[{\"fileName\":\"2.jpg\",\"payload\":\"base64code\"}]",
      "name" : "uploadFile" //固定值，补充工单模板附件时需要传该字段，仅访客补充材料支持
    }
  ]
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID
staffId	是	持有工单的客服ID,填-1时表示访客补充材料
customFields	是	自定义字段更新列表, 最多20个
customFields.id	是	自定义字段ID
customFields.fieldId	是	自定义字段FieldId，对应工单模板字段接口返回的fieldId字段，fieldId和id同时存在以fieldId为准
customFields.value	是	新值 `如果是级联字段，需要按顺序用英文逗号,分割传入子集的ID。看入参示例入参。子集ID从[获取级联字段子字段详细信息]接口获取`
customFields.name	否	固定值uploadFile，补充工单模板附件时需要传该字段，仅访客补充材料支持

响应

{
  "code":200,
  "message": {
    "custom[id1,field1]": {
      "code":200,
      "message": true
    },
    "custom[id2,field2]": {
      "code":14106,
      "message": "工单不存在"
    }
  }
}

返回成功或者失败。

# 申领工单

工单在分组内时，可先由组内处理人申领方能继续处理。

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/apply?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":12345,
  "staffId":123
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID
staffId	是	客服ID

响应

{
  "code":200,
  "message": true
}

返回成功或者失败。

# 转交工单

此接口可将工单转交给其他处理人或者客服分组继续处理。

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/transfer?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":12345,
  "staffId":123,
  "comment": "转交他人继续处理",
  "targetGroupId":0,
  "targetStaffId":1,
  "attachments":[
    {
      "fileName":"附件1",
      "type":1,
      "payload":"附件BASE64"
    }
  ]
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID
staffId	是	持有工单的客服ID
targetGroupId	否	目标客服分组
targetStaffId	否	和targetGroupId二选一，目标客服分组
comment	否	评论内容
attachments	否	附件内容，具体含义参阅创建工单

响应

{
  "code":200,
  "message": true
}

返回成功或者失败。

# 回复工单

此接口用于对工单发表回复或添加附件等处理行为。

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/reply?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":12345,
  "staffId":123,
  "comment": "已处理",
  "attachments":[
    {
      "fileName":"附件1",
      "type":1,
      "payload":"附件BASE64"
    }
  ]
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID
staffId	是	持有工单的客服ID
comment	否	评论内容
attachments	否	附件内容，具体含义参阅创建工单

响应

{
  "code":200,
  "message": true
}

返回成功或者失败。

# 催单接口

此接口用于对未完结的工单执行催单操作。

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/reminder?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":12345,
  "staffId":123,
  "comment": "这是催单",
  "attachments":[
    {
      "fileName":"附件1",
      "type":1,
      "payload":"附件BASE64"
    }
  ]
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID
staffId	是	发起催单客服的ID
comment	是	催单内容
attachments	否	催单附件

响应

{
  "code":200,
  "message": 1321
}

返回催单ID。

# 完结工单

此接口用于对已处理完成的工单执行完结操作。

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/finish?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":12345,
  "staffId":123,
  "comment": "已完成",
  "attachments":[
    {
      "fileName":"附件1",
      "type":1,
      "payload":"附件BASE64"
    }
  ]
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID
staffId	是	持有工单的客服ID
comment	否	评论内容
attachments	否	附件内容，具体含义参阅创建工单

响应

{
  "code":200,
  "message": true
}

返回成功或者失败。

# 重新打开工单

此接口可将工单转交给其他处理人或者客服分组继续处理。

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/reopen?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":12345,
  "staffId":123,
  "comment": "转交他人继续处理",
  "targetGroup":0,
  "targetStaff":1
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID
staffId	是	持有工单的客服ID
targetGroup	是	目标客服分组
targetStaff	是	和targetGroupId二选一，目标客服分组
comment	是	评论内容

响应

{
  "code":200,
  "message": true
}

返回成功或者失败。

# 搜索工单

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/search?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":123,
  "mobile":"18668686868",
  "limit":50,
  "offset": 0,
  "sortBy":"ct",
  "order":"asc",
  "start":1498736257082,
  "end":1498736257082,
  "opStart":1498736257082,
  "opEnd":1498736257082,
  "withCustomField":false,
  "uid":"abc175"
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	否	工单ID
mobile	否	用户手机号
limit	否	一次请求获取的工单数上限，最大为50
offset	否	偏移量
sortBy	否	排序方式，默认为"ct"创建时间
order	否	升降序，默认desc，降序
start	否	起始毫秒时间戳（若不传该参数，则默认支持时间跨度为30天）
end	否	截止毫秒时间戳
opStart	否	操作时间起始毫秒时间戳
opEnd	否	操作时间截止毫秒时间戳（不超过90天）
withCustomField	否	是否包含自定义字段信息
uid	否	访客的foreignid

其中自定义字段如果是级联类型的，其fieldValue格式如：

{
  "path": "1级/1.1级",  // 每一级的完整名称
  "idpath": [1555974, 1555977], // 每一级对应的ID
  "id": 1555977 //级联自定义字段ID
}

ticketId和mobile二选一，时间跨度不得超过90天。

响应

{
  "code":200,
  "message":{
    "total":100,
    "tickets":[
      {
        "id":123,
        "staffId":123456,
        "templateId":12345,
        "userName":"大门",
        "userEmail":"a@b.c",
        "userMobile":"18668686868",
        "typeId":11,
        "priority":1,
        "groupId":12345,
        "title":"退货",
        "content":"太好了",
        "status":5,
        "properties":"{}",
        "createTime":1498736257082,
        "custom": [
          {
            "id":111,
            "name":"abc",
            "value":"def"
          }
        ],
        "connectionType": 1,
        "connectionId": 123
      }
    ]
  }
}

响应码为200时，message包含指定用户当前过滤器下的工单数量以及工单列表。其中，id为工单id，staffId为客服ID，templateId为模板ID，userName为用户名，userEmail为邮箱，userMobile为用户手机号，typeId为分类ID，priority为优先级，groupId为客服分组，title为工单标题，content为工单内容，status为工单状态[1]，properties为工单属性，createtime为工单创建时间。该列表按创建时间降序排列，custom为该工单包含的自定义字段，其中id为字段编号，name为字段名，value为字段值，connectionType为关联类型：0=无关联、1=关联会话、2=社媒渠道，connectionId为关联ID。

# 获取工单详情

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/new/detail?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":12345
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID

响应

{
    "code": 200,
    "data": {
        "attachments": [
            {
                "name": "工单附件.xlsx",
                "size": 9847,
                "type": 0,
                "url": "https://qiyukf.net/0426aba4f048f0577de5a69a3ae732c1"
            }
        ],
        "content": "这里记录的是工单的内容",
        "createTime": 1631081162000,
        "crmForeignId": "",
        "crmId": "60d02bd9108bfa001d68c0fc",
        "crmUserEmail": "18888888888@163.com",
        "crmUserName": "张三1",
        "crmUserPhone": "18888888888",
        "custom": [
            {
                "fieldId": 45756,
                "id": 2782984,
                "name": "自定义字段name1",
                "value": "自定义字段1内容"
            },
            {
                "fieldId": 45919,
                "id": 2782985,
                "name": "自定义字段name2",
                "value": "自定义字段2内容"
            }
        ],
        "follower": {
            192054: "李四",
            178669: "超级管理员"
         },
        "fromType": 3,
        "groupId": 1718465,
        "holderCorp": 0,
        "holderId": 191473,
        "id": 12345,
        "isCrossCorp": 0,
        "priority": 5,
        "properties": "",
        "questionType": {
            "id": 1709053,
            "name": "企业name",
            "parent": 1708930,
            "path": "一级分类/二级分类"
        },
        "relationCorp": 0,
        "relationWorksheet": 0,
        "staffId": 178669,
        "status": 10,
        "templateId": 127237,
        "templateName": "模版名称",
        "title": "这是工单标题",
        "typeId": 1709053,
        "userEmail": "",
        "userId": 0,
        "userMobile": "",
        "userName": "",
        "sender": "123@abc.com",
        "foreword": "456@def.com",
        "lastFinishTime": 1631081162000,
        "connectionType": 1,
        "connectionId": 123
    }
}

参数说明如下：

参数	参数说明	备注
content	工单内容
templateName	模版名称
title	工单标题
targetGroup	受理组名称
status	工单状态	查看附录[1]
attachments	附件	name为文件名，url为资源地址，size为文件大小，字节数
createTime	工单创建时间	时间戳
crmForeignId	客户foreignID	用户的uid，如果传了，则作为客户资料的唯一标识，否则使用phone作为唯一标识
crmId	客户id	七鱼系统中的客户id
crmUserEmail	客户邮箱地址	七鱼系统中的客户邮箱地址
crmUserName	客户用户名	七鱼系统中的客户用户名
crmUserPhone	客户手机	七鱼系统中的客户手机
custom	自定义字段	工单里面的自定义字段值
follower	工单关注人
groupId	客服组id	若选择分配到客服组改值不为0
holderCorp	当前受理企业ID	跨企业工单特有
holderId	当前客服ID	跨企业工单需要和holderCorp配合使用
id	工单id
isCrossCorp	跨企业标示	0:企业内工单；1:跨企业工单
priority	优先级	优先级:2=低;5=一般;8=紧急;10=非常紧急
properties	附加属性对
questionType	工单分类
relationCorp	跨企业所关联企业ID	默认为0，只有跨企业工单创建方才会有值
relationWorksheet	跨企业所关联工单ID	跨企业工单特有
staffId	创建工单的客服id
templateId	模板id
typeId	工单分类id
userEmail	用户邮箱
userId	用户ID
userMobile	用户手机
userName	用户姓名
sender	邮件工单发件人
receiver	邮件工单接收邮箱(废弃),用foreword字段代替
foreword	邮件工单接收邮箱
lastFinishTime	最近一次完结时间
fromType	来源渠道	来源渠道：1=工单系统-坐席创建 2=工单系统-接口创建 3=在线会话-坐席创建 4=呼叫通话-坐席创建 41=呼叫通话访客留言创建 5=在线会话-访客自助填写 51=在线会话-坐席邀请访客填写 6=机器人会话-访客自助填写 61=工单系统-工单插件 7=工单系统-表格导入 8=邮件工单 9=社媒工单-googleplay 10=社媒工单-苹果商店 11=社媒工单-facebook
connectionType	关联类型	关联类型： 0=无关联, 1=关联会话, 2=社媒渠道
connectionId	关联ID

# 获取工单日志列表

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/log?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":12345
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID

响应

{
    "code": 200,
    "data": [
        {
            "action": "更新工单",
            "actionType": 123,
            "corpName": "操作方企业名称",
            "id": 1626751,
            "info": [
                {
                    "content": "由 “企业名称1” 更改为 “企业名称2”",
                    "title": "受理企业",
                    "titleLang": "受理企业"
                },
                {
                    "content": "由 “分组名称1” 更改为 “分组名称2”",
                    "title": "受理组",
                    "titleLang": "受理组"
                },
                {
                    "content": "由 “张三” 更改为 “李四”",
                    "title": "受理人",
                    "titleLang": "受理人"
                },
                {
                    "content": "转交备注",
                    "title": "",
                    "titleLang": ""
                }
            ],
            "operator": "超级管理员",
            "operatorCorpId": 89265,
            "operatorId": 178669,
            "time": 1631082000000
        },
        {
            "action": "新建工单",
            "actionLang": "新建工单",
            "actionType": 2,
            "attachments": [
                {
                    "name": "工单附件1.xlsx",
                    "size": 9847,
                    "type": 0,
                    "url": "https://qiyukf.net/0426aba4f048f0577de5a69a3ae732c1"
                }
            ],
            "corpName": "操作方企业名称",
            "id": 1627561,
            "info": [
                {
                    "content": "这是工单标题",
                    "title": "工单标题",
                    "titleLang": "工单标题"
                },
                {
                    "content": "这里记录的是工单的内容",
                    "title": "工单内容",
                    "titleLang": "工单内容"
                },
                {
                    "content": "一级分类/二级分类",
                    "title": "工单分类",
                    "titleLang": "工单分类"
                },
                {
                    "content": "工单模版名称1",
                    "title": "模板类型",
                    "titleLang": "模板类型"
                },
                {
                    "content": "受理中",
                    "title": "工单状态",
                    "titleLang": "工单状态"
                },
                {
                    "content": "一般",
                    "title": "优先级",
                    "titleLang": "优先级"
                },
                {
                    "content": "企业名称1",
                    "title": "受理企业",
                    "titleLang": ""
                },
                {
                    "content": "分组名称1",
                    "title": "受理组",
                    "titleLang": "受理组"
                },
                {
                    "content": "张三",
                    "title": "受理人",
                    "titleLang": "受理人"
                },
                {
                    "content": "",
                    "title": "用户姓名",
                    "titleLang": "用户姓名"
                },
                {
                    "content": "",
                    "title": "邮箱",
                    "titleLang": "邮箱"
                },
                {
                    "content": "",
                    "title": "手机号码",
                    "titleLang": "用户手机"
                }
            ],
            "operator": "超级管理员",
            "operatorCorpId": 89265,
            "operatorId": 178669,
            "time": 1631081162000
        },
      {
        "action": "回复工单",
        "actionLang": "回复工单",
        "actionType": 20,
        "attachments": [
          {
            "name": "工单附件1.xlsx",
            "size": 9847,
            "type": 0,
            "url": "https://qiyukf.net/0426aba4f048f0577de5a69a3ae732c1"
          }
        ],
        "corpName": "操作方企业名称",
        "id": 1627561,
        "info": [
          {
            "content": "回复内容",
            "title": "",
            "titleLang": ""
          }
        ],
        "operator": "超级管理员",
        "operatorCorpId": 89265,
        "operatorId": 178669,
        "time": 1631081162000,
        "customerSee": true
      }
    ]
}

部分参数说明如下：

参数	参数说明	备注
corpName	操作方企业名称	跨企业工单返回操作者所在企业名称
operatorCorpId	操作方企业ID	跨企业工单返回操作者所在企业ID
operator	操作人姓名
operatorId	操作客服ID
actionType	变更操作类型	详细说明见：actionType说明

actionType说明：

int UNDEFINED = 0;
int CREATE = 1;//创建
int CREATE_TO_GROUP_WITH_STAFF = 2;//创建工单时同时指定受理人和受理组
int DISPATCH_TO_GROUP = 5;//转交到组
int DISPATCH_TO_GROUP_WITH_STAFF = 6;//转交到组时同时指定受理人
int DISPATCH_TO_STAFF = 10;//转交

int APPLY = 15;//领取
int DEAL_WITH = 20;//回复\编辑\更新\评论等处理操作
int FINISH = 25;//关闭
int INVITE_EVALUATION = 26;//邀请评价
int EVALUATE = 35;//评价
int FLOW_TO_STAFF = 40;//流转到客服（批准）
int FLOW_TO_GROUP = 45;//流转达客服组（批准）
int REJECT = 50;//驳回工单
int REBORN = 55;//重新发起，已驳回工单发起者重新发起
int REOPEN = 60;//重新打开
int REOPEN_TO_GROUP_WITH_STAFF = 61;//reopen时给最后处理的受理组和受理人

int UPDATE_PATH_NODE_TO_STAFF = 65;//自动流转节点改变导致的重新流转（到人）
int UPDATE_PATH_NODE_TO_GROUP = 70;//自动流转节点改变导致的重新流转（到组）

int MODIFY = 100;//修改工单
int MODIFY_REPLY = 101;//修改工单回复
int AUTO_APPLY = 105;//客服自动接单 自动分配给某一客服
int REMINDER = 110;//催单
int RELATION = 115;//关联工单
int RELATION_CANCEL = 116;//取消关联工单

int DISPATCH_TO_CORP_WITH_GROUP = 121;//转交到其他企业受理组
int DISPATCH_TO_CORP_WITH_GROUP_AND_STAFF = 123;//转交到其他企业受理组和受理人
int DISPATCH_TO_CORP_WITH_STAFF = 124;//转交到其他企业受理人
int DISPATCH_FROM_CORP = 125;//从其他企业转入

int DISPATCH_TO_CORP_WITH_GROUP_FOR_CREATE = 127;//创建并转交到其他企业受理组
int DISPATCH_TO_CORP_WITH_GROUP_AND_STAFF_FOR_CREATE = 128;//转交到其他企业受理组和受理人
int DISPATCH_TO_CORP_WITH_STAFF_FOR_CREATE = 129;//转交到其他企业受理人
int DISPATCH_FROM_CORP_FOR_CREATE = 130;//创建并从其他企业转入
int PENDING = 200;//挂起
int CANCEL_PENDING = 210;//取消挂起

# 获取工单过滤器列表

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/filter/list?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "staffId":12345,
  "status":1
}

接口参数说明如下：

参数	是否必须	参数说明
staffId	否	客服ID不填列举管理员视角的过滤器列表，否则为某个客服视角的过滤器列表
status	否	0=所有，1=已启用的过滤器列表

响应

{
  "code":200,
  "message": [
    {
      "id":123,
      "name":"过滤器名",
      "status":1,
      "crossType":0
    }
  ]
}

返回对应条件的过滤器列表。status取值1=启用，2=已禁用; crossType取值0=企业内过滤器，1=跨企业过滤器。

# 获取过滤器下的工单数量

用以查询某个过滤器下的工单数量

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/filter/count?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "staffId":12345,
  "filterId":123
}

接口参数说明如下：

参数	是否必须	参数说明
staffId	是	客服ID
filterId	是	过滤器ID

响应

{
  "code":200,
  "message": 89757
}

返回对应过滤器下的工单数量。

# 获取过滤器下的工单

POST 请求为：

https://qiyukf.com/openapi/v2/ticket/list?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "staffId":12345,
  "filterId":123,
  "limit":3,
  "offset":0,
  "sortBy": "ct",
  "order":"asc"
}

接口参数说明如下：

参数	是否必须	参数说明
staffId	是	客服ID
filterId	是	过滤器ID
limit	否	一次请求获取的工单数上限，最大为50
offset	否	偏移量
sortBy	否	排序方式，默认为"ct"创建时间
order	否	升降序，默认desc，降序

响应

{
  "code":200,
  "message":{
    "total":100,
    "tickets":[
      {
        "id":123,
        "staffId":123456,
        "templateId":12345,
        "userName":"大门",
        "userEmail":"a@b.c",
        "userMobile":"18668686868",
        "typeId":11,
        "priority":1,
        "groupId":12345,
        "title":"退货",
        "follower":["1111","1112"],
        "content":"太好了",
        "status":5,
        "properties":"{}",
        "createTime":1498736257082,
        "connectionType": 1,
        "connectionId": 123
      }
    ]
  }
}

响应码为200时，message包含指定用户当前过滤器下的工单数量以及工单列表。其中，id为工单id，staffId为客服ID，templateId为模板ID，userName为用户名，userEmail为邮箱，userMobile为用户手机号，typeId为分类ID，priority为优先级，groupId为客服分组，title为工单标题，content为工单内容，status为工单状态[1]，properties为工单属性，createtime为工单创建时间，connectionType为关联类型：0=无关联、1=关联会话、2=社媒渠道，connectionId为关联ID。该列表按创建时间降序排列。

# 获取工单关注人

POST 请求为

https://qiyukf.com/openapi/v2/ticket/followers/update?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":1111,
  "staffId":27663,
  "optype":0,
  "followers":["111","2222"]
}

接口参数说明如下:

参数	是否必须	参数说明
ticketId	是	企业id
staffId	是	操作客服id
optype	是	操作类型0 关注 1 取消关注
followers	是	关注人列表

响应内容:

{
  "code":200,
  "total": 2,
  "message": [{"1111": "kefu1", "2222": "kefu2"}]
}

# 获取工单模板

POST 请求为：

https://qiyukf.com//openapi/v2/ticket/template/list?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "status":1
}

接口参数说明如下：

参数	是否必须	参数说明
status	否	模板状态，-1为全部状态

{
  "code":200,
  "message": [
    {
      "id":12345,
      "name":"模板名",
      "status":1,
      "autoFlow":0,
      "createTime":1498736257082
    }
  ]
}

返回指定状态的工单模板列表。status取0=停用，1=启用，2=已删除。autoFlow为是否自动流转，1=是，0=否。

# 获取工单模板字段

POST 请求为：

https://qiyukf.com//openapi/v2/ticket/template/fields?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "templateId":1
}

接口参数说明如下：

参数	是否必须	参数说明
templateId	是	工单模板ID

{
  "code":200,
  "message": [
    {
      "id":12345,
      "fieldId":123,
      "name":"字段名",
      "required":1,
      "type":1,
      "status":1,
      "description":"字段描述",
      "prefill":"预填值",
      "hint":"暗纹",
      "customer":0
    }
  ]
}

返回指定模板的字段列表。id为自增字段，暂无用处。fieldId为自定义字段id。required=1为必填，0=非必填。type为0=文本，1=单选，2=多选，3=时间控件，6=级联，7=附件。status为0=正常，1=删除。customer访客填写为0=关，1=开。

# 获取级联字段子字段详细信息

POST 请求为：

https://qiyukf.com/openapi/category/get?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "fieldId":1
}

接口参数说明如下：

参数	是否必须	参数说明
fieldId	是	自定义字段ID

{
  "code": 200,
  "data": {
    "result": [
      {
        "id": 2115348,
        "name": "1AAA",
        "children": [
          {
            "id": 2115350,
            "name": "2AAA",
            "children": null,
            "disabled": false,
            "highlight": null,
            "ai": 0,
            "sort": 4,
            "cloud": false
          },
          {
            "id": 2115351,
            "name": "2BBB",
            "children": [
              {
                "id": 2114619,
                "name": "3AAA",
                "children": null,
                "disabled": false,
                "highlight": null,
                "ai": 0,
                "sort": 4,
                "cloud": false
              }
            ],
            "disabled": false,
            "highlight": null,
            "ai": 0,
            "sort": 4,
            "cloud": false
          }
        ],
        "disabled": false,
        "highlight": null,
        "ai": 0,
        "sort": 4,
        "cloud": false
      },
      {
        "id": 2115349,
        "name": "1BBB",
        "children": null,
        "disabled": false,
        "highlight": null,
        "ai": 0,
        "sort": 4,
        "cloud": false
      }
    ],
    "total": 5
  }
}

部分参数说明如下：

参数	参数说明	备注
result.id	级联自定义字段的子集id	用于创建、修改、批量修改接口，自定义字段的value入参
result.name	级联自定义字段子集名字
result.children	当前字段的子集
total	级联字段的子集的总数

# 获取工单满意度评价状态

POST 请求为：

https://qiyukf.com//openapi/worksheet/satisfaction/getEvaluationStatus?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":1
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID

{
  "code": 200,
  "data": {
    "evaluationTxt": "抱歉，评价已完成，不可重复评价！",
    "evaluationStatus": 2  //状态
  }
}

返回指定状态对应关系如下：

evaluationStatus=0; //不可以评价（受规则限制等）
evaluationStatus=1;//可以评价
evaluationStatus=2;//已完成评价
evaluationStatus=3;//已过期
evaluationStatus=4;//已失效（对于工单来说可评价的状态，但是此时评价规则又是关闭的）

# 获取工单满意度评价规则

POST 请求为：

https://qiyukf.com//openapi/worksheet/satisfaction/getRule?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":1
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID

{
  "code": 200,
  "data": {
    "evaluationWay": 4,
    "list": [
      {
        "model": 2,
        "resolvedEnabled": 0,
        "resolvedRequired": 0,
        "settings": [
          {
            "commentRequired": false,
            "name": "满意",
            "tagList": [
              "sdsd",
              "aaa"
            ],
            "tagRequired": false,
            "value": 100
          },
          {
            "commentRequired": false,
            "name": "不满意",
            "tagList": [
              "123131",
              "bbb"
            ],
            "tagRequired": true,
            "value": 1
          }
        ],
        "title": "模式1"
      },
      {
        "model": 3,
        "resolvedEnabled": 0,
        "resolvedRequired": 0,
        "settings": [
          {
            "commentRequired": false,
            "name": "满意",
            "tagList": [],
            "tagRequired": false,
            "value": 100
          },
          {
            "commentRequired": false,
            "name": "一般",
            "tagList": [],
            "tagRequired": false,
            "value": 50
          },
          {
            "commentRequired": false,
            "name": "不满意",
            "tagList": [],
            "tagRequired": false,
            "value": 1
          }
        ],
        "title": "模式2"
      },
      {
        "model": 4,
        "resolvedEnabled": 0,
        "resolvedRequired": 0,
        "settings": [
          {
            "commentRequired": false,
            "name": "非常满意",
            "tagList": [
              "a"
            ],
            "tagRequired": false,
            "value": 100
          },
          {
            "commentRequired": false,
            "name": "满意",
            "tagList": [
              "b"
            ],
            "tagRequired": false,
            "value": 75
          },
          {
            "commentRequired": false,
            "name": "不满意",
            "tagList": [
              "aadsada",
              "sdsda",
              "1123"
            ],
            "tagRequired": true,
            "value": 25
          },
          {
            "commentRequired": true,
            "name": "非常不满意",
            "tagList": [
              "sdsdsdsdsds",
              "aaa"
            ],
            "tagRequired": true,
            "value": 1
          }
        ],
        "title": "模式3"
      },
      {
        "model": 5,
        "resolvedEnabled": 1,
        "resolvedRequired": 1,
        "settings": [
          {
            "commentRequired": false,
            "name": "非常满意",
            "tagList": [
              "非常整洁"
            ],
            "tagRequired": false,
            "value": 100
          },
          {
            "commentRequired": false,
            "name": "满意",
            "tagList": [
              "整洁",
              "小角落不太干净"
            ],
            "tagRequired": false,
            "value": 75
          },
          {
            "commentRequired": true,
            "name": "一般",
            "tagList": [
              "大体过得去",
              "表面干净整洁",
              "觉得少有遗憾",
              "体验一般"
            ],
            "tagRequired": true,
            "value": 50
          },
          {
            "commentRequired": true,
            "name": "不满意",
            "tagList": [
              "脏乱差",
              "不满意的一次体验"
            ],
            "tagRequired": true,
            "value": 25
          },
          {
            "commentRequired": true,
            "name": "非常不满意",
            "tagList": [
              "非常糟糕",
              "无处下脚"
            ],
            "tagRequired": true,
            "value": 1
          }
        ],
        "title": "模式4"
      }
    ],
    "messageDuplicate": "抱歉，评价已完成，不可重复评价！",
    "messageExpired": "抱歉，评价已过有效期！",
    "messageInvite": "请您对我们的工作进行评价！",
    "messageReopen": "抱歉，工单被重新开启，评价失效！",
    "messageThanks": "感谢您对我们的评价！",
    "model": 5,
    "resolvedEnabled": 1,
    "resolvedRequired": 1
  }
}

部分参数说明如下：

参数	参数说明	备注
result.list	规则列表
result.model	表示使用的是哪个模板，对应选用的模板编号
list.model	评价模板编号
list.resolvedEnabled	表示是否展示在界面上	不需要可以忽略
list.resolvedRequired	是否需要勾选已解决	表示是否必填
list.model.settings	评价模板对应的评价规则
list.model.title	评价模板对应的模板名字
list.model.settings.commentRequired	是否需要评论	true:需要; false:不需要;
list.model.settings.name	评价名
list.model.settings.tagList	评价标签
list.model.settings.tagRequired	标签是否需要	true:需要; false:不需要;
list.model.settings.value	评价对应的分值

# 工单满意度评价

POST 请求为：

https://qiyukf.com/openapi/worksheet/satisfaction/clickEvaluation?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":1,
  "evaluationValue":"100",
  "evaluationModel":"5",
  "tagList":"整洁,小角落不太干净",
  "content":"评价内容",
  "evaluationWay":"评价内容",
  "isSolved":"评价内容"
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID
evaluationValue	是	评价分值，0为未评价，1为不满意（二级）或非常不满意，100为满意（二级）或非常满意，50为一般（三级或五级），25为不满意（四级或五级）75为满意（四级或五级）
evaluationModel	是	评价模型，0为未评价，2为二级评价模型，3为三级评价模型，4为四级评价模型，5为五级评价模型
tagList	根据模板规则	评价标签
content	根据模板规则	评价内容
evaluationWay	是	评价方式，从模板中拿
isSolved	根据模板规则	是否已解决，根据模板规则，规则如果是必填，则必填。2=未解决；1=已解决；0=未评价已解决或未解决；

{
  "code": 200,
  "data": true
}

# 获取工单满意度评价结果

POST 请求为：

https://qiyukf.com/openapi/worksheet/satisfaction/getEvaluationWithRule?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "ticketId":1
}

接口参数说明如下：

参数	是否必须	参数说明
ticketId	是	工单ID

{
  "code": 200,
  "data": {
    "evaluation": {
      "attachmentsCount": 0,
      "crmId": "",
      "crossCorpWorksheet": false,
      "evaluationContent": "评价内容",
      "evaluationModel": 5,
      "evaluationStatus": 2,
      "evaluationTags": "非常整洁",
      "evaluationTxt": "MESSAGE_DUPLICATE",
      "evaluationValue": 100,
      "needEvaluation": true,
      "organizerCorp": false,
      "originAuth": false,
      "typeId": 0
    },
    "isResolved": 1
  }
}

部分参数说明如下：

参数	参数说明	备注
evaluationContent	评价内容
evaluationTags	评价标签
evaluationModel	评价模板编号
evaluationStatus	评价状态	参考`获取工单满意度评价状态`接口对应状态关系
evaluationValue	评价模板对应的分值
isResolved	是否解决	2=未解决；1=已解决；0=未评价已解决或未解决；

# 工单推送

# 说明

工单推送: 七鱼向企业(以下称第三方)接口推送工单变更事件
推送时机: 当某一工单被回复、完结等等操作时进行实时推送
接收地址：第三方应该提供一个 http 格式的 url 作为事件接收的地址，如: http://xxxx/receive。请求的Content-Type:application/json;charset=utf-8

为了方便做完整性校验，七鱼请求该 url 时，会在参数中增加 checksum 参数，其具体计算和校验规则参考通用说明-数据校验 (opens new window)
接收参数：七鱼会以【POST】方式推送数据，且所有数据在请求体内，因此你需要看以下关于数据的说明。
注: 当七鱼发现某一工单发生事件变更时会进行实时推送，但是由于数据包在网络中传输等各种原因，因此第三方企业不能以七鱼推送事件的顺序作为工单变更的顺序。应以请求体中的time字段描述的时间为准.

# 请求体说明

以下是推送数据的定义

元数据

目前支持的工单事件及定义
object WorksheetEvent {
  val UNDEFINED = -1      // 未定义
  val CREATE = 0          // 创建工单
  val REPLY = 1           // 回复工单
  val FINISH = 2          // 完结工单
  val TRANSMIT = 3        // 转交工单
  val MODIFY = 4          // 修改工单
  val APPLY = 5           // 申领(分配)工单
  val AUTO_APPLY = 6      // 系统分配工单
  val REBORN = 7          // 重新发起
  val APPROVE = 8         // 批准工单
  val REJECT = 9          // 驳回工单
  val REOPEN = 10         // 重新打开工单
  val REMINDER = 11       // 催单
  val CREATE_CROSS = 12   // 创建跨企业
  val TRANSMIT_CROSS = 13 // 转交跨企业
  val DELETE = 14 //删除工单
  val SLA_PUSH = 15;//SLA推送
  val EVALUATE=35 //工单满意度评价结果
  val PENDING=40 //工单挂起
  val CANCEL_PENDING=41 //工单取消挂起
}

细分的工单事件及定义
object WorksheetSubEvent {
    val UNDEFINED = -1                                   // 未定义
    val CREATE = 0                                       // 创建
    val REBORN_TO_STAFF = 10                             // 重新发起工单给客服
    val REBORN_TO_GROUP = 11                             // 重新发起工单给客服组
    val APPROVE_FLOW_TO_STAFF = 20                       // 批准工单自动流转到客服
    val APPROVE_FLOW_TO_GROUP = 21                       // 批准工单自动流转到客服组
    val APPROVE_UPDATE_PATH_NODE_TO_STAFF = 22           // 自动流转节点变更到客服
    val TRANSMIT_DISPATCH_TO_STAFF = 30                  // 转交给客服
    val TRANSMIT_DISPATCH_TO_GROUP = 31                  // 转交给客服组
    val TRANSMIT_DISPATCH_TO_GROUP_WITH_STAFF = 32       // 转交时指定了客服组组和客服
    val AUTO_APPLY_CREATE = 40                           // 创建时
    val AUTO_APPLY_DISPATCH_TO_GROUP = 41                // 因为自动分配到组导致的自动分配
    val AUTO_APPLY_UPDATE_PATH_NODE_TO_GROUP = 42        // 因为更新模板路径自动分配到组导致的自动分配
    val AUTO_APPLY_REOPEN_TO_GROUP = 43                  // reopen 到组导致的自动分配
    val AUTO_APPLY_CROSS_TO_GROUP = 44                   // 跨企业工单重新打开时候，如果此时之前受理人已被删除，则会触发重新分配的逻辑。
    val MODIFY_CUSTOM = 50                               // 修改自定义字段
    val MODIFY_TITLE = 51                                // 修改标题
    val MODIFY_PRIORITY = 52                             // 修改工单优先级
    val MODIFY_TYPE = 53                                 // 修改工单分类
    val MODIFY_USER_NAME = 54                            // 修改用户信息，姓名
    val MODIFY_USER_PHONE = 55                           // 修改用户信息，手机号
    val MODIFY_USER_EMAIL = 56                           // 修改用户信息，邮箱
}

object Status {
  val UNDEFINED = 0                    // 未定义
  val COMMITTED = 1                    // 已提交
  val WAITING_FOR_BEING_APPLIED = 5;   // 已分配待申领，未受理
  val APPLIED = 10;                    // 已领取/已受理/处理中
  val FINISHED = 20;                   // 完结
  val REJECTED = 25;                   // 已驳回
  val PENDING = 50;                   // 已挂起
}

工单中指定的User对象
class UserVO {
  var name: String = _    // 姓名
  var phone: String = _   // 手机号
  var email: String = _   // 邮箱地址
}

客服对象
class StaffVO {
  var corpId: Long = _    // 企业id
  var id: Long = _        // 客服id
  var name: String = _    // 客服名字
}

客服组对象
class GroupVO {
  var corpId: Long = _    // 企业id
  var id: Long = _        // 组id
  var name: String = _    // 组名字
}

企业对象
class CorpVO {
  var id: Long = _        // 企业id
  var name: String = _    // 企业名字
}


自定义字段对象
class CustomFiledVO {
  var key: String = _      // 字段名
  var value: String = _    // 字段值
}
其中自定义字段如果是级联类型的，其fieldValue格式如：
{
  "path": "1级/1.1级",  // 每一级的完整名称
  "idpath": [1555974, 1555977], // 每一级对应的ID
  "id": 1555977 //级联自定义字段ID
}

工单分类对象
class CategoryVO {
  var id: Long = _        // 分类id
  var name: String = _    // 分类名字
}

模板对象
class TemplateVO {
  var id: Long = _        // 模板id
  var name: String = _    // 模板名字
}

请求体

创建工单时推送的对象
class WorksheetVO{
  val event: Int = WorksheetEvent.CREATE         // 事件类型
  var sheetId: Long = _                          // 工单id
  var title: String = _                          // 工单标题
  var content: String = _                        // 工单内容
  var attachList: List[String] = _               // 附件地址列表
  var creator: StaffVO = _                       // 创建的客服
  var priority: Int = _                          // 优先级
  var toStaff: StaffVO = _                       // 被分配的客服
  var toGroup: GroupVO = _                       // 被分配的组
  var category: CategoryVO = _                   // 工单分类
  var template: TemplateVO = _                   // 工单模板
  var time: Long = _                             // 事件发生的时间
  var user: UserVO = _                           // user对象
  var customFiledList: List[CustomFiledVO] = _   // 自定义字段
  var crmId: String = _                          // 七鱼的客户中心Id
  var status: Int = _                            // 工单状态
  var connectionType: Int = _                    // 关联类型 0=无关联、1=关联会话、2=社媒渠道
  var connectionId: Long = _                     // 关联id
}

跨企业工单 -- 创建工单时推送的对象
class CrossWorksheetVO {
  // 事件类型
  val event: Int = WorksheetEvent.CREATE_CROSS
  // 工单id
  var sheetId: Long = _
  // 工单标题
  var title: String = _
  // 工单内容
  var content: String = _
  // 附件地址列表
  var attachList: util.List[String] = _
  // 创建的客服
  var creator: StaffVO = _
  // 工单状态
  var status: Int = _
  // 优先级
  var priority: Int = _
  // 被分配的企业
  var toCorp: CorpVO = _
  // 被分配的客服
  var toStaff: StaffVO = _
  // 被分配的组
  var toGroup: GroupVO = _
  // 工单分类
  var category: CategoryVO = _
  // 工单模板
  var template: TemplateVO = _
  // 事件发生的时间
  var time: Long = _
  // user对象
  var user: UserVO = _
  // 自定义字段
  var customFiledList: util.List[CustomFiledVO] = _
  // crmId
  var crmId: String = _
  // foreignId
  var foreignId: String = _

  // 上一节点所属企业
  var preCorp: CorpVO = _
  // 上一节点所属客服
  var preStaff: StaffVO = _
  // 上一节点所属分组
  var preGroup: GroupVO = _
}

回复工单事件
class ReplyVO{
  val event: Int = WorksheetEvent.REPLY          // 事件类型
  var sheetId: Long = _                          // 工单id
  var operator: StaffVO = _                      // 事件操作者
  var remark: String = _                         // 备注
  var attachList: List[String] = _               // 附件
  var time: Long = _                             // 事件发生的时间
  var status: Int = _                            // 工单状态
  var customerSee: Boolean = _                        // 是否访客可见
}

修改工单事件
class ModifyVO{
  val event: Int = WorksheetEvent.MODIFY
  var sheetId: Long = _
  var operator: StaffVO = _
  var time: Long = _
  var fieldId: Long = _                         // 自定义字段ID
  var pre: java.lang.Object = _                 // 修改前的值
  var after: java.lang.Object = _               // 修改后的值
  var status: Int = _                           // 工单状态
  var supEvent: Int = _                         // WorksheetSubEvent
}

申领(分配)工单事件
class ApplyVO{
  val event: Int = WorksheetEvent.APPLY
  var sheetId: Long = _
  var operator: StaffVO = _
  var time: Long = _
  var status: Int = _
}

自动分配工单事件
class AutoApplyVO{
  val event: Int = WorksheetEvent.AUTO_APPLY
  var supEvent: Int = _   // WorksheetSubEvent
  var sheetId: Long = _
  var time: Long = _
  var toStaff: StaffVO = _
  var status: Int = _
}

转交工单事件
class TransmitVO{
  val event: Int = WorksheetEvent.TRANSMIT
  var sheetId: Long = _
  var toStaff: StaffVO = _
  var toGroup: GroupVO = _
  var operator: StaffVO = _
  var attachList: List[String] = _
  var remark: String = _
  var time: Long = _
  var status: Int = _
  var foreignId: String = _
}

转交工单事件 -  跨企业工单
class CorpTransmitVO {
  val event: Int = WorksheetEvent.TRANSMIT_CROSS
  var corpId: Long = _
  var sheetId: Long = _
  var operator: StaffVO = _
  var attachList: util.List[String] = _
  var remark: String = _
  var time: Long = _
  //非必然返回，无返回则表示未涉及
  var toCorp: CorpVO = _      //下一个节点所属企业
  var toStaff: StaffVO = _    //下一个节点所属客服
  var toGroup: GroupVO = _    //下一个节点所属分组
  //非必然返回，无返回则表示未涉及
  var preCorp: CorpVO = _     //上一个节点所属企业
  var preStaff: StaffVO = _   //上一个节点所属客服
  var preGroup: GroupVO = _   //上一个节点所属分组
  //工单状态
  var status: Int = _
}

批准工单事件
class ApproveVO{
  val event: Int = WorksheetEvent.APPROVE
  var supEvent: Int = _   // WorksheetSubEvent
  var sheetId: Long = _
  var time: Long = _
  var operator: StaffVO = _
  var toStaff: StaffVO = _
  var toGroup: GroupVO = _
  var attachList: List[String] = _
  var remark: String = _
  var status: Int = _
}

驳回工单事件
class RejectVO{
  val event: Int = WorksheetEvent.REJECT
  var sheetId: Long = _
  var time: Long = _
  var operator: StaffVO = _
  var toStaff: StaffVO = _
  var attachList: List[String] = _
  var remark: String = _
  var status: Int = _
}

已驳回工单发起者重新发起
class RebornVO{
  val event: Int = WorksheetEvent.REBORN
  var supEvent: Int = _   // WorksheetSubEvent
  var sheetId: Long = _
  var time: Long = _
  var operator: StaffVO = _
  var toStaff: StaffVO = _
  var toGroup: GroupVO = _
  var attachList: List[String] = _
  var remark: String = _
  var status: Int = _
}

完结工单事件
class FinishVO{
  val event: Int = WorksheetEvent.FINISH
  var sheetId: Long = _
  var operator: StaffVO = _
  var remark: String = _
  var attachList: List[String] = _
  var time: Long = _
  var status: Int = _
}

已完结工单重新打开
class ReopenVO{
  val event: Int = WorksheetEvent.REOPEN
  var sheetId: Long = _
  var time: Long = _
  var operator: StaffVO = _
  var toStaff: StaffVO = _
  var toGroup: GroupVO = _
  var remark: String = _
  var status: Int = _
  //跨企业工单重新打开-再分配的企业
  var toCorp: CorpVO = _
  //跨企业工单重新打开-再分配前的企业、客服组、客服
  var preCorp: CorpVO = _
  var preStaff: StaffVO = _
  var preGroup: GroupVO = _
}

催单事件
class ReminderVO{
  val event: Int = WorksheetEvent.REMINDER
  var sheetId: Long = _
  var operator: StaffVO = _
  var remark: String = _
  var attachList: util.List[String] = _
  var time: Long = _
  var status: Int = _
}

删除工单事件
class DeleteVO{
  val event: Int = WorksheetEvent.DELETE
  var sheetId: Long = _
  var operator: StaffVO = _
  var remark: String = _
  var time: Long = _
}

工单满意度评价结果
class EvaluateVO {
  val event: Int = WorksheetEvent.EVALUATE   //事件类型
  var sheetId:Long = _                       //工单ID
  var evaluationModel: Int = _               //评价模式
  var evaluationValue: Int = _               //评价结果
  var evaluationTags:String = _              //评价标签
  var evaluationContent:String = _           //评价内容
  var isSolved: Int = _                      //是否解决
}

class SLAPushVO {
  // 事件类型
  val event: Int = WorksheetEvent.SLA_PUSH
  // 工单id
  var sheetId: Long = _
  // SLA ID
  var slaId: Long = _
  // slaName
  var slaName: String = _
  //工单状态
  var status: Int = _
}

// 挂起工单事件
class PendingVO {
  val event: Int = WorksheetEvent.PENDING   //事件类型
  var sheetId: Long = _                     //工单ID
  var operator: StaffVO = _					// 事件操作者
  var remark: String = _					// 备注
  var attachList: List[String] = _			// 附件
  var time: Long = _						// 事件发生的时间
  var status: Int = _						// 工单状态
}

// 取消挂起工单事件
class CancelPendingVO {
  val event: Int = WorksheetEvent.CANCEL_PENDING 		//事件类型
  var sheetId: Long = _									//工单ID
  var operator: StaffVO = _								// 事件操作者
  var remark: String = _								// 备注
  var attachList: List[String] = _						// 附件
  var time: Long = _									// 事件发生的时间
  var status: Int = _									// 工单状态
}

# 工单开放能力

# 说明

开放能力是指，在工单系统中将工单的部分能力开放，能让第三方介入到工单的流程中。目前支持触发器和SLA。

# 触发器开放能力

# 触发器-条件接口

说明：用于触发器中触发工单范围、触发器条件中的条件选项
请求方式：POST
请求字段说明：

参数	类型	参数说明
ticketId	Long	工单id
triggerName	String	触发器名称
triggerId	Long	触发器id

{
    "ticketId":123,
    "triggerName":"触发器名称",
    "triggerId":123
}

响应字段说明：

参数	类型	参数说明
code	Long	响应码 200-代表成功；其他-代表失败
message	String	响应信息
result	Boolean	响应结果 true-满足条件;false-不满足条件

{
    "code":200,
    "message":"success",
    "result":true
}

# 触发器-第三方通知接口

说明：用于触发器中执行操作中的第三方通知
请求方式：POST
请求字段说明：

参数	类型	参数说明
ticketId	Long	工单id
triggerName	String	触发器名称
triggerId	Long	触发器id

{
    "ticketId":123,
    "triggerName":"触发器名称",
    "triggerId":123
}

响应字段说明： (触发器对响应结果不关心，只负责触发；如果要返回结果，可以参考如下格式返回)

参数	类型	参数说明
code	Long	响应码 200-代表成功；其他-代表失败
message	String	响应信息
result	Boolean	响应结果 true-满足条件;false-不满足条件

{
    "code":200,
    "message":"success",
    "result":true
}

# SLA开放能力

# SLA-条件接口

说明：用于SLA服务目标中筛选条件中的条件选项
请求方式：POST
请求字段说明：

参数	类型	参数说明
ticketId	Long	工单id
slaName	String	SLA名称
slaId	Long	SLA的id

{
  "ticketId":12313,
  "slaName":"sla名称",
  "slaId":123
}

响应字段说明：

参数	类型	参数说明
code	Long	响应码 200-代表成功；其他-代表失败
message	String	响应信息
result	Boolean	响应结果 true-满足条件;false-不满足条件

{
    "code":200,
    "message":"success",
    "result":true
}

# SLA-第三方服务目标接口

说明：用于SLA服务目标中选择第三方服务目标设置
请求方式：POST
请求字段说明：

参数	类型	参数说明
ticketId	Long	工单id
slaName	String	SLA名称
slaId	Long	SLA的id
slaNodeType	String	SLA目标节点类型，用于SLA目标节点的区分；比如首次响应，完结等;非必填，若传该值时，代表只返回sla目标节点类型为该值的数据

{
  "ticketId":123123,
  "slaName":"sla名称",
  "slaId":123,
  "slaNodeType":"create"
}

响应字段说明：

参数	类型	是否必填	参数说明
code	Long	Y	响应码 200-代表成功；其他-代表失败
message	String	Y	响应信息
result	ObjectArray	Y	响应结果（对象数据）

result字段说明：

参数	类型	是否必填	参数说明
name	String	Y	sla目标节点名称
type	String	Y	sla目标节点类型
time	List	Y	提醒时间点
reminder	Object	Y	提醒数据

reminder字段说明：

参数	类型	是否必填	参数说明
actionSettings	ObjectArray	Y	提醒渠道
target	Object	Y	提醒对象

actionSettings字段说明：

参数	类型	是否必填	参数说明
action	Long	Y	1-邮件提醒；2-短信提醒；4-站内通知；5-第三方接口通知
value	String	N	第三方接口通知时才有值，比如第三方通知的接口地址

target字段说明：

参数	类型	是否必填	参数说明	备注
target	Boolean	N	受理人	这3个至少得有一个有值
creator	Boolean	N	发起人	这3个至少得有一个有值
custom	Boolean	N	自定义坐席	这3个至少得有一个有值
customTargets	LongArray	N	自定义坐席的id	设置为自定义时，customTargets传坐席id

{
  "code":200,
  "msg":"success",
  "result":[
    {
      "name":"目标1",
      "type":"create",
      "time":1690192205210,
      "reminder":{
        "actionSettings":[
          {
            "action":5,
            "value":"http://abc.com"
          },{
            "action":1
          }
        ],
        "target": {
          "target": true,
          "creator": true,
          "custom": true,
          "customTargets": ["6281062"]
        }
      }
    },
    {
      "name":"目标2",
      "type":"apply",
      "time":1690192205210,
      "reminder":{
        "actionSettings":[
          {
            "action":4
          },{
            "action":1
          }
        ],
        "target": {
          "target": false,
          "creator": false,
          "custom": true,
          "customTargets": ["6281062"]
        }
      }
    }
  ]
}

# SLA-第三方通知接口

说明：用于SLA中提醒节点中的第三方通知
请求方式：POST
请求字段说明：

参数	类型	参数说明
ticketId	Long	工单id
slaName	String	SLA名称
slaId	Long	SLA的id
content	String	工单内容
title	String	工单标题
priority	Long	工单优先级 2-低；5-一般；8-紧急；10-非常紧急
name	String	SLA目标节点名称
responseTime	String	服务目标响应时间；例如n分钟，n小时，n天；只有在系统设置目标里才有这个字段返回；第三方服务目标不会有这个字段

{
  "ticketId":123,
  "slaName":"sla名称",
  "slaId":123,
  "content":"工单内容",
  "title":"工单标题",
  "priority":5,
  "name":"首次响应",
  "responseTime":"2分钟"
}

响应字段说明： (触发器对响应结果不关心，只负责触发；如果要返回结果，可以参考如下格式返回)

参数	类型	参数说明
code	Long	响应码 200-代表成功；其他-代表失败
message	String	响应信息
result	Boolean	响应结果 true-满足条件;false-不满足条件

{
    "code":200,
    "message":"success",
    "result":true
}

# 工单自定义字段同步

# 基本用法

第一步：配置支持同步的字段

登录七鱼客服系统超级管理员账号，在应用 -> 工单系统 -> 工单字段同步，配置字段同步任务。
第二步：字段同步的使用

编辑设置过的字段，触发字段同步功能。
同步地址：第三方应该提供一个 http或https 格式的 url 作为事件接收的地址，如: http://xxxx或https://xxxx。请求的Content-Type:application/json;charset=utf-8

为了方便做完整性校验，七鱼请求该 url 时，会在参数中增加 checksum 参数，其具体计算和校验规则参考通用说明-数据校验 (opens new window)
接收参数：七鱼会以【POST】方式推送数据，且所有数据在请求体内，因此你需要看以下关于数据的说明。

参数名称	类型	说明
fieldId	Long	自定义字段ID
fieldName	String	自定义字段名称
fieldType	String	字段值类型（TEXT：文本；DATEBOX：时间选择器；CHECKBOX:多选框；CASCADE:级联选择框）
fieldValue	String	当前触发字段值

请求示例：当任务触发字段只有一个时：

{
	"worksheet":{
		"fieldId":1,//自定义字段ID
		"fieldName":"触发字段",//自定义字段名称
		"fieldType":"TEXT",//字段值类型：文本内容（包括单选）
		"fieldValue":"fieldValue"//自定义字段当前值
	}
}

或

{
	"worksheet":{
		"fieldId":1,
		"fieldName":"触发字段",
		"fieldType":"DATEBOX",//字段值类型：时间选择器
		"fieldValue":"1606287144574"
	}
}

或

{
	"worksheet":{
		"fieldId":1,
		"fieldName":"触发字段",
		"fieldType":"CHECKBOX",//字段值类型：多选框
		"fieldValue":"选项1;选项2"
	}
}

或

{
	"worksheet":{
		"fieldId":1,
		"fieldName":"触发字段",
		"fieldType":"CASCADE",//字段值类型：级联选择框
		"fieldValue":"{\\"id\\":1030847,\\"path\\":\\"1111/222/333\\",\\"idpath\\":[1030845,1030846,1030847]}"
	}
}

当任务中配置有多个触发字段时，每当触发字段内容被修改，就会将所有的触发条件进行参数拼接，并进行任务触发。fieldValue可能为空。请求参数格式如下：

{
	"worksheet": [{
		"fieldName": "触发字段2",
		"fieldType": "TEXT",
		"fieldValue": "",
		"fieldId": 48104
	}, {
		"fieldName": "触发字段1",
		"fieldType": "TEXT",
		"fieldValue": "触发内容1",
		"fieldId": 46235
	}]
}

返回值示例：

{
	"code":200,
	"result":[{
		"fieldId":2,
		"fieldName":"fieldName1",//字段名称
		"fieldValue":"fieldValue1"//字段值
	},
	{
		"fieldId":3,
		"fieldName":"多选内容",
		"fieldValue":"选项1;选项2"
	}]
}

响应码为200表示请求成功，fieldId或fieldName至少返回其中一项，优先根据fieldId匹配字段。

# 获取工单分类

POST 请求为：

POST https://qiyukf.com/openapi/category/list?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

Content-Type:application/json;charset=utf-8

请求内容示例如下：

{
  "type":2
}

接口参数说明如下：

参数	是否必须	参数说明
type	是	分类类型，2:工单分类（暂不支持其他分类类型）

响应

{
  "code": 200,
  "message": [
    {
      "id": 12345,
      "parentId": 0,
      "name": "母婴",
      "rank": 2
    }
  ]
}

响应码为200时，message即为分类列表。 message为参数说明：

参数	参数说明
id	分类ID
parentId	父类ID，0表示无父分类
name	分类名
rank	同级分类的排序权值

← 机器人短信 →