开放接口V2

版本 说明 日期
2.0.1 接口草案 2017.07.03
2.0.2 创建新增templateId字段 2017.07.11

场景及用途

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

工单的操作严格按照七鱼工单系统的可操作行为来定义接口。

接口鉴权

参阅《消息接口文档》

接口协议

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

创建工单

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,
  "follower":["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
follower 工单关注人
attachments 附件列表
attachments.fileName 附件的文件名,不超过128个字符
attachments.type 附件的类型,1=文件的Base64,目前仅支持此类型
attachments.payload 对应type的内容
customFields 自定义字段
customFields.id 自定义字段的ID
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/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/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 起始毫秒时间戳
end 截止毫秒时间戳
withCustomField 是否包含自定义字段信息

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/apply?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

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

请求内容示例如下:

{
  "ticketId":12345
}

接口参数说明如下:

参数 是否必须 参数说明
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/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": "转交他人继续处理",
  "targetGroupId":0,
  "targetStaffId":1
}

接口参数说明如下:

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

响应

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

返回成功或者失败。

修改工单属性

修改工单部分属性。

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

接口参数说明如下:

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

响应

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

返回成功或者失败。

工单过滤器列表

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/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/staff/list?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

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

请求内容示例如下:

{
  "status":0,
  "role":1
}

接口参数说明如下:

参数 是否必须 参数说明
status 客服状态,默认所有状态
role 客服角色,默认所有角色
{
  "code":200,
  "message": [
    {
      "id":123,
      "username": "登录用户名",
      "realname": "真实姓名",
      "nickname": "昵称",
      "role": 0,
      "phone": "18888888888",
      "email": "some@b.c",
      "status": 1,
      "createtime": 1498736257082,
      "maxServiceCount": 1
    }
  ]
}

返回对客服列表。其中,status取1=正常,2=已删除,3=已停用。role取-1=工单客服,0=普通客服,1=管理员,2=超级管理员。

客服分组列表

POST 请求为:

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

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

请求内容示例如下:

{
  "staff":false
}

接口参数说明如下:

参数 是否必须 参数说明
staff 是否包含客服ID列表,默认不包含
{
  "code":200,
  "message": [
    {
      "id":123,
      "name": "客服分组名",
      "staffIdList": [111,222,333]
    }
  ]
}

返回对客服分组列表。其中staffIdList为该分组下的客服ID列表。

客服分组成员列表

POST 请求为:

https://qiyukf.com/openapi/v2/staff/group/members?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]

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

请求内容示例如下:

{
  "groupId":12345,
  "role":0
}

接口参数说明如下:

参数 是否必须 参数说明
groupId 客服分组ID
role 角色
{
  "code":200,
  "message": [
    {
      "id":123,
      "username": "登录用户名",
      "realname": "真实姓名",
      "nickname": "昵称",
      "role": 0,
      "phone": "18888888888",
      "email": "some@b.c",
      "status": 1,
      "createtime": 1498736257082,
      "maxServiceCount": 1
    }
  ]
}

返回指定客服分组的成员客服列表。其中role取-1=工单客服,0=普通客服,1=管理员,2=超级管理员。

工单模板列表

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,
      "name":"字段名",
      "required":1,
      "type":1,
      "status":1,
      "description":"字段描述"
    }
  ]
}

返回指定模板的字段列表。required=1为必填,0=非必填。type为0=文本,1=单选,2=多选,3=时间控件。status为0=正常,1=删除。

获取工单分类

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即为分类列表,id为分类ID,parentId为父类ID,0表示无父分类,name为分类名,rank为同级分类的排序权值。

错误码

参数 参数说明
200 成功
14001 App Key错误
14002 请求校验失败
14003 时间错误
14004 请求参数错误
14500 内部错误
14100 客服不存在
14101 分类不存在
14102 客服分组不存在
14103 附件个数超出限制
14104 附件大小超出限制
14105 用户不存在
14106 工单不存在
14107 附件大小超出企业总大小限制
14200 不支持的分类类型
16001 服务不可用

附录

[1] 工单状态:1:已提交,5:待申领, 10:处理中,20:已完结