接口规则
基本信息
所有API请求必须使用HTTPS 接入端点如下:
| 端点 | 环境 | 备注 |
|---|---|---|
| https://open-fat.cb.paykka.com | 测试环境 | |
| 正式环境 | 线下申请 |
数据格式
- 使用JSON作为消息体的数据交换格式
- 请求头须设置
Content - Type: application / json
Accept: application / json备注: 文件上传的API除外
参数兼容性
- 请求是否成功，与请求参数的顺序无关
- 请求是否成功，与请求JSON中的键值对出现的顺序无关
- 处理应答时，不应假设应答JSON中的键值对出现的顺序
- 新的API版本可能在请求或应答中加入新的参数或者JSON的键值对
- 新的API版本不会去除请求和应答中已经存在的必填参数或者JSON的键值对
- 当请求或应答中的JSON键值对的值为空（null）时，可以省略
字符编码
使用UTF-8作为消息体的编码
时间格式
所有的时间对象，使用ISO 8601所定义的格式。 其中时区部分使用UTC时区 (即字符Z)
报文示例：
{
"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 | 未认证的请求(常见于签名验证异常) |