Requests 工单(普通用户)接口

Requests API为普通用户调用，用户在验证时采用{email_address}/token:{api_token}方式

JSON 格式

NameTypeRead-onlyMandatoryComment
idintegeryesno工单编号，创建工单时系统自动分配
urlstringyesno此工单的url地址
titlestringnono标题
descriptionstringyesno第一条工单回复的文本内容
typestringnono类型："problem", "incident", "question", "task"
statusstringnono状态："new","open", "pending", "solved", "closed"
prioritystringnono优先级："low", "medium", "high", "urgent"
recipientstringyesno邮件工单的原收件人地址
requester_idintegernoyes发起人id
assignee_idintegernono受理客服id
organization_idintegeryesno发起人所属公司组织id
group_idintegeryesno受理客服组id
due_datedatenonotask工单的截止时间
created_atdateyesno创建时间
updated_atdateyesno最后更新时间
sourcestringyesno工单来源
custom_fieldsarraynono工单自定义字段

JSON 示例

{
	"id": 118,
	"url": "https://support.kf5.com/apiv2/requests/118.json",
	"title": "123",
	"description": "Test",
	"type": null,
	"status": "pending",
	"priority": null,
	"requester_id": 733,
	"assignee_id": 733,
	"organization_id": 186,
	"group_id": 165,
	"due_date": null,
	"created_at": "2014-08-09 16:12:27",
	"updated_at": "2014-08-30 14:26:49",
	"custom_fields": [
	 {
		"name": "field_4",
		"value": "技术问题"
	 },
	 {
		"name": "field_8",
		"value": "订单号"
	 }
	]
}

工单(普通用户)回复 JSON格式

NameTypeRead-onlyComment
idintegeryes回复id，由系统自动分配
contentstringyes工单回复文本内容
html_contentstringyes工单回复html内容
author_idintegeryes回复的用户id
created_atdateyes回复的时间
attachmentsarrayyes回复所带的附件，请参照 Attachments API

工单(普通用户)回复 JSON 示例

{
  "id": 2060,
  "content": "the content",
  "html_content": "the content",
  "created_at": "2014-03-05 18:40:33",
  "author_id": 733,
  "attachments": [
    {
     "id": 1743,
     "url": "https://support.kf5.com/apiv2/attachments/1743.json",
     "name": "测试.jpg",
     "size": 577,
     "content_url": "https://support.kf5.com/attachments/download/1743/d82e779e28719c5623af75c6fd2966b/",
     "token": "d82e779e28719c5623af75c6fd2966b"
    }
   ]
}

工单请求列表

GET /apiv2/requests.json

获取当前用户的工单请求列表，即发起人为当前用户的工单,默认按工单编号升序排列

调用权限

end user

请求参数

created_order：按创建时间排序规则，可选值：asc,desc (默认为desc)

updated_order：按更新时间排序规则，可选值：asc,desc

status_order：按工单状态排序规则，可选值：asc,desc

field_order: 按自定义字段属性排序规则,参数格式：field_690_asc,或field_690_desc。其中field_690为该工单的自定义字段name，可以通过 工单自定义字段接口获得

也可以使用如下API：
获取状态小于已解决的工单
GET /apiv2/requests/open.json
获取状态已解决和已关闭的工单
GET /apiv2/requests/solved.json
获取指定用户的工单请求(调用权限 agent)
GET /apiv2/users/{id}/requests.json
获取指定公司组织的工单请求(调用权限 agent)
GET /apiv2/organizations/{id}/requests.json
curl 示例
curl https://{subdomain}.kf5.com/apiv2/requests.json \
  -v -u {email_address}/token:{api_token}
返回示例
Status: 200 OK

{
  "requests": [
    {
      "id": 33,
      "status": "open",
      "title": "here is a bug",
      ...
    },
    {
      "id": 34,
      "status": "closed",
      "title": "here is another bug",
      ...
    }
  ]
}

所属公司组织的工单请求列表

GET /apiv2/requests/organization.json

获取当前用户所属公司组织的工单列表，需要用户所属公司组织不能为空，其所属公司组织开启了“能查看组织的所有工单”

调用权限

end user

请求参数

status: 状态筛选条件，可选值：open 状态小于已解决、solved 状态已解决和已关闭

created_order: 按创建时间排序规则，可选值：asc、desc

updated_order: 按更新时间排序规则，可选值：asc、desc

status_order: 按工单状态排序规则，可选值：asc、desc

field_order: 按自定义字段属性排序规则，例如：field_xxx_asc、field_xxx_desc

请求示例
GET /apiv2/requests/organization.json?status=open GET /apiv2/requests/organization.json?created_order=asc GET /apiv2/requests/organization.json?status=solved&field_order=field_xxx_asc
返回示例
Status: 200 OK

{
  "requests": [
    {
      "id": 33,
      "status": "open",
      "title": "here is a bug",
      ...
    },
    {
      "id": 34,
      "status": "closed",
      "title": "here is another bug",
      ...
    }
  ]
}
GET /apiv2/requests/search.json
调用权限

end user

请求参数

range: 搜索范围，可选值：user 自己发起的工单、organization 所属公司组织的工单，默认：user

query: 查询关键词，模糊查询多个字段

status: 状态筛选条件

fieldvalue: 自定义字段条件

created_order: 搜索结果按创建时间排序，可选值：asc,desc (默认为desc)

请求示例
GET /apiv2/requests/search.json?query=iphone6 GET /apiv2/requests/search.json?status=open,solved GET /apiv2/requests/search.json?range=organization&query=iphone6&status=open
获取含有自定义字段值为12345的工单列表
GET /apiv2/requests/search.json?fieldvalue=12345
返回示例
Status: 200 OK

{
  "requests": [
    {
      "id": 33,
      "status": "open",
      "title": "here is a bug",
      ...
    },
    {
      "id": 34,
      "status": "closed",
      "title": "here is another bug",
      ...
    }
  ]
}

查看工单请求

GET /apiv2/requests/{id}.json
调用权限

end user

curl 示例
curl https://{subdomain}.kf5.com/apiv2/requests/{id}.json \
  -v -u {email_address}/token:{api_token}
返回示例
Status: 200 OK

{
  "request": {
      "id": 33,
      "status": "open",
      "title": "here is a bug",
      ...
  }
}

创建工单请求

POST /apiv2/requests.json
调用权限

end user

curl 示例
curl https://{subdomain}.kf5.com/apiv2/requests.json \
  -d '{"request": {"title": "Help!", "comment": {"content": "My new requests", "uploads": ["00156a9d6e82efefcbbd874ffbf617e","00156a9d6e82efefcbbd874ffbf617e"]}}}' \
  -v -u {email_address}/token:{api_token} -X POST -H "Content-Type: application/json"
上传工单附件

在创建或者更新工单时，可以给工单回复添加附件。首先需要调用 Attachments API 里的上传附件接口， 成功后会返回附件token，然后将token添加到comment里的uploads数组里，这样工单回复在保存时就能把附件给关联上。

"comment":  {
	"content": "with attachments",
	"uploads":  ["00154af5872418a7792dda", ...]
}
返回示例
Status: 201 Created
Location: https://{subdomain}.kf5.com/apiv2/requests/{id}.json

{
  "request": {
      "id": 33,
      "status": "open",
      "title": "My new requests",
      ...
  }
}

回复工单

PUT /apiv2/requests/{id}.json
调用权限

end user

curl 示例
curl https://{subdomain}.kf5.com/apiv2/requests/{id}.json \
  -d '{"request": {"comment": {"content": "Thanks!"}}}' \
  -v -u {email_address}/token:{api_token} -X PUT -H "Content-Type: application/json"
返回示例
Status: 200 OK

{
  "request": {
      "id": 33,
      "status": "open",
      "title": "here is a bug",
      ...
  }
}

工单回复列表

GET /apiv2/requests/{id}/comments.json
调用权限

end user

按创建时间排序，可添加排序参数

sort_order：排序规则，可选值：asc,desc (默认为asc)

curl 示例
curl https://{subdomain}.kf5.com/apiv2/requests/{id}/comments.json \
  -v -u {email_address}/token:{api_token}
返回示例
Status: 200 OK

{
  "comments": [
    {
      "id": 43,
      "content": "Thanks for your help!",
      ...
    },
    ...
  ]
}

查看指定工单回复

GET /apiv2/requests/{request_id}/comments/{id}.json
调用权限

end user

curl 示例
curl https://{subdomain}.kf5.com/apiv2/requests/{request_id}/comments/{id}.json \
  -v -u {email_address}/token:{api_token}
返回示例
Status: 200 OK

{
  "comment":{
      "id": 43,
      "content": "Thanks for your help!",
      ...
   }
}