# 接口规则

## 基本信息

所有API请求必须使用HTTPS 接入端点如下:

| 端点 | 环境 | 备注 |
|  --- | --- | --- |
| https://open-fat.cb.paykka.com | 测试环境 |  |
|  | 正式环境 | 线下申请 |


## 数据格式

- 使用JSON作为消息体的数据交换格式
- 请求头须设置



```header
Content - Type: application / json
Accept: application / json
```

备注: 文件上传的API除外

## 参数兼容性

- 请求是否成功，与请求参数的顺序无关
- 请求是否成功，与请求JSON中的键值对出现的顺序无关
- 处理应答时，不应假设应答JSON中的键值对出现的顺序
- 新的API版本可能在请求或应答中加入新的参数或者JSON的键值对
- 新的API版本不会去除请求和应答中已经存在的必填参数或者JSON的键值对
- 当请求或应答中的JSON键值对的值为空（null）时，可以省略


## 字符编码

使用UTF-8作为消息体的编码

## 时间格式

所有的时间对象，使用ISO 8601所定义的格式。
其中时区部分使用UTC时区 (即字符Z)

报文示例：


```json
{
  "date": "2023-12-04T23:25:59Z"
}
```

上述报文中的date字段表示的是UTC时间2023年12月4日23点25分59秒, 对应北京时间(UTC+8)2023年12月5日7点25分59秒

## 错误信息

使用HTTP状态码表示请求处理的结果

| 状态码 | 说明 |
|  --- | --- |
| 200 | 请求被正确的处理了 |
| 4xx | 请求没有被处理, 原因是请求的内容存错误: 格式错误/参数完整性错误/请求对象不存在/状态错误/余额不足等 |
| 5xx | 处理过程发生了异常, 请求没有被处理: 网络故障/程序缺陷等 |


## 错误码和错误提示

当请求处理失败时，除了HTTP状态码表示错误之外，API将在消息体返回错误相应说明具体的错误原因。

| 键 | Type | 说明 |
|  --- | --- | --- |
| ret_code | String(6) | 错误码 |
| ret_msg | String | 错误响应信息, 是对具体错误描述 |


## 常见错误码及其说明

| 错误码 | 说明 |
|  --- | --- |
| 999999 | 未知异常(请联系平台技术人员确认) |
| 010000 | 请求参数错误(格式错误, 缺少参数等) |
| 010001 | 请求过于频繁 |
| 010002 | 请求数据不存在 |
| 010003 | 请求数据状态不正确 |
| 010004 | 破坏数据完整性 |
| 010005 | 超过文件大小限制 |
| 010100 | 未认证的请求(常见于签名验证异常) |
| 010200 | 未认证的请求(常见于签名验证异常) |