工单:工单_客服

此接口仅供客服使用。

名称	类型	只读	必填	注释
ticketId	int	是	否	工单ID，系统自动生成
url	string	是	否	该工单的url地址
subject	string	否	是	工单标题
descript	string	否	否	工单描述，即第一条工单回复的文本内容
ticketSource	int	否	否	工单来源：1–远程，2–聊天，3–呼叫中心，4–留言，5–系统创建
ticketType	int	否	否	工单类型：1–问题，2–事务，3–故障，4–任务
priorityLevel	int	否	否	工单优先级：1–低，2–正常，3–高，4–紧急
ticketStatus	int	否	是	工单状态：1–新建，2–已开启，3–待回应，4–已解决，5–自动关闭，6–手动关闭
custUserId	int	否	是	联系人ID
agentId	int	否	否	服务商ID
createrId	int	否	否	创建人ID
servicerUserId	int	否	否	客服ID
servicerGroupId	int	否	否	客服组ID
ccUserIdList	string	否	否	抄送人ID列表
ccGroupIdList	string	否	否	抄送组ID列表
ticketTemplateId	int	否	否	工单模板ID
tagList	string	否	否	工单标签列表
createDT	date	是	否	创建时间
updateDT	date	是	否	更新时间
custom_fields	array	否	否	工单自定义字段

JSON示例

{
     "ticketId": 1,
     "url": "https://www.bangwo8.com/api/v1/tickets/1.json",
     "subject": "产品咨询",
     "description": "帮我吧是什么？",
     "ticketSource": 0,
     "ticketType": 1,
     "priorityLevel": 2,
     "ticketStatus": 0,
     "custUserId": 121,
     "agentId": 37809,
     "createrId": 0,
     "servicerUserId": 234,
     "servicerGroupId": 0,
     "ccUserIdList": "123,456,789",
     "ccGroupIdList": "2432,3455,2323"
     "tagList": "vip客户,普通客户",
     "createDT": "2017-05-04 14:08:22",
     "updateDT": "2017-05-04 14:08:22",
     "custom_fields": [
      {
          "key": "field_1",
          "value": "4334"
      },
      {
          "key": "field_3",
          "value": "1" //复选框
      },
      {
          "key": "field_2",
          "value": "下拉菜单的某一项"
      },
      {
          "key": "field_4",
          "value": "附件的下载地址" //附件多个时，以逗号分隔
      }
     ]
}

GET /api/v1/tickets.json

查询参数

名称	必要的	类型	注释
created_start	否	string	按创建时间查询：开始时间
created_end	否	string	按创建时间查询：结束时间
updated_start	否	string	按更新时间查询：开始时间
updated_end	否	string	按更新时间查询：结束时间
created_order	否	string	按创建时间排序：asc（升序），desc（降序）
updated_order	否	string	按更新时间排序：asc（升序），desc（降序）
status_order	否	string	按工单状态排序：asc（升序），desc（降序）
page	否	number	页码，默认为 1
per_page	否	number	每页大小，默认为 100

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

调用者权限

管理员

也可以使用下面的接口

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

调用示例

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

返回值示例

Status: 200 OK

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

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

调用者权限

  管理员

调用示例

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

返回示例

Status: 200 OK

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

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

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

调用者权限

  管理员

调用示例

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

返回值示例

Status: 200 OK

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

POST /api/v1/tickets.json

调用者权限

  管理员

请求参数

名称	类型	必须的	描述
subject	string	是	工单标题
ticketReply	object	是	工单描述，请参考工单回复
custUserId	int	否	联系人id，说明该工单是为该客户解决问题
custUser	object	否	联系人信息
createrId	int	否	创建人id
servicerUserId	int	否	受理客服id
servicerGroupId	int	否	受理客服组id
ccUserIdList	string	否	抄送客服id列表
ccGroupIdList	string	否	抄送客服组id列表
ticketSource	int	否	工单来源：1–远程，2–聊天，3–呼叫中心，4–留言，5–系统创建
ticketType	int	否	工单类型：1–问题，2–事务，3–故障，4–任务
priorityLevel	int	否	工单优先级：1–低，2–正常，3–高，4–紧急
ticketStatus	int	否	工单状态：1–新建，2–已开启，3–待回应，4–已解决，5–自动关闭，6–手动关闭
ticketTemplateId	int	否	如果需要传工单来源、类型、优先级、状态或者自定义字段，则必须传该字段值
tagList	int	否	工单标签列表，以逗号分隔
custom_fields	array	否	工单自定义字段

custUser参数说明
目前支持的联系人信息有mobilephone、name、fixnumber、qq、email，如果要使用该参数，则mobilephone是必需的，其余是选填项。如果数据库里没有该联系人信息，则会自动创建。

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

自定义字段说明
key是字段的唯一标识，可从“帮我吧后台-》工单自定义字段”查看；value是该字段的具体值。

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

上传工单附件
工单附件包含两种类型：自定义字段类型的附件和工单回复里的附件。无论是哪种类型的附件，都需要先调用工单回复里的上传附件接口，调用成功后，系统会返回相应的附件token，然后将参数置位此token即可。

/*自定义字段附件*/
"custom_fields": [
	{
            "key": "field_4", //附件自定义字段的唯一标识
            "value": "11234af5467818a7865weq,34523af5467818a7865wer" //token
        }
]

/*工单回复里的附件*/
"ticketReply": {
        "attachments": [
           "11234af5467818a7865weq", //附件1的token
           "34243rt5644334a6755sda" //附件2的token
        ]
}

调用示例

curl https://www.bangwo8.com/api/v1/tickets.json \
  -d '{"ticket": {"subject": "产品咨询", "ticketReply": { "replyMsg":"你好，我想咨询下帮我吧产品" }}}' \
  -H "Content-Type: application/json" -v -u {account}:{password} -X POST

返回值示例

Status: 201 Created
Location: https://www.bangwo8.com/api/v1/tickets/{id}.json

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

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

调用者权限

所有客服

请求参数

名称	类型	必需的	描述
ticketReply	object	是	工单描述，请参考工单回复
servicerUserId	int	否	受理客服id
servicerGroupId	int	否	受理客服组id
ccUserIdList	int	否	抄送客服id列表，如果是抄送的客服分组，则传客服分组id，多个id之间以逗号分隔
ticketSource	int	否	工单来源：1–远程，2–聊天，3–呼叫中心，4–留言，5–系统创建
ticketType	int	否	工单类型：1–问题，2–事务，3–故障，4–任务
priorityLevel	int	否	工单优先级：1–低，2–正常，3–高，4–紧急
ticketStatus	int	否	工单状态：1–新建，2–已开启，3–待回应，4–已解决，5–自动关闭，6–手动关闭
ticketTemplateId	int	否	如果需要更新工单来源、类型、优先级、状态或者自定义字段，则必须传该字段值
tagList	int	否	工单标签列表，以逗号分隔
custom_fields	array	否	工单自定义字段

调用示例

curl https://www.bangwo8.com/api/v1/tickets/{id}.json \
  -H "Content-Type: application/json" \
  -d '{"ticket": {"ticketStatus": "open", "ticketReply": { "replyMsg": "这里是工单回复文本内容", "replyUserId": 233434 }}}' \
  -v -u {account}:{password} -X PUT

返回值示例

Status: 200 OK

{
  "ticket": {
     "ticketId": 123,
     "subject": "这里是工单标题",
     "ticketStatus":  "已解决",
     ...
  }
}

PUT /api/v1/tickets/update_many.json
PUT /api/v1/tickets/update_many.json?ids={ids}

说明：一次最多更新100个工单

调用权限

所有客服

调用示例
对不同的工单进行相同的处理，调用下面的接口：

PUT /api/v1/tickets/update_many.json?ids=111,222,333

{
  "ticket": {
    "ticketStatus": "已解决"
  }
}

对不同的工单进行不同的处理，调用下面的接口：

PUT /api/v1/tickets/update_many.json

{
  "tickets": [
    { "ticketId": 111, "ticketStatus": "已解决" },
    { "ticketId": 222, "ticketStatus": "待回应" }
  ]
}

返回值示例

Status: 200 OK

{
  "results": [
    {
      "ticketId": 111,
      "success": false,
      "error_log": "字段值不合法"
    },
    {
      "ticketId": 222,
      "success": true,
      "error_log": ""
    }
  ]
}

GET /api/v1/tickets/search.json

调用权限

所有客服

请求参数

名称	类型	必需的	注释
query	string	是	搜索内容
sort_by	string	否	按时间排序，目前支持：createDT-创建时间，updateDT-更新时间
sort_order	string	否	按升序还是降序返回，取值为：asc-升序，desc-降序，默认为降序

query参数说明

搜索内容	返回结果
query=2444	模糊搜索，返回工单编号、工单标题或者联系人姓名包含该内容的工单
query=status:已开启，已解决	搜索
query=field_1:454	返回自定义字段唯一标识为“field_1”的内容里面包含“454”的工单
query=2444 createDT>2017-07-01	返回工单编号、工单标题或者联系人姓名包含该内容的工单，并且创建时间是2017年7月1日以后的
query=status:已开启，已解决 createDT⇐2017-07-01	返回工单状态为已开启或已解决的工单，并且创建时间是2017年7月1日以前的，包含2017年7月1日当天
query=status:已开启，已解决 updateDT>=2017-07-01	返回工单状态为已开启或已解决的工单，并且更新时间是2017年7月1日以后的，包含2017年7月1日当天

说明：当query参数增加了时间的过滤条件时，两个条件之间要以空格分开，比如“status:已开启，已解决 updateDT>=2017-07-01”

调用示例

curl "https://www.bangwo8.com/api/v1/tickets/search.json" \
  -G --data-urlencode "query=status:已解决 createDT>2017-07-03" \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

{
  "results": [
    {
      "subject":   "这里是工单标题",
      "createDT":  "2009-05-13 10:07:08",
      "updateDT":  "2011-07-22 11:11:12",
      "ticketId":  211,
      "url":       "https://www.bangwo8.com/api/v1/tickets/211.json"
    },
    {
      "subject":   "这里是工单标题",
      "createDT":  "2010-07-13 10:07:08",
      "updateDT":  "2011-07-13 11:11:12",
      "ticketId":  122,
      "url":       "https://www.bangwo8.com/api/v1/tickets/122.json"
    },
    ...
  ],
  "next_page": "https://www.bangwo8.com/api/v1/tickets/search.json?query=\"status:已开启\"&sort_by=createDT&sort_order=desc&page=2",
  "prev_page": null,
  "count":     1234
}

目录

工单(客服)接口

JSON格式

工单列表

查看工单

查看多个工单

创建工单

更新工单

更新多个工单

搜索工单