(版本 V2.0.7)
增值税发票进项管理平台接口协议说明
(版本 V2.0.7)
北京航天信息技术服务有限公司
2018 年 1 月
版本号 | 修订类型 | 修订章节 | 修订内容概要(或原因) | 编制人 | 日期 |
V2.0.1 | M | 5.3.5 | 发票查验接口的返回报文中:货运运输业增值税专用发票 vehicleType 改为 vehicleNum ; | ||
V2.0.2 | M | 5.3.5 | 1.发票查验接口:返回报文中增加buyerAddressPhone 字段; 2.发票查验接口:返回报文中 增加 detailNo 字段; | 2017-10-20 | |
V2.0.3 | M | 5.3.5 | 修改发票获取接口中发票状 态字段含义 | 2017-11 | |
V2.0.4 | M | 3 | 1. 接口分类顺序调整; 2. 去掉发票批量查验接口 | 2018-01 | |
V2.0.5 | M | 5.3.1 | 1.发票获取增加认证归属期字段 2. 发票状态获取增加认证归 属期字段 | 2018-01 | |
V2.0.6 | M | 增加税款所属期获取接口 | 2018-01 | ||
V2.0.7 | M | 1. 发票获取接口:增加通行费发票获取 2. 发票获取接口增加:是否代办退税、认证类型字段 3. 申请认证接口增加:认证类型字段 4. 认证结果获取接口增加: 认证类型字段 | 2018-02 |
*修订类型分为:A-ADDED,M-MODIFIED,D-DELETED
1. 概述
此文档专为增值税进项发票管理平台相关接口提供技术规范,用户按照此规范进行程序开发。
2. 接口实现方式
此文档中接口由增值税进项发票管理平台提供接口服务;接口服务以 rest 方式提供服务,数据格式为 json 格式;
格式如: xxxx://xx/xxxx/xxxXxxxxxxxXxxxxxx
3. 接口分类
1.发票获取接口:实时反馈结果、批量处理。系统传递参数发票采集日期,进项管理平台则根据从国税采集发票的日期与此日期匹配,反馈所有的结果,但因发票明细不确定,因此需要根据情况要多次请求,如果数据结束了,再给出一个结束本次请求的请求。
2.发票状态获取接口;实时反馈结果、批量处理。系统传递发票变更日期,则进项管理平台则把此日期内发生认证状态、发票状态变化的发票及状态反馈给用户,用户可进行重复请求,并在请结束后有一个确认请求结束的请求。
3.发票认证接口:通过此接口,用户可以推送认证的发票,经过数据校验后,反馈给请求处理结果,如果数据校验通过则反馈接收成功,否则反馈失败原因;【发票认证过程是异步过程,不实时返回,建议一次请求认证发票数量小于 500 张】
4.发票认证结果获取接口:实时反馈结果,批量处理。系统传一个批次号,进项管理平台根据批次号返回那个批次提交认证发票的认证结果。
5.税款所属期查询接口:通过此接口实时返回税号的税款所属期。
4. 接口列表
序号 | URL | 接口编码 | 接口名称 | 说明 |
1 | /rest/invoice/dii (data interaction | INVOICE.GET | 发票获取接口 | 获得发票信息; |
2 | INVOICE.STATE | 发票状态获取接口 | 获得发票状态; |
3 | INVOICE.LEGALI ZE | 发票认证接口 | 发票认证请求接口; | |
4 | INVOICE.LEGALI ZE_STATUS | 发票认证结果获取接 口 | 根据批次进行返回发票认 证情况 | |
5 | INVOICE.PERIOD .GET | 属期查询接口 | 获取某个税号当前的税款 所属期 |
5. 接口说明
5.1. 通用请求报文
5.1.1. 通用请求报文格式示例
{
“authorize”:{
“appSecId”:” 289efb7512e54146273b982456b03f42ea93”,
“appSec ”:”123456rewedfgfertrefg”
},
"globalInfo": {
"appId": "JXFP",
"version": "接口版本", “interfaceCode”:”接口编码”, "enterpriseCode": "企业代码",
"dataExchangeId": "数据交换流水号"
}
“data”:base64(数据内容)
}
5.1.2. 通用请求报文格式说明
1、授权信息描述(authorize)的数据项说明:
数据项 | 类型 | 长度 | 是否必填 | 说明 | |
appSecId | 授权 ID | String | 32 | 是 | 航信提供; |
appSec | 签名数据 | String | 是 | 根据签名算法生成,具体长度不 确定 |
2、globalInfo数据项说明:
数据项 | 数据项名称 | 类型 | 长度 | 是否必填 | 说明 |
appId | 应用标识 | String | 4 | 是 | 固定为:JXFP |
version | 接口版本 | String | 4 | 是 | 接口版本,当前 v1.0 |
interfaceCode | 接口编码 | String | 16 | 是 | 不同接口编码不一样,详见下面 接口列表 |
enterpriseCode | 企业代码 | String | 8 | 是 | 由航信提供; |
dataExchangeId | 数据交换流水号 | String | 25 | 是 | enterpriseCode+8 位 日 期 (YYYYMMDD)+9 位序列号 |
5.1.3. 申请安全凭证
在第一次使用 API 之前,用户需要申请安全凭证。安全凭证包括 appSecId 和 appSec ,其中:
appSecId :用于标识 API 调用者身份
appSec :用于加密签名字符串和服务器端验证签名字符串的密钥
注意:API 密钥是构建API 请求的重要凭证,为了您的服务安全,请妥善保存。
5.1.4. 生成签名串
有了安全凭证 appSecId 和 appSec 后,就可以生成签名串了,具体过程参考对接过程参考文档。
5.2. 通用响应报文
5.2.1. 通用响应报文格式示例
{
"appId": "JXFP",
"version": "接口版本", “interfaceCode”:”接口编码”, "enterpriseCode": "企业代码", "dataExchangeId": "数据交换流水号"
}
"returnStateInfo": { "returnCode": "返回代码",
"returnMessage": "返回描述"
}
“data”:base64(返回数据内容);
}
5.2.2. 返回值说明
序号 | returnCode | returnMessage |
1. | 0000 | 处理成功 |
2. | 9999 | 处理失败 |
3. | 2001 | 发票不存在 |
4. | 2002 | 授权信息错误 |
5. | 2003 | 请求报文格式错误 |
6. | 2004 | 内容有差异(传过去 500,但实际确 100) |
7. | 2005 | 接口代码不存在 |
8. | 2006 | 批次号不能为空并且为 32 位 |
9. | 2007 | 当期起始日期不能为空并且为 14 位 |
10. | 2008 | 状态标志不能为空并且为 1 位 |
11. | 2009 | 开始行数为数字并且不为空 |
12. | 2010 | 当期结束日期不能为空并且为 14 位 |
13. | 2011 | 其他异常 |
5.3. 业务接口
5.3.1. 发票获取接口
5.3.1.1.请求报文示例与数据项说明
“data”:{
“buyerTaxNo”:””,
“invoiceType”:””,
“batchNo”:”12345678901234567890123456789012”,
“acquisitionDateBegin”:“20170101010130”, “acquisitionDateEnd”:” 20170101010230” “startRow”:10,
“status”:”1”
}
数据内容(data)数据项说明:
数据项 | 数据项说明 | 类型 | 长度 | 是否必填 | 备注 |
buyerTaxNo | 购方税号 | String | 20 | 否 | 15 或 18 位 |
invoiceType | 发票类型 | String | 2 | 是 | 增值税专用发票:01 货运运输业增值税专用发票:02机动车销售统一发票:03 通行费电子发票:14 |
batchNo | 批次号 | String | 32 | 是 | 32 位如果多次重复的话,此值要一样, 代表是一次请求。 |
acquisitionDate Begin | 发票采集开 始时间 | String | 14 位 | 是 | YYYYMMDDHHMMSS 例 如 : 20170101140245 |
acquisitionDate End | 发票采集结 束时间 | String | 14 位 | 是 | YYYYMMDDHHMMSS 例 如 : 20170101140345 |
startRow | 开始行数 | int | 是 | 整数,第一次请求时为 1 |
status | String | 1 位 | 是 | 当给 1 时继续请求,0 时结束请求 |
5.3.1.2.返回报文示例与数据项说明
5.3.1.2.1.增值税专用发票返回报文
“returnStateInfo”:{
“returnCode”:”0000”, “returnMessage”:”处理成功”,
}
“data”:{
“invoiceType”:”01”, “totalRows”:360,
“startRow”:1, “contentRows”:10, invoices:[{//增值税专用发票
“invoiceCode”:”123456787654”, “invoiceNo”:”12343211”, “currentTaxPeriod”:””, “legalizeEndDate”:””, “legalizeInvoiceDateBegin”:””, “legalizeInvoiceDateEnd”:””,
“invoiceType”:””,
“buyerName”:””,
“buyerTaxNo”:””, “buyerAddressPhone”:””, “buyerAcount”:””,
“salerName”:””,
“salerTaxNo”:””, “salerAddressPhone”:””, “salerAcount”:””,
“invoiceDate”:””,
“invoiceAmount”:””,
“taxAmount”:””,
“totalAmount”:””,
“remark”:””,
“invoiceStatus”:””,
“legalizeState”:””,
“legalizeDate”:””, "legalizeBlongDate":"", "sfdbts":"0",
"rzlx":"0", detailList:[{ “detailNo”:””,
“goodsName”:””,
“goodsNum”:””, “specificationModel”:””, “unit”:””,
“num”:””,
“unitPrice”:””,
“detailAmount”:””,
“taxRate”:””,
“taxAmount”:””
}]
}]
}
数据内容(data)数据项说明:
数据项 | 数据项说明 | 类型 | 长度 | 是否必填 | 备注 |
invoiceType | 发票类型 | String | 2 | 是 | 增值税专用发票:01 货运运输业增值税专用发票:02 |
机动车销售统一发票:03 | |||||
totalRows | 总行数 | int | 是 | 整数 | |
startRow | 开始行数 | int | 是 | 整数,第一次请求时为 1 | |
contentRows | 本次请求返回 行数 | int | 是 | 整数 | |
invoiceCode | 发票代码 | String | 20 | 是 | 10 或 12 位 |
invoiceNo | 发票号码 | String | 8 | 是 | 8 位 |
currentTaxPeriod | 当前税款所属 期 | String | 6 | 是 | YYYYMM |
legalizeEndDate | 当前税款所属 期勾选截止日 | String | 8 | 是 | YYYYMMDD |
legalizeInvoiceDa teBegin | 当前税款所属期可勾选发票 开票日期起 | String | 8 | 是 | YYYYMMDD |
legalizeInvoiceDa teEnd | 当前税款所属期可勾选发票 开票日期止 | String | 8 | 是 | YYYYMMDD |
invoiceType | 发票类型 | String | 2 位 | 是 | 增值税专用发票:01 货运运输业增值税专用发票:02机动车销售统一发票:03 |
buyerName | 购方名称 | string | 100 | 否 | |
buyerTaxNo | 购方税号 | string | 20 | 否 | 现在是 15/18 位 |
buyerAddressPho ne | 购方地址、电 话 | string | 100 | 否 | |
buyerAcount | 购方开户行及 账号 | string | 100 | 否 | |
salerName | 销方名称 | string | 100 | 否 |
salerTaxNo | 销方税号 | string | 20 | 否 | 真实税号是 15/18 位 |
salerAddressPhon e | 销方地址、电 话 | string | 100 | 否 | |
salerAcount | 销方开户行及 账号 | string | 100 | 否 | |
invoiceDate | 开票日期 | string | 8 | 否 | yyyyMMdd |
invoiceAmount | 发票金额 | string | 16 | 否 | |
taxAmount | 发票税额 | string | 16 | 否 | |
totalAmount | 价税合计 | string | 16 | 否 | |
remark | 备注 | string | 200 | 否 | |
invoiceStatus | 发票状态 | string | 2 位 | 否 | 0-正常 1 失控 2 作废 3 红冲 4 异常 |
legalizeState | 认证状态 | string | 1 位 | 否 | 0:未认证,1 认证; |
legalizeDate | 认证日期 | string | 8 位 | 否 | yyyyMMdd |
legalizeBlongDat e | 认证归属期 | String | 6 | 否 | yyyyMM |
sfdbts | 是否代办退税 | String | 1 | 否 | 0:否 1:是 |
rzlx | 认证类型 | String | 1 | 否 | 1-抵扣 2-退税 3-代理退税(未 认证是为 0) |
发票明细数据 | |||||
detailNo | 明细编号 | string | 90 | 否 | |
goodsName | 货物名称 | string | 255 | 否 | |
goodsNum | 商品编码 | String | 19 | 否 | |
specificationM odel | 规格型号 | string | 50 | 否 | |
unit | 计量单位 | string | 10 | 否 | |
num | 数量 | string | 24 | 否 | |
unitPrice | 不含税单 价 | string | 24 | 否 |
金额 | string | 22 | 否 | ||
taxRate | 税率 | string | 10 | 否 | 正数如税率 17%,填写 17 |
taxAmount | 税额 | string | 24 | 否 |
5.3.1.2.2.机动车销售统一发票
“returnStateInfo”:{
“returnCode”:”0000”, “returnMessage”:”处理成功”,
}
“data”:{
“invoiceType”:”03”, “totalRows”:360,
“startRow”:1, “contentRows”:10, invoices:[{//机动车销售统一发票
“invoiceCode”:””,
“invoiceNo”:””, “currentTaxPeriod”:””, “legalizeEndDate”:””, “legalizeInvoiceDateBegin”:””, “legalizeInvoiceDateEnd”:””, “buyerName”:””,
“invoiceDate”:””,
“buyerIDNum”:””,
“buyerTaxNo”:””,
“vehicleType”:””,
“factoryModel”:””,
“productPlace”:””,
“certificate”:””, “certificateImport”:””,
“inspectionNum”:””,
“engineNo”:””,
“vehicleNo”:””,
“totalAmount”:””,
“salerName”:””,
“phone”:””,
“taxNum”:””,
“buyerAcount”:””, “buyerAddressPhone”:””, “buyerBank”:””,
“taxRate”:””,
“taxAmount”:””,
“taxBureauCode”:””,
“taxBureauName”:””,
“invoiceAmount”:””,
“taxRecords”:””,
“tonnage”:””,
“limitPeople”:””,
“invoiceStatus”:””,
“checkStatus”:””,
“legalizeState”:””,
“legalizeDate”:””,
“taxPeriod”:””, “legalizeType”:”” "sfdbts":"0",
"rzlx":"0",
}]
}
数据项 | 数据项说明 | 类型 | 长度 | 是否必填 | 备注 |
invoiceCode | 发票代码 | String | 20 | 是 | 10 或 12 位 |
invoiceNo | 发票号码 | String | 8 | 是 | 8 位 |
currentTaxP eriod | 当前税款所 属期 | String | 6 | 是 | YYYYMM |
legalizeEnd Date | 当前税款所属期勾选截 止日 | String | 8 | 是 | YYYYMMDD |
legalizeInvoi ceDateBegin | 当前税款所属期可勾选发票开票日 期起 | String | 8 | 是 | YYYYMMDD |
legalizeInvoi ceDateEnd | 当前税款所属期可勾选发票开票日 期止 | String | 8 | 是 | YYYYMMDD |
invoiceType | 发票类型 | String | 2 位 | 是 | 增值税专用发票:01 货运运输业增值税专用发票:02 机动车销售统一发票:03 |
buyerName | 购方名称 | string | 100 | 是 | |
invoiceDate | 开票日期 | String | 8 | 是 | YYYYMMDD |
buyerIDNu m | 购买方身份证号码/组织 机构代码 | String | 240 | 否 | |
buyerTaxNo | 购方税号 | String | 20 | 是 | 现在是 15/18 位 |
vehicleType | 车辆类型 | String | 80 | 否 | |
factoryMode l | 厂牌型号 | String | 100 | 否 | |
productPlace | 产地 | String | 80 | 否 | |
certificate | 合格证书 | String | 100 | 否 | |
certificateIm port | 进口证明书 号 | String | 80 | 否 | |
inspectionN um | 商检单号 | String | 80 | 否 | |
engineNo | 发动机号码 | String | 120 | 否 | |
vehicleNo | 车架号码/车 辆识别号 | VARCHAR2 (40) | 40 | 否 | |
totalAmount | 价税合计 | String | 16 | 否 | 2 位小数 |
salerName | 销货单位名 称 | String | 240 | 是 | |
phone | 电话 | String | 80 | 否 | |
taxNum | 纳税人识别 | String | 20 | 是 |
buyerAcount | 账号 | String | 80 | 否 | |
buyerAddres sPhone | 地址 | String | 160 | 否 | |
buyerBank | 开户银行 | String | 160 | 否 | |
taxRate | 税率 | string | 10 | 是 | 正数如税率 17%,填写 17 |
taxAmount | 税额 | String | 16 | 是 | 2 位小数 |
taxBureauCo de | 主管税务机 关代码 | String | 11 | 否 | |
taxBureauNa me | 主管税务机 关名称 | String | 80 | 否 | |
invoiceAmo unt | 合计金额 | String | 16 | 是 | 2 位小数 |
taxRecords | 完税凭证号 码 | String | 100 | 否 | |
tonnage | 吨位 | String | 40 | 否 | |
limitPeople | 限乘人数 | String | 40 | 否 | |
invoiceStatu s | 发票状态 | String | 1 | 是 | 0:正常 1:失控 2:作废 3: 红冲 4:异常 |
checkStatus | 是否已勾选 | String | 1 | 是 | 0-未勾选 1-已勾选 |
legalizeState | 认证状态 | String | 1 | 是 | 0:未认证 1:已认证 2 不 认证 |
legalizeDate | 认证日期 | String | 8 | 否 | YYYYMMDD |
taxPeriod | 税款所属期 | String | 4 | 否 | YYYYMM |
legalizeType | 认证方式 | String | 1 | 否 | 1:勾选认证 2:扫描认证 |
sfdbts | 是否代办退 税 | String | 1 | 否 | 0:否 1:是 |
rzlx | 认证类型 | String | 1 | 否 | 1-抵扣 2-退税 3-代理退 税(未认证是为 0) |
5.3.1.2.3.通行费电子发票返回报文
“returnStateInfo”:{
“returnCode”:”0000”, “returnMessage”:”处理成功”,
}
“data”:{
“invoiceType”:”14”, “totalRows”:360,
“startRow”:1, “contentRows”:10, invoices:[{//通行费电子发票
“invoiceCode”:”123456787654”, “invoiceNo”:”12343211”, “currentTaxPeriod”:””, “legalizeEndDate”:””, “legalizeInvoiceDateBegin”:””, “legalizeInvoiceDateEnd”:””,
“invoiceType”:””,
“buyerName”:””,
“buyerTaxNo”:””, “buyerAddressPhone”:””, “buyerAcount”:””,
“salerName”:””,
“salerTaxNo”:””, “salerAddressPhone”:””, “salerAcount”:””,
“invoiceDate”:””,
“invoiceAmount”:””,
“taxAmount”:””,
“totalAmount”:””,
“remark”:””,
“invoiceStatus”:””,
“legalizeState”:””,
“legalizeDate”:””, "legalizeBlongDate":"",
"sfdbts":"0",
"rzlx":"0",
"checkCode":"", detailList:[{ “detailNo”:””,
“goodsName”:””,
“detailAmount”:””,
“taxRate”:””,
“taxAmount”:””
"cph":"",
"lx":"",
"txrqq":"20180226",
"txrqz":"20180226",
}]
}]
}
数据内容(data)数据项说明:
数据项 | 数据项说明 | 类型 | 长度 | 是否必填 | 备注 |
invoiceType | 发票类型 | String | 2 | 是 | 增值税专用发票:01 货运运输业增值税专用发票:02机动车销售统一发票:03 通行费电子发票:14 |
totalRows | 总行数 | int | 是 | 整数 | |
startRow | 开始行数 | int | 是 | 整数,第一次请求时为 1 | |
contentRows | 本次请求返回 行数 | int | 是 | 整数 | |
invoiceCode | 发票代码 | String | 20 | 是 | 10 或 12 位 |
invoiceNo | 发票号码 | String | 8 | 是 | 8 位 |
currentTaxPeriod | 当前税款所属 期 | String | 6 | 是 | YYYYMM |
legalizeEndDate | 当前税款所属 期勾选截止日 | String | 8 | 是 | YYYYMMDD |
legalizeInvoiceDa teBegin | 当前税款所属期可勾选发票 开票日期起 | String | 8 | 是 | YYYYMMDD |
legalizeInvoiceDa teEnd | 当前税款所属 期可勾选发票开票日期止 | String | 8 | 是 | YYYYMMDD |
invoiceType | 发票类型 | String | 2 位 | 是 | 增值税专用发票:01 货运运输业增值税专用发票:02机动车销售统一发票:03 |
buyerName | 购方名称 | string | 100 | 否 | |
buyerTaxNo | 购方税号 | string | 20 | 否 | 现在是 15/18 位 |
buyerAddressPho ne | 购方地址、电 话 | string | 100 | 否 | |
buyerAcount | 购方开户行及 账号 | string | 100 | 否 | |
salerName | 销方名称 | string | 100 | 否 | |
salerTaxNo | 销方税号 | string | 20 | 否 | 真实税号是 15/18 位 |
salerAddressPhon e | 销方地址、电 话 | string | 100 | 否 | |
salerAcount | 销方开户行及 账号 | string | 100 | 否 | |
invoiceDate | 开票日期 | string | 8 | 否 | yyyyMMdd |
invoiceAmount | 发票金额 | string | 16 | 否 | |
taxAmount | 发票税额 | string | 16 | 否 |
totalAmount | 价税合计 | string | 16 | 否 | |
remark | 备注 | string | 200 | 否 | |
invoiceStatus | 发票状态 | string | 2 位 | 否 | 0-正常 1 失控 2 作废 3 红冲 4 异常 |
legalizeState | 认证状态 | string | 1 位 | 否 | 0:未认证,1 认证; |
legalizeDate | 认证日期 | string | 8 位 | 否 | yyyyMMdd |
legalizeBlongDat e | 认证归属期 | String | 6 | 否 | yyyyMM |
sfdbts | 是否代办退税 | String | 1 | 否 | 0:否 1:是 |
rzlx | 认证类型 | String | 1 | 否 | 1-抵扣 2-退税 3-代理退税(未 认证是为 0) |
checkCode | 校验码 | String | 255 | 否 | |
发票明细数据 | |||||
detailNo | 明细编号 | string | 90 | 否 | |
goodsName | 货物名称 | string | 255 | 否 | |
goodsNum | 商品编码 | String | 19 | 否 | |
cph | 车牌号 | string | 50 | 否 | |
lx | 类型 | String | 50 | ||
txrqq | 通行时间 起 | string | 50 | 否 | |
txrqz | 通行时间 止 | string | 50 | 否 | |
detailAmount | 金额 | string | 22 | 否 | |
taxRate | 税率 | string | 10 | 否 | 正数如税率 17%,填写 17 |
taxAmount | 税额 | string | 24 | 否 |
5.3.2. 发票状态获取接口
5.3.2.1.请求报文示例与数据项说明
“data”:
{
“buyerTaxNo”:””, “batchNo”:”12345678901234567890123456789012”,
“statusChangeDateBegin”:”20170101010120’’, “statusChangeDateEnd”:”20170101010220’’, “Status”:”1”,
“startRow”:1
}
数据内容(data)数据项说明:
数据项 | 数据项说明 | 类型 | 长度 | 是 否 必 填 | 备注 |
buyerTaxNo | 购方税号 | String | 20 | 否 | 15 或 18 位 |
batchNo | 批次号 | String | 32 | 是 | 32 位如果多次重复的话,此值要一样,代表是一次请 求。 |
statusChange DateBegin | 状态变更日期时间。开始 | String | 14 | 是 | 发票认证状态,发票状态都有可能变化 保留最后时 间。YYYYMMDDHHMMSS |
statusChange DateEnd | 状态变更日期时间。结束 | String | 14 | 是 | 格式:YYYYMMDDHHMMSS |
Status | 状态 | String | 1 位 | 是 | 1 继续请求,0 结束请求 |
startRow | 开始行号 | int | 是 | 从第几开始索取数据 |
5.3.2.2.返回报文示例与数据项说明
“returnStateInfo”:{
“returnCode”:”0000”, “returnMassage”:”处理成功”
}
“data”:{
“totalRows”:360, “startRow”:1, “contentRows”:10,
Invoices:[{
“invoiceCode”:”123456787654”, “invoiceNo”:”12343211”,
“invoiceStatus”: “legalizeState”: “legalizeDate”: "legalizeBlongDate":""
}… …]}
数据内容(data)数据项说明:
数据项 | 数据项说明 | 类型 | 长度 | 是否必填 | 备注 |
totalRows | 涉及到总行数 | 数值 | 是 | 要返回值数据的总行数 | |
startRow | 开始行数 | 数值 | 是 | x次返回结果的是从总集合里第 几行开始获取的 | |
contentRows | 本次返回行数 | 数值 | 是 | x次返回的内容共多少行 | |
invoiceCode | 发票代码 | String | 20 | 是 | 10 或 12 位 |
invoiceNo | 发票号码 | String | 8 | 是 | 8 位 |
invoiceStatus | 发票状态 | string | 1 位 | 是 | 0-正常 1 失控 2 作废 3 红冲 4 异常 |
legalizeState | 认证状态 | string | 1 位 | 否 | 0:未认证,1 认证; |
认证日期 | string | 8 位 | 否 | yyyyMMdd | |
legalizeBlongD ate | 认证归属期 | String | 6 位 | 否 | yyyyMM |
5.3.3. 发票认证接口
5.3.3.1.请求报文示例与数据项说明
“data”:{ “batchNo”:”12345678901234567890123456789012”,
“buyerTaxNo”:””, “contentRows”:365, “invoices”:[
{
“invoiceCode”:”123456787654”, “invoiceNo”:”12343211”,
“applyTaxPeriod”:”201705”, “buyerTaxNo”:“123456789123456789”
“applyRzlx”:”2”
},
{
“invoiceCode”:”123456789054”, “invoiceNo”:”12342311”, “applyTaxPeriod”:”201705”, “buyerTaxNo”:“123456789123456789”
“applyRzlx”:”2”
}… …
]
}
数据内容(data)数据项说明:
数据项 | 类型 | 长度 | 是否必填 | 备注 | |
contentRows | 总条数 | Int | 整数 | 是 | x次请求,共多少条 |
invoiceCode | 发票代码 | String | 20 位 | 是 | 10 或 12 位 |
invoiceNo | 发票号码 | String | 8 位 | 是 | 8 位 |
applyTaxPeri od | 申请认证税 款所属期 | String | 6 位 | 是 | 6 位(YYYYMM) |
buyerTaxNo | 购方税号 | String | 20 | 是 | 15 或 18 位 |
applyRzlx | 认证类型 | String | 10 | 是 | 1:抵扣 2:退税 3:代办退税 (如果为空默认为 1) |
batchNo | 批次号 | 字符串 | 32 位 | 是 | 32 位代表本次请求的批次,下次查询发票认证状态时,也需要此 值 。 |
5.3.3.2.返回报文示例与数据项说明
因为返回报文只有外层报文,无数据项。
“returnStateInfo”:{
“returnCode”:”0000”, “returnMessage”:”处理成功”
}
5.3.4. 发票认证结果获取接口
5.3.4.1.请求报文示例与数据项说明
“data”:{
“batchNo”:”12345678901234567890123456789012”
}
数据项 | 数据项说明 | 类型 | 是否必填 | 备注 |
xxxxxXx | 认证批次号 | String | 是 | 32 位 |
5.3.4.2.返回报文示例与数据项说明
“data”:{
“batchNo”:” 12345678901234567890123456789012”
“contentRows”:”365” “batchState ”:Y/N
Invoices:[{ “invoiceCode”:”123456787654”, “invoiceNo”:”12343211”, “legalizeState”:””,
“legalizeDate”:””,
“authState”:””,
“failureReason”: “”,
“legalizeType”:”1”, “legalizeBelongDate”:”201801” "rzlx":2,
},
{ “invoiceCode”:”123456787654”, “invoiceNo”:”12343211”, “legalizeState”:”1”, “legalizeDate”:”2017-01-01”, “authState”:”1”,
“failureReason ”: “”,
“legalizeType”:”1”, “legalizeBelongDate”:”201801” "rzlx":2,
}… …]}
数据项 | 数据项说明 | 类型 | 长度 | 是否必填 | 备注 |
XxxxxXx | String | 32 | 是 | 32 位 | |
contentRows | 返回内容 | int | 是 | ||
invoiceCode | 发票代码 | String | 20 | 是 | 10 位 或 12 位 |
invoiceNo | 发票号码 | String | 8 | 是 | 8 位 |
legalizeState | 认证状态 | String | 1 位 | 是 | 0:未认证,1 认证; |
legalizeDate | 认证时间 | String | 8 位 | 是 | 8 位 YYYYMMDD |
xxxxxxxXxxxxx | 失败原因 | String | 50 位 | 否 | 1 位 详见失败原因数据说明 authState 为 5 认证失败时 不为空否则为空 |
authState | 认证处理状态 | String | 2 位 | 是 | 见认证处理状态数据说明 |
legalizeType | 认证方式 | String | 1 位 | 是 | 具体值参考 1:勾选;2:扫 描 |
legalizeBelongD ate | 认证归属期 | String | 6 位 | 是 | 6 位 YYYYMM |
batchState | 批次状态 | String | 1 位 | 是 | Y /N |
rzlx | 认证类型 | String | 1 | 否 | 1-抵扣 2-退税 3-代理退 税(未认证是为 0) |
5.3.4.3.失败原因数据说明
失败序号 | 失败原因 | 是否可以再次请求认证 |
1 | 成功 | 不可重复提交 |
2 | 无此票 | 可重复提交 |
3 | 该票异常无法认证 | 不可重复提交 |
4 | 该票已认证 | 不可重复提交 |
5 | 该票已经逾期无法认证 | 不可重复提交 |
6 | 该票已经申请认证 | 不可重复提交 |
7 | 申请认证月份不匹配 | 可重复提交 |
8 | 其他异常 | 可重复提交 |
9 | 该票未到期 | 可重复提交 |
10 | 红票无法认证 | 不可重复提交 |
认证类型不匹配 | 可重复提交 |
5.3.4.4.认证处理状态数据说明
认证处理状态序号 | 状态说明 |
0 | 未认证 |
1 | 待认证 |
2 | 系统认证中 |
3 | 第三方认证中 |
4 | 认证成功 |
5 | 认证失败 |
5.3.5. 属期查询接口
5.3.5.1.请求报文示例与数据项说明
“data”:{
“taxno”:””,
}
数据项 | 数据项说明 | 类型 | 长度 | 是否必填 | 备注 |
taxno | 查询税号 | String | 40 | 是 |
5.3.5.2.返回报文示例与数据项说明
“returnStateInfo”:{ “returnCode”:”0000”, “returnMessage”:”处理成功”
}
“data”:{
"curTaxno": "912203000527625252",
"oldTaxno": "220300052762525",
"compName": " XXX 有限公司", "incomeMoth": "201709",
"selectStartDate": "20170305",
"selectEndDate": "20170930",
"incomeEndDate": "20171015", "compLevel": "A",
"appPeriod": "1"
}
数据项 | 数据项说明 | 类型 | 长度 | 是否必填 | 备注 |
curTaxno | 当前税号 | String | 40 | 是 | |
oldTaxno | 旧税号 | String | 40 | 否 | |
compName | 企业名 | String | 50 | 是 | |
incomeMoth | 当前税款所属 期 | String | 20 | 是 | |
selectStartDa te | 勾选开始日期 | String | 20 | 是 | |
selectEndDate | 勾选结束日期 | String | 20 | 是 | |
incomeEndDate | 所属期结束日 期 | String | 20 | 是 | |
compLevel | 企业信用等级 | String | 10 | 是 | |
appPeriod | 申报周期 | String | 10 | 是 | 1-月报,3-季报 |
5.4. HMAC-SHA1 加密
5.5. 申请安全凭证
在第一次使用 API 之前,用户需要申请安全凭证。安全凭证包括 appSecId 和
appSecKey,其中:
appSecId:用于标识 API 调用者身份;
appSecKey:用于加密签名字符串和服务器端验证签名字符串的密钥。
注意:API 密钥是构建 API 请求的重要凭证,为了您的服务安全,请妥善保存。
5.6. 生成签名串
有了安全凭证 appSecId 和 appSecKey 后,就可以生成签名串了。下面给出了一个生成签名串的详细过程。
假设用户的 appSecId 和 appSecKey 分别是: appSecId:289efb7512e54146273b982456b03f42ea93 appSecKey:27a06832a2214a4fa3b7105e4a72d370
注意:这里只是示例,请用户根据自己实际的 appSecId 和 appSecKey 进行后续操作。
5.6.1. 1.首先拼接请求字符串
POST/recipt/checkFp/getFPInfoByNSRSBH?authorize={“appSecId”:” 289efb7512e54146273b982456b03f42ea93”}&glo
balInfo={ “appId”: “CYFP”, “version”: “V1.0”, “interfaceCode”:”
PLCY”, “enterpriseCode”: ““,”dataExchangeId”:”“}&data=请求数据
5.6.2. 2.用 HMAC-SHA1 算法对第一步骤的签名原文进行签名,然后生成签名串使用 Base64 进行编码,即可获得最终的签名串。
具体代码如下,以 Java 语言为例:
String appSecKey = “27a06832a2214a4fa3b7105e4a72d370”; String srcStr
=“ POST/recipt/checkFp/getFPInfoByNSRSBH?authorize={“appSecId”:” 289efb7512e54146273b982456b03f42ea93”} &
globalInfo={ “appId”:”CYFP”, “version”:”“, “interfaceCode”:”接口编码”, “enterpriseCode”: “企业代码”,”dataExchangeId”:
“数据交换流水号”}&data=请求数据;
SecretKeySpec keySpec = new SecretKeySpec(appSecKey.getBytes(“UTF-8”),
“HmacSHA1”);
Mac mac = Mac.getInstance(“HmacSHA1”); mac.init(keySpec);
byte[] signBytes = mac.doFinal(srcStr.getBytes(“UTF-8”)); String appSec = Base64.encodeBase64String(signBytes); System.out.println(appSec);
最终得到的 appSec 为最终得到的签名串。
使用其它程序设计语言开发时,可用上面示例中的原文进行签名验证,得到的签名串与例子中的一致即可。