Users 用户接口

用户分为三种角色：

普通用户 end_user

客服 agent

管理员 admin

JSON格式（客服和管理员角色调用）

NameTypeComment
idinteger用户id，由系统自动分配
urlstring资源url
emailstring用户邮箱
namestring用户昵称
agent_display_namestring客服处理工单时显示名称
rolestring用户角色，可选值:end_user,agent,admin
phonestring用户手机
phone_bindboolean手机是否绑定
signaturestring客服处理工单时显示签名
detailsstring详细信息
notesstring用户说明
organization_idinteger用户所属组织id
languagestring用户的偏好语言
created_atdate创建时间
updated_atdate最后更新时间
last_login_atdate最近登录时间
statusstring用户状态，可选值：suspended暂停,active正常,unverified未审核
photostring用户头像图片的url地址
moderatorboolean客服文档权限，true表示能编辑文档
public_commentsboolean客服回复工单权限，false为只能私密回复
manage_peopleboolean客服管理用户权限，true表示可以管理用户
ticket_restrictionstring客服受理工单权限，all表示可以受理所有工单，
groups表示只能受理客服组的工单，
assigned表示只能受理分配的工单
custom_role_idinteger客服所属的自定义角色id，高级服务模式才有此功能。
若值不为空，那么上面的客服权限字段不再起作用，
权限按照custom_role里的设置生效
wechat_appidstring微信公众号的id
wechat_openidstring微信用户的openid
tagsarray用户标签
user_fieldsarray用户自定义字段

JSON 示例（客服和管理员角色调用）

{
	"id": 733,
	"url": "https://support.kf5.com/apiv2/users/733.json",
	"email": "support@kf5.com",
	"name": "小叶",
	"agent_display_name": "客服小叶",
	"role": "admin",
	"phone": "",
	"phone_bind": false,
	"signature": "客户==上帝?true:false",
	"details": "金牌客服",
	"notes": "一些简介",
	"organization_id": 186,
	"language": "zh_cn",
	"created_at": "2012-05-08 11:26:29",
	"updated_at": "2015-01-04 16:15:42",
	"last_login_at": "2015-01-09 16:20:29",
	"status": "active",
	"photo": "https://support.kf5.com/upload/4/201306/1371800160_490.gif",
	"moderator": false,
	"public_comments": false,
	"manage_people": false,
	"ticket_restriction": "all",
	"custom_role_id": null,
	"tags": [
		"tag1",
		"tag2"
	],
	"user_fields": [
	{
		"name": "field_7",
		"value": "男"
	},
	{
		"name": "field_11",
		"value": "技术客服"
	}
	]
}

JSON格式（普通用户调用）

NameTypeComment
idinteger用户id，由系统自动分配
urlstring资源url
emailstring用户邮箱
namestring用户昵称
rolestring用户角色，可选值:end_user,agent,admin
phonestring用户手机
phone_bindboolean手机是否绑定
organization_idinteger用户所属组织id
languagestring用户的偏好语言
created_atdate创建时间
updated_atdate最后更新时间
last_login_atdate最近登录时间
statusstring用户状态，可选值：suspended暂停,active正常,unverified未审核

JSON 示例（普通用户调用）

{
	"id": 168,
	"url": "https://support.kf5.com/apiv2/users/168.json",
	"email": "myemail@kf5.com",
	"name": "myname",
	"role": "end_user",
	"phone": "",
	"phone_bind": false,
	"organization_id": 186,
	"language": "zh_cn",
	"created_at": "2012-05-08 11:26:29",
	"updated_at": "2015-01-04 16:15:42",
	"last_login_at": "2015-01-09 16:20:29",
	"status": "active"
	"photo": "https://support.kf5.com/upload/4/201306/1371800160_490.gif",
}

获取用户列表

GET /apiv2/users.json
Query参数
NameRequiredTypeComment
role否string用户角色，可选值：admin、agent、end_user，可组合使用如：admin,agent
created_start否string按创建时间筛选，开始时间
created_end否string按创建时间筛选，结束时间
updated_start否string按更新时间筛选，开始时间
updated_end否string按更新时间筛选，结束时间
created_order否string按创建时间排序，可选值：asc、desc
updated_order否string按更新时间排序，可选值：asc、desc
page否number页码，默认为 1
per_page否number分页尺寸，默认为 100
备注：按创建和更新时间进行筛选的参数 created_start、created_end、updated_start、updated_end，支持日期格式（如 2016-01-01 00:00:00）和时间戳（秒级别的整型）。

还可以使用如下API:

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

agent

curl 示例
curl https://{subdomain}.kf5.com/apiv2/users.json \
  -v -u {email_address}:{password}
返回示例
Status: 200

{
  "users": [
    {
      "id": 523,
      "name": "Agent",
      ...
    },
    {
      "id": 566,
      "name": "admin",
      ...
    }
  ]
}

查看指定用户信息

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

agent

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

{
  "user": {
    "id":   523,
    "name": "Agent",
    ...
  }
}

查看自己的信息

GET /apiv2/users/me.json
调用权限

all

curl 示例
curl https://{subdomain}.kf5.com/apiv2/users/me.json \
  -v -u {email_address}:{password}
返回示例
Status: 200

{
  "user": {
    "id":   523,
    "name": "myname",
    ...
  }
}

获取多个用户信息

GET /apiv2/users/show_many.json?ids={ids}
调用权限

agent

curl 示例
curl https://{subdomain}.kf5.com/apiv2/users/show_many.json?ids={ids} \
  -v -u {email_address}:{password}
返回示例
Status: 200

{
  "users": [
    {
      "id": 523,
      "name": "Agent",
      ...
    },
    {
      "id": 566,
      "name": "admin",
      ...
    }
  ]
}

创建用户信息

POST /apiv2/users.json
调用权限

agent

可以通过email和phone两种属性来创建用户。当email和phone参数同时存在时，以email优先创建用户
curl 示例
curl -v -u {email_address}:{password} https://{subdomain}.kf5.com/apiv2/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user": {"name": "liuming", "email": "liuming@qq.com"}}'
返回示例
Status: 201 Created
Location: https://{subdomain}.kf5.com/apiv2/users/{id}.json

{
  "user": {
    "id":   66,
    "name": "liuming",
    ...
  }
}

合并用户

PUT /apiv2/users/{id}/merge.json

URL里指定id的用户，将会被合并到传递参数中id所代表的用户。 前者的数据也会合并为后者的数据，之后前者将会被删除。 被合并的用户，只能是普通用户角色。

调用权限

admin

curl 示例
curl -v -u {email_address}:{password} https://{subdomain}.kf5.com/apiv2/users/{id}/merge.json \
  -H "Content-Type: application/json" -X PUT -d '{"user": {"id": 1234}}'
返回示例
Status: 200 OK
Location: https://{subdomain}.kf5.com/apiv2/users/{id}.json

{
  "user": {
    "id":   66,
    "name": "Liu Ming",
    ...
  }
}

修改用户信息

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

agent

curl 示例
curl -v -u {email_address}:{password} https://{subdomain}.kf5.com/apiv2/users/{id}.json \
  -H "Content-Type: application/json" -X PUT -d '{"user": {"name": "Liu Ming"}}'
返回示例
Status: 200 OK

{
  "user": {
    "id":   66,
    "name": "Liu Ming",
    ...
  }
}

删除用户

DELETE /apiv2/users/{id}.json
调用权限

admin

curl 示例
curl -v -u {email_address}:{password} https://{subdomain}.kf5.com/apiv2/users/{id}.json \
  -X DELETE
返回示例
Status: 200 OK
GET /apiv2/users/search.json?query={query}

Note:query为查询参数，模糊搜索(名称，邮箱，手机号)

调用权限

agent

curl 示例
curl https://{subdomain}.kf5.com/apiv2/users/search.json?query=刘先生 \
  -v -u {email_address}:{password}
返回示例
Status: 200 OK

{
  "users": [
    {
      "id": 523,
      "name": "刘先生",
      ...
    }
  ]
}