---
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