From 314c228654d4a5dd3ae9c1c20fbc1162bf504c9e Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 26 Aug 2026 15:08:00 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=BC=80=E7=A5=A8=E7=94=B3=E8=AF=B7?= =?UTF-8?q?=E6=8C=89=E7=A8=8E=E5=8F=B7=E8=87=AA=E5=8A=A8=E5=9B=9E=E5=A1=AB?= =?UTF-8?q?=E4=BC=81=E4=B8=9A=E5=B7=A5=E5=95=86=E4=BF=A1=E6=81=AF=EF=BC=88?= =?UTF-8?q?#6406=20/=20PR=20#6415=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 GET /v3/admin/invoice/company-info?taxNo=，按税号返回元典工商照面 + 本系统历史开票抬头两段数据，后端不合并由前端取舍；已合并 dev-v3 并部署测试服， 网关 API 实测 companyInfo / lastInvoiceTitle 往返一致，非法税号返回 581526。 --- ...税号自动回填企业工商信息-新增接口-管理后台.md | 188 ++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 changelogs-v2/2026-08/26_6406_开票申请按税号自动回填企业工商信息-新增接口-管理后台.md diff --git a/changelogs-v2/2026-08/26_6406_开票申请按税号自动回填企业工商信息-新增接口-管理后台.md b/changelogs-v2/2026-08/26_6406_开票申请按税号自动回填企业工商信息-新增接口-管理后台.md new file mode 100644 index 00000000..45f42c32 --- /dev/null +++ b/changelogs-v2/2026-08/26_6406_开票申请按税号自动回填企业工商信息-新增接口-管理后台.md @@ -0,0 +1,188 @@ +--- +schema: "hl-changelog/v2" +ticket: "6406" +title: "开票申请按税号自动回填企业工商信息" +consumer: "admin" +author: "wx(GIT)" +change_type: "新增接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +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`**： + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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 +``` + +#### 成功响应示例 + +```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