开发向导

Restful API说明

Restful API 是逸创云客服的第二版API,功能更强大,能力更完善,支持多种验证方式。

安全与验证

1. 仅支持ssl

2. 验证方式为 Basic Auth,有邮箱和手机两种形式:

用邮箱验证的方式为:{email_address}:{password} 或者 {email_address}/token:{api_token}

用手机验证的方式为:{phone}:{password} 或者 {phone}/token:{api_token}

token为您云客服平台的API通信密钥,您可以在您的平台中的下面位置找到:

系统设置 > 支持渠道 > 开放API设置

curl调用规范

curl -u {email_address}/token:{api_token} https://{yourdomain}.kf5.com/apiv2/...

示例:

curl -u myemail@kf5.com/token:85d56fef211265f024079a2aca7030 \
https://tianxiang.kf5.com/apiv2/tickets.json

数据格式

1. 仅支持json格式

2. POST和PUT操作,必须在header里设置Content-Type: application/json

分页

默认每个分页返回100条数据,可以在请求url里传递一个per_page参数来设置每个分页需要返回的条数, per_page值不能超过100。

当请求的资源个数超过per_page值时,可以设置自增的page参数来继续请求下一页资源。

示例:

{
  "users": [ ... ],
  "count": 123,
  "next_page": "https://{yourdomain}.kf5.com/apiv2/users.json?page=2",
  "previous_page": null
}

返回结果说明

成功的请求,会返回200或300范围的http状态码

失败的请求,会返回400范围的http状态码

如果返回500范围的http状态码,可能是云客服存在bug,也可能是服务正在更新维护(此时会返回503 Service Unavailable)

调用次数限制

为了保证服务稳定性,免费服务模式每天最多不超过100次调用请求,升级为付费服务模式调用次数无限制

文档说明

文档中关于 "调用权限" 里,admin 表示管理员,agent 表示客服,end user 表示普通用户。

权限从大到小依次是: admin > agent > end user

如果调用权限是: admin 则表示只有 admin 角色的用户可以调用。

如果调用权限是: agent 则表示 agent 和 admin 角色的用户都可以调用。

如果调用权限是: end user 则表示 end user、agent 和 admin 角色的用户都可以调用,不过不推荐管理层角色调用。