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

工单(客服)接口

此接口仅供客服使用。

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": "附件的下载地址" //附件多个时，以逗号分隔
      }
     ],
     "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}.json

调用者权限

  管理员

调用示例

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

返回值示例

Status: 200 OK

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

查看多个工单

GET /api/v1/tickets/show_many.json?ids={ids}

说明：工单id要以逗号分隔。此接口最多返回100个工单。
调用者权限

  管理员

调用示例

curl https://www.bangwo8.com/api/v1/tickets/show_many.json?ids=110,111,112 \
 -v -u {account}:{password}

返回值示例

Status: 200 OK

{
  "tickets": [
    {
      "ticketId": 110,
      "subject": "产品咨询",
      ...
    },
    {
      "ticketId": 111,
      "subject": "产品服务"
      ...
    },
    ...
  ]
}

创建工单

POST /api/v1/tickets.json

调用者权限

  管理员

请求参数

名称	类型	必须的	描述
subject	string	是	工单标题
ticketReply	object	是	工单描述，请参考工单回复
custUserId	int	否	联系人id，说明该工单是为该客户解决问题
custUser	object	否	联系人信息
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	否	如果需要传工单来源、类型、优先级、状态或者自定义字段，则必须传该字段值
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": "open", "ticketReply": { "replyMsg": "这里是工单回复文本内容", "replyUserId": 233434 }}}' \
  -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
}

目录

工单(客服)接口

JSON格式

JSON示例

工单列表

查看工单

查看多个工单

创建工单

更新工单

更新多个工单

搜索工单