接口格式统一标准与鉴权
我们的接口采用国际通用标准，请使用 UTF-8 / Unicode 编码格式。
除非必要，交互格式统一为 JSON。
服务器时间
在请求时，我们通常会为了 业务需要 或为了接口安全，防重放攻击 ，要求客户端请求时，有关于时间的单位，除非特别说明，否则一律采用东八区时间 Asia/Shanghai。
其它东八区时间
以下时间均为 东八区时间，如果您的时间已是列表中的时区，则无需特意修改。
| 时间码 | 说明 | 时间码 | 说明 |
|---|---|---|---|
Asia/Shanghai | 中国上海 | Asia/Taipei | 中华台北 |
Asia/Macau | 澳门特区 | Asia/Hong_Kong | 香港特区 |
Asia/Singapore | 新加坡 | Asia/Kuala_Lumpur | 马来西亚吉隆坡 |
Asia/Manila | 菲律宾 | Asia/Brunei | 文莱 |
Asia/Makassar | 印尼苏拉威西 |
请避免使用以下可能存在时区争议或废弃的标准时间码：
Asia/Chongqing重庆时间，已废弃，链接到Asia/Shanghai。Asia/Urumqi中国新疆乌鲁木齐时间，名义上被定义为东六区时间 (GMT+6) ，但实际被 TZDB 列入东八区时间 (GMT+8)。Asia/Irkutsk俄罗斯伊尔库茨克，目前是东八区时间 (GMT+8)。Asia/Choibalsan蒙古国的东部部分地区。Australia/Perth澳大利亚西部。
废弃的时间码部分计算机系统库可能不被支持。
于此同时，也请尽量不要使用别名：
| 别名 | 链接到 | 说明 |
|---|---|---|
PRC | Asia/Shanghai | 中国大陆标准时间 |
ROC | Asia/Taipei | 中华台北标准时间 |
Hongkong | Asia/Hong_Kong | 香港特别行政区标准时间 |
Singapore | Asia/Singapore | 新加坡标准时间 |
API 端点
暂不支持沙盒环境
沙盒环境我们正在开发中。
http
https://api.kuocai.nethttp
https://api-sandbox.kuocai.net鉴权
请参阅 “接口鉴权规则”。
JSON 统一交互语言
括彩云的程序强行要求必须使用 JSON 作为统一交互语言，不得例外！无论你的请求头 Content-Type 是什么，括彩云的程序都将一律无视，一律视为：
Content-Type: application/json并且，括彩云的程序返回内容时也采用 JSON。
成功与失败格式标准
响应头的状态码为判断本次接口请求成功与否的关键，只要括彩云返回了 200 状态码，那么就表示请求是成功的。
括彩云的简洁接口设计
括彩云的 v1 接口没有冗余的 status / code / data 等接口信息。
当括彩云返回了 400 状态码，那么则为请求失败，请求失败固定返回格式如下：
json
{
"code": "ERR_NOT_FOUND_USER", // 错误状态码
"message": "用户不存在" // 错误原因，为中文
}当括彩云返回了 301 / 302 状态码，请带着你的请求参数重新跟随 Location 请求，因为这往往是我们调整了接口。
当括彩云返回了 500 的服务器错误状态码，往往是我们的内部错误或是 CDN 错误，你不必担心，稍后将自动恢复。如果长时间未恢复请联系我们。
通用错误码
这里的错误码是非业务性的通用错误码，常见用于你犯了非常低级的错误或是括彩云的部分服务异常。除此之外，你也应该关注每个接口自己的业务错误码，对自己的业务进行错误处理。
| 错误码 | 原因 / 解决方案 |
|---|---|
ERR_SIGN_NOT_GOOD | 你技术实力不行，用户签名错误 请参阅 “接口鉴权规则” |
ERR_USER_BANNED | 请求的用户被封禁 在后台查询被封禁原因，看看能否解封账号 |
ERR_USER_NOT_VERIFY | 请求的用户没有完成括彩云的实名认证 登录括彩云后台完成个人或企业的实名认证 |
ERR_USER_API_KEY_NOT_FOUND | 用户请求的 API Key 不存在或被删除、销毁、吊销 重新创建新的 API Key 并用新的 API Key 请求 |
ERR_REQUEST_IP_ERROR | 用户请求的服务器 IP 因恶意请求被临时列入黑名单 提交工单，申请解封 |