发票开具

1、修订记录

修订记录 日期 说明
1.0 2026.07.01 初版
1.1 2026.07.27 新增“交易渠道”参数
1.2 2.26.08.06 调整各项参数描述字段

2、业务说明

（1）接口说明

发票开具

请求主体类型：application/json

请求方式：POST

3、请求地址

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

4、请求参数说明

4.1、公共请求参数

参数 类型 长度 必填 参数说明
timeStamp String - Y 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"
method String 128 Y 接口名称，固定值：invoice.issue
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 32 Y 请求唯一流水号,商户系统唯一，要求32个字符内（最少14个字符），只能是数字、大小写字母_-且在同一个商户号下唯一。最后12位要求格式为"yyMMddHHmmss" 示例值：xy1415220315145602
certId String - Y 发起方商户号，服务商在银盛给自己开设的商户号，即可当作发起方商户号，由银盛生成并下发。 注意：不同于子商户号，服务商发展的商户即为子商户号
version String - Y 调用的接口版本，固定为：1.1

4.2、业务请求参数

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

参数 类型 长度 必填 参数说明
ability String 50 Y 开票类型,BASIC-基础行业，REAL_ESTATE_LEASE -不动产租赁，REFINED_OIL-成品油
buyerType String 20 Y 购买方类型:ENTERPRISE-企业，INDIVIDUAL-个人
amount String 15 Y 开票金额，单位分
buyerAddress String 500 N 购买方地址
buyerBankAccount String 500 N 购买方银行账号
buyerBankName String 500 N 购买方开户行
buyerName String 100 Y 购买方名称
buyerTaxNo String 50 N 购买方税号 购买方为企业则必填
channelOrderNo String 100 Y 渠道订单号，微信支付传微信的订单号，支付宝传支付宝的订单号
payTime String 100 Y 支付时间,毫秒时间戳
channelType String 20 Y 渠道类型,WECHAT-微信，ALIPAY-支付宝
goodsInfo Array - Y 商品开票信息列表
invoiceKind String 20 Y 发票种类,NORMAL-增值税普通发票，SPECIAL-增值税专用发票
merchantId String 50 Y 商户号
orderAmount String 15 Y 订单金额，单位分
outOrderNo String 50 Y 商户订单号
outerApplyId String 64 Y 服务商侧开票申请编号
partnerId String 32 Y 服务商编号,801开头的代理商编号
remark String 500 N 备注
realEstateInfo Array - N 不动产信息列表,产品为不动产租赁发票时必填
transactionChannel String - N 交易渠道 OTHER-非微信交易
渠道类型为微信并且是非微信交易，则交易渠道传OTHER，否则传空

4.2.1 goodsInfo具体参数

参数 类型 长度 必填 参数说明
goodsName String - Y 商品/服务名称
taxCode String - Y 税务编码
taxRate String - Y 税率：由商户确定开票的税率，系统仅做透传 例：13% 传值13 商品不同税率不同，税率不在范围内会开票失败。（税务编号及对应的名称，可以通过第三方接口查询获取；如果需要我司提供，请联系技术对接人员）
specification String 20 N 规格型号
discount String - Y 是否折扣行 取值范围（Boolean：true/false）：指定该发票行是否折扣行，折扣行必须是被折扣行的下一行。当某个goodsInfo数据为折扣行时，只能传taxCode、taxRate、goodName、amount、discount这几个参数并保持和上一条被折扣行数据一致（折扣行时金额为负数），其他的参数不要传，否者会开票失败
preferentialPolicy String - N 优惠政策标识,优惠政策标识。SIMPLE_COLLECTION-简易征收; RARE_EARTH_PRODUCT-稀土产品; TAX_EXEMPT-免税; NO_COLLECTION-不征税; ADVANCE_REFUND-先征后退; FULL_ADVANCE_REFUND-100%先征后退; HALF_ADVANCE_REFUND-50%先征后退; SIMPLE_COLLECTION_3_PERCENT-按3%简易征收; SIMPLE_COLLECTION_5_PERCENT-按5%简易征收; SIMPLE_COLLECTION_5_PERCENT_REDUCED-按5%简易征收减按1.5%计征; IMMEDIATE_REFUND_30_PERCENT-即征即退30%; IMMEDIATE_REFUND_50_PERCENT-即征即退50%; IMMEDIATE_REFUND_70_PERCENT-即征即退70%; IMMEDIATE_REFUND_100_PERCENT-即征即退100%; SUPER_TAX_REFUND_3_PERCENT-超税负3%即征即退; SUPER_TAX_REFUND_8_PERCENT-超税负8%即征即退; SUPER_TAX_REFUND_12_PERCENT-超税负12%即征即退; SUPER_TAX_REFUND_6_PERCENT-超税负6%即征即退
fuelInfo Object - N 成品油信息
quantity String - N 数量, 据实际情况定，最多支持4位小数
unit String - N 单位,成品油时必须为：LITER 或 TON，普通发票为自由单位，建议传中文计量单位，如个/件/份/升/次
amount String - N 价格,含税金额（分），折扣行时必填且必须为负数，非折扣行选填（不传则使用订单金额）

4.2.1.1 fuelInfo具体参数

参数 类型 长度 必填 参数说明
gunNumber String 20 Y 油枪编号
station String 100 Y 油站地址

4.2.2 realEstateInfo具体参数

参数 类型 长度 必填 参数说明
serialNo String 32 Y 明细行号，与商品明细行号对应
province String 20 Y 不动产坐落省份，必须以省、自治区、特别行政区、北京市、天津市、上海市、重庆市任意一个关键词结尾。涉及多笔不动产租赁订单时，该字段值必须相同
city String 20 N 不动产坐落城市，必须以市、盟、自治州、地区、区任意一个关键词结尾。省为香港/澳门/台湾时可为空，其他情况必填。省为重庆市/海南省时可以县结尾
address String 80 Y 不动产坐落详细地址，必须包含街、路、村、乡、镇、道、巷、号任意一个关键词。发票版式文件上的不动产地址由省、市、详细地址三个字段拼接而成
startTime String 32 Y 租赁期起，遵循RFC3339标准格式：yyyy-MM-DDTHH:mm:ss+TIMEZONE
endTime String 32 Y 租赁期止，遵循RFC3339标准格式：yyyy-MM-DDTHH:mm:ss+TIMEZONE
crossCityFlag String 32 Y 跨地（市）标志，销售方营业执照注册地址与不动产地址中地市一致时为false，不一致时为true
certificateNo String 40 N 产权证书/不动产权证号，无值时传"无"。该字段为密文字段，需要使用微信支付公钥加密
plateNos Array - N 车牌号列表，最多3个。发票行信息tax_code为3040502020200000000（车辆停放服务）时必填
area String 30 Y 不动产使用面积，整数最长17位，小数最长13位，单位为平方米
code String 32 N 不动产自定义编码，仅支持英文字母（大写和小写）、数字、短横线（-）和下划线（_）

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 错误信息,成功为空，失败返回具体错误描述
fapiaoApplyId String 50 N 发票申请ID,系统内发票申请编号（受理成功时返回）
outerApplyId String 64 N 外部申请单号,服务商侧开票申请编号（原样返回）
invoiceStatus String 20 N 发票状态,APPLYING-开票中，SUCCESS-开票成功，FAIL-开票失败，REVERSING-冲红中，REVERSED-已冲红

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

响应码 响应码描述 解决方案
00000 成功 请求处理成功
40000 参数错误 请求参数缺失或格式不正确
40001 签名验证不通过 请求签名验证失败，请检查签名参数
40002 商户号有误 请检查商户号是否真实存在
40003 频率超限 请求频率超过限制，请稍后重试
40004 开票金额超过可开票额度 开票金额超过该订单剩余可开票额度
40005 交易剩余开票额度不足 该交易剩余可开票额度不足
40006 商户税号不匹配 商户税号与配置不一致
40007 开票产品类型不支持 开票产品类型不支持
40008 不支持该税收分类编码 该税收分类编码不支持
40009 并发冲突，请稍后重试 并发冲突，请稍后重试
40010 网关非法参数 检查请求参数，修改后重新发起请求
40011 前置系统参数验证错误 检查请求参数，修改后重新发起请求
40012 不允许开具增值税专用发票 该场景不允许开具增值税专用发票
40013 个人抬头不允许开增值税专用发票 个人抬头不允许开具增值税专用发票
50000 系统异常 系统内部异常，请稍后重试
50001 失败 请求处理失败
50002 交易超时 请求处理超时，请稍后查询确认结果
50003 业务失败 参看具体错误描述
50004 商户无权限 商户未开通该功能或无操作权限
50005 资源不存在 请求的资源不存在
50006 发票申请单已存在 同一订单或外部申请单号已存在发票申请
50007 发票开具中，不可重复申请 该笔订单已有开票申请正在处理中
50008 发票冲红中，不可重复申请 该发票正在冲红处理中，请等待完成
50009 关联蓝字发票不存在 冲红时关联的蓝字发票不存在
50010 关联蓝字发票状态异常 冲红时关联的蓝字发票状态异常
50011 发票信息不存在 查询的发票信息不存在
50012 蓝字发票已被红冲 蓝字发票已被红冲，不可重复操作
50013 企业开票配置不存在 企业开票配置信息不存在
50014 企业发票产品不存在 企业发票产品信息不存在
50015 开票产品未开通 开票产品尚未开通
50016 开票产品未启用 开票产品未启用
50017 商品不存在 商品信息不存在
50018 企业未配置默认商品 企业未配置默认商品
50019 购买方信息与用户填写抬头不一致 购买方信息与用户填写抬头不一致
50020 订单所属商户与当前商户不一致 订单所属商户与当前商户不一致
50021 用户尚未完成发票抬头填写 用户尚未完成发票抬头填写
50022 业务规则限制 业务规则限制
50023 发票状态异常 发票状态异常
50024 发票文件下载失败 发票文件下载失败
50025 发票文件下载返回空 发票文件下载返回空
50026 查询结果为空 原订单或发票记录不存在

results matching ""

    No results matching ""