前端对接开票
供应商上传发票校验
上传发票时对图片/PDF 做 OCR 抬头硬校验，抬头与申请单不一致直接拦截；含 PDF 要求、报错文案与抬头比对规则
Markdown 原文（给 AI 用）：https://doc.xfun.fun/supplier-invoice-upload-api.md
要点
- 上传接口
POST /invoice/task/upload，入参只有申请单id和发票地址invoiceUrl。 - 后端对发票图片 / PDF 做 OCR，识别票面 购买方名称，与申请单抬头不一致直接拦截，报错文案透出给供应商。数电票原生 PDF 也支持。
- 金额、税号、重复上传均 不拦截，只拦抬头。
- 「已开票」状态重新上传发票时，同样会过这套校验。
- 校验由 Nacos 开关
xm.invoice.ocr-check-enabled控制（默认关闭），关闭时不做 OCR，直接按原规则上传。
接口定义
POST/invoice/task/upload上传发票
调用方：供应商小程序。鉴权、Header 与其他发票接口一致。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | Long | 必填 | 开票申请单 ID |
invoiceUrl | String | 必填 | 发票图片（jpg/png）或 PDF 的 OSS 地址 |
注意
PDF 必须保留 .pdf 扩展名：后端按 URL 路径后缀（忽略 ? 后的参数）区分 PDF 与图片识别通道。如果上传组件会改文件名，确认生成的 URL 以 .pdf 结尾。
请求示例
{
"id": 123,
"invoiceUrl": "https://image-bulky.xunmengvip.com/supplier/invoice/dzfp_2611xxxx.pdf"
}响应
{ "code": 0, "msg": "success", "data": true }校验不通过时 code != 0，msg 为面向供应商的完整文案，直接 toast 展示即可，无需按 code 分支。
报错文案速查
| msg 文案 | 触发场景 | 前端处理建议 |
|---|---|---|
| 发票抬头“云南乙花卉有限公司”与申请单抬头“云南甲花卉有限公司”不一致，请核对后重新开具 | OCR 识别出的购买方名称与申请单抬头不一致（动态文案，含两边抬头） | toast / 弹窗展示，引导重新开票 |
| 发票识别失败，请确认图片清晰完整后重试 | 传的不是发票、图片模糊不完整，或未识别出购买方名称 | toast，引导重新拍摄 / 上传 |
| 发票识别失败，请稍后重试 | OCR 服务调用异常 | toast，可重试同一文件 |
| 当前状态不支持上传发票 | 申请单状态既非待开票 / 逾期，也非已开票重传 | toast 并刷新列表 |
| 申请单不存在 | id 错误或不属于当前供应商 | toast 并刷新列表 |
抬头比对规则
- 比对前做归一化：忽略所有空白字符，全角括号（）与半角括号 () 视为相同，其余必须完全一致。
- 例：申请单抬头「云南甲花卉（集团）有限公司」，票面「云南甲花卉(集团) 有限公司」→ 通过；票面「云南乙花卉有限公司」→ 拦截。
联调注意
- 联调前先和后端确认环境的
xm.invoice.ocr-check-enabled已打开，否则任何文件都能上传成功。 - 测试请用真实票面文件，随便找张图会命中「发票识别失败」。