总体规范
1. 术语和定义
1.1 机构
与中金签订数据服务协议，通过中金进行业务对接的商户。
1.2 报文
中金数据平台与机构系统之间交换的结构化信息。
1.3 数据平台
全称为“中金数据服务平台”，是打通中金数通科技内部系统与外部其他数据源，建设多源数据的信息交互平台。是在信息交互的基础上，建立个人用户画像与企业用户画像数据库，对外提供信用类数据的收费服务。
2. 安全要求
2.1 生成数字信封
[!TIP] （代码示例可见”加解密示例代码“）
1．报文发送方自行产生随机密钥，然后再使用接收方公钥对随机秘钥进行RSA非对称加密，生成dgtlenvlp。
2．按照报文规范生成报文原文，然后对报文原文（JSON格式字符串）使用对称密钥字节数组进行AES256算法加密，再进行Base64编码，生成message。
3．再对报文原文进行签名，得到签名结果（十六进制字符串），签名算法采用“SHA1withRSA”，生成signature。
2.2 解开数字信封
[!TIP] （代码示例可见”加解密示例代码“）
将响应报文中dgtlenvlp参数进行Base64解码后，再使用接收方私钥进行解码，得到对称密钥字节数组。
将响应报文中的message参数进行Base64解码后，再使用对称密钥字节数组进行解密，得到message明文字节数组。
将响应报文中的signature参数转化为字节数组后，采用SHA1withRSA算法对signature参数和message明文字节数组进行验签。
3. 通信方式
同步交易请求：机构产生交易报文后，向数据平台发送交易请求，数据平台受理请求后，立即回复一个响应。同步交易请求时，机构系统将institutionID、message、signature、dgtlenvlp、signSN和encryptSN六个参数以“institutionID=val1&message=val2&signature=val3&dgtlenvlp=val4&signSN=val5&encryptSN=val6”的形式（val1,val2,val3,val4，val5和val6进行URL编码）。
异步交易请求：机构产生交易报文后，向数据平台发送交易请求，数据平台受理请求，处理完之后推送一个异步通知。异步交易请求时，机构系统将institutionID、message、signature、dgtlenvlp、signSN和encryptSN六个参数以Form表单（enctype属性的值为application/x-www-form-urlencoded）的形式，通过HTTP post提交到大数据平台异步交易网关地址。
4. 数据传输
机构与数据平台的接口系统通讯采用HTTPS方式，数据平台接口目前仅支持post方式，系统接受6个参数：institutionID、message、signature、dgtlenvlp、signSN和encryptSN，或者，institutionID、message、signature、dgtlenvlp、signSN、encryptSN和file（目前只对3205接口起作用），对应机构号、加密后的报文（Base64字符串）、签名结果（大写十六进制字符串）、数字信封参数（Base64字符串）、签名证书序列号（发送方私钥证书）、加密证书序列号（接收方公钥证书）、文件（附件的二进制流）。
数据平台响应结果格式：message、signature、dgtlenvlp、signSN和encryptSN，对应加密后的报文（Base64字符串）、签名结果（大写十六进制字符串）、数字信封参数（Base64字符串）、签名证书序列号（发送方私钥证书）和加密证书序列号（接收方公钥证书）。
如果中金解密或者验签失败，会直接返回message，对应加密后的密文（Base64字符串）。
5. 报文概述
5.1 字符集与编码
报文采用Unicode字符集，UTF-8编码方式。所有长度均按字节计算，中文算三个字节（个别中文算四个字节），英文、数字算一个字节。
5.2 保留字
报文主体采用Json格式，“^”、“*”、“&”、“；”、“$”和“%”为报文主体全局保留字，传输数据内容中不可出现。
6. 报文格式
机构与数据平台的通讯报文采用JSON格式，请求报文的总体结构如下：
6.1 大数据平台请求、响应的报文格式
6.1.1 报文样例
请求报文示例：
{
"TxCode":"2104",
"IdentificationNumber":"511102198310242028",
"InstitutionID":"000020",
"TxSN":"202211231417271160084377180",
"IdentificationType":"0",
"Remark":"",
"Name":"王测试"
}
响应报文示例：
{
"ResponseCode":"0000",
"TxCode":"2105",
"Message":"SUCCESS",
"InstitutionID":"000020",
"TxSN":"202211231513413398535216531",
"Verification":"20",
"ResponseMessage":"匹配",
"Code":"2000",
"TraceNo":"2211231515176011112017128"
}
6.1.2 报文常见元素说明
6.1.2.1 Txcode 交易类型
具体指对应的接口编号，例：1113-组织机构基本信息查询接口，TxCode为1113。
6.1.2.2 InstitutionID 机构编号
每个机构都在与数据平台对接过程中开有独立且唯一的机构号，由数据平台分配。
6.1.2.3 TxSN 交易流水号
交易流水号作为交易的唯一标识，必须保证全局唯一。我方提供生成合法流水号GUIDGenerator.genGUID()方法，交易流水号由 32 位数字或字母组成，其中字母区分大小写。流水号格式：14 位时间格式 （YYYYMMDDHHmmss）+18 位（数字或字母）。例如， 202109181059209123003102938，表示 2021 年 9 月 18 日 10 时 59 分 20 秒生成的交易流水号。我方对流水号进行了校验，YYYYMMDD 必须和当天日期保持一致。
6.1.2.4 Remark 备注
在测试环境下，并不验证信息的有效性。只要输入的字段符合字段格式要求，通过操纵 remark 参数，便可验证成功。
Remark 字段 输入 1，返回不匹配；2 返回未知，3 是请求失败；非 1,2,3，就是匹配。（该规则仅针对测试环境）
6.1.2.5 TraceNo 系统跟踪号
该元素只在返回报文中存在，是数据平台生成的系统流水号，为了方便快速跟踪查询交易，建议商户对该元素进行留存。
6.1.3 格式说明
6.1.3.1 元素出现要求格式说明
| 符号 | 说明 |
|---|---|
| R | 报文中该元素必须出现（Required） |
| O | 报文中该元素可选出现（Optional） |
| C | 报文中该元素在一定条件（返回code为2000时）可选出现（Conditional） |
6.1.3.2 数据格式说明
| 数据符号 | 含义 |
|---|---|
| Ax | 长度为x字节的定长字母字符 |
| Ax..y | 长度为x-y字节的变长字母字符 |
| Nx | 长度为x字节的定长数字字符，若表示金额，则以分为单位且不包含千分符与小数点 |
| Nx..y | 长度为x-y字节的变长数字字符，若表示金额，则以分为单位且不包含千分符与小数点 |
| Sx | 长度为x字节的定长特殊字符（含中文字符） |
| Sx..y | 长度为x-y字节的变长特殊字符（含中文字符） |
| ANx | 长度为x字节的定长字母和数字字符（可以只包含字母或者数字） |
| ANx..y | 长度为x-y字节的变长字母和数字字符 |
| ASx | 长度为x字节的定长字母和特殊字符 |
| ASx..y | 长度为x-y字节的变长字母和特殊字符 |
| NSx | 长度为x字节的定长数字和特殊字符 |
| NSx..y | 长度为x-y字节的变长数字和特殊字符 |
| ANSx | 长度为x字节的定长字母、数字和特殊字符 |
| ANSx..y | 长度为x-y字节的变长字母、数字和特殊字符 |
| YYYY | 年（4个字节） |
| YY | 年（2个字节） |
| MM | 月 |
| DD | 日 |
| hh | 时(24小时制） |
| mm | 分 |
| ss | 秒 |
| YYYYMMDD | 长度为8个字节的定长日期格式 |
| YYYYMMDDhhmmss | 长度为14个字节的定长时间格式 |
| VARx | 个数为x的复合数据元素 |
| VARx..y | 个数为x-y的复合数据元素 |
举例：
1、A2表示长度为2个字节的字母字符，如bc,At
2、A6-8表示长度为6-8个字节的字母字符，如dalian,BEIJING,Provider
6.2 大数据平台通知的报文格式
6.2.1 请求报文
通知基于“请求-应答”模式，由大数据平台主动推送，机构系统作为服务方受理请求，并返回响应报文。
6.2.2 响应报文
机构系统需响应大数据系统的报文为{\"Code\":\"2000\",\"Message\":\"SUCCESS\"}的 json 串或者直接返回Base64加密后的改字符串。加密后的字符串固定为：eyJDb2RlIjoiMjAwMCIsIk1lc3NhZ2UiOiJTVUNDRVNTIn0=
6.3 交易状态和响应码使用规则
Code为系统响应码，辅助描述系统处理结果(可参考00-总体规范-常见系统响应码)；ResponseCode为业务响应码，辅助描述业务处理结果。
如果Code值为2000，则说明数据平台受理成功，业务处理结果从验证状态Status或者Verification中获取，或者通过交易查询来获取。如果Code非2000，说明数据平台受理失败。
6.4 交易结果判断说明
Code 2000为我方对交易的计费标识，即：Code2000的结果均为计费交易。在Code为2000的基础上，以 Status或Verification字段返回结果来判断这笔交易业务处理的最终结果。
6.5 数据平台通知失败
通知失败的情况分为通知未达和通知未确认。
应对方法：数据平台在通知失败时，通常采用重发机制来补偿。具体的策略是：主动补发通知三次。如果商户通知未确认，有可能是商户解密通知失败或者返回给数据平台的响应报文Code非2000。