==== 工单(客服)接口 ====
此接口仅供客服使用。
==== JSON格式 ====
^ 名称 ^ 类型 ^ 只读 ^ 必填 ^ 注释 ^
| ticketId | int | 是 | 否 | 工单ID，系统自动生成 |
| url | string | 是 | 否 | 该工单的url地址 |
| subject | string | 否 | 是 | 工单标题 |
| descript | string | 否 | 否 | 工单描述，即第一条工单回复的文本内容 |
| ticketSource | int | 否 | 否 | 工单来源：1--远程，2--聊天，3--呼叫中心，4--留言，5--系统创建 |
| ticketType | int | 否 | 否 | 工单类型：1--问题，2--事务，3--故障，4--任务 |
| priorityLevel | int | 否 | 否 | 工单优先级：1--低，2--正常，3--高，4--紧急 |
| ticketStatus| int | 否 | 是| 工单状态：1--新建，2--已开启，3--待回应，4--已解决，5--自动关闭，6--手动关闭 |
| custUserId| int | 否 | 是 | 联系人ID |
| agentId| int | 否 | 否 | 服务商ID |
| createrId| int | 否 | 否 | 创建人ID |
| servicerUserId| int | 否 | 否 | 客服ID |
| servicerGroupId| int | 否 | 否 | 客服组ID |
| ccUserIdList| string | 否 | 否 | 抄送人ID列表|
|ccGroupIdList| string |否 | 否 |抄送组ID列表|
|ticketTemplateId| int | 否 | 否 | 工单模板ID|
| tagList| string| 否 | 否 | 工单标签列表|
| createDT| date| 是| 否 | 创建时间|
| updateDT| date| 是| 否 | 更新时间|
| custom_fields| array| 否 | 否 | 工单自定义字段|
JSON示例
{
"ticketId": 1,
"url": "https://www.bangwo8.com/api/v1/tickets/1.json",
"subject": "产品咨询",
"description": "帮我吧是什么？",
"ticketSource": 0,
"ticketType": 1,
"priorityLevel": 2,
"ticketStatus": 0,
"custUserId": 121,
"agentId": 37809,
"createrId": 0,
"servicerUserId": 234,
"servicerGroupId": 0,
"ccUserIdList": "123,456,789",
"ccGroupIdList": "2432,3455,2323"
"tagList": "vip客户,普通客户",
"createDT": "2017-05-04 14:08:22",
"updateDT": "2017-05-04 14:08:22",
"custom_fields": [
{
"key": "field_1",
"value": "4334"
},
{
"key": "field_3",
"value": "1" //复选框
},
{
"key": "field_2",
"value": "下拉菜单的某一项"
},
{
"key": "field_4",
"value": "附件的下载地址" //附件多个时，以逗号分隔
}
]
}
==== 工单列表 ====
GET /api/v1/tickets.json
查询参数
^ 名称 ^ 必要的 ^ 类型 ^注释 ^
| created_start | 否 | string | 按创建时间查询：开始时间 |
| created_end | 否 | string | 按创建时间查询：结束时间 |
| updated_start | 否 | string | 按更新时间查询：开始时间 |
| updated_end | 否 | string | 按更新时间查询：结束时间 |
| created_order | 否 | string | 按创建时间排序：asc（升序），desc（降序） |
| updated_order | 否 | string | 按更新时间排序：asc（升序），desc（降序） |
| status_order | 否 | string | 按工单状态排序：asc（升序），desc（降序）|
| page | 否 | number | 页码，默认为 1 |
| per_page | 否 | number | 每页大小，默认为 100 |
//说明：默认按编码升序返回。时间参数（created_start、created_end、updated_start、updated_end）格式为“2012-01-01 00:00:00”。//
调用者权限
管理员
也可以使用下面的接口
/*查看服务商下某个客户的工单*/
GET /api/v1/companys/{company_id}/tickets.json
/*查看服务商下某个客户的某个联系人的工单*/
GET /api/v1/users/{user_id}/tickets.json
调用示例
curl https://www.bangwo8.com/api/v1/tickets.json \
-v -u {account}:{password}
返回值示例
Status: 200 OK
{
"tickets": [
{
"ticketId": 110,
"subject": "产品咨询",
...
},
{
"ticketId": 111,
"subject": "产品服务",
...
}
]
}
==== 查看工单 ====
GET /api/v1/tickets/{id}.json
调用者权限
管理员
调用示例
curl https://www.bangwo8.com/api/v1/tickets/{id}.json \
-v -u {account}:{password}
返回示例
Status: 200 OK
{
"ticket": {
"ticketId": 110,
"subject": "产品咨询",
...
}
}
==== 查看多个工单 ====
GET /api/v1/tickets/show_many.json?ids={ids}
//说明：工单id要以逗号分隔。此接口最多返回100个工单。//\\
调用者权限
管理员
调用示例
curl https://www.bangwo8.com/api/v1/tickets/show_many.json?ids=110,111,112 \
-v -u {account}:{password}
返回值示例
Status: 200 OK
{
"tickets": [
{
"ticketId": 110,
"subject": "产品咨询",
...
},
{
"ticketId": 111,
"subject": "产品服务"
...
},
...
]
}
==== 创建工单 ====
POST /api/v1/tickets.json
调用者权限
管理员
请求参数
^ 名称 ^ 类型 ^ 必须的 ^描述^
| subject | string |是 |工单标题|
| ticketReply | object |是 | 工单描述，请参考[[:工单:工单回复|工单回复]]|
| custUserId| int|否 | 联系人id，说明该工单是为该客户解决问题|
| custUser| object|否 | 联系人信息|
| createrId | int|否 | 创建人id|
| servicerUserId| int|否 | 受理客服id|
| servicerGroupId| int|否 | 受理客服组id|
| ccUserIdList| string|否 | 抄送客服id列表|
| ccGroupIdList| string|否 | 抄送客服组id列表|
| ticketSource| int|否 | 工单来源：1--远程，2--聊天，3--呼叫中心，4--留言，5--系统创建|
| ticketType| int|否 |工单类型：1--问题，2--事务，3--故障，4--任务|
| priorityLevel| int|否 | 工单优先级：1--低，2--正常，3--高，4--紧急|
| ticketStatus| int|否 | 工单状态：1--新建，2--已开启，3--待回应，4--已解决，5--自动关闭，6--手动关闭|
| ticketTemplateId| int |否 |如果需要传工单来源、类型、优先级、状态或者自定义字段，则必须传该字段值|
| tagList| int|否 | 工单标签列表，以逗号分隔|
| custom_fields| array|否 | 工单自定义字段|
custUser参数说明 \\
//目前支持的联系人信息有mobilephone、name、fixnumber、qq、email，如果要使用该参数，则mobilephone是必需的，其余是选填项。如果数据库里没有该联系人信息，则会自动创建。//
"custUser":{
"mobilephone": 13240138438,
"name": "张三" ,
"fixnumber": "010-63701717" ,
"qq": "601100987" ,
"email": "bangwo8@126.com" ,
}
自定义字段说明 \\
//key是字段的唯一标识，可从“帮我吧后台-》工单自定义字段”查看；value是该字段的具体值。//
"custom_fields": [
{
"key": "field_1",
"value": "文本框内容"
},
{
"key": "field_2",
"value": "下拉框的某选项"
}
]
上传工单附件 \\
//工单附件包含两种类型：自定义字段类型的附件和工单回复里的附件。无论是哪种类型的附件，都需要先调用[[:工单:工单回复|工单回复]]里的上传附件接口，调用成功后，系统会返回相应的附件token，然后将参数置位此token即可。//
/*自定义字段附件*/
"custom_fields": [
{
"key": "field_4", //附件自定义字段的唯一标识
"value": "11234af5467818a7865weq,34523af5467818a7865wer" //token
}
]
/*工单回复里的附件*/
"ticketReply": {
"attachments": [
"11234af5467818a7865weq", //附件1的token
"34243rt5644334a6755sda" //附件2的token
]
}
调用示例
curl https://www.bangwo8.com/api/v1/tickets.json \
-d '{"ticket": {"subject": "产品咨询", "ticketReply": { "replyMsg":"你好，我想咨询下帮我吧产品" }}}' \
-H "Content-Type: application/json" -v -u {account}:{password} -X POST
返回值示例
Status: 201 Created
Location: https://www.bangwo8.com/api/v1/tickets/{id}.json
{
"ticket": {
"ticketId": 110,
"subject": "产品咨询",
...
}
}
==== 更新工单 ====
PUT /api/tickets/v1/{id}.json
调用者权限
所有客服
请求参数
^ 名称 ^ 类型 ^ 必需的 ^描述^
| ticketReply | object |是 | 工单描述，请参考[[:工单:工单回复|工单回复]]|
| servicerUserId| int|否 | 受理客服id|
| servicerGroupId| int|否 | 受理客服组id|
| ccUserIdList| int|否 | 抄送客服id列表，如果是抄送的客服分组，则传客服分组id，多个id之间以逗号分隔|
| ticketSource| int|否 | 工单来源：1--远程，2--聊天，3--呼叫中心，4--留言，5--系统创建|
| ticketType| int|否 |工单类型：1--问题，2--事务，3--故障，4--任务|
| priorityLevel| int|否 | 工单优先级：1--低，2--正常，3--高，4--紧急|
| ticketStatus| int|否 | 工单状态：1--新建，2--已开启，3--待回应，4--已解决，5--自动关闭，6--手动关闭|
| ticketTemplateId | int | 否 | 如果需要更新工单来源、类型、优先级、状态或者自定义字段，则必须传该字段值|
| tagList| int|否 | 工单标签列表，以逗号分隔|
| custom_fields| array|否 | 工单自定义字段|
调用示例
curl https://www.bangwo8.com/api/v1/tickets/{id}.json \
-H "Content-Type: application/json" \
-d '{"ticket": {"ticketStatus": "open", "ticketReply": { "replyMsg": "这里是工单回复文本内容", "replyUserId": 233434 }}}' \
-v -u {account}:{password} -X PUT
返回值示例
Status: 200 OK
{
"ticket": {
"ticketId": 123,
"subject": "这里是工单标题",
"ticketStatus": "已解决",
...
}
}
====更新多个工单====
PUT /api/v1/tickets/update_many.json
PUT /api/v1/tickets/update_many.json?ids={ids}
//说明：一次最多更新100个工单//
调用权限
所有客服
调用示例 \\
//对不同的工单进行相同的处理，调用下面的接口：//
PUT /api/v1/tickets/update_many.json?ids=111,222,333
{
"ticket": {
"ticketStatus": "已解决"
}
}
//对不同的工单进行不同的处理，调用下面的接口：//
PUT /api/v1/tickets/update_many.json
{
"tickets": [
{ "ticketId": 111, "ticketStatus": "已解决" },
{ "ticketId": 222, "ticketStatus": "待回应" }
]
}
返回值示例
Status: 200 OK
{
"results": [
{
"ticketId": 111,
"success": false,
"error_log": "字段值不合法"
},
{
"ticketId": 222,
"success": true,
"error_log": ""
}
]
}
====搜索工单====
GET /api/v1/tickets/search.json
调用权限
所有客服
请求参数
^名称 ^类型 ^必需的 ^注释 ^
|query |string |是 |搜索内容|
|sort_by |string | 否 |按时间排序，目前支持：createDT-创建时间，updateDT-更新时间|
|sort_order| string | 否 | 按升序还是降序返回，取值为：asc-升序，desc-降序，默认为降序|
query参数说明
^搜索内容 ^返回结果 ^
|query=2444 | 模糊搜索，返回工单编号、工单标题或者联系人姓名包含该内容的工单|
|query=status:已开启，已解决| 搜索|
|query=field_1:454 | 返回自定义字段唯一标识为“field_1”的内容里面包含“454”的工单|
|query=2444 createDT>2017-07-01|返回工单编号、工单标题或者联系人姓名包含该内容的工单，并且创建时间是2017年7月1日以后的|
|query=status:已开启，已解决 createDT<=2017-07-01|返回工单状态为已开启或已解决的工单，并且创建时间是2017年7月1日以前的，包含2017年7月1日当天|
|query=status:已开启，已解决 updateDT>=2017-07-01|返回工单状态为已开启或已解决的工单，并且更新时间是2017年7月1日以后的，包含2017年7月1日当天|
//说明：当query参数增加了时间的过滤条件时，两个条件之间要以空格分开，比如“status:已开启，已解决 updateDT>=2017-07-01”//
调用示例
curl "https://www.bangwo8.com/api/v1/tickets/search.json" \
-G --data-urlencode "query=status:已解决 createDT>2017-07-03" \
-v -u {account}:{password}
返回值示例
Status: 200 OK
{
"results": [
{
"subject": "这里是工单标题",
"createDT": "2009-05-13 10:07:08",
"updateDT": "2011-07-22 11:11:12",
"ticketId": 211,
"url": "https://www.bangwo8.com/api/v1/tickets/211.json"
},
{
"subject": "这里是工单标题",
"createDT": "2010-07-13 10:07:08",
"updateDT": "2011-07-13 11:11:12",
"ticketId": 122,
"url": "https://www.bangwo8.com/api/v1/tickets/122.json"
},
...
],
"next_page": "https://www.bangwo8.com/api/v1/tickets/search.json?query=\"status:已开启\"&sort_by=createDT&sort_order=desc&page=2",
"prev_page": null,
"count": 1234
}