侧边栏

文档首页


CRM扩展

数据接口

呼叫能力

Android IM SDK手册(暂停使用)

iOS IM SDK手册(暂停使用)

Android SIP SDK手册

iOS SIP SDK手册

客户端标准版快速集成

帮我吧远程SDK版本

网页在线客服集成

微信接入

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

这是本文档旧的修订版!


工单接口

此接口仅供客服使用。

JSON格式

名称 类型 只读 必填 注释
ticketId int 工单ID,系统自动生成
url string 该工单的url地址
subject string 工单标题
descript string 工单描述,即第一条工单回复的文本内容
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–手动关闭
custUserId int 联系人ID
agentId int 服务商ID
createrId int 创建人ID
servicerUserId int 客服ID
servicerGroupId int 客服组ID
ccUserIdList string 抄送人ID列表
ccGroupIdList string 抄送组ID列表
ticketTemplateId int 工单模板ID。一个工单有哪些字段取决于工单模板,所以设置工单的字段值,必须传工单模板ID
tagList string 工单标签列表
createDT date 创建时间
updateDT date 更新时间
custom_fields array 工单自定义字段,不支持验证码、评星等特殊自定义字段
tables 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": "附件的下载地址" //附件多个时,以逗号分隔
      },
      {
          "key": "field_6",
          "value": "180", //支付字段的收款金额
          "pay_status":1 //0:未支付状态,1:已支付状态
      }
     ],
     "tables":[
         {//第一个表单
          "custom_fields_key": "", //工单表单字段的唯一标识,可从帮我吧后台查看
          "tableData":[
                {//表单的第一行数据
                   "fieldkey": "第一列内容",//fieldkey为表头项的唯一标识
                   "fieldkey": "第二列内容",//fieldkey为表头项的唯一标识
                    ...
                },
                {//表单的第二行数据
                   "fieldkey": "第一列内容",//fieldkey为表头项的唯一标识
                   "fieldkey": "第二列内容",//fieldkey为表头项的唯一标识
                   ...
                }
                ...
           ]
        },
        {//第二个表单
          "custom_fields_key": "", //工单表单字段的唯一标识,可从帮我吧后台查看
          "tableData":[
                {//表单的第一行数据
                   "fieldkey": "第一列内容",//fieldkey为表头项的唯一标识
                   "fieldkey": "第二列内容",//fieldkey为表头项的唯一标识
                    ...
                },
                {//表单的第二行数据
                   "fieldkey": "第一列内容",//fieldkey为表头项的唯一标识
                   "fieldkey": "第二列内容",//fieldkey为表头项的唯一标识
                   ...
                }
                ...
           ]
        }
        ...
        
     ]
} 

工单列表

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/companies/{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":"产品咨询",
            "custom_fields":[
                {
                    "key":"field_14",
                    "value":"15997"
                },
                {
                    "key":"sfsk",
                    "value":"1"
                },
                {
                    "key":"cpxx",
                    "value":[
                        {
                            "cpdm":"001.005",
                            "cpmc":"铺助面板",
                            "zjm":"PZMB",
                            "ggxh":"A6020青古"
                        },
                        {
                            "cpdm":"001.005",
                            "cpmc":"铺助面板",
                            "zjm":"PZMB",
                            "ggxh":"A6020青古"
                        }
                    ]
                }
            ]
        }
    ],
    "count":42,
    "next_page":"https://www.bangwo8.com/api/v1/tickets.json?per_page=40&page=2",
    "previous_page":null
}

查看工单

GET /api/v1/tickets/{id}_v2.json

调用者权限

  管理员

调用示例

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

返回值示例

Status: 200 OK

{
	"ticket": {
		"ticketId": 27890,
		"subject": "产品咨询",
		...
	}
}

查看工单(旧)

GET /api/v1/tickets/{id}.json

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


调用者权限

  管理员

调用示例

curl https://www.bangwo8.com/api/v1/tickets/110.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 联系人信息
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 工单自定义字段

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": "15761b339251466e9fec23698503eb53,12343b339251466e9fec23698503eb54" //token
        }
]

/*工单回复里的附件*/
"ticketReply": {
        "attachments": [
           "15761b339251466e9fec23698503eb53", //附件1的token
           "12343b339251466e9fec23698503eb54" //附件2的token
        ]
}

创建带表单类型的工单
表单类型的字段与普通自定义字段传值方式不一样,不在“custom_fields”进行传值,而是在“tables”里传值,“tables”与“custom_fields”是并列关系。

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


调用示例

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: 200 OK
Location: https://www.bangwo8.com/api/v1/tickets/{id}.json

{
  "ticket": {
    "ticketId": 110,
    "subject": "产品咨询",
    ...
  }
}

更新工单

PUT /api/v1/tickets/{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/3232.json \
  -H "Content-Type: application/json" \
  -d '{"ticket": {"ticketStatus": "2", "ticketReply": { "replyMsg": "这里是工单回复文本内容" }}}' \
  -v -u {account}:{password} -X PUT

返回值示例

Status: 200 OK

{
  "ticket": {
     "ticketId": 3232,
     "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=ticketStatus:2,4 搜索工单状态为已开启或已解决的工单
query=field_1:454 返回自定义字段唯一标识为“field_1”的内容里面包含“454”的工单
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日当天

说明:
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当天

调用示例

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
}

页面工具