wx/hl-api-changelog

派生 0

文件

T

yaosutu 16c68b6b25

changelog-filename-gate / validate (push) Failing after 2s

详情

docs(mp): C端发票切流v3状态枚举值域变化+email必填收紧 (#7252 )

2026-09-07 12:05:07 +08:00

5.6 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7252	C端发票切流 order-v3：状态枚举值域变化 + email 必填收紧	mp	yst(GIT)	修改接口	deployed	verified	pending				2026-09-07	C端发票 4 接口后端由 order-v2 切到 order-v3，路径/入参/出参字段名零变化；但状态枚举值域变化（PENDING→REQUESTED 等）+ email 必填收紧，前端需适配状态映射与表单校验。后端/网关已测试服验证，前端待消费。	2026-09-07	dev-v3

【修改接口·小程序端】C端发票切流 order-v3：状态枚举值域变化 + email 必填收紧（#7252）

1. 接口背景

order-v2 全量下线工程，C 端发票 invoice 由 order-v2 切流到 order-v3 发票域承接。4 个对外接口的路径、请求方法、入参字段名、出参字段名全部不变，前端无需改请求地址与字段名。

但后端切换带来 2 处对外可见的行为变化，前端需要适配：

发票状态 status 枚举值域变化（v2 → v3 值不同）
email 由可选变为必填（v3 服务端强制校验）

2. 变更清单

接口	路径	方法	变化
申请开票	`/mp/invoice/apply`	POST	出参 status 值域变化；email 必填收紧
发票详情	`/mp/invoice/{id}`	GET	出参 status 值域变化
按订单查发票	`/mp/invoice/order/{orderId}`	GET	出参 status 值域变化；未开票仍返 data=null
发票换开	`/mp/invoice/{invoiceId}/reissue`	POST	出参 status 值域变化；email 必填收紧

3. 接口详情

路径 / 方法 / Content-Type 均不变。仅出参 status 的取值集合与入参 email 的必填性变化。

4. 入参

入参字段名、类型、必填性基本不变，唯一变化：

email（申请开票 / 换开）：由可选变为必填。前端若不传 email，v3 服务端返回 400「收件邮箱不能为空」。建议前端表单将邮箱设为必填项。

5. 出参

出参字段名、类型不变。唯一变化是 status 字段的取值集合：

维度	v2 旧值（切流前）	v3 新值（切流后）
status 枚举	`PENDING` / `ISSUED` / `CANCELLED`	`REQUESTED` / `ISSUED` / `VOIDED` / `FAILED`

映射关系（供前端文案/样式适配参考）：

REQUESTED ≈ 旧 PENDING（已申请待开票）
ISSUED = 旧 ISSUED（已开票，不变）
VOIDED ≈ 旧 CANCELLED（已作废）
FAILED 为 v3 新增（开票失败）

其余出参字段（id / invoiceId / orderId / invoiceTitle / taxNumber / titleType / amount / invoiceUrl / pdfUrl / fileUrl / createdAt / issuedAt）字段名与类型均不变。

6. 枚举/数据字典

发票状态 status：

REQUESTED 待开票（已提交申请）
ISSUED 已开票
VOIDED 已作废（换开后原发票作废为此态）
FAILED 开票失败

抬头类型 titleType（不变）：PERSONAL 个人 / COMPANY 单位。

7. 错误码

600004 订单ID格式错误（apply 时 orderId 非数字兜底）
email 缺失：v3 服务端 Bean Validation 返 400「收件邮箱不能为空」
581500 发票不存在（含归属校验：非本订单属主查询时也返此码）

8. 示例

典型：申请开票（email 必填）

POST /mp/invoice/apply
{
  "orderId": "2091418470443810817",
  "invoiceTitle": "上海呼籁旅行科技有限公司",
  "titleType": "COMPANY",
  "taxNumber": "91310115MA1K48XXXX",
  "email": "finance@hulalv.com",
  "remark": "对公开票"
}

响应（status 为新值域）：

{
  "code": 200,
  "data": {
    "id": "2091422818997612545",
    "invoiceId": "2091422818997612545",
    "orderId": "2091418470443810817",
    "invoiceTitle": "上海呼籁旅行科技有限公司",
    "taxNumber": "91310115MA1K48XXXX",
    "titleType": "COMPANY",
    "status": "REQUESTED",
    "invoiceUrl": null,
    "pdfUrl": null,
    "fileUrl": null,
    "createdAt": "2026-09-07 12:00:00",
    "issuedAt": null
  }
}

边界：按订单查发票（未开票）

GET /mp/invoice/order/2091418470443810817
→ { "code": 200, "data": null }

异常：email 缺失

POST /mp/invoice/apply  （body 无 email）
→ { "code": 400, "message": "收件邮箱不能为空" }

9. 业务边界

invoiceUrl / pdfUrl 为历史遗留字段，恒为 null（v2 侧从未赋值），前端不应依赖，请使用 fileUrl。
申请开票时 invoiceType 固定按增值税普通发票（VAT_NORMAL）提交，C 端入参无发票类型选择字段。
换开成功后旧发票置 VOIDED，返回新发票完整信息。

10. 修改前后对比

项	修改前（v2）	修改后（v3）
后端服务	order-v2	order-v3
status 值域	PENDING/ISSUED/CANCELLED	REQUESTED/ISSUED/VOIDED/FAILED
email 必填	可选	必填（缺失返 400）

11. 影响评估 / 回滚

前端需适配：①状态文案/样式映射按新枚举 ②邮箱表单必填。
回滚：后端可切回 v2 client（需回滚 mp-service 代码并重新部署）。

12. 注意事项

路径与字段名零变化，前端不需要改请求地址，只需处理状态枚举值与 email 必填。
若前端对 status 有硬编码判断（如 status === 'PENDING'），必须改为新值 REQUESTED。

13. 关联 / 联系人

Issue：https://git.1814.love:8443/wx/HL/issues/7252
PR：https://git.1814.love:8443/wx/HL/pulls/7255
负责人：yst(GIT)

5.6 KiB 原始文件 Blame 文件历史 Unescape Escape