189 行
5.7 KiB
Markdown
189 行
5.7 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "6406"
|
||
title: "开票申请按税号自动回填企业工商信息"
|
||
consumer: "admin"
|
||
author: "wx(GIT)"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "080ea8df"
|
||
target_release: ""
|
||
verified_at: "2026-08-26"
|
||
status_note: "PR #6415 已合并 dev-v3 并部署测试服，经网关 API 实测 companyInfo 与 lastInvoiceTitle 两段往返一致，非法税号返回 581526"
|
||
updated_at: "2026-08-26"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 🔍 开票申请：按税号自动回填企业工商信息
|
||
|
||
开票申请填写页面现支持按税号自动回填企业工商信息。后端对接第三方企业信息查询服务（元典开放平台），并同时返回本系统同税号最近一条历史开票抬头，两段数据并列返回、由前端自行决定展示与回填优先级，后端不做合并取舍。
|
||
|
||
> **PR**: [#6415](https://git.1814.love:8443/wx/HL/pulls/6415) | **服务**: hl-order-service-v3 | **作者**: wx | **更新时间**: 2026-08-26
|
||
|
||
---
|
||
|
||
## 一、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 开票企业信息自动回填查询 | GET | `/v3/admin/invoice/company-info` | 新增 | 按税号查两段回填数据 |
|
||
|
||
---
|
||
|
||
## 二、接口详情
|
||
|
||
### 1. 开票企业信息自动回填查询 `GET /v3/admin/invoice/company-info`
|
||
|
||
**入参**: `taxNo`（Query 参数）
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| taxNo | Query | String | ✅ | 非空；去空格后长度 15 或 18 | 统一社会信用代码（或旧 15 位注册号） |
|
||
|
||
**出参 `Result<CompanyInfoRespVO>`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| companyInfo | Object 或 null | 元典第三方工商照面；查不到/第三方异常/全 key 耗尽时为 null |
|
||
| lastInvoiceTitle | Object 或 null | 本系统同税号最近一条非作废发票的历史抬头；无历史时为 null |
|
||
|
||
**companyInfo 字段**（元典工商照面）：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| titleName | String | 企业名称 |
|
||
| taxNo | String | 统一社会信用代码 |
|
||
| legalPersonName | String | 法定代表人 |
|
||
| registAddress | String | 注册地址 |
|
||
| regStatus | String | 经营状态（存续/注销/吊销等，由第三方返回） |
|
||
|
||
**lastInvoiceTitle 字段**（本系统历史抬头）：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| titleName | String | 开票抬头 |
|
||
| bankName | String | 开户行 |
|
||
| bankAccount | String | 银行账号 |
|
||
| registAddress | String | 注册地址 |
|
||
| registPhone | String | 注册电话 |
|
||
| email | String | 邮箱 |
|
||
|
||
#### 请求示例
|
||
|
||
```
|
||
GET /v3/admin/invoice/company-info?taxNo=91110000802100433B
|
||
Authorization: Bearer <admin-token>
|
||
```
|
||
|
||
#### 成功响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"companyInfo": {
|
||
"titleName": "北京百度网讯科技有限公司",
|
||
"taxNo": "91110000802100433B",
|
||
"registAddress": "北京市海淀区上地十街10号百度大厦2层",
|
||
"legalPersonName": "梁志祥",
|
||
"regStatus": "存续"
|
||
},
|
||
"lastInvoiceTitle": {
|
||
"titleName": "北京百度网讯科技有限公司",
|
||
"bankName": "招商银行北京分行",
|
||
"bankAccount": "110900100011110",
|
||
"registAddress": "北京市海淀区上地十街10号百度大厦2层",
|
||
"registPhone": "010-59928888",
|
||
"email": "invoice@baidu.com"
|
||
}
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 降级响应示例（任一段查不到为 null，互不阻塞）
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"companyInfo": null,
|
||
"lastInvoiceTitle": null
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 非法税号错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 581526,
|
||
"message": "税号格式不正确（统一社会信用代码须为 15 或 18 位）",
|
||
"data": null,
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、边界行为
|
||
|
||
- 未登录 → 401（网关拦截）
|
||
- 税号为空 / 去空格后非 15 或 18 位 → `581526` 参数错误
|
||
- 元典查无该企业 → `companyInfo = null`，`lastInvoiceTitle` 照常返回
|
||
- 元典接口超时 / 异常 / 全部 key 不可用 → 降级 `companyInfo = null`，不影响 `lastInvoiceTitle`
|
||
- 本系统无同税号历史发票 → `lastInvoiceTitle = null`
|
||
- 税号含空格 → 后端自动去空格后再查询，不报错
|
||
|
||
---
|
||
|
||
## 四、不影响范围（显式声明）
|
||
|
||
- **仅新增**：本查询接口为纯只读旁路查询
|
||
- **零影响**：
|
||
- 开票申请提交接口（`/v3/admin/order/{orderId}/invoice/apply`）行为不变
|
||
- 开票流程、开票记录写入逻辑
|
||
- 既有发票列表/详情查询
|
||
- 订单、订单核心、房务、车务模块
|
||
|
||
---
|
||
|
||
## 五、测试环境已验证
|
||
|
||
网关实测（`https://api.test.1814.love:9443`）：
|
||
|
||
```
|
||
GET /v3/admin/invoice/company-info?taxNo=91110000802100433B
|
||
→ 200 + companyInfo(北京百度网讯科技有限公司/梁志祥/存续) ✓
|
||
→ 200 + lastInvoiceTitle(招商银行北京分行/110900100011110/invoice@baidu.com) ✓
|
||
GET /v3/admin/invoice/company-info?taxNo=123
|
||
→ 581526 税号格式不正确 ✓
|
||
未带 Authorization 头
|
||
→ 401 缺少有效的 Authorization 头 ✓
|
||
```
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- 关联 Issue: [wx/HL#6406](https://git.1814.love:8443/wx/HL/issues/6406)
|
||
- 关联 PR: [wx/HL#6415](https://git.1814.love:8443/wx/HL/pulls/6415)
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#6406](https://git.1814.love:8443/wx/HL/issues/6406)
|
||
- **PR**: [#6415](https://git.1814.love:8443/wx/HL/pulls/6415)
|
||
- **Merge commit**: [f2c6e9fef53315a458b79f71747ee3494c420694](https://git.1814.love:8443/wx/HL/commit/f2c6e9fef53315a458b79f71747ee3494c420694)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|