发票查询

1、修订记录

修订记录 日期 说明
1.0 2026.07.01 初版

2、业务说明

（1）接口说明

发票查询

请求主体类型：application/json

请求方式：POST

3、请求地址

环境 HTTPS请求地址
测试环境 https://appdev.ysepay-test.com/openapi/invoice/query
正式环境 https://ysgate.ysepay.com/openapi/invoice/query

4、请求参数说明

4.1、公共请求参数

参数 类型(长度） 必填 参数说明
timeStamp String Y 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"
method String(128) Y 接口名称，固定值：invoice.query
charset String(10) Y 请求使用的编码格式，如utf-8,gbk,gb2312等,固定为utf-8
sign String Y 商户请求参数的签名串（签名算法默认为国密）,详见demo,注意:请用商户私钥进行签名
check String Y 银盛公钥加密随机生成的字符串（key）得到的加密值，详见demo
bizContent String Y 业务参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递。注意：需要通过AES以及随机生成的字符串（key）加密业务参数集合，得到bizContent
reqId String Y 请求唯一流水号,商户系统唯一，要求32个字符内（最少14个字符），只能是数字、大小写字母_-且在同一个商户号下唯一。最后12位要求格式为"yyMMddHHmmss" 示例值：xy1415220315145602
certId String Y 发起方商户号，服务商在银盛给自己开设的商户号，即可当作发起方商户号，由银盛生成并下发。 注意：不同于子商户号，服务商发展的商户即为子商户号
version String Y 调用的接口版本，固定为：1.0

4.2、业务请求参数

（bizContent加密前的json数据明文字符串）

参数 类型(长度） 必填 参数说明
merchantId String(50) Y 商户号,商户号
outerApplyId String(64) Y 服务商侧开票申请编号,服务商侧开票申请编号
partnerId String(32) Y 服务商编号,801开头的代理商编号

5、响应参数说明

请注意：银盛后期会对返回参数保留扩展的权力，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。

5.1、公共响应参数

参数 类型(长度） 必填 参数说明
code String(5) Y 网关响应码，示例值：00000 ，详见网关公共响应码
msg String(50) Y 网关响应码描述
subCode String Y 业务响应码，参见具体的API接口文档
subMsg String Y 业务响应描述
timeStamp String Y 响应时间，格式"yyyy-MM-dd HH:mm:ss"
norce String(128) Y 随机参数
sign String Y 响应参数的签名串，详见demo,
注意:请用银盛公钥进行验签
businessData String Y 业务响应参数集合，
注意：银盛网关通过AES加密业务响应参数集合，得到businessData，商户需要对其进行解密，详情请见demo

5.2、业务响应参数

响应业务参数businessData(json数据)

参数 类型(长度） 必填 参数说明
statusCode String(10) Y 业务状态码,业务状态码，成功为0000，失败返回对应错误码
errorMsg String(500) N 错误信息,成功为空，失败返回具体错误描述
outerApplyId String(64) N 外部申请单号,服务商侧开票申请编号（原样返回）
merchantId String(50) N 商户号,商户号
channelType String(20) N 渠道类型,WECHAT-微信，ALIPAY-支付宝
amount String(20) N 开票金额,开票金额（分）
invoiceType String(50) N 发票类型,发票类型：BASIC-基础行业，HOUSING_RENTAL-不动产租赁，FUEL-成品油
invoiceKind String(50) N 发票种类,发票种类：NORMAL-增值税普通发票，SPECIAL-增值税专用发票
invoiceStatus String(50) N 发票状态,发票状态
buyerName String(200) N 购买方名称,购买方名称
buyerTaxNo String(50) N 购买方税号,购买方税号
invoiceNo String(50) N 发票号码,发票号码
invoiceTime String(50) N 开票时间,开票时间
reverseReason String(500) N 冲红原因,冲红原因
goodsList Object N 商品明细列表,商品明细列表
realPropertyList Object N 不动产明细列表,不动产明细列表（不动产租赁场景）

5.2.1.1 goodsList具体参数

参数 类型(长度） 必填 参数说明
taxCode String(50) N 税收分类编码,税收分类编码
goodsName String(200) N 商品名称,商品名称
specification String(100) N 规格型号,规格型号
unit String(50) N 单位,单位
quantity String(50) N 数量,数量
amount String(20) N 金额,金额（不含税，分）
taxAmount String(20) N 税额,税额（分）
taxRate String(10) N 税率,税率，如 1300 表示 13%
preferentialPolicy String(50) N 优惠政策标识,优惠政策标识
fuelInfo Object N 成品油信息,成品油信息（成品油发票时返回）
5.2.1.1.1 fuelInfo具体参数
参数 类型(长度） 必填 参数说明
fuelType String(50) N 燃油种类,燃油种类：汽油、柴油、乙醇汽油
fuelSpec String(50) N 燃油规格,燃油规格：92#、95#、98#、0#等
gunNumber String(50) N 油枪编号,油枪编号
station String(100) N 加油站名称,加油站名称

5.2.1.2 realPropertyList具体参数

参数 类型(长度） 必填 参数说明
serialNo String(10) N 序号,序号
realPropertyCode String(50) N 不动产编码,不动产编码
realPropertyProvince String(50) N 省份,省份
realPropertyCity String(50) N 城市,城市
realPropertyAddress String(500) N 详细地址,详细地址
crossCityFlag String(20) N 跨城市标识,跨城市标识
realPropertyCertNo String(100) N 不动产证书号,不动产证书号
realPropertyArea String(50) N 面积,面积
startTime String(50) N 开始时间,开始时间
endTime String(50) N 结束时间,结束时间

6、业务响应码 网关公共响应码

响应码 响应码描述 解决方案
00000 成功 请求处理成功
40000 参数错误 请求参数缺失或格式不正确
40001 签名验证不通过 请求签名验证失败，请检查签名参数
40002 商户号有误 请检查商户号是否真实存在
40006 商户税号不匹配 商户税号与配置不一致
40009 并发冲突，请稍后重试 并发冲突，请稍后重试
40010 网关非法参数 检查请求参数，修改后重新发起请求
40011 前置系统参数验证错误 检查请求参数，修改后重新发起请求
50000 系统异常 系统内部异常，请稍后重试
50001 失败 请求处理失败
50002 交易超时 请求处理超时，请稍后查询确认结果
50003 业务失败 参看具体错误描述
50004 商户无权限 商户未开通该功能或无操作权限
50005 资源不存在 请求的资源不存在
50011 发票信息不存在 查询的发票信息不存在
50013 企业开票配置不存在 企业开票配置信息不存在
50014 企业发票产品不存在 企业发票产品信息不存在
50015 开票产品未开通 开票产品尚未开通
50016 开票产品未启用 开票产品未启用
50020 订单所属商户与当前商户不一致 订单所属商户与当前商户不一致
50022 业务规则限制 业务规则限制
50026 查询结果为空 原订单或发票记录不存在

results matching ""

    No results matching ""