侧边栏

文档首页

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 参数不能为空

页面工具

关于我们 | 联系我们 | 意见建议 | 论 坛 | 管理后台

增值电信业务经营许可证:京B2-20192684 京ICP备05008343号

Copyright @ 2004-2020 Gnway.com All rights reserved