本规范规定了财政电子票据公共服务接口,为财政电子票据服务平台和外部系统间在交互财政电子票据相关电子信息时的接口技术规范,实现财政电子票据的下载和入账反馈。
使用公共服务接口时,基于HTTPS协议,采用POST方式“请求-响应”模式进行交互。
(1)请求方发送请求
请求方系统由财政电子票据服务平台分配一个身份标识app_id,每个app_id配有一个秘钥(appKey)。请求方根据接口要求,构造请求参数并使用密钥(appKey)对请求参数进行签名。
(2)电子票据服务平台返回响应结果
电子票据服务平台通过验证请求参数的签名来验证请求方身份合法性及数据完整性,无误后进行处理。
a)处理成功时,根据请求服务不同,响应结果分为两种情况:电子票据下载时,返回电子票据文件压缩包;电子票据入账时,返回JSON格式的参数。
b)处理失败时,响应结果为JSON格式的参数。
(3)请求方接收数据
请求方收到响应结果后,首先判断电子票据服务平台响应是否成功:电子票据下载时,通过HTTP Content-Type判断是否成功;电子票据入账时,通过返回码判断是否成功。
说明:
(1)参数名必须为小写字母;
(2)业务参数message的构成,根据具体接口描述构造;
(3)字符集统一采用 UTF-8编码格式。
单位通过该接口下载待入账电子票据。
节点:message
根据HTTP响应头中Content-Type值判断成功或失败。成功时值为application/x-zip-compressed,失败时值为application/json。
(1)成功返回电子票据文件压缩包,命名规则为:包内电子票据份数-最大批次序列号.zip。电子票据压缩包文件名提取方式:HTTP Header content-disposition,值为"attachment;filename=包内电子票据份数-最大批次序列号.zip"。
压缩包内包含电子票据文件和清单文件,每批最大份数100。电子票据文件命名规则为:电子票据代码-电子票据号码.后缀名(后缀名为png)。清单文件是JSON格式的文本文件,命名规则为:最大批次序列号.json。
清单文件内容如下:
Data包含一系列电子票据,每份电子票据的数据项目:
(2)失败返回参数:
节点:error_message
单位入账后,通过该接口将财政电子票据入账凭证号反馈财政电子票据服务平台。
节点:message
(1)成功返回参数
节点:message
(2)失败返回参数:
节点:error_message
以accountForRecode调用为例,具体步骤如下:
请求参数(示例):
method=“accountForRecode”,
app_id=”7e7f4ec1a5c2cce38a4219b3”,
format=”json”,
datetime=”203123”,
version=”1.0.1”,
message_id=”132e4ef89ff44816b0d2”,
message=”JTdCJTIybWVzc2FnZSUyMiUzQSUyMCU3QiUyMCUyMnBsYWNlX2NvZGUlMjIlM0ElMjAlMjIwMDElMjIlMjAlN0QlN0Q=”
其中,message为业务参数转换为Base64编码。
app_id=”7e7f4ec1a5c2cce38a4219b3”,
datetime=”203123”,
format=”json”,
message=”JTdCJTIybWVzc2FnZSUyMiUzQSUyMCU3QiUyMCUyMnBsYWNlX2NvZGUlMjIlM0ElMjAlMjIwMDElMjIlMjAlN0QlN0Q=”,
message_id=”132e4ef89ff44816b0d2”,
method=”accountForRecode”,
version=”1.0.1”
把各个参数值进行拼接,结果为:
7e7f4ec1a5c2cce38a4219bjsonJTdCJTIybWVzc2FnZSUyMiUzQSUyMCU3QiUyMCUyMnBsYWNlX2NvZGUlMjIlM0ElMjAlMjIwMDElMjIlMjAlN0QlN0Q=132e4ef89ff44816b0d2accountForRecode1.0.1
调用接口时需要生成请求参数防伪码(security),服务器会对该参数进行验证,用于确认调用者身份是否合法及参数信息完整性。
防伪码(security)为32位大写字符串,计算过程如下:
(1)将appKey 拼接到参数字符串头、尾
假设appkey为”helloworld”,则拼接后的结果为:
helloworld7e7f4ec1a5c2cce38a4219bjsonJTdCJTIybWVzc2FnZSUyMiUzQSUyMCU3QiUyMCUyMnBsYWNlX2NvZGUlMjIlM0ElMjAlMjIwMDElMjIlMjAlN0QlN0Q=132e4ef89ff44816b0d2accountForRecode1.0.1helloworld
(2)对拼接结果进行md5加密
(3)转化成32位大写,security为:66987CB115214E59E6ECFB8
将所有参数名和参数值采用utf-8进行URL编码(参数顺序可随意,但必须要包括防伪参数),然后通过POST方式发起请求,如:
http://IP:PORT/?app_id=7e7f4ec1a5c2cce38a4219b3&datetime=203123&message=JTdCJTIybWVzc2FnZSUyMiUzQSUyMCU3QiUyMCUyMnBsYWNlX2NvZGUlMjIlM0ElMjAlMjIwMDElMjIlMjAlN0QlN0Q=&message_id=132e4ef89ff44816b0d2&method=accountForRecode&version=1.0.1&security=66987CB115214E59E6ECFB8
本文来源:https://www.2haoxitong.net/k/doc/2391bd2adf3383c4bb4cf7ec4afe04a1b171b029.html
文档为doc格式