工单系统

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

接口鉴权

接口鉴权参考通用说明-数据校验

接口协议

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

错误码

参数 参数说明
200 成功
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:已完结

创建工单

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",
  "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":"恩"
    }
  ]
}

接口参数说明如下:

参数 是否必须 参数说明
title 工单标题,不超过30个字符
uid 开发者的应用里的用户ID,不超过64个字符
typeId 分类ID,0表示未分类
content 工单内容,不超过3000个字符
userName 用户姓名,不超过128个字符
userMobile 用户联系方式,不超过128个字符
userEmail 用户联系邮箱,不超过255个字符
targetStaffId 指定客服ID
targetGroupId 指定客服分组ID
staffId 托管客服ID
priority 优先级,5=一般;8=紧急;10=非常紧急
templateId 模板ID
followerIds 工单关注人
attachments 附件列表
attachments.fileName 附件的文件名,不超过128个字符
attachments.type 附件的类型,1=文件的Base64,目前仅支持此类型
attachments.payload 对应type的内容
customFields 自定义字段, 暂不支持级联类型自定义字段
customFields.id 自定义字段的ID,对应获取工单模板字段接口返回的fieldId字段
customFields.value 自定义字段的值
properties 附加属性对,json格式,不超过1024个字符
  • userMobile和userEmail二者必填其一;
  • targetStaffId和targetGroupId二者必填其一;
  • 创建一个工单时最多可以添加5个附件,其中二进制格式的附件总大小不得超过5MB。

响应

{
  "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,
  "value":"值"
}

接口参数说明如下:

参数 是否必须 参数说明
ticketId 工单ID
staffId 持有工单的客服ID
type 修改类型,0=自定义字段,1=标题,2=优先级,3=分类
customId type=0时,填写自定义字段ID,否则填0, 暂不支持级联类型自定义字段
value 新值

响应

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

返回成功或者失败。

申领工单

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

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": true
}

返回成功或者失败。

完结工单

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

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,
  "withCustomField":false
}

接口参数说明如下:

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

其中自定义字段如果是级联类型的,其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"
          }
        ]
      }
    ]
  }
}

响应码为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为字段值。

获取工单详情

POST 请求为:

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

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

请求内容示例如下:

{
  "ticketId":12345
}

接口参数说明如下:

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

响应

{
  "code":200,
  "message":{
     "id":123,
     "staffId":123456,
     "templateId":12345,
     "userName":"大门",
     "userEmail":"a@b.c",
     "userMobile":"18668686868",
     "typeId":11,
     "priority":1,
     "groupId":12345,
     "title":"退货",
     "content":"太好了",
     "follower":["111","1112"],
     "status":5,
     "properties":"{}",
     "createTime":1498736257082,
     "comments":[
       {
         "staffId":111,
         "comment":"abc",
         "timestamp":1498736257082,
         "attachments": [
           {
             "name":"a.jpg",
             "url":"http://download.from/he.re",
             "size":123
           }
         ]
       }
     ],
     "custom": [
       {
         "id":111,
         "name":"abc",
         "value":"def"
       }
     ],
     "attachments": [
       {
         "name":"b.jpg",
         "url":"http://download.from/the.re",
         "size":345
       }
     ]
   }
}

message字段为工单详情,具体含义可参阅上文,其中新增comments和attachments字段。comments中staffId为评论客服ID,评论内容,评论时间,和附件。attachments中name为文件名,url为资源地址,size为文件大小,字节数。

获取工单过滤器列表

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
    }
  ]
}

返回对应条件的过滤器列表。status取值1=启用,2=已禁用。

获取过滤器下的工单数量

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

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
      }
    ]
  }
}

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

获取工单关注人

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=时间控件。status为0=正常,1=删除。customer访客填写为0=关,1=开。

工单推送

说明

  • 工单推送: 七鱼向企业(以下称第三方)接口 推送工单变更事件

  • 推送时机: 当某一工单被回复、完结等等操作时进行实时推送

  • 接收地址: 第三方应该提供一个 http 格式的 url 作为事件接收的地址,如: http://xxxx/receive。 请求的Content-Type:application/json;charset=utf-8

    为了方便做完整性校验,七鱼请求该 url 时,会在参数中增加 checksum 参数,其具体计算和校验规则 参考 通用说明-数据校验

  • 接收参数: 七鱼会以【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       // 催单
}

细分的工单事件及定义
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 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;                   // 已驳回
}

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

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

客服组对象
class GroupVO {
  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 = _                            // 工单状态
}

回复工单事件
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 = _                            // 工单状态
}

修改工单事件
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 = _
}

批准工单事件
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 = _
}

催单事件
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 = _
}

工单自定义字段同步

基本用法

  • 第一步:配置支持同步的字段

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

  • 第二步:字段同步的使用

    编辑设置过的字段,触发字段同步功能。

  • 同步地址: 第三方应该提供一个 http或https 格式的 url 作为事件接收的地址,如: http://xxxx或https://xxxx。 请求的Content-Type:application/json;charset=utf-8

    为了方便做完整性校验,七鱼请求该 url 时,会在参数中增加 checksum 参数,其具体计算和校验规则 参考 通用说明-数据校验

  • 接收参数: 七鱼会以【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]}"
	}
}

返回值示例:

{
	"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 同级分类的排序权值