数据同步
开票接口说明
文档说明
此接口规范用于建立会员企业与荣e通平台之间业务数据交互的规范，保证对接数据的完整性、一致性、安全性。为会员企业及其客户提供优质的电子发票及线上支付服务。
数据范围
本接口规范涉及数据如下：发票信息。
流程图例
接口协议
接口采用https协议通信且只能使用post方式请求，企业向荣e通发起接口请求，荣e通返回请求的处理结果；所有数据采用json格式传输，utf8编码(即：Content-Type:application/json;chartset=UTF-8)。
接口安全
签名验证：请求的数据需要经过平台提供的方式签名，否则请求非法；
请求报文
参数说明
| 索引 | ID | 名称 | 类型及长度 | 必须 | 说明 |
| 1 | accessKey | 请求唯一标识 | varchar(36) | 是 | 荣e通平台为客户分配 |
| 2 | nonce | 随机数字 | varchar(36) | 是 | 随机值，不允许重复（推荐使用UUID） |
| 3 | timestamp | 时间戳 | varchar(20) | 是 | Unix时间戳，保留到毫秒，不允许和服务器时间相差15分钟以上 |
| 4 | sign | 数据签名 | varchar(32) | 是 | 签名方式详见下方数据签名 |
| 5 | body | 请求信息 | object | 是 | 接口的请求参数信息 |
| 6 | callbackUrl | 回调地址 | varchar(500) | 否 | 回调地址 |
| 7 | apiName | 接口名称 | varchar(100) | 是 | 请求的接口名称 |
请求样例
JSON格式
[{
"timestamp": "1725797231000",
"nonce": "00000000001",
"accessKey": "F0D16DD2EFF945C4B73A4B37F99C2696",
"sign": "AB15D04C25F6B63317F2C166B58EED61",
"body": "object",
"callbackUrl": "https://example/test",
"apiName": "api.invoice.draw"
}]
复制代码
返回报文
参数说明
| 索引 | ID | 名称 | 类型及长度 | 必须 | 说明 |
| 1 | code | 返回状态码 | varchar(10) | 是 | 参考下方请求响应码对照表 |
| 2 | message | 返回消息 | varchar(200) | 是 | |
| 3 | data | 返回的数据 | object | 否 | 如果开票或冲红失败，该字段为空值 |
返回样例
JSON格式
[{
"code": "200",
"message": "请求成功",
"data": object
}]
复制代码
数据签名
第一步： 将请求参数（除 sign之外）模型转换为 json 字符串（假设存在三个业务参数 aparam、bparam、cparam）
strStep1={"aparam":"test1","bparam":"test2","cparam":"{\"subMember1\":\"对象模型内的字段 1\",\"subMember2\":\"对象模型内的字段 2\"}","accessKey":"xxxxxx","nonce":1000,"timestamp":10000100}
strStep1={"aparam":"test1","bparam":"test2","cparam":"{\"subMember1\":\"对象模型内的字段 1\",\"subMember2\":\"对象模型内的字段 2\"}","accessKey":"xxxxxx","nonce":1000,"timestamp":10000100}
第二步：将参数以 key=value 的格式拼接，并按照参数名 ASCII 字典序排序（包括 value，如果 value 为json 结构，也需要排序）如下：
strStep2="accessKey=xxxxxx&aparam=test1&bparam=test2&cparam={\"subMember1\":\"对象模型内的字段 1\",\"subMember2\":\"对象模型内的字段 2\"}&nonce=1000×tamp=10000100”
strStep2="accessKey=xxxxxx&aparam=test1&bparam=test2&cparam={\"subMember1\":\"对象模型内的字段 1\",\"subMember2\":\"对象模型内的字段 2\"}&nonce=1000×tamp=10000100”
第三步：拼接 API 密钥：（secretKey 为商户平台设置的访问密钥）
strStep3 = strStep2 +"&secretKey=192006250b4c09247ec02edce69f6"
strStep3 = strStep2 +"&secretKey=192006250b4c09247ec02edce69f6"
第四步：使用 MD5 算法加密第二步拼接好的明文，将加密结果转为英文大写：
sign = MD5(strStep3).toUpperCase()
sign = MD5(strStep3).toUpperCase()
以下为java签名的示例代码
JAVA
//入参req为整个请求体
public String getSign(Map reqParam) {
// 1. 将请求参数 Map 按照参数名 ASCII 字典序排序
Map sortReqParam = new TreeMap<>(reqParam);
// 2. 如果有 sign，则删除 sign
sortReqParam.remove("sign");
// 3. 将排好序的 Map 转为 key=value 格式的字符串
StringBuilder sb = new StringBuilder();
for (Map.Entry entry : sortReqParam.entrySet()) {
sb.append(entry.getKey()).append("=").append(String.valueOf(entry.getValue())).append("&");
}
// 4. 在最后拼接上 secretKey 的 key 和 value
sb.append("secretKey").append("=").append(secretKey);
// 5. 将拼接完成的参数字符串 md5 加密并转大写
return DigestUtils.md5DigestAsHex(sb.toString().getBytes()).toUpperCase();
}
复制代码
请求响应码对照表
| 序号 | 响应码 | 响应说明 |
| 1 | 200 | 处理成功 |
| 2 | 500 | 服务异常，请联系荣e通客服 |
| 3 | 100001 | 参数无效，【参数名】不正确 |
| 4 | 100002 | 请求时间超出有效时间 |
| 5 | 100003 | 商户accessKey不存在，请联系荣e通客服 |
| 6 | 100004 | 商户accessKey已停用 |
| 7 | 100005 | 验证签名失败 |
| 8 | 100006 | 请求重复，请重新发起(nonce重复) |
| 9 | 200000 | 开票参数异常，详情参考message描述 |
| 10 | 200016 | 预扣权益失败！ |
| 11 | 200024 | 数据重复提交！冲红流水号重复 |
| 12 | 200025 | 更新冲红状态异常！发票冲红中或已冲红 |
| 13 | 200052 | 发票备注格式不正确或发票超限额 |
| 14 | 200101 | 开票流水号重复，不允许重复提交 |
| 15 | 200102 | 不支持当前参数名 |
| 16 | 200103 | 接口只能冲红接口开的发票，当前条件未查询到可冲红的发票 |
| 17 | 200104 | 权限不足，缺少API接口调用权限 |
| 18 | 900059 | 接口调用方式错误，接口只允许POST请求 |
| 19 | 999999 | 请求处理异常，请联系技术人员 |
开票、冲红操作状态码对照表
| 序号 | 响应码 | 响应说明 |
| 1 | 0 | 处理成功 |
| 2 | 1 | 正在处理中 |
| 3 | 2 | 处理失败 |
- 文档说明
- 数据范围
- 流程图例
- 接口协议
- 接口安全
- 请求报文
- 返回报文
- 数据签名
- 请求响应码对照表
- 开票、冲红操作状态码对照表
