3.3 财政电子票据数字签名

财政电子票据数字签名包括：开票单位数字签名、财政部门监制数字签名等两类。两类签名原文不同，计算方法相同。其组织方式如下：

序号	数据项	数据项名称	类型	长度	说明	基数
1	EInvoiceSignature	电子票据数字签名	节点			1
2	└ Signature	开票单位数字签名、财政部门监制数字签名	节点			2
3	├ SignedInfo	签名信息	节点			1
4	│ ├ Reference	签名原文引用	String			1
5	│ ├ SignatureAlgorithm	签名算法	String			1
6	│ └ SignatureFormat	签名格式类型	String	6	固定值，DETACH	1
7	├ SignatureTime	签名时间	UTCDateTime			1
8	├ Signaturevalue	签名值	base64Binary			1
9	└ KeyInfo	证书信息	节点			1
10	├ SerialNumber	证书编号	String			1
11	└ X509IssuerName	X.509证书颁发者名称	String			1

开票单位数字签名原文为：财政电子票据头部（Header）、财政电子票据票面信息（EInvoiceData）；财政部门监制数字签名原文为：开票单位数字签名原文的Hash值、开票单位数字签名（Signature）。

财政电子票据公共服务接口规范

1 适用范围

本规范规定了财政电子票据公共服务接口，为财政电子票据服务平台和外部系统间在交互财政电子票据相关电子信息时的接口技术规范，实现财政电子票据的下载和入账反馈。

2 技术规范

2.1 处理流程

使用公共服务接口时，基于HTTPS协议，采用POST方式“请求-响应”模式进行交互。

 

（1）请求方发送请求

请求方系统由财政电子票据服务平台分配一个身份标识app_id，每个app_id配有一个秘钥（appKey）。请求方根据接口要求，构造请求参数并使用密钥（appKey）对请求参数进行签名。

（2）电子票据服务平台返回响应结果

电子票据服务平台通过验证请求参数的签名来验证请求方身份合法性及数据完整性，无误后进行处理。

a) 处理成功时，根据请求服务不同，响应结果分为两种情况：电子票据下载时，返回电子票据文件压缩包；电子票据入账时，返回JSON格式的参数。

b) 处理失败时，响应结果为JSON格式的参数。

（3）请求方接收数据

请求方收到响应结果后，首先判断电子票据服务平台响应是否成功：电子票据下载时，通过HTTP Content-Type判断是否成功；电子票据入账时，通过返回码判断是否成功。

2.2 数据类型

序号	类型	类型名称	说明
1	String	字符串	标准XML字符串类型（xs:string）。长度分为定长和变长两种，例如：长度“8”表示字符串长度固定为8，长度“[1,100]”表示字符串长度在1到100之间
2	NString	数字串	表示由数字0-9组成的字符串，如：0123456789
3	Integer	整数	标准XML整数类型（xs:integer）
4	Decimal	实数	标准XML实数类型（xs:decimal）
5	base64Binary	base64编码字符串	标准XML base64编码字符串类型（xs:base64Binary）
6	Date	日期	表示日期，格式为yyyyMMdd（年月日），长度为8位，如：20160613
7	Time	时间	表示时间，格式为HH:mm:ss（时分秒），长度为8位，如：09:29:53
8	DateTime	日期时间	表示日期时间，格式为yyyyMMddHH:mm:ss（年月日 时分秒），长度为17位，如：20160613 09:29:53
9	UTCDateTime	UTC日期时间	表示UTC日期时间，格式为dd MMM yyyyHH:mm:ss z（日月年 时分秒 时区），长度为24位，如：13 Jun 2016 09:29:53 GMT
10	Currency	金额	表示金额，单位为元，整数部分最长15位，小数部分固定两位，不能包含逗号等分隔符，如：12345.67

2.3 参数说明

序号	标识符	数据项名称	类型	长度	说明	强制
1	method		String		接口服务名称	是
2	app_id		String		应用帐号	是
3	security	安全码	String		请求串的防伪码。	是
4	format		String		定义请求参数message和接口返回的数据格式。 取值说明：json	是
5	datetime		DateTime		时间，格式为yyyyMMddHHmmssSSS	是
6	version	版本	NString	5	接口版本,默认版本1.0.1	是
7	message_id	请求编号	String	[1,50]	每次请求生成一个唯一请求编号	是
8	message	请求业务参数	String		请求业务参数，参见具体接口描述。需转换为base64编码。

说明：

（1）参数名必须为小写字母；

（2）业务参数message的构成，根据具体接口描述构造；

（3）字符集统一采用 UTF-8编码格式。

3 接口列表

接口服务名称	描述
downloadPNG4AccountByDate	电子票据下载
accountForRecode	电子票据入账反馈

4 接口描述

4.1 电子票据下载

单位通过该接口下载待入账电子票据。

4.1.1 服务名downloadPNG4AccountByDate

4.1.2 业务参数

节点：message

序号	标识符	数据项名称	类型	长度	说明	强制
1	agency_code	单位代码	String	[1,30]	一般采用组织机构代码	是
2	agency_name	单位名称	String	[1,100]		是
3	agency_type	单位类型	NString	1	1:开票单位 2:交款单位	是
4	bill_batch_code	电子票据代码	NString	8		否
5	end_date	开票终止日期	Date			否
6	batch_no	批次序列号	NString	13	上次下载时返回的最大的序列号；初始值为0	是

4.1.3 返回参数

根据HTTP响应头中Content-Type值判断成功或失败。成功时值为application/x-zip-compressed，失败时值为application/json。

（1）成功返回电子票据文件压缩包，命名规则为：包内电子票据份数-最大批次序列号.zip。电子票据压缩包文件名提取方式：HTTP Header content-disposition，值为"attachment;filename=包内电子票据份数-最大批次序列号.zip"。

压缩包内包含电子票据文件和清单文件，每批最大份数100。电子票据文件命名规则为：电子票据代码-电子票据号码.后缀名（后缀名为png）。清单文件是JSON格式的文本文件，命名规则为：最大批次序列号.json。

清单文件内容如下：

序号	标识符	数据项名称	类型	长度	说明	强制
1	Data	电子票据清单内容	String	[1,4096]	JSON格式	是

Data包含一系列电子票据，每份电子票据的数据项目：

序号	标识符	数据项名称	类型	长度	说明	强制
1	EInvoiceCode	票据代码	NString	8		是
2	EInvoiceNumber	票据号码	NString	10		是
3	EInvoiceName	电子票据名称	String	[1,100]		是
4	InvoicingPartyName	开票单位名称	String	[1,100]		是
5	IssueDate	开票日期	Date			是
6	TotalAmount	总金额	Currency			是
7	HandlingPerson	开票人	String	[1,20]		是
8	PayerPartyName	交款人名称	String	[1,100]		是
9	Item	项目明细
	|-ItemCode	项目编码	String	[1,30]		是
	|-ItemName	项目名称	String	[1,100]		是
	|-ItemQuantity	数量	Integer			否
	|-ItemUnit	单位	String	[1,30]		否
	|-ItemAmount	金额	Currency			是
	|-ItemExt	项目明细扩展	节点			否
10	RelatedEInvoice	相关电子票据
	|-RelatedEInvoiceCode	相关电子票据代码	NString	8	红字电子票据非空	否
	|-RelatedEInvoiceNumber	相关电子票据号码	NString	10	红字电子票据非空	否
11	MainExt	基本信息扩展	节点			否
12	EInvoiceFileNumber	电子票据份数	NString	[1,3]	固定值 1	是
13	EInvoiceFile	电子票据文件名	String	[1,100]	PNG文件名称	是

（2）失败返回参数：

节点：error_message

序号	标识符	数据项名称	类型	长度	说明	强制
1	error_code	返回码	NString	3	失败的返回代码	是
2	error_msg	返回消息	NString	[1,200]	错误信息	是

4.2 电子票据入账反馈

单位入账后，通过该接口将财政电子票据入账凭证号反馈财政电子票据服务平台。

4.2.1 服务名accountForRecode

4.2.2 业务参数

节点：message

序号	标识符	数据项名称	类型	长度	说明	强制
1	agency_code	单位代码	String	[1,30]	一般采用组织机构代码	是
2	agency_name	单位名称	String	[1,100]		是
3	agency_type	单位类型	NString	1	1:开票单位 2:交款单位	是
4	bill_batch_code	电子票据代码	NString	8		是
5	bill_no	电子票据号码	NString	10		是
6	acc_number	入账凭证号	String		账务系统生成的记账凭证号	是
7	acc_amount	入账金额	Currency			是

4.2.3 返回参数

（1）成功返回参数

节点：message

序号	标识符	数据项名称	类型	长度	说明	强制
1	succ_code	返回码	NString	3	成功的返回代码：200	是
2	succ_msg	返回消息	NString	[1,200]		是

（2）失败返回参数：

节点：error_message

序号	标识符	数据项名称	类型	长度	说明	强制
1	error_code	返回码	NString	3	失败的返回代码	是
2	error_msg	返回消息	NString	[1,200]	错误信息	是

5 调用步骤说明

以accountForRecode调用为例，具体步骤如下：

5.1 设置参数值

请求参数（示例）：

method=“accountForRecode”,

app_id=”7e7f4e61189145c1a5c2cce38a4219b3”,

format=”json”,

datetime=”20161018192033123”,

version=”1.0.1”,

message_id=”132e4ef89ff44816b9200219274480d2”,

message=”JTdCJTIybWVzc2FnZSUyMiUzQSUyMCU3QiUyMCUyMnBsYWNlX2NvZGUlMjIlM0ElMjAlMjIwMDElMjIlMjAlN0QlN0Q=”

其中，message为业务参数转换为base64编码。

5.2 按

app_id=”7e7f4e61189145c1a5c2cce38a4219b3”,

datetime=”20161018192033123”,

format=”json”,

message=”JTdCJTIybWVzc2FnZSUyMiUzQSUyMCU3QiUyMCUyMnBsYWNlX2NvZGUlMjIlM0ElMjAlMjIwMDElMjIlMjAlN0QlN0Q=”,

message_id=”132e4ef89ff44816b9200219274480d2”,

method=”accountForRecode”,

version=”1.0.1”

5.3 参数值拼接

把各个参数值进行拼接，结果为：

7e7f4e61189145c1a5c2cce38a4219b320161018192033123jsonJTdCJTIybWVzc2FnZSUyMiUzQSUyMCU3QiUyMCUyMnBsYWNlX2NvZGUlMjIlM0ElMjAlMjIwMDElMjIlMjAlN0QlN0Q=132e4ef89ff44816b9200219274480d2accountForRecode1.0.1

5.4 生成防伪码

调用接口时需要生成请求参数防伪码(security)，服务器会对该参数进行验证，用于确认调用者身份是否合法及参数信息完整性。

防伪码(security)为32位大写字符串，计算过程如下：

（1） 将appKey 拼接到参数字符串头、尾

假设appkey为”helloworld”，则拼接后的结果为：

helloworld7e7f4e61189145c1a5c2cce38a4219b320161018192033123jsonJTdCJTIybWVzc2FnZSUyMiUzQSUyMCU3QiUyMCUyMnBsYWNlX2NvZGUlMjIlM0ElMjAlMjIwMDElMjIlMjAlN0QlN0Q=132e4ef89ff44816b9200219274480d2accountForRecode1.0.1helloworld

（2） 对拼接结果进行md5加密

（3） 转化成32位大写，security为：66987CB115214E59E6EC978214934FB8

5.5 组装HTTP请求

将所有参数名和参数值采用utf-8进行URL编码（参数顺序可随意，但必须要包括防伪参数），然后通过POST方式发起请求，如：

http://IP:PORT/?app_id=7e7f4e61189145c1a5c2cce38a4219b3&datetime=20161018192033123&message=JTdCJTIybWVzc2FnZSUyMiUzQSUyMCU3QiUyMCUyMnBsYWNlX2NvZGUlMjIlM0ElMjAlMjIwMDElMjIlMjAlN0QlN0Q=&message_id=132e4ef89ff44816b9200219274480d2&method=accountForRecode&version=1.0.1&security=66987CB115214E59E6EC978214934FB8

6 附录

6.1 返回结果代码

序号	返回码	说明	分类
1	200	调用成功	成功
2	401	参数错误	失败
3	418	AppID不存在或者为空
4	419	身份认证错误
5	410	票据不存在
6	415	该票据已经被其他单位入账备案,不能备案
7	416	入账金额超额，可用入账金额小于当前入账金额
8	417	同一单位入账多次
9	421	服务不可用，原因：[根据具体情况而定]
10	500	系统错误