API Changelog Bot 941e3453d5 feat(traveler-ocr): 小程序出行人接入阿里云 OCR 多证件识别（PR #1039）

- 新增 POST /mp/traveler/ocr：支持身份证/护照/港澳通/台湾通行证
- 下线 POST /mp/user/ocr/idcard（微信 OCR 不让用了）
- 前端需替换老接口调用 + 增加证件类型选择

2026-04-20 22:42:57 +08:00

4.1 KiB

原始文件 永久链接 Blame 文件历史

小程序出行人接入阿里云 OCR 多证件识别，下线微信 OCR

日期：2026-04-20 PR：#1039 Issue：#1036 影响：小程序端「出行人录入」模块

业务变化

微信官方 OCR 接口不再允许使用。出行人证件 OCR 后端切换到阿里云「个人证照识别」SDK，并扩展支持4 种证件：

证件	idCardType	后端走的 SDK
身份证	`ID_CARD`	RecognizeIdcard
护照	`PASSPORT`	RecognizePassport
港澳通行证	`HK_MACAU_PASS`	RecognizeExitEntryPermitToHK
台湾通行证	`TAIWAN_PASS`	RecognizeExitEntryPermitToHK（同接口，签发格式一致）

军官证 / 其他证件类型直接返回 400「不支持的证件类型」，前端做好容错。

❌ 下线接口

`POST /mp/user/ocr/idcard`（微信 OCR 老接口）

下线原因：微信 OCR 接口权限被关闭。

前端必须在本次同步内去掉该接口调用。

✅ 新增接口

`POST /mp/traveler/ocr` —— 多证件 OCR 识别

用途：小程序出行人录入页，用户上传证件照到 OSS 后，用 OSS URL 调此接口识别，返回结构化字段供用户确认后再手动调 POST /user/traveler 保存（OCR 不直接落库）。

请求 Content-Type: application/json：

{
  "idCardType": "ID_CARD",
  "ossUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/xxx/id-front.jpg"
}

字段	类型	必填	说明
idCardType	string	是	证件类型。仅支持 `ID_CARD` / `PASSPORT` / `HK_MACAU_PASS` / `TAIWAN_PASS`，其余直接返回 400
ossUrl	string	是	证件图 OSS 公开地址（走现有 `POST /mp/file/upload` 拿）

响应（TravelerOcrRespVO，所有字段均为字符串/日期，按证件类型可能为 null）：

{
  "code": 200,
  "message": "success",
  "data": {
    "name": "张三",
    "gender": "男",
    "nationality": "汉",
    "nationalityText": "中国 / CHN",
    "birthday": "1990-01-01",
    "idCardNo": "110101199001011234",
    "address": "北京市朝阳区...",
    "validityStart": "2020-01-01",
    "validityEnd": "2040-01-01",
    "issueAuthority": "北京市公安局朝阳分局",
    "issuePlace": null
  }
}

字段适用表：

字段	身份证	护照	港澳通	台湾通
name	✔️	✔️	✔️	✔️
gender	✔️	✔️	✔️	✔️
nationality	民族（汉）	国籍英文（CHN）	—	—
nationalityText	—	国籍中文（中国）	—	—
birthday	✔️	✔️	✔️	✔️
idCardNo	身份证号	护照号	通行证号	通行证号
address	✔️（身份证住址）	—	—	—
validityStart / validityEnd	✔️	✔️	✔️	✔️
issueAuthority	—	✔️	✔️	✔️
issuePlace	—	✔️	—	—

错误码

HTTP	code	message	原因
200	200	success	识别成功
200	400	不支持的证件类型	idCardType 不在上面 4 种之内
200	400	参数校验失败	ossUrl 不是 http/https 或 idCardType 空
200	500	身份证识别失败，请重试	阿里云 SDK 异常（图片质量/网络/额度等），失败已记审计

建议前端：调用前做图片压缩（建议 ≤ 3MB）；失败后提示用户"重新拍照"，不要自动重试（会多扣配额）。

前端改造 checklist

出行人录入页 OCR 入口替换为 POST /mp/traveler/ocr
增加证件类型选择（4 个），默认 ID_CARD
老接口 /mp/user/ocr/idcard 调用代码全部删除
OCR 返回字段渲染到表单输入框里，让用户确认/编辑后再提交，不要直接调保存
根据 idCardType 决定展示哪些字段（护照多个 nationalityText，身份证多个 address）

其它

免费额度：每类证件 200 次/月，超出按量付费（阿里云账单）
QPS：默认 10
审计日志（traveler_ocr_log）仅后端使用，前端不感知

4.1 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape