BBIT-Kai
14 KiB
14 KiB
票通对接业务流程说明
本文基于以下资料整理：
1. 你的角色本质是什么
结论：是的，你本质上是“接入方平台 / 第三方平台 / 中台”，帮助甲方企业对接票通，以甲方企业的名义完成开票。
但这里不是简单的 HTTP 转发，还包括以下职责：
- 维护“你的平台”和“开票企业”的绑定关系
- 维护或选择甲方企业可用的数电账号
- 组织开票报文并调用票通接口
- 处理登录认证、风险认证
- 接收票通推送或主动查询开票结果
- 再把开票结果回写给你自己的业务系统
从票通文档看，这个角色被明确定义为：
第三方平台/集团企业接入方系统
关键依据：
- 对接指引说明“接入方系统开发完成后，由票通提供正式环境参数”
- 直接开票场景中，
系统接入方组织好待开票信息后，直接调用 2.9 开具蓝字数电发票 - 企业通过接口注册后，会自动生成“平台和企业的绑定关系”；如果企业已在票通完成入驻，则需要联系票通侧建立“接入方平台和开票企业的绑定关系”
所以业务归属上：
- 开票主体是甲方企业
- 票通是开票服务平台
- 你是中间接入平台
2. 票通是否提供测试接口
结论：提供。
2.1 测试环境说明
票通对接指引明确写了：
- 测试环境和参数信息由票通对接人员提供
- 包括平台编码、RSA 证书、3DES 密钥、测试税号
- 正式上线前，再由票通提供正式环境参数
文档里的核心说明：
- 测试环境参数：平台编码、RSA 签名验签证书、3DES 密钥、测试税号
- 联调测试阶段，可直接使用票通对接人员提供的测试税号
2.2 测试地址风格
核心测试地址统一是：
http://fpkj.testnw.vpiaotong.cn/tp/openapi/...
正式地址统一是：
https://fpkj.vpiaotong.com/tp/openapi/...
2.3 你当前真正会用到的测试接口
register.ptregisterUser.ptsendLoginSmsCode.ptsmsLogin.ptgetAuthenticationQrcode.ptqueryAuthQrcodeScanStatus.ptgetTaxBureauAccountAuthStatus.ptlistTaxBureauAccount.ptinvoiceBlue.ptqueryInvoice.ptqueryInvoiceInfo.ptlogoutEtax.ptgetEnterpriseInfo.ptqueryEnterpriseBankInfo.pt
注意：
- 推送接口
2.13 / 2.14 / 2.48没有票通固定测试地址，因为这是“票通调用你提供的接口地址” - 也就是说，回调 URL 不是你调用票通时传进去的，而是你提供给票通侧配置使用的
3. 开票结果“回写”到底分几层
这里要分清楚两层，不要混在一起。
3.1 第一层：票通把结果返回给你的平台
这是票通体系内的结果同步，主要有两种方式：
方式 A：票通推送
票通文档定义了：
2.13 推送发票主要信息2.14 推送发票全票面信息
调用关系写得很明确：
票通平台调用第三方平台接口地址：第三方平台提供
这就是我们说的“回调”。
方式 B：你的平台主动查询
票通文档定义了：
2.11 查询发票主要信息2.12 查询发票全票面信息
也就是说，开票结果可以：
- 等票通推送过来
- 或者你主动轮询查询
最佳实践不是二选一，而是：
- 主用推送
- 查询作为补偿和兜底
3.2 第二层：你的平台再把结果写回你自己的业务系统
这个“开票结果回写接口”不是给票通用的。
它是你自己的业务系统接口，用来做这些事：
- 把原始业务单据状态改成“开票成功/失败/处理中”
- 回写发票号码、数电发票号码、开票日期
- 回写失败原因
- 记录票通流水号或发票请求流水号
所以：
票通 -> 你的平台：票通文档里有你的平台 -> 你的业务系统：票通文档里没有，需要你自己定义
4. 回调是怎么和票通绑定的
从文档能确认两件事：
2.13 / 2.14 / 2.48都是“票通平台调用第三方平台”- 接口地址不是你在开票请求里传递，而是“第三方平台提供”
因此可以得出一个明确结论：
- 回调地址不是按每张发票动态传的
- 而是你先提供给票通，由票通侧事先配置
文档没有给出“通过某个接口动态设置回调地址”的描述，所以这里应按“线下配置 / 对接阶段配置”理解。
实际落地时通常就是：
- 你先准备一个公网可访问的回调地址
- 提供给票通对接人员
- 票通侧把这个地址配置成推送接收地址
- 票通后续在开票成功、失败、认证异常等场景调用你的回调接口
对你来说要注意：
- 回调接口必须能公网访问
- 必须按票通公共报文做验签和解密
- 要做幂等，避免重复推送重复入库
- 不能只靠回调，最好仍保留主动查询兜底
5. 开票结果样例怎么理解
这里也分两种。
5.1 票通推送/查询给你的样例
这个在票通文档里是有的。
最有代表性的就是：
2.13 推送发票主要信息样例2.11 查询发票主要信息样例2.12 查询发票全票面信息样例
例如 2.13 的成功推送报文会包含：
taxpayerNuminvoiceReqSerialNoinvoiceTypeinvoiceKindcodemsgtradeNodefinedDatainvoiceCodeinvoiceNoelectronicInvoiceNoinvoiceDatenoTaxAmounttaxAmountinvoicePdfinvoiceXmldownloadUrl
其中：
code=0000表示成功code=3999表示需要扫码或短信认证code=9999表示开票失败
5.2 你写回甲方业务系统的样例
这个在票通文档里没有，因为这是你自己的内部系统接口。
你至少需要自己约定一份这样的回写报文：
{
"bizOrderNo": "CG202604290001",
"companyId": "COMP_001",
"invoiceReqSerialNo": "DEMO202604290001234567",
"status": "SUCCESS",
"ptCode": "0000",
"ptMsg": "开具成功",
"invoiceCode": "123456789012",
"invoiceNo": "12345678",
"electronicInvoiceNo": "12345678901212345678",
"invoiceDate": "2026-04-29 14:20:31",
"noTaxAmount": "90.50",
"taxAmount": "11.50",
"downloadUrl": "https://...",
"definedData": "自定义数据"
}
失败样例建议至少保留：
{
"bizOrderNo": "CG202604290001",
"companyId": "COMP_001",
"invoiceReqSerialNo": "DEMO202604290001234567",
"status": "FAILED",
"ptCode": "9999",
"ptMsg": "开票失败，失败原因见票通返回",
"failReason": "票通返回的失败描述"
}
6. 按业务流程顺序，你需要知道和会用到的接口
下面按实际开发顺序来列，不按文档章节号罗列。
6.1 安全机制和公共报文
所有接口调用前都要先满足：
- 公共报文使用 RSA 签名
- 业务报文使用 3DES 加密
- 编码统一 UTF-8
- 公共字段包括：
platformCodesignTypesignformattimestampversionserialNocontent
注意事项：
content里放的是除公共参数外的全部业务参数- RSA 签名结果要做 Base64 编码
- 业务 JSON 编码统一 UTF-8
6.2 企业是否已入驻票通
你需要先确认开票企业是否已经具备票通开票资格。
可用接口：
2.2 注册企业2.47 查询企业信息2.48 企业审核结果推送
使用顺序建议：
- 如果甲方企业尚未入驻，走
2.2 注册企业 - 注册后用
2.47 查询企业信息看审核状态 - 如果票通侧支持，可接
2.48 企业审核结果推送
注意事项：
- 企业必须先完成入驻才能开票
- 如果企业不是通过接口注册，而是在票通侧已存在，需要和票通做“平台与企业绑定”
reviewStatus要关注：0待审核1审核通过2审核不通过3审核中
6.3 数电账号准备
如果甲方企业已经入驻，下一步是准备可以用于开票的数电账号。
可用接口：
2.3 数电账号登记2.45 查询数电账号列表2.8 查询数电账号认证状态2.46 退出电子税局登录
使用顺序建议：
- 先用
2.45查询某税号下已经维护好的数电账号 - 如果你需要平台内维护账号，再用
2.3登记 - 开票前用
2.8检查认证状态 - 如存在异常登录状态，再视情况用
2.46退出后重登
注意事项：
2.3的密码和身份密码要用票通要求的 3DES 加密2.45 / 2.8会返回：operationProposedauthStatusswitchablewechatUserBindStatus
operationProposed最重要：0无需认证1需扫码认证2需扫码或短信认证3需短信认证
6.4 开票前置检查
正式开票前，建议先做企业和票面数据检查。
建议用到：
2.47 查询企业信息2.49 查询企业开户行及账号2.45 查询数电账号列表2.8 查询数电账号认证状态
注意事项：
2.49文档明确说明：可用于避免“企业没有维护开户行及账号导致开票失败”- 如果票通平台和电子税局都没有维护开户行及账号，需要先提醒企业维护
- 查询电子税局开户行及账号时，要求数电账号已登录认证
6.5 发起开票
核心接口：
2.9 开具蓝字数电发票
你的业务场景重点注意以下字段：
invoiceIssueKindCode- 农产品收购发票只能开数电普通票，建议按
82
- 农产品收购发票只能开数电普通票，建议按
specialInvoiceKind- 农产品收购发票必须传
02
- 农产品收购发票必须传
invoiceReqSerialNo- 一张发票的唯一幂等号
account- 明确指定开票使用的数电账号
definedData- 建议传你自己的业务单号或关联标识，后续推送会原样带回
tradeNo- 可传业务订单号，不传时票通默认使用
invoiceReqSerialNo
- 可传业务订单号，不传时票通默认使用
农产品收购发票特别注意：
- 文档写明：
specialInvoiceKind=02时，只能开具数电票（普通发票） - 文档还写明：
购方信息代表实际的销方信息，销方信息是实际的购方 purchaseInvSellerIdType开具农产品收购发票时必填buyerTaxpayerNum开具农产品收购发票时必填
注意事项：
invoiceReqSerialNo对同一张票重试时不能变- 文档明确提示：如果变更同一张票的请求流水号，可能造成重开发票
- 返回里的
qrCodePath/qrCode可用于打开 H5 实时查看开票状态
6.6 如果开票遇到认证
如果开票返回 3999，不要直接判成普通失败。
可用接口：
2.8 查询数电账号认证状态2.4 获取登录短信验证码2.5 短信登录2.6 获取实名认证二维码2.7 查询实名认证二维码扫码状态
短信认证路径：
- 调
2.8看建议 - 如果允许短信认证，调
2.4 - 再调
2.5完成登录
扫码认证路径：
- 调
2.6获取二维码 - 展示二维码给用户
- 轮询
2.7查询扫码状态 - 认证完成后，再继续原开票流程
注意事项：
2.4返回6666时，文档说“无需真正发送短信验证码，系统会自动登录成功”2.6二维码一般 5 分钟左右过期2.7文档特别提示：接口比较耗时，请调长超时时间2.7的scanStatus：1未扫码2已扫码3二维码已过期
6.7 获取开票结果
结果同步建议两条线都做。
第一条：票通推送
2.13 推送发票主要信息2.14 推送发票全票面信息
作用：
- 票通开票成功、失败、需要认证时，主动通知你
注意事项：
- 接口地址由你提供给票通配置
- 你返回的业务结果码：
0000接收成功9999接收失败
第二条：主动查询
2.11 查询发票主要信息2.12 查询发票全票面信息
作用：
- 回调没到时兜底
- 开票中状态补偿查询
- 手动刷新状态
关键状态码：
0000开票成功6666未开票7777开票中9999开票失败3999需要扫码或短信认证
6.8 结果落库并回写你自己的业务系统
这一段票通不会帮你做，需要你自己做。
建议你的平台在收到 2.13 推送或 2.11 / 2.12 查询结果后：
- 更新本地开票任务状态
- 保存发票号码、数电发票号码、开票时间、失败原因
- 再调用你自己的业务系统回写接口
建议你自己的回写接口至少要包含：
- 业务单号
- 公司标识
- 发票请求流水号
- 开票状态
- 票通状态码
- 票通状态描述
- 发票号码 / 数电发票号码
- 开票日期
- 金额 / 税额
- 下载地址或文件标识
7. 这份文档给你的最终结论
你现在最需要抓住的不是“票通有多少接口”，而是下面这条最小闭环：
- 确认企业已入驻且已与平台绑定
- 确认企业下有可用数电账号
- 开票前检查认证状态和企业基础信息
- 调
2.9发起农产品收购发票开具 - 如遇
3999，走短信认证或扫码认证 - 用
2.13 / 2.14收推送，同时用2.11 / 2.12做补偿查询 - 最后把结果回写到你自己的业务系统
如果只按开发优先级排序，你最先应该落的接口就是：
2.45 查询数电账号列表2.8 查询数电账号认证状态2.9 开具蓝字数电发票2.11 查询发票主要信息2.13 推送发票主要信息2.4 / 2.5 / 2.6 / 2.7认证链路
对你这个项目最容易踩坑的点有 4 个：
- 农产品收购发票字段语义和普通蓝票不同，购销方字段有反转
invoiceReqSerialNo必须稳定复用，不能重试就换- 回调地址不是请求里传的，而是提前配置给票通的
- “开票结果回写接口”不是票通接口，而是你自己的业务系统接口