银盛支付即开票系统服务商接口接入指引

项目	内容
文档版本	V1.6
更新日期	2026-09-01
适用对象	通过银盛开放平台 API 接入即开票系统的服务商
接口文档	开放平台网关文档 · 增值业务 > 数电发票

本文档只做接入指引，接口字段、枚举值、错误码等细节一律以官方在线接口文档为准，本文不再罗列。

接口文档地址：https://gateway-doc.ysepay.com/gatewayDocs/summary/N0000004/N0000677/I0000468.html

一、接入前置准备

入网、开票、冲红都是异步流程：接口同步返回只代表"受理成功"，最终结果以异步回调通知或主动查询为准。
回调服务：回调地址 notifyUrl 在商户入网时就要传入，且必须公网可达，所有的通知都是这一个接口。

环境与地址：

环境	网关地址
正式环境	`https://ysgate.ysepay.com/openapi/invoice/{接口路径}`

1.1 角色与链路

二、接口清单

序号	接口名称	路径	用途	接入优先级
1	发票渠道激活码查询	`invoice/activateCodeQuery`	查询服务商名下可用激活码	★ 按需
2	发票商户入网新增	`invoice/merchantRegister`	登记商户 + 提交激活码，返回邀请链接	★★★★ 必须
3	发票邀请查询	`invoice/inviteStatusQuery`	查询商户邀请授权状态	★★★★ 必须
4	发票产品状态查询	`invoice/productStatusQuery`	查询是否具备开票能力	★★★★ 必须
5	发票开具	`invoice/issue`	发起开票	★★★★ 必须
6	发票查询	`invoice/query`	查询发票状态/票号	★★★ 建议
7	发票下载	`invoice/download`	下载发票文件（Base64）	★★ 按需
8	发票冲红	`invoice/reverse`	对已开发票全额冲红	★★ 按需
9	发票商户入网查询	`invoice/merchantQuery`	查询商户入网详情	★★★ 建议
10	发票渠道邀请链接查询	`invoice/inviteUrlQuery`	补偿获取授权邀请链接	★★ 按需
11	发票商户入网修改	`invoice/merchantModify`	商户信息变更 / 新增渠道	★★ 按需
—	商户入驻状态回调通知	（回调接收）	入网/授权/产品状态变更	★★★ 建议
—	发票状态变更回调通知	（回调接收）	开票/冲红结果通知	★★★ 建议

四、接口说明

接口参数细节请查阅官方在线文档。

步骤 0：购买激活码（商务准备，无接口）

到终端商城购买发票渠道激活码。

同时准备好：服务商编号 partnerId、发起方商户号 certId、商户私钥/银盛公钥、公网可达的回调地址 notifyUrl、试点商户资料

步骤 1：查询可用激活码

-- 可选步骤

接口：invoice/activateCodeQuery
目的：确认名下有 ACTIVE 状态的激活码。该接口只读，适合作为连通性验证的第一个接口。

步骤 2：发票商户入网

接口：invoice/merchantRegister
目的：提交商户资料 + 激活码 + notifyUrl，系统返回 merchantId 和各渠道授权邀请链接。
后续节点：把邀请链接/二维码发给商户，引导商户在微信/支付宝端完成授权。
辅助接口（按需）：授权链接失效补偿 invoice/inviteUrlQuery；查询入网状态 invoice/merchantQuery；信息变更/新增渠道 invoice/merchantModify。

步骤 3：查询商户授权状态

接口：invoice/inviteStatusQuery
枚举：邀请状态为 ACCEPTED（已接受）即商户授权完成；INVITING 表示链接已生成待商户操作；FAILED 需查看原因并重新发链接。

步骤 4：查询产品状态

-- 此状态决定是否能开票

接口：invoice/productStatusQuery
枚举：对应渠道的产品接入状态为 ENABLED 且授权状态为 AUTHORIZED，才真正可以开票。
系统也会主动推送商户入驻状态回调（PRODUCT_AUTHORIZED 等事件），收到回调后再调本接口核对即可，无需高频轮询。

步骤 5：发起开票

接口：invoice/issue
要点：
- outerApplyId（服务商侧开票申请编号）幂等键，需服务商自行保证唯一性，重复提交会开票失败；
- 金额单位一律为分；
- 同步返回成功仅代表受理，返回 fapiaoApplyId，开票结果异步产出。

步骤 6：获取开票结果（回调 + 查询）

被动接收：发票状态变更回调推送到 notifyUrl
主动查询：invoice/query，按 outerApplyId 查发票状态。

回调重试多次后仍失败将不再推送，建议对长时间受理中的申请单主动发起查询。

开票失败（INVOICE_FAIL）：按 failReason 修正数据后，更换新的 outerApplyId 重新调用开票接口。

步骤 7：发票下载

接口：invoice/download（前置条件：发票状态 SUCCESS）
返回 fileContent 为 Base64 编码的文件内容（非下载链接），解码后保存为 PDF/OFD 交付商户。

冲红与重开（按需）

接口：invoice/reverse，传原蓝字发票的 outerApplyId，仅开票成功的蓝字发票可冲红，且为全额冲红。
结果以回调 REVERSE_SUCCESS / REVERSE_FAIL 或 invoice/query 查询为准。
冲红后如需重开：换新的 outerApplyId 重新调用开票接口。

五、全流程时序图

> 主链路自上而下读：准备 → 入网授权 → 开票交付

六、异步回调接收要求

项目	要求
推送方式	`POST` JSON，推送到入网时配置的 `notifyUrl`
成功应答	5 秒内返回 HTTP `200`，响应体为字符串 `success`
失败重试	系统自动重试，多次失败（最多 8 次）后不再推送，可查询兜底
实现要点	先落库再异步处理；按业务单号幂等去重

两类核心通知：

通知	关键事件
商户入驻状态回调	`PRODUCT_AUTHORIZED`（授权成功可开票）、`PRODUCT_AUTH_FAILED`、`PRODUCT_DISABLED` 等
发票状态变更回调	`INVOICE_APPLYING`、`INVOICE_SUCCESS`、`INVOICE_FAIL`、`REVERSE_SUCCESS`、`REVERSE_FAIL`

另外还有抬头变更等业务通知，按需处理，字段结构见官方在线文档。

七、接入自检清单

[ ] 回调服务就绪：公网可达，5 秒内应答 HTTP 200 + success，需服务商做幂等去重
[ ] 调通激活码查询【连通性验证】
[ ] 入网拿到 merchantId，商户完成扫码授权
[ ] 产品状态确认为 ENABLED + AUTHORIZED，收到 PRODUCT_AUTHORIZED 回调
[ ] 开票受理成功，收到 INVOICE_SUCCESS（或查询到 SUCCESS），能下载并解码发票文件
[ ] 同一 outerApplyId 重复提交被幂等拦截，不重复开票
[ ] 开票失败有内部处理流程（修正后换新 outerApplyId 重试）
[ ] 【按需】冲红成功，冲红后能换新单号重开

服务商接口接入指南