侧边栏

文档首页


CRM扩展

数据接口

呼叫能力

Android IM SDK手册(暂停使用)

iOS IM SDK手册(暂停使用)

Android SIP SDK手册

iOS SIP SDK手册

客户端标准版快速集成

帮我吧远程SDK版本

网页在线客服集成

微信接入

帮我吧文档:数据接口:工单:工单

工单列表

请求参数

名称 必要的 类型 注释
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 每页大小,默认为 10

说明:默认按编码升序返回。时间参数(created_start、created_end、updated_start、updated_end)格式为“2012-01-01 00:00:00”。

分页:数据返回条数太多时,会自动分页,默认每页100条,可以在请求url里更改per_page参数的值来自定义每页返回的条数,建议不要超过100条,因为会影响接口返回速度。 当请求的数据个数超过per_page参数值时,可设置自增的page参数继续请求下一页数据。

请求地址

GET  http://www.bangwo8.com/api/v1/tickets.json

也可以使用下面的接口

/*查看服务商下某个客户的工单*/
GET http://www.bangwo8.com/api/v1/companies/{company_id}/tickets.json
/*查看服务商下某个客户的某个联系人的工单*/
GET http://www.bangwo8.com/api/v1/users/{user_id}/tickets.json

调用者权限

管理员

调用示例

(若看不懂,请先看一下开发向导

curl  -X GET -v -u {account}:{password} https://www.bangwo8.com/api/v1/tickets.json?created_start=2020-06-08 10:27:07

返回参数

名称 类型 必填 描述
ticketId int 工单id,系统自动生成
custUserId int 联系人id,说明该工单是为该客户解决问题
subject String 工单标题
descript String 工单描述
servicerUserId int 受理客服id(如果想置空需要传0)
ccUserIdList string 抄送客服id列表
ticketType int 工单类型:1–问题,2–事务,3–故障,4–任务
priorityLevel int 工单优先级:1–低,2–正常,3–高,4–紧急
tagList int 工单标签列表,以逗号分隔
ticketStatus int 工单状态:1–新建,2–已开启,3–待回应,4–已解决,5–自动关闭,6–手动关闭
createDT datetime 工单创建时间
updateDT datetime 工单更新时间
solveDT datetime 解决时间
waitDT datetime 等待时间
openDT datetime 开启时间
closeDT datetime 关闭时间
servicerGroupId int 受理客服组id
createrId int 工单创建人id
createrType int 工单创建人类型,0-客服 1-客户
agentId int 关联agents表aId
ticketSource int 工单来源:1–远程,2–聊天,3–呼叫中心,4–留言,5–系统创建,6-其他,7–API,8–工单模板发布,9–邮件接入,10-其他服务商,11-工单工作台,12-手动导入,13-客户管理自动化任务,14-帮我吧APP
ticketTemplateId int 工单模板id,创建工单需指明当前工单使用哪个工单模板
ccGroupIdList string 抄送客服组id列表
customTemplateId int 客户模板id
rootTicket int 该工单关联哪单,填写想关联工单的工单号即可(显示在后台会显示拆自此单,工单来源为API)
createrType String 创建类型
currentNodeField String
currentNodeFieldValue String
nodeFieldIntoTime String
queryIDs String
custom_fields array 工单自定义字段
tables array 工单中的普通表单、评价表单
count int 所有工单数量
next_page String 下一页地址
previous_page String 下一页地址

返回值示例

Status: 200 OK
{
"tickets": [
        {
            "ticketId": "4350556",
            "custUserId": "21064351",
            "subject": "201910010091",
            "descript": "",
            "servicerUserId": "0",
            "ccUserIdList": "",
            "ticketType": "0",
            "priorityLevel": "0",
            "tagList": "",
            "ticketStatus": "1",
            "createDT": "2019-09-30 10:13:02",
            "updateDT": "2019-09-30 10:13:02",
            "solveDT": "",
            "waitDT": "",
            "openDT": "",
            "closeDT": "",
            "servicerGroupId": "127213",
            "createrId": "529379",
            "agentId": "373063",
            "ticketSource": "5",
            "ticketTemplateId": "15",
            "rootTicket":"4360708",
            "ccGroupIdList": "",
            "customTemplateId": "0",
            "createrType": "0",
            "currentNodeField": "",
            "currentNodeFieldValue": "",
            "nodeFieldIntoTime": "0",
            "queryIDs": ",17,,2,,41,,43,",
            "custom_fields": [
                {
                    "key": "field_59",
                    "value": "智一销售"
                },
                {
                    "key": "field_60",
                    "value": "腾衍慧"
                },
                {
                    "key": "field_69",
                    "value": [
                        {
                            "field_1": "20109029",
                            "field_2": "QDP1016B",
                            "field_4": "台",
                            "field_5": "2.0000000000",
                            "rowId": "1"
                        }
                    ]
                },
                {
                    "key": "field_87",
                    "value": [
                        {
                            "field_1": "20109029",
                            "field_2": "QDP1016B",
                            "field_4": "台",
                            "field_5": "2.0000000000",
                            "rowId": "1"
                        }
                    ]
                },
                {
                    "key": "field_88",
                    "value": ""
                }
            ]
        },
        {
            "ticketId": "4350601",
            "custUserId": "21064363",
            "subject": "201910010052",
            "descript": "",
            "servicerUserId": "0",
            "ccUserIdList": "",
            "ticketType": "0",
            "priorityLevel": "0",
            "tagList": "",
            "ticketStatus": "1",
            "createDT": "2019-09-30 10:17:02",
            "updateDT": "2019-09-30 10:17:02",
            "solveDT": "",
            "waitDT": "",
            "openDT": "",
            "closeDT": "",
            "servicerGroupId": "127213",
            "createrId": "529379",
            "agentId": "373063",
            "ticketSource": "5",
            "ticketTemplateId": "15",
            "rootTicket":"",
            "ccGroupIdList": "",
            "customTemplateId": "0",
            "createrType": "0",
            "currentNodeField": "",
            "currentNodeFieldValue": "",
            "nodeFieldIntoTime": "0",
            "queryIDs": ",17,,2,,41,,43,",
            "custom_fields": [
                {
                    "key": "field_16",
                    "value": ""
                },
                {
                    "key": "field_68",
                    "value": ""
                },
                {
                    "key": "field_69",
                    "value": [
                        {
                            "field_1": "20109153",
                            "field_2": "QDP2126B",
                            "field_4": "台",
                            "field_5": "4.0000000000",
                            "rowId": "1"
                        },
                        {
                            "field_1": "20109015",
                            "field_2": "QDP1020B",
                            "field_4": "台",
                            "field_5": "3.0000000000",
                            "rowId": "2"
                        }
                    ]
                },
                {
                    "key": "field_87",
                    "value": [
                        {
                            "field_1": "20109153",
                            "field_2": "QDP2126B",
                            "field_4": "台",
                            "field_5": "4.0000000000",
                            "rowId": "1"
                        },
                        {
                            "field_1": "20109015",
                            "field_2": "QDP1020B",
                            "field_4": "台",
                            "field_5": "3.0000000000",
                            "rowId": "2"
                        },
                        {
                            "field_1": "20109217",
                            "field_2": "QDP1022A",
                            "field_4": "台",
                            "field_5": "4.0000000000",
                            "rowId": "3"
                        }
                    ]
                },
                {
                    "key": "field_114",
                    "value": ""
                }
            ]
        }
     ],
    "count":1456,
    "next_page":"https://www.bangwo8.com/api/v1/tickets.json?per_page=40&page=2",
    "previous_page":null
}

查看工单

请求参数

名称 只读 必选 类型 说明
ticketId int 工单id

请求地址

GET   /api/v1/tickets/{ticketId}_v2.json //说明:id为工单id  

调用者权限

  管理员

调用示例

(若看不懂,请先看一下开发向导

curl https://www.bangwo8.com/api/v1/tickets/4360708_v2.json
  -v -u {account}:{password}

返回参数

名称 类型 必填 描述
ticketId int 工单id,系统自动生成
custUserId int 联系人id,说明该工单是为该客户解决问题
subject String 工单标题
descript String 工单描述
servicerUserId int 受理客服id
ccUserIdList string 抄送客服id列表
ticketType int 工单类型:1–问题,2–事务,3–故障,4–任务
priorityLevel int 工单优先级:1–低,2–正常,3–高,4–紧急
tagList int 工单标签列表,以逗号分隔
ticketStatus int 工单状态:1–新建,2–已开启,3–待回应,4–已解决,5–自动关闭,6–手动关闭
createDT datetime 工单创建时间
updateDT datetime 工单更新时间
solveDT datetime 解决时间
waitDT datetime 等待时间
openDT datetime 开启时间
closeDT datetime 关闭时间
servicerGroupId int 受理客服组id
createrId int 工单创建人id
agentId int 关联agents表aId
ticketSource int 工单来源:1–远程,2–聊天,3–呼叫中心,4–留言,5–系统创建,7–API,8–工单模板发布,9–邮件接入
ticketTemplateId int 工单模板id,创建工单需指明当前工单使用哪个工单模板
ccGroupIdList string 抄送客服组id列表
customTemplateId int 客户模板id
createrType String 创建类型
currentNodeField String
currentNodeFieldValue String
nodeFieldIntoTime String
queryIDs String
rootTicket int 该工单关联哪单,填写想关联工单的工单号即可(显示在后台会显示拆自此单,工单来源为API)
custom_fields array 工单自定义字段

返回值示例

Status: 200 OK
{
    "ticket": [
        {
            "ticketId": "4360708",
            "custUserId": "21088717",
            "subject": "遗留",
            "descript": "",
            "servicerUserId": "529999",
            "ccUserIdList": "",
            "ticketType": "0",
            "priorityLevel": "0",
            "tagList": "",
            "ticketStatus": "1",
            "createDT": "2019-10-02 14:33:55",
            "updateDT": "2019-10-11 09:53:57",
            "solveDT": "",
            "waitDT": "",
            "openDT": "",
            "closeDT": "",
            "servicerGroupId": "127413",
            "createrId": "529711",
            "agentId": "373063",
            "ticketSource": "11",
            "ticketTemplateId": "9",
            "ccGroupIdList": "",
            "customTemplateId": "3",
            "createrType": "0",
            "currentNodeField": "",
            "currentNodeFieldValue": "",
            "nodeFieldIntoTime": "0",
            "queryIDs": ",2,,21,,29,,31,,33,,35,,41,,61,,39,",
            "rootTicket":"",
            "custom_fields": [
                {
                    "key": "field_33",
                    "value": "sign0"
                },
                {
                    "key": "field_56",
                    "value": "1142216"
                },
                {
                    "key": "field_58",
                    "value": "滨江珑湖国际3-1602"
                },
                {
                    "key": "field_59",
                    "value": "分销"
                },
                {
                    "key": "field_61",
                    "value": "曹贵森"
                },
                {
                    "key": "field_66",
                    "value": "1618A 噪音比较大 有安装单"
                },
                {
                    "key": "field_69",
                    "value": []
                },
                {
                    "key": "field_6",
                    "value": [
                        {
                            "field_1": "普通表单",
                            "field_2": "8002",
                            "field_3": "081",
                            "create_time": "",
                            "update_time": "",
                            "rowId": "1",
                            "EAVRowId": "1"  //表单数据的唯一id,可用于修改对应的表单数据
                        }
                    ]
                },
                {
                    "key": "field_88",
                    "value": "2019-10-03"
                },
                {
                    "key": "field_95",
                    "value": "分销部"
                },
                {
                    "key": "field_103",
                    "value": "1333129"
                },
                {
                    "key": "field_104",
                    "value": "1333229"
                },
                {
                    "key": "field_112",
                    "value": ""
                },
                {
                    "key": "field_113",
                    "value": "否"
                }
            ]
        }
    ]
}

查看工单(旧)

请求参数

名称 只读 必选 类型 说明
ticketId int 工单id,系统自动分配

请求地址

GET /api/v1/tickets/{ticketId}.json  //说明:id为工单id  

说明:与查看工单接口的调用方式、传参方式均一致,只是返回值格式不太一样,具体请看“返回值示例”。

调用者权限

  管理员

调用示例

(若看不懂,请先看一下开发向导

curl https://www.bangwo8.com/api/v1/tickets/4360708.json
-v -u {account}:{password}

返回参数

名称 类型 必填 描述
ticketId int 工单id,系统自动生成
custUserId int 联系人id,说明该工单是为该客户解决问题
subject String 工单标题
descript String 工单描述
servicerUserId int 受理客服id
ccUserIdList string 抄送客服id列表
ticketType int 工单类型:1–问题,2–事务,3–故障,4–任务
priorityLevel int 工单优先级:1–低,2–正常,3–高,4–紧急
tagList int 工单标签列表,以逗号分隔
ticketStatus int 工单状态:1–新建,2–已开启,3–待回应,4–已解决,5–自动关闭,6–手动关闭
createDT datetime 工单创建时间
updateDT datetime 工单更新时间
solveDT datetime 解决时间
waitDT datetime 等待时间
openDT datetime 开启时间
closeDT datetime 关闭时间
servicerGroupId int 受理客服组id
createrId int 工单创建人id
agentId int 关联agents表aId
ticketSource int 工单来源:1–远程,2–聊天,3–呼叫中心,4–留言,5–系统创建,7–API,8–工单模板发布,9–邮件接入
ticketTemplateId int 工单模板id,创建工单需指明当前工单使用哪个工单模板
ccGroupIdList string 抄送客服组id列表
customTemplateId int 客户模板id
createrType String 创建类型
currentNodeField String
currentNodeFieldValue String
nodeFieldIntoTime String
queryIDs String
custom_fields array 工单自定义字段

返回值示例

Status: 200 OK
{
    "ticket": {
        "ticketId": "4360708",
        "custUserId": "21088717",
        "subject": "遗留",
        "descript": "",
        "servicerUserId": "529999",
        "ccUserIdList": "",
        "ticketType": "0",
        "priorityLevel": "0",
        "tagList": "",
        "ticketStatus": "1",
        "createDT": "2019-10-02 14:33:55",
        "updateDT": "2019-10-11 09:53:57",
        "solveDT": "",
        "waitDT": "",
        "openDT": "",
        "closeDT": "",
        "servicerGroupId": "127413",
        "createrId": "529711",
        "agentId": "373063",
        "ticketSource": "11",
        "ticketTemplateId": "9",
        "ccGroupIdList": "",
        "customTemplateId": "3",
        "createrType": "0",
        "currentNodeField": "",
        "currentNodeFieldValue": "",
        "nodeFieldIntoTime": "0",
        "queryIDs": ",2,,21,,29,,31,,33,,35,,41,,61,,39,",
        "custom_fields": [
            {
                "key": "field_16",
                "value": ""
            },
            {
                "key": "field_28",
                "value": ""
            },
            {
                "key": "field_30",
                "value": ""
            },
            {
                "key": "field_32",
                "value": ""
            },
            {
                "key": "field_33",
                "value": "sign0"
            },
            {
                "key": "field_56",
                "value": "1142216"
            },
            {
                "key": "field_58",
                "value": "滨江珑湖国际3-1602"
            },
            {
                "key": "field_59",
                "value": "分销"
            },
            {
                "key": "field_61",
                "value": "曹贵森"
            },
            {
                "key": "field_66",
                "value": "1618A 噪音比较大 有安装单"
            },
            {
                "key": "field_69",
                "value": []
            },
            {
                "key": "field_74",
                "value": ""
            },
            {
                "key": "field_81",
                "value": ""
            },
            {
                "key": "field_87",
                "value": []
            },
            {
                "key": "field_88",
                "value": "2019-10-03"
            },
            {
                "key": "field_89",
                "value": ""
            },
            {
                "key": "field_90",
                "value": ""
            },
            {
                "key": "field_95",
                "value": "分销部"
            },
            {
                "key": "field_103",
                "value": "1333129"
            },
            {
                "key": "field_104",
                "value": "1333229"
            },
            {
                "key": "field_112",
                "value": ""
            },
            {
                "key": "field_113",
                "value": "否"
            },
            {
                "key": "field_115",
                "value": "否"
            }
        ]
    }
}

查看多个工单

请求参数

名称 只读 必选 类型 说明
ticketId int 工单id

请求地址

GET /api/v1/tickets/show_many.json?ids={ids}  //ids为多个工单id,以逗号分隔

说明:工单id要以逗号分隔。此接口最多返回100个工单。

调用者权限

  管理员

调用示例

(若看不懂,请先看一下开发向导

curl http://www.bangwo8.com/api/v1/tickets/show_many.json?ids=3759835,3758879 
 -v -u {account}:{password}

返回参数

名称 类型 必填 描述
ticketId int 工单id,系统自动生成
custUserId int 联系人id,说明该工单是为该客户解决问题
subject String 工单标题
descript String 工单描述
servicerUserId int 受理客服id
ccUserIdList string 抄送客服id列表
ticketType int 工单类型:1–问题,2–事务,3–故障,4–任务
priorityLevel int 工单优先级:1–低,2–正常,3–高,4–紧急
tagList int 工单标签列表,以逗号分隔
ticketStatus int 工单状态:1–新建,2–已开启,3–待回应,4–已解决,5–自动关闭,6–手动关闭
createDT datetime 工单创建时间
updateDT datetime 工单更新时间
solveDT datetime 解决时间
waitDT datetime 等待时间
openDT datetime 开启时间
closeDT datetime 关闭时间
servicerGroupId int 受理客服组id
createrId int 工单创建人id
agentId int 关联agents表aId
ticketSource int 工单来源:1–远程,2–聊天,3–呼叫中心,4–留言,5–系统创建,7–API,8–工单模板发布,9–邮件接入
ticketTemplateId int 工单模板id,创建工单需指明当前工单使用哪个工单模板
ccGroupIdList string 抄送客服组id列表
customTemplateId int 客户模板id
createrType String 创建类型
currentNodeField String
currentNodeFieldValue String
nodeFieldIntoTime String
queryIDs String
custom_fields array 工单自定义字段

返回值示例

Status: 200 OK
{
    "tickets": [
        {
            "ticketId": "3758879",
            "custUserId": "19519071",
            "subject": "更换滤芯工单",
            "descript": "",
            "servicerUserId": "520177",
            "ccUserIdList": "",
            "ticketType": "4",
            "priorityLevel": "0",
            "tagList": "",
            "ticketStatus": "4",
            "createDT": "2019-07-23 09:33:44",
            "updateDT": "2019-07-26 15:03:32",
            "solveDT": "2019-07-26 15:03:32",
            "waitDT": "",
            "openDT": "",
            "closeDT": "",
            "servicerGroupId": "0",
            "createrId": "520177",
            "agentId": "369029",
            "ticketSource": "11",
            "ticketTemplateId": "3",
            "ccGroupIdList": "",
            "customTemplateId": "2",
            "createrType": "0",
            "currentNodeField": "",
            "currentNodeFieldValue": "",
            "nodeFieldIntoTime": "0",
            "queryIDs": "",
            "custom_fields": []
        },
        {
            "ticketId": "3759835",
            "custUserId": "19513171",
            "subject": "ceshi",
            "descript": "",
            "servicerUserId": "0",
            "ccUserIdList": "",
            "ticketType": "0",
            "priorityLevel": "0",
            "tagList": "",
            "ticketStatus": "4",
            "createDT": "2019-07-23 10:36:07",
            "updateDT": "2019-07-26 15:03:31",
            "solveDT": "2019-07-26 15:03:31",
            "waitDT": "",
            "openDT": "",
            "closeDT": "",
            "servicerGroupId": "0",
            "createrId": "520177",
            "agentId": "369029",
            "ticketSource": "0",
            "ticketTemplateId": "2",
            "ccGroupIdList": "",
            "customTemplateId": "2",
            "createrType": "0",
            "currentNodeField": "",
            "currentNodeFieldValue": "",
            "nodeFieldIntoTime": "0",
            "queryIDs": "",
            "custom_fields": []
        }
    ]
}

没有权限返回示例

Status:403 Forbidden
{
    "status": "19003",
    "message": "No relevant permissions"
}

创建工单

请求参数

名称 类型 必须的 描述
subject string 工单标题
descript string 工单描述
custUserId int 联系人id,说明该工单是为该客户解决问题
custUser object 联系人信息
createrId int 工单创建人id
createrType int 工单创建人类型,0-客服 1-客户,不传此参数默认为0
servicerUserId int 受理客服id
servicerGroupId int 受理客服组id
ccUserIdList string 抄送客服id列表
ccGroupIdList string 抄送客服组id列表
ticketSource int 工单来源:1–远程,2–聊天,3–呼叫中心,4–留言,5–系统创建,7–API,8–工单模板发布,9–邮件接入
ticketType int 工单类型:1–问题,2–事务,3–故障,4–任务
priorityLevel int 工单优先级:1–低,2–正常,3–高,4–紧急
ticketStatus int 工单状态:1–新建,2–已开启,3–待回应,4–已解决,5–自动关闭,6–手动关闭
ticketTemplateId int 工单模板id,创建工单需指明当前工单使用哪个工单模板
tagList int 工单标签列表,以逗号分隔
lockKey string 帮我吧中添加幂等锁的字段的唯一标识
lockValue string 需要锁判断的字段的具体值,该值将被放入缓存,在5s内该参数值重复将不会重复创建工单。
custom_fields array 工单自定义字段(可自定义类型:下拉列表,单行文本,多行文本,正整数,小数,复选框,高级复选框,日期,验证码,表单,附件,级联,地址位置)
tables array 工单自定义表单数据(仅支持普通表单和评价表单,不支持资产表)
isAppraise int 评价表单中的是否评价,1-已评价 0-未评价

请求地址

POST /api/v1/tickets.json

调用者权限

管理员

custUser参数说明

目前支持的联系人信息有mobilephone、name、fixnumber、qq、email、companyid,如果要使用该参数,则mobilephone是必需的,其余是选填项。如果数据库里没有该联系人信息,则会自动创建。当传companyid时,是为了绑定这个公司和这个手机号为当前工单的客户信息,要确认该companyid的公司下已经绑定该手机号,如果未绑定: companyid存在于此服务商,创建工单失败 提示:The phone number is not correct; companyId存在于其他服务商 创建工单失败 提示:The phone number is not correct; companyid错误id,不存在的或者不是数字 创建工单失败 提示:The phone number is not correct 当不传companyid时,则默认绑定该手机号绑定的第一家公司为当前工单的客户信息

"custUser":{ 
	"mobilephone": 13240138438,
	"name": "张三" ,
	"fixnumber": "010-63701717" ,
	"qq": "601100987" ,
	"email": "bangwo8@126.com" ,
        "companyid":"2349"
}

自定义字段说明

key是字段的唯一标识,可从“帮我吧后台如下图中查看自定义字段的唯一标识;value是该字段的具体值。

"custom_fields":[
     {
      "key": "field_1",
      "value": "文本框内容"
     },
     {
      "key": "field_2",
      "value": "下拉框的某选项"
     }
    ]

上传工单附件

工单附件包含两种类型:自定义字段类型的附件和工单回复里的附件。上传附件有两种方式:
说明:传的附件会将原有的附件全量覆盖,请谨慎使用
方式一:直接将附件地址上传(该地址需要是https协议地址),附件名称fileName一定要有后缀,后缀与附件的格式是一样的。

 "custom_fields":[{
              "key": "zhuandanfujian",//附件自定义字段唯一标识
                  "value":[
                  {
                      "fileName":"file1.org", //命名需要有后缀才能在工单中正确显示
                      "fileUrl":"https://huixing.org" 
                  }, 
                  {
                      "fileName":"file2.org",
                      "fileUrl":"https://huixing.org" 
                  }
                  ]
          }]

方式二:先调用工单附件里的上传附件接口,调用成功后,系统会返回相应的附件token,然后将返回的token配置到value对应值即可。

/*自定义字段附件*/
"custom_fields": [
    {
            "key": "field_4", //附件自定义字段的唯一标识
            "value": "15761b339251466e9fec23698503eb53,
            12343b339251466e9fec23698503eb54" //上传附件接口返回的token
        }
]
/*工单回复里的附件*/
"ticketReply": {
        "attachments": [
           "15761b339251466e9fec23698503eb53", //附件1的token
           "12343b339251466e9fec23698503eb54" //附件2的token
        ]
}

创建带普通表单类型的工单

表单类型的字段与普通自定义字段传值方式不一样,不在“custom_fields”进行传值,而是在“tables”里传值,“tables”与“custom_fields”是并列关系,在创建表单数据时返回数据中会有一个curId,最好把每行数据curId存储,以便后期在调用更新工单的表单数据时根据curId进行更新表单数据。

"tables":[
        {
            "custom_fields_key":"",//工单表单字段的唯一标识
            "tableData":[
                {//第一行数据
                    "cpdm":"001.005",
                    "cpmc":"铺助面板",
                    "zjm":"PZMB",
                    "ggxh":"A6020青古"
                },
                {//第二行数据
                    "cpdm":"001.005",
                    "cpmc":"铺助面板",
                    "zjm":"PZMB",
                    "ggxh":"A6020青古"
                }
            ]
        }
    ]

创建带评价表单的工单

{
    "ticket":{
        "subject":"工单名字",
        "ticketTemplateId":"8",
        "custom_fields":[
            "field_30":"是"
        ],
        "tables":[
            {
                "custom_fields_key":"field_25",
                "tableData":[
                    {
                        "fwtd":"5",
                        "isAppraise":"1",    //该参数值为1时是“已评价”状态
                        "fwzl":"5",
                        "qlxc":"5",
                        "field_2":"评价",
                        "jsxx":"5",
                        "key":"field_3",
                        "value":[
                            {
                                "fileName":"1640312200299.jpg",
                                "fileUrl":"https://shenbin-xiaojin.f.wmeimob.com/upload/20211224/1640312200299.jpg"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

级联字段可以通过选项内容传值也可以通过外部扩展id传值
选项内容传值:

{
    "ticket": {
        "subject": "API推送级联",
        "ticketTemplateId": "8",
        "custom_fields": [
            {
                "key": "question",
                "value": "1"
            },
            {
                "key": "field_4",
                "value": [
                    "北京市",
                    "海淀区",
                    "中关村"
                ]
            }
        ]
    }
}

通过外部扩展id传值:

{
    "ticket": {
        "subject": "API推送级联",
        "ticketTemplateId": "8",
        "custom_fields": [
            {
                "key": "question",
                "value": "1"
            },
            {
                "key": "field_4",
                "value": [
                    "1",
                    "11",
                    "111"
                ],
                "valtype": "extetnal_id"
            }
        ]
    }
}

复选框字段
普通复选框:0为置空,1为选中

{
    "ticket": {
        "subject": "API推送复选框",
        "ticketTemplateId": "8",
        "custom_fields": [
            {
                "key": "field_29",
                "value": "1"
            }
        ]
    }
}

高级复选框:两种方式,传选项id,或者传外部扩展id

{
    "ticket": {
        "subject": "API推送级联",
        "ticketTemplateId": "8",
        "custom_fields": [
            {
                "key": "field_4",
                "value": "356786,367528"
            },
            {
                "key": "field_5",
                "value":"01,02,03",
                "valtype": "extetnal_id"
            }
        ]
    }
}

调用示例

curl

curl https://www.bangwo8.com/api/v1/tickets.json \
  -d  '{
    "ticket":{
        "subject":"测试",
        "ticketTemplateId":"4",
        "ticketReply": {
            "replyType":2,
            "replyMsg":"测试"
        },
        "custUser":{
            "mobilephone":"150****6428",
            "name":"小雅"
        },
        "custom_fields":[
            {
                "key":"field_3",
                "value":"AMS"
            },
            {
                "key":"field_5",
                "value": "本地部署"
            },
            {
                "key":"field_112",
                "value":"新需求"
            },
            {
                "key":"field_1",
                "value":"问题详情"
            },
            {
                "key":"field_8",
                "value":"解决方案"
            },
            {
                "key":"field_9",
                "value":"新建"
            },
            {
                "key":"carbon_copy",
                "value":"293345@qq.com"
            }
        ]
    }
}
' 
  -H "Content-Type: application/json"
  -v -u {account}:{password} 
  -X POST

java 说明:添加Header头Authorization时,账号密码格式为:账号:密码,需要用base64进行加密后写入,即.addHeader(“Authorization”, “Basic 加密后的账号:密码”)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"ticket\": {\r\n        \"subject\"\"测试\",\r\n        \"ticketTemplateId\"\"4\",\r\n        \"ticketReply\": {\r\n            \"replyType\": 2,\r\n            \"replyMsg\"\"测试\"\r\n        },\r\n        \"custUser\": {\r\n            \"mobilephone\"\"15010796428\",\r\n            \"name\":\"任文雅\"\r\n        },\r\n        \"custom_fields\": [\r\n            {\r\n                \"key\"\"field_3\",\r\n                \"value\"\"AMS\"\r\n            },\r\n            {\r\n                \"key\"\"field_5\",\r\n                \"value\"\"本地部署\"\r\n            },\r\n            {\r\n                \"key\"\"field_112\",\r\n                \"value\"\"新需求\"\r\n            },\r\n            {\r\n                \"key\"\"field_1\",\r\n                \"value\"\"问题详情\"\r\n            },\r\n            {\r\n                \"key\"\"field_8\",\r\n                \"value\"\"解决方案\"\r\n            },\r\n            {\r\n                \"key\"\"field_9\",\r\n                \"value\"\"新建\"\r\n            },\r\n            {\r\n                \"key\"\"carbon_copy\",\r\n                \"value\"\"293345@qq.com\"\r\n            }\r\n        ]\r\n    }\r\n}");
Request request = new Request.Builder()
  .url("https://www.bangwo8.com/api/v1/tickets.json")
  .method("POST", body)
  .addHeader("Authorization""Basic YmpnZW53YW5nOmExMjM0NTY=")
  .addHeader("Content-Type""application/json")
  .build();
Response response = client.newCall(request).execute();

返回参数

名称 类型 必填 描述
ticketId int 工单id,系统自动生成
subject string 工单标题
ticketReply object 工单描述
custUserId int 联系人id,说明该工单是为该客户解决问题
custUser object 联系人信息
servicerUserId int 受理客服id
servicerGroupId int 受理客服组id
ccUserIdList string 抄送客服id列表
ccGroupIdList string 抄送客服组id列表
ticketSource int 工单来源:1–远程,2–聊天,3–呼叫中心,4–留言,5–系统创建,7–API,8–工单模板发布,9–邮件接入
ticketType int 工单类型:1–问题,2–事务,3–故障,4–任务
priorityLevel int 工单优先级:1–低,2–正常,3–高,4–紧急
ticketStatus int 工单状态:1–新建,2–已开启,3–待回应,4–已解决,5–自动关闭,6–手动关闭
ticketTemplateId int 工单模板id,创建工单需指明当前工单使用哪个工单模板
createrId int 创建人id
tagList int 工单标签列表,以逗号分隔
lockValue string 帮我吧中添加幂等锁字段的唯一标识
lockValue string 需要锁判断的字段的具体值,该值将被放入缓存,在5s内该参数值重复将不会重复创建工单。
custom_fields array 工单自定义字段(包含自定义表单)

返回值示例

Status: 200 OK
Location: https://www.bangwo8.com/api/v1/tickets/{id}.json
{
    "ticket": {
        "ticketId": "13309903",
        "custUserId": "32161762",
        "subject": "测试",
        "descript": "",
        "servicerUserId": "952726",
        "ccUserIdList": "",
        "ticketType": "0",
        "priorityLevel": "0",
        "tagList": "",
        "ticketStatus": "1",
        "createDT": "2020-12-23 13:14:15",
        "updateDT": "2020-12-23 13:14:15",
        "solveDT": "",
        "waitDT": "",
        "openDT": "",
        "closeDT": "",
        "servicerGroupId": "0",
        "createrId": "952726",
        "agentId": "587413",
        "ticketSource": "7",
        "ticketTemplateId": "4",
        "ccGroupIdList": "",
        "customTemplateId": "0",
        "createrType": "0",
        "currentNodeField": "",
        "currentNodeFieldValue": "",
        "nodeFieldIntoTime": "0",
        "queryIDs": "",
        "workflow_node_id": "",
        "workflow_id": "0",
        "custom_fields": [
            {
                "key": "field_1",
                "value": "问题详情"
            },
            {
                "key": "field_3",
                "value": "3296950"
            },
            {
                "key": "field_5",
                "value": "3298234"
            },
            {
                "key": "field_8",
                "value": "解决方案"
            },
            {
                "key": "field_9",
                "value": "3415675"
            },
            {
                "key": "field_19",
                "value": ""
            },
            {
                "key": "field_20",
                "value": ""
            },
            {
                "key": "field_112",
                "value": "4185970"
            },
            {
                "key": "carbon_copy",
                "value": "293345@qq.com"
            }
        ]
    }
}

添加幂等锁后触发锁机制返回参数

{
    "code": "40000",
    "message": "请2秒后再试",
    "data": {
        "lockKey": "field_167",
        "lockValue": "123123",
        "expAt": "1687760000"  //幂等锁解锁时间戳
    }
}

删除工单

请求地址

DELETE  /api/v1/tickets/{tid}.json

调用者权限

管理员

调用示例

(若看不懂,请先看一下开发向导

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/tickets/18738405.json \
  -H "Content-Type: application/json"
  -X DELETE

返回参数

{
    "ticketId": "18738405",
    "success": "true"
}

更新工单

请求参数

名称 类型 必填 描述
ticketId int 工单id,系统自动分配
subject string 工单标题
descript string 工单描述
ticketReply object 工单回复
custUserId int 联系人id,说明该工单是为该客户解决问题
servicerUserId int 受理客服id
servicerGroupId int 受理客服组id
ccUserIdList string 抄送客服id列表
ccGroupIdList string 抄送客服组id列表
ticketSource int 工单来源:1–远程,2–聊天,3–呼叫中心,4–留言,5–系统创建,7–API,8–工单模板发布,9–邮件接入
ticketType int 工单类型:1–问题,2–事务,3–故障,4–任务
priorityLevel int 工单优先级:1–低,2–正常,3–高,4–紧急
ticketStatus int 工单状态:1–新建,2–已开启,3–待回应,4–已解决,5–自动关闭,6–手动关闭
ticketTemplateId int 工单模板id,创建工单需指明当前工单使用哪个工单模板
tagList int 工单标签列表,以逗号分隔
custom_fields array 工单自定义字段
tables array 工单自定义表单数据(仅支持普通表单,不支持资产表)
isSubmit string 该参数=N时,可控制工单提交但不触发触发器,param类型参数,直接拼接在链接后即可

请求地址

PUT /api/v1/tickets/{ticketId}.json

调用者权限

所有客服

调用示例

如需置空单行文本和下拉字段,请传“NULL”字符串

curl

curl https://www.bangwo8.com/api/v1/tickets/3232.json?isSubmit=N \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": {
        "subject": "测试",
        "ticketReply": {
            "replyType": 2,
            "replyMsg": "测试更新工单",
            "attachment":[
                {
                    "fileName":"11111.txt",
                    "filePath":"https://bangwo8.oss-cn-shenzhen.aliyuncs.com/874731/edm5ms5y26.txt" 
                },
                {
                    "fileName":"file1.png",
                    "filePath":"https://i.loli.net/2021/11/16/y58tisB2JuWoVLG.png" 
                }
            ]
        },
        "tables": [
            {
                "custom_fields_key": "field_6",
                "tableData": [
                    {
                        "field_1": "测试",
                        "field_2": "8002",
                        "field_3": "081",
                        "EAVRowId": "1"  //此参数为非必填参数,不加此参数时,更新表单为全覆盖操作;添加此参数,则只更新id对应的表单内容
                    }
                ]
            }
        ],
        "custom_fields": [
            {
                "key": "field_3",
                "value": "FAS"
            },
            {
                "key": "field_9",
                "value": "客服处理中"
            }
        ]
    }
}' \
  -v -u {account}:{password} -X PUT

java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"ticket\": {\r\n        \"subject\"\"测试\",\r\n        \"ticketReply\": {\r\n            \"replyType\": 2,\r\n            \"replyMsg\"\"测试更新工单\"\r\n        },\r\n        \"custom_fields\": [\r\n            {\r\n                \"key\"\"field_3\",\r\n                \"value\"\"FAS\"\r\n            },\r\n            {\r\n                \"key\"\"field_9\",\r\n                \"value\"\"客服处理中\"\r\n            }\r\n        ]\r\n    }\r\n}");
Request request = new Request.Builder()
  .url("https://www.bangwo8.com/api/v1/tickets/13309903.json")
  .method("PUT", body)
  .addHeader("Authorization""Basic YmpnZW53YW5nOmExMjM0NTY=")
  .addHeader("Content-Type""application/json")
  .addHeader("Cookie""acw_tc=2760826716087004557644411e46a13fe0355ef463e7fd47ad8adbb5e198d2; TFAPICLNTID=95fdc9683793f9a1afaa2a83b90f0b04")
  .build();
Response response = client.newCall(request).execute();

返回参数

名称 类型 必填 描述
ticketId int 工单id,系统自动分配
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 String 联系人id,说明该工单是为该客户解决问题
agentId String
createrId String 创建人ID
servicerUserId int 受理客服id
servicerGroupId int 受理客服组id
ccUserIdList String 抄送客服id列表,多个id之间以逗号分隔
ccGroupIdList String 抄送客服组id列表,多个id之间以逗号分隔
ticketTemplateId int 工单模板ID
tagList Stirng 工单标签列表,以逗号分隔
createDT date 工单创建时间
updateDT date 工单更新时间
custom_fields array 工单自定义字段

返回值示例

Status: 200 OK
{
    "ticket": {
        "ticketId": "13309903",
        "custUserId": "32161762",
        "subject": "测试",
        "descript": "",
        "servicerUserId": "952726",
        "ccUserIdList": "",
        "ticketType": "0",
        "priorityLevel": "0",
        "tagList": "",
        "ticketStatus": "1",
        "createDT": "2020-12-23 13:14:15",
        "updateDT": "2020-12-23 13:20:08",
        "solveDT": "",
        "waitDT": "",
        "openDT": "",
        "closeDT": "",
        "servicerGroupId": "0",
        "createrId": "952726",
        "agentId": "587413",
        "ticketSource": "7",
        "ticketTemplateId": "4",
        "ccGroupIdList": "",
        "customTemplateId": "0",
        "createrType": "0",
        "currentNodeField": "",
        "currentNodeFieldValue": "",
        "nodeFieldIntoTime": "0",
        "queryIDs": "",
        "workflow_node_id": "",
        "workflow_id": "0",
        "custom_fields": [
            {
                "key": "field_1",
                "value": "问题详情"
            },
            {
                "key": "field_3",
                "value": "3296953"
            },
            {
                "key": "field_5",
                "value": "3298234"
            },
            {
                "key": "field_8",
                "value": "解决方案"
            },
            {
                "key": "field_9",
                "value": "3415678"
            },
            {
                "key": "field_19",
                "value": ""
            },
            {
                "key": "field_20",
                "value": ""
            },
            {
                "key": "field_112",
                "value": "4185970"
            },
            {
                "key": "carbon_copy",
                "value": "293345@qq.com"
            }
        ]
    }
}

更新多个工单

请求参数

名称 类型 必填 描述
ticketId int 工单id,系统自动分配
subject string 工单标题
ticketReply object 工单描述,请参考工单回复
custUserId int 联系人id,说明该工单是为该客户解决问题
custUser object 联系人信息
servicerUserId int 受理客服id
servicerGroupId int 受理客服组id
ccUserIdList string 抄送客服id列表
ccGroupIdList string 抄送客服组id列表
ticketSource int 工单来源:1–远程,2–聊天,3–呼叫中心,4–留言,5–系统创建,7–API,8–工单模板发布,9–邮件接入
ticketType int 工单类型:1–问题,2–事务,3–故障,4–任务
priorityLevel int 工单优先级:1–低,2–正常,3–高,4–紧急
ticketStatus int 工单状态:1–新建,2–已开启,3–待回应,4–已解决,5–自动关闭,6–手动关闭
ticketTemplateId int 工单模板id,创建工单需指明当前工单使用哪个工单模板
tagList int 工单标签列表,以逗号分隔
custom_fields array 工单自定义字段

请求地址

PUT /api/v1/tickets/update_many.json?ids={ids} //ids为多个工单id,以逗号分隔//说明:一次最多更新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": "3" },
    { "ticketId": 222, "ticketStatus": "2" }
  ]
}

返回参数

名称 类型 必填 描述
ticketId int 工单id,系统自动分配
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 String 当前客服
agentId String
createrId String
servicerUserId int 受理客服id
servicerGroupId int 受理客服组id
ccUserIdList String 抄送客服id列表,多个id之间以逗号分隔
ccGroupIdList String 抄送客服组id列表,多个id之间以逗号分隔
ticketTemplateId int 工单模板ID
tagList Stirng 工单标签列表,以逗号分隔
createDT date 工单创建时间
updateDT date 工单更新时间
custom_fields array 工单自定义字段

返回值示例

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=ticketStatus:2,4 搜索工单状态为已开启或已解决的工单
query=field_1:454 返回自定义字段唯一标识为“field_1”的内容里面包含“454”的工单,454是该字段的值
query=uId:9516936 返回公司uId为“9516936”的所有工单
query=2444 createDT>2017-07-01 返回工单编号、工单标题或者联系人姓名包含该内容的工单,并且创建时间是2017年7月1日以后的
query=ticketStatus:2,4 createDT< =2017-07-01 返回工单状态为已开启或已解决的工单,并且创建时间是2017年7月1日以前的,包含2017年7月1日当天
query=ticketStatus:2,4 updateDT>=2017-07-01 返回工单状态为已开启或已解决的工单,并且更新时间是2017年7月1日以后的,包含2017年7月1日当天
时间相关字段 字段含义
createDT 创建时间
updateDT 修改时间
waitDT 等待时间
solveDT 解决时间
openDT 开启时间
closeDT 关闭时间

说明:

1、暂不支持搜索内容本身带有空格

2、当query参数增加了时间的过滤条件时,两个条件之间要以空格分开,比如“ticketStatus:2,4 updateDT>=2017-07-01”

3、时间过滤条件目前支持以下几种方式:(以createDT为例)

createDT<2017-09-01 //过滤2017-09-01之前的工单,不包含2017-09-01当天
createDT>2017-09-01 //过滤2017-09-01之后的工单,不包含2017-09-01当天
createDT:2017-09-01 //过滤2017-09-01当天的工单
createDT<=2017-09-01 //过滤2017-09-01之前的工单,包含2017-09-01当天
createDT>=2017-09-01 //过滤2017-09-01之后的工单,包含2017-09-01当天
solveDT>=2021-07-01 solveDT< =2021-11-01 //过滤2021-07-01之后到2021-11-01的工单,包含2021-07-01当天和2021-11-01当天

调用示例

(若看不懂,请先看一下开发向导

curl "https://www.bangwo8.com/api/v1/tickets/search.json" \
  -G --data-urlencode "query=ticketStatus:4 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
}

拆单

请求参数

名称 必要的 类型 注释
ticketId number 需要拆单的工单号
separatedCount number 需要拆成多少个工单

请求地址

POST  /api/v1/splitTicket.json

调用者权限

管理员

请求示例

curl https://172.18.152.248/api/v1/splitTicket.json -d '{"ticketId":248727,"separatedCount":2}' -H "Content-Type: application/json" -v -u { account}:{password} -X POST

返回示例

返回成功

{
    "status": "200",
    "message": "Successful",
    "data": {
        "separatedTicketIds": "21238876,21238879,21238882",
        "separatedCount": "3"
    }
}

返回失败

Status: 403 Forbidden 
{
   "errorCode": "110043",//错误码,不同的错误码代表不同的错误信息 
   "errorMsg": "The ticket has been separated."//错误信息
}

错误码说明

错误码 说明
110041 参数为空
110042 拆分个数必须为1~15
110043 此工单已被拆单
110044 被拆出来的工单无法继续拆分
110045 拆分失败
110046 没有权限操作此工单或工单不存在
110047 参数不能为空

页面工具