BBIT-Kai
514 lines
14 KiB
Markdown
514 lines
14 KiB
Markdown
# 票通对接业务流程说明
|
||
|
||
本文基于以下资料整理：
|
||
|
||
- [系统设计.md](C:\Users\BBIT\Desktop\农产品收购发票开票平台\系统设计.md)
|
||
- [doc\票通数电平台对接指引v1.0(2).txt](C:\Users\BBIT\Desktop\农产品收购发票开票平台\doc\票通数电平台对接指引v1.0(2).txt)
|
||
- [doc\票通数电发票接口文档3.3.5.txt](C:\Users\BBIT\Desktop\农产品收购发票开票平台\doc\票通数电发票接口文档3.3.5.txt)
|
||
|
||
## 1. 你的角色本质是什么
|
||
|
||
结论：是的，你本质上是“接入方平台 / 第三方平台 / 中台”，帮助甲方企业对接票通，以甲方企业的名义完成开票。
|
||
|
||
但这里不是简单的 HTTP 转发，还包括以下职责：
|
||
|
||
- 维护“你的平台”和“开票企业”的绑定关系
|
||
- 维护或选择甲方企业可用的数电账号
|
||
- 组织开票报文并调用票通接口
|
||
- 处理登录认证、风险认证
|
||
- 接收票通推送或主动查询开票结果
|
||
- 再把开票结果回写给你自己的业务系统
|
||
|
||
从票通文档看，这个角色被明确定义为：
|
||
|
||
- `第三方平台` / `集团企业`
|
||
- `接入方系统`
|
||
|
||
关键依据：
|
||
|
||
- 对接指引说明“接入方系统开发完成后，由票通提供正式环境参数”
|
||
- 直接开票场景中，`系统接入方组织好待开票信息后，直接调用 2.9 开具蓝字数电发票`
|
||
- 企业通过接口注册后，会自动生成“平台和企业的绑定关系”；如果企业已在票通完成入驻，则需要联系票通侧建立“接入方平台和开票企业的绑定关系”
|
||
|
||
所以业务归属上：
|
||
|
||
- 开票主体是甲方企业
|
||
- 票通是开票服务平台
|
||
- 你是中间接入平台
|
||
|
||
## 2. 票通是否提供测试接口
|
||
|
||
结论：提供。
|
||
|
||
### 2.1 测试环境说明
|
||
|
||
票通对接指引明确写了：
|
||
|
||
- 测试环境和参数信息由票通对接人员提供
|
||
- 包括平台编码、RSA 证书、3DES 密钥、测试税号
|
||
- 正式上线前，再由票通提供正式环境参数
|
||
|
||
文档里的核心说明：
|
||
|
||
- 测试环境参数：平台编码、RSA 签名验签证书、3DES 密钥、测试税号
|
||
- 联调测试阶段，可直接使用票通对接人员提供的测试税号
|
||
|
||
### 2.2 测试地址风格
|
||
|
||
核心测试地址统一是：
|
||
|
||
```text
|
||
http://fpkj.testnw.vpiaotong.cn/tp/openapi/...
|
||
```
|
||
|
||
正式地址统一是：
|
||
|
||
```text
|
||
https://fpkj.vpiaotong.com/tp/openapi/...
|
||
```
|
||
|
||
### 2.3 你当前真正会用到的测试接口
|
||
|
||
- `register.pt`
|
||
- `registerUser.pt`
|
||
- `sendLoginSmsCode.pt`
|
||
- `smsLogin.pt`
|
||
- `getAuthenticationQrcode.pt`
|
||
- `queryAuthQrcodeScanStatus.pt`
|
||
- `getTaxBureauAccountAuthStatus.pt`
|
||
- `listTaxBureauAccount.pt`
|
||
- `invoiceBlue.pt`
|
||
- `queryInvoice.pt`
|
||
- `queryInvoiceInfo.pt`
|
||
- `logoutEtax.pt`
|
||
- `getEnterpriseInfo.pt`
|
||
- `queryEnterpriseBankInfo.pt`
|
||
|
||
注意：
|
||
|
||
- 推送接口 `2.13 / 2.14 / 2.48` 没有票通固定测试地址，因为这是“票通调用你提供的接口地址”
|
||
- 也就是说，回调 URL 不是你调用票通时传进去的，而是你提供给票通侧配置使用的
|
||
|
||
## 3. 开票结果“回写”到底分几层
|
||
|
||
这里要分清楚两层，不要混在一起。
|
||
|
||
### 3.1 第一层：票通把结果返回给你的平台
|
||
|
||
这是票通体系内的结果同步，主要有两种方式：
|
||
|
||
#### 方式 A：票通推送
|
||
|
||
票通文档定义了：
|
||
|
||
- `2.13 推送发票主要信息`
|
||
- `2.14 推送发票全票面信息`
|
||
|
||
调用关系写得很明确：
|
||
|
||
- `票通平台调用第三方平台`
|
||
- `接口地址：第三方平台提供`
|
||
|
||
这就是我们说的“回调”。
|
||
|
||
#### 方式 B：你的平台主动查询
|
||
|
||
票通文档定义了：
|
||
|
||
- `2.11 查询发票主要信息`
|
||
- `2.12 查询发票全票面信息`
|
||
|
||
也就是说，开票结果可以：
|
||
|
||
- 等票通推送过来
|
||
- 或者你主动轮询查询
|
||
|
||
最佳实践不是二选一，而是：
|
||
|
||
- 主用推送
|
||
- 查询作为补偿和兜底
|
||
|
||
### 3.2 第二层：你的平台再把结果写回你自己的业务系统
|
||
|
||
这个“开票结果回写接口”不是给票通用的。
|
||
|
||
它是你自己的业务系统接口，用来做这些事：
|
||
|
||
- 把原始业务单据状态改成“开票成功/失败/处理中”
|
||
- 回写发票号码、数电发票号码、开票日期
|
||
- 回写失败原因
|
||
- 记录票通流水号或发票请求流水号
|
||
|
||
所以：
|
||
|
||
- `票通 -> 你的平台`：票通文档里有
|
||
- `你的平台 -> 你的业务系统`：票通文档里没有，需要你自己定义
|
||
|
||
## 4. 回调是怎么和票通绑定的
|
||
|
||
从文档能确认两件事：
|
||
|
||
1. `2.13 / 2.14 / 2.48` 都是“票通平台调用第三方平台”
|
||
2. 接口地址不是你在开票请求里传递，而是“第三方平台提供”
|
||
|
||
因此可以得出一个明确结论：
|
||
|
||
- 回调地址不是按每张发票动态传的
|
||
- 而是你先提供给票通，由票通侧事先配置
|
||
|
||
文档没有给出“通过某个接口动态设置回调地址”的描述，所以这里应按“线下配置 / 对接阶段配置”理解。
|
||
|
||
实际落地时通常就是：
|
||
|
||
1. 你先准备一个公网可访问的回调地址
|
||
2. 提供给票通对接人员
|
||
3. 票通侧把这个地址配置成推送接收地址
|
||
4. 票通后续在开票成功、失败、认证异常等场景调用你的回调接口
|
||
|
||
对你来说要注意：
|
||
|
||
- 回调接口必须能公网访问
|
||
- 必须按票通公共报文做验签和解密
|
||
- 要做幂等，避免重复推送重复入库
|
||
- 不能只靠回调，最好仍保留主动查询兜底
|
||
|
||
## 5. 开票结果样例怎么理解
|
||
|
||
这里也分两种。
|
||
|
||
### 5.1 票通推送/查询给你的样例
|
||
|
||
这个在票通文档里是有的。
|
||
|
||
最有代表性的就是：
|
||
|
||
- `2.13 推送发票主要信息` 样例
|
||
- `2.11 查询发票主要信息` 样例
|
||
- `2.12 查询发票全票面信息` 样例
|
||
|
||
例如 `2.13` 的成功推送报文会包含：
|
||
|
||
- `taxpayerNum`
|
||
- `invoiceReqSerialNo`
|
||
- `invoiceType`
|
||
- `invoiceKind`
|
||
- `code`
|
||
- `msg`
|
||
- `tradeNo`
|
||
- `definedData`
|
||
- `invoiceCode`
|
||
- `invoiceNo`
|
||
- `electronicInvoiceNo`
|
||
- `invoiceDate`
|
||
- `noTaxAmount`
|
||
- `taxAmount`
|
||
- `invoicePdf`
|
||
- `invoiceXml`
|
||
- `downloadUrl`
|
||
|
||
其中：
|
||
|
||
- `code=0000` 表示成功
|
||
- `code=3999` 表示需要扫码或短信认证
|
||
- `code=9999` 表示开票失败
|
||
|
||
### 5.2 你写回甲方业务系统的样例
|
||
|
||
这个在票通文档里没有，因为这是你自己的内部系统接口。
|
||
|
||
你至少需要自己约定一份这样的回写报文：
|
||
|
||
```json
|
||
{
|
||
"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": "自定义数据"
|
||
}
|
||
```
|
||
|
||
失败样例建议至少保留：
|
||
|
||
```json
|
||
{
|
||
"bizOrderNo": "CG202604290001",
|
||
"companyId": "COMP_001",
|
||
"invoiceReqSerialNo": "DEMO202604290001234567",
|
||
"status": "FAILED",
|
||
"ptCode": "9999",
|
||
"ptMsg": "开票失败，失败原因见票通返回",
|
||
"failReason": "票通返回的失败描述"
|
||
}
|
||
```
|
||
|
||
## 6. 按业务流程顺序，你需要知道和会用到的接口
|
||
|
||
下面按实际开发顺序来列，不按文档章节号罗列。
|
||
|
||
### 6.1 安全机制和公共报文
|
||
|
||
所有接口调用前都要先满足：
|
||
|
||
- 公共报文使用 RSA 签名
|
||
- 业务报文使用 3DES 加密
|
||
- 编码统一 UTF-8
|
||
- 公共字段包括：
|
||
- `platformCode`
|
||
- `signType`
|
||
- `sign`
|
||
- `format`
|
||
- `timestamp`
|
||
- `version`
|
||
- `serialNo`
|
||
- `content`
|
||
|
||
注意事项：
|
||
|
||
- `content` 里放的是除公共参数外的全部业务参数
|
||
- RSA 签名结果要做 Base64 编码
|
||
- 业务 JSON 编码统一 UTF-8
|
||
|
||
### 6.2 企业是否已入驻票通
|
||
|
||
你需要先确认开票企业是否已经具备票通开票资格。
|
||
|
||
可用接口：
|
||
|
||
- `2.2 注册企业`
|
||
- `2.47 查询企业信息`
|
||
- `2.48 企业审核结果推送`
|
||
|
||
使用顺序建议：
|
||
|
||
1. 如果甲方企业尚未入驻，走 `2.2 注册企业`
|
||
2. 注册后用 `2.47 查询企业信息` 看审核状态
|
||
3. 如果票通侧支持，可接 `2.48 企业审核结果推送`
|
||
|
||
注意事项：
|
||
|
||
- 企业必须先完成入驻才能开票
|
||
- 如果企业不是通过接口注册，而是在票通侧已存在，需要和票通做“平台与企业绑定”
|
||
- `reviewStatus` 要关注：
|
||
- `0` 待审核
|
||
- `1` 审核通过
|
||
- `2` 审核不通过
|
||
- `3` 审核中
|
||
|
||
### 6.3 数电账号准备
|
||
|
||
如果甲方企业已经入驻，下一步是准备可以用于开票的数电账号。
|
||
|
||
可用接口：
|
||
|
||
- `2.3 数电账号登记`
|
||
- `2.45 查询数电账号列表`
|
||
- `2.8 查询数电账号认证状态`
|
||
- `2.46 退出电子税局登录`
|
||
|
||
使用顺序建议：
|
||
|
||
1. 先用 `2.45` 查询某税号下已经维护好的数电账号
|
||
2. 如果你需要平台内维护账号，再用 `2.3` 登记
|
||
3. 开票前用 `2.8` 检查认证状态
|
||
4. 如存在异常登录状态，再视情况用 `2.46` 退出后重登
|
||
|
||
注意事项：
|
||
|
||
- `2.3` 的密码和身份密码要用票通要求的 3DES 加密
|
||
- `2.45 / 2.8` 会返回：
|
||
- `operationProposed`
|
||
- `authStatus`
|
||
- `switchable`
|
||
- `wechatUserBindStatus`
|
||
- `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 查询实名认证二维码扫码状态`
|
||
|
||
短信认证路径：
|
||
|
||
1. 调 `2.8` 看建议
|
||
2. 如果允许短信认证，调 `2.4`
|
||
3. 再调 `2.5` 完成登录
|
||
|
||
扫码认证路径：
|
||
|
||
1. 调 `2.6` 获取二维码
|
||
2. 展示二维码给用户
|
||
3. 轮询 `2.7` 查询扫码状态
|
||
4. 认证完成后，再继续原开票流程
|
||
|
||
注意事项：
|
||
|
||
- `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` 查询结果后：
|
||
|
||
1. 更新本地开票任务状态
|
||
2. 保存发票号码、数电发票号码、开票时间、失败原因
|
||
3. 再调用你自己的业务系统回写接口
|
||
|
||
建议你自己的回写接口至少要包含：
|
||
|
||
- 业务单号
|
||
- 公司标识
|
||
- 发票请求流水号
|
||
- 开票状态
|
||
- 票通状态码
|
||
- 票通状态描述
|
||
- 发票号码 / 数电发票号码
|
||
- 开票日期
|
||
- 金额 / 税额
|
||
- 下载地址或文件标识
|
||
|
||
## 7. 这份文档给你的最终结论
|
||
|
||
你现在最需要抓住的不是“票通有多少接口”，而是下面这条最小闭环：
|
||
|
||
1. 确认企业已入驻且已与平台绑定
|
||
2. 确认企业下有可用数电账号
|
||
3. 开票前检查认证状态和企业基础信息
|
||
4. 调 `2.9` 发起农产品收购发票开具
|
||
5. 如遇 `3999`，走短信认证或扫码认证
|
||
6. 用 `2.13 / 2.14` 收推送，同时用 `2.11 / 2.12` 做补偿查询
|
||
7. 最后把结果回写到你自己的业务系统
|
||
|
||
如果只按开发优先级排序，你最先应该落的接口就是：
|
||
|
||
- `2.45 查询数电账号列表`
|
||
- `2.8 查询数电账号认证状态`
|
||
- `2.9 开具蓝字数电发票`
|
||
- `2.11 查询发票主要信息`
|
||
- `2.13 推送发票主要信息`
|
||
- `2.4 / 2.5 / 2.6 / 2.7` 认证链路
|
||
|
||
对你这个项目最容易踩坑的点有 4 个：
|
||
|
||
- 农产品收购发票字段语义和普通蓝票不同，购销方字段有反转
|
||
- `invoiceReqSerialNo` 必须稳定复用，不能重试就换
|
||
- 回调地址不是请求里传的，而是提前配置给票通的
|
||
- “开票结果回写接口”不是票通接口，而是你自己的业务系统接口
|