开票接口说明

文档说明

此接口规范用于建立会员企业与荣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.drawincoice"
                    }]
                  
复制代码

返回报文

参数说明
索引 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}

第二步:将参数以key=value的格式拼接,并按照参数名ASCII字典序排序(包括value,如果value为json结构,也需要排序)如下:

strStep2="accessKey=xxxxxx&aparam=test1&bparam=test2&cparam={\"subMember1\":\"对象模型内的字段1\",\"subMember2\":\"对象模型内的字段2\"} &nonce=1000×tamp=10000100"

第三步:拼接API密钥:(accessSecret为商户平台设置的访问密钥)

strStep3 = strStep2 +"&accessSecret=192006250b4c09247ec02edce69f6"

第四步:使用MD5算法加密第二步拼接好的明文,将加密结果转为英文大写:

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
                    b.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 处理失败
  • 文档说明
  • 数据范围
  • 流程图例
  • 接口协议
  • 接口安全
  • 请求报文
  • 返回报文
  • 数据签名
  • 请求响应码对照表
  • 开票、冲红操作状态码对照表