发票开具
1、修订记录
| 修订记录 |
日期 |
说明 |
| 1.0 |
2026.07.01 |
初版
|
2、业务说明
（1）接口说明
发票开具
请求主体类型：application/json
请求方式：POST
3、请求地址
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 |
Y |
请求唯一流水号,商户系统唯一，要求32个字符内（最少14个字符），只能是数字、大小写字母_-且在同一个商户号下唯一。最后12位要求格式为"yyMMddHHmmss" 示例值：xy1415220315145602 |
| certId |
String |
Y |
发起方商户号，服务商在银盛给自己开设的商户号，即可当作发起方商户号，由银盛生成并下发。 注意：不同于子商户号，服务商发展的商户即为子商户号 |
| version |
String |
Y |
调用的接口版本，固定为：1.0 |
4.2、业务请求参数
（bizContent加密前的json数据明文字符串）
| 参数 |
类型(长度） |
必填 |
参数说明 |
| ability |
String(50) |
Y |
开票类型,BASIC-基础行业，REAL_ESTATE_LEASE -不动产租赁，REFINED_OIL-成品油 |
</pre> |
| 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 | 不动产信息列表,不动产信息列表，产品为不动产租赁发票时必填
|
4.2.1 goodsInfo具体参数
| 参数 |
类型(长度） |
必填 |
参数说明 |
| goodsName |
String |
Y |
商品/服务名称 |
| taxCode |
String |
Y |
税务编码 |
| taxRate |
String |
Y |
税率 |
| specification |
String(20) |
N |
规格型号,规格型号
|
| discount |
String |
Y |
是否折扣行,是否折扣行
|
| 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 |
数量,数量
|
| unit |
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-已冲红 |
| 响应码 |
响应码描述 |
解决方案 |
| 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 |
查询结果为空 |
原订单或发票记录不存在 |