在对数据项进行描述时,本规范定义了11种基本数据类型。在用JSON描述数据项时,各数据项的取值本质上都是以字符串的形式表述。
| 数据类型 | 定义 | JSON文本格式 | 
|---|---|---|
| N | 数字字符串,Unicode 字符集范围为\u0030-\u0039 | 数字字符串 | 
| AN | 数字字符和英文字符组成的字符串,Unicode字符集范围为\u0020-\u007E | 数字字符和英文字符组成的字符串 | 
| ANC | 可以包含所有字符 (包括汉字) 的字符串 | 可以包含所有字符 (包括汉字) 的字符串 | 
| Enum | 枚举(代码) 型数据。代码可以由数字和英文字母构成 | 数字和英文字母构成的字符串,总长度不超过 8 | 
| Year | 年份 | 由数字字符组成的用以表示日期的字符串 (格式 yyyy) | 
| Month | 年月 (包含年、月) | 由数字字符组成的用以表示日期的字符串 (格式为 yyyyMM)例: 202102 | 
| Date | 日期 (包含年、月、日) | 由数字字符组成的用以表示日期的字符串 (格式为 yyyyMMdd) 例: 20210201 | 
| Time | 时间 (包含年、月、日、时、分、秒) | 由数字字符组成的用以表示时间的字符串 (格式为 yyyyMMddHHmmss) 例: 20220908220200 | 
| Timestamp | 时间戳,精确到毫秒 | |
| Int | 整数 | 由数字字符和“-”组成的十进制整数的字符串其中“-”加在数字前表示该整数位负数 | 
| Float | 实数 | 由数字字符、“-”“.”组成的十进制实数的字符串,其中“.”用以分隔整数和小数部分、8加在数字前表示该实数是负数 | 
在对数据对象进行描述时,本规范定义了 2 种复合数据类型。
| 数据类型 | 定义 | 
|---|---|
| Object | 对象类型,由基本数据类型和复合数据类型组合而成 | 
| Array | 数组类型,具有相同基本数据类型或复合数据类型的有序集 | 
本规范从两个维度对数据项和数据对象的填写进行约束:一是出现约束,规定是否出现;二是空值约束,规定当出现时,取值是否允许为空。
● 针对数据项或数据对象是否需要出现,本规范做了如下定义:
所有的数据项或者数据对象都要出现,父数据对象是空值的情况除外。
● 针对数据项或数据对象是否可以填写空值,本规范使用了3 种类型的填写约束:
1、M(非空型),表示必须填写有意义的值,不能填写空值。
2、O(可空型),当此数据项或数据对象获取不到相关信息时,可以填写空值。
3、C(条件非空),在特定条件为真的情况下,必须填报有意义的值,不能填写空值;反之,可以为空值。
在基本数据类型中,如果 Int 或者 Float 类型为空值,填写 null;其它情况,填写空字符串(“”)。
在复合数据类型中如果 Array 类型为空值,填写[];如果 Object 类型为空值,填写null。
在信息交换时采用“Unicode”字符集以及 UTF-8 编码。
对于单笔接口,使用HTTP/HTTPS 传输协议,具体约定如下表 所示:
| 序号 | 约定项 | 约定描述 | 
|---|---|---|
| 1 | 通讯协议 | HTTP/HTTPS 协议 | 
| 2 | TLS 版本 | TLSv1.2 | 
| 3 | HTTP METHOD | GET/POST | 
| 4 | HTTP STATUS | 200 表示网络传输成功,其它表示不成功 | 
| 5 | 响应Content-Type | application/json | 
| 6 | 报文格式 | JSON | 
数字签名是把用户标识(appKey)、请求时间戳(timestamp)、用户密钥(secretKey)进行拼接,然后使用摘要算法进行加密得到签名值。
摘要算法默认使用SM3,可选择使用MD5和SHA256。
| 参数项 | 名称 | 类型 | 空值约束 | 示例/备注 | 
|---|---|---|---|---|
| appKey | 用户标识 | AN | M | |
| timestamp | 时间戳 | Timestamp | M | 当前时间的时间戳(毫秒) | 
| signType | 摘要算法 | AN..6 | O | 默认SM3,还支持MD5/SHA256 | 
| requestId | 请求标识 | AN..36 | O | 请求唯一标识,一个appKey下全局唯一 | 
| 数据项 | 名称 | 类型 | 空值约束 | 示例/备注 | 
|---|---|---|---|---|
| code | 结果代码 | AN | M | 0000代表成功,其余为失败,详见附录A | 
| msg | 结果消息 | ANC | M | 错误消息提示 | 
| requestId | 请求标识 | AN..36 | O | 如用户请求时未提交该参数,则返回自动生成的UUID | 
| data | 结果数据 | Object | O | 具体类型以业务接口说明为准。 | 
系统只记录调用日志供对账用,不记录结果数据,不支持结果数据和报文的回溯。