fucai
/
fucai-server
5
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
fucai-server/OCR_API_DOCUMENT.md

455 lines
12 KiB
Markdown
Raw Permalink Normal View History

身份证识别
2025-11-26 21:26:16 +08:00
# OCR 识别接口 API 文档
## 接口概述
结婚证OCR识别接口，集成百度AI的结婚证识别能力，返回结婚证上所有主要信息的识别结果，包括识别准确度（probability）和位置信息（location）。
---
## 接口端点
### 1. 图片上传接口
**URL:** `/marriage/ocr/upload`
**方法:** `POST`
**请求参数:**
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| file | MultipartFile | 是 | 结婚证图片文件 |
**请求示例:**
```bash
curl -X POST \
-F "file=@marriage_certificate.jpg" \
http://localhost:8080/marriage/ocr/upload
```
**响应示例:**
```json
{
"code": 200,
"msg": "success",
"data": {
"uploadId": "a1b2c3d4e5f6g7h8"
}
}
```
**响应参数:**
| 参数名 | 类型 | 说明 |
|-------|------|------|
| uploadId | String | 上传文件标识，后续parse接口需要使用 |
---
### 2. 图片解析接口
**URL:** `/marriage/ocr/parse`
**方法:** `POST`
**Content-Type:** `application/json`
**请求参数:**
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| mobile | String | 是 | 手机号 |
| smsCode | String | 是 | 验证码 |
| uploadId | String | 是 | 上传文件标识（来自upload接口） |
**请求示例:**
```json
{
"mobile": "18888888888",
"smsCode": "123456",
"uploadId": "a1b2c3d4e5f6g7h8"
}
```
**响应示例:**
```json
{
"code": 200,
"msg": "success",
"data": {
"raw": "{\"words_result_num\": 14, \"words_result\": {...}}",
"words": ["王连杰", "320321199504011218", "1995年04月01日", ...],
"parsed": {
"husbandName": "王连杰",
"husbandId": "320321199504011218",
"husbandBirthDate": "1995-04-01",
"husbandNationality": "中国",
"husbandGender": "男",
"wifeName": "张丹",
"wifeId": "320321199406197047",
"wifeBirthDate": "1994-06-19",
"wifeNationality": "中国",
"wifeGender": "女",
"marriageNo": "320321201700004108",
"certificateHolder": "王连杰",
"registerDate": "2017-04-01"
},
"parsed_detailed": {
"husbandName": {
"word": "王连杰",
"probability": {
"average": 20.68798065,
"min": 0.9106679559
},
"location": {
"width": 109,
"height": 47,
"top": 933,
"left": 253
}
},
"wifeName": {
"word": "张丹",
"probability": {
"average": 19.14912224,
"min": 0.8554975986
},
"location": {
"width": 83,
"height": 43,
"top": 1204,
"left": 239
}
},
"husbandId": {
"word": "320321199504011218",
"probability": {
"average": 13.2870388,
"min": 0.5172381401
},
"location": {
"width": 341,
"height": 68,
"top": 1081,
"left": 343
}
},
"wifeId": {
"word": "320321199406197047",
"probability": {
"average": 15.98988342,
"min": 0.6194867492
},
"location": {
"width": 336,
"height": 56,
"top": 1351,
"left": 326
}
},
"husbandBirthDate": {
"word": "1995-04-01",
"probability": {
"average": 20.66628647,
"min": 0.7240950465
},
"location": {
"width": 250,
"height": 55,
"top": 1044,
"left": 857
}
},
"wifeBirthDate": {
"word": "1994-06-19",
"probability": {
"average": 25.62935066,
"min": 0.9226108789
},
"location": {
"width": 255,
"height": 56,
"top": 1322,
"left": 829
}
},
"husbandNationality": {
"word": "中国",
"probability": {
"average": 17.19703484,
"min": 0.7144192457
},
"location": {
"width": 79,
"height": 43,
"top": 1011,
"left": 249
}
},
"wifeNationality": {
"word": "中国",
"probability": {
"average": 23.41218376,
"min": 0.9498358369
},
"location": {
"width": 79,
"height": 46,
"top": 1264,
"left": 242
}
},
"husbandGender": {
"word": "男",
"probability": {
"average": 24.97878838,
"min": 0.9302400351
},
"location": {
"width": 39,
"height": 40,
"top": 973,
"left": 792
}
},
"wifeGender": {
"word": "女",
"probability": {
"average": 21.57674408,
"min": 0.8877936602
},
"location": {
"width": 42,
"height": 42,
"top": 1243,
"left": 765
}
},
"marriageNo": {
"word": "320321201700004108",
"probability": {
"average": 16.35309982,
"min": 0.6457977891
},
"location": {
"width": 363,
"height": 44,
"top": 650,
"left": 272
}
},
"certificateHolder": {
"word": "王连杰",
"probability": {
"average": 16.20750237,
"min": 0.6932016015
},
"location": {
"width": 119,
"height": 44,
"top": 362,
"left": 271
}
},
"registerDate": {
"word": "2017-04-01",
"probability": {
"average": 19.06731987,
"min": 0.7248777151
},
"location": {
"width": 354,
"height": 42,
"top": 511,
"left": 272
}
}
}
}
}
```
---
## 响应数据说明
### 顶级字段
| 字段名 | 类型 | 说明 |
|-------|------|------|
| code | Integer | 错误码，200表示成功 |
| msg | String | 错误消息或"success" |
| data | Object | 响应数据体 |
### data 字段说明
| 字段名 | 类型 | 说明 |
|-------|------|------|
| raw | String | 百度OCR API原始返回结果（JSON字符串） |
| words | Array | 识别出的所有文本内容（数组格式） |
| parsed | Object | 简化格式的解析结果（Map<String, String>），用于向后兼容 |
| parsed_detailed | Object | **新增** 详细格式的解析结果（Map<String, OcrFieldData>），包含probability和location |
### OcrFieldData 结构
```json
{
"word": "识别的文本内容",
"probability": {
"average": 识别准确度平均值,
"min": 识别准确度最小值
},
"location": {
"width": 文本框宽度,
"height": 文本框高度,
"top": 距离图片顶部的像素数,
"left": 距离图片左侧的像素数
}
}
```
### 支持的字段列表
| 字段键 | 说明 |
|-------|------|
| husbandName | 男方姓名 |
| husbandId | 男方身份证号 |
| husbandBirthDate | 男方出生日期 |
| husbandNationality | 男方国籍 |
| husbandGender | 男方性别 |
| wifeName | 女方姓名 |
| wifeId | 女方身份证号 |
| wifeBirthDate | 女方出生日期 |
| wifeNationality | 女方国籍 |
| wifeGender | 女方性别 |
| marriageNo | 结婚证字号 |
| certificateHolder | 持证人 |
| registerDate | 登记日期 |
| remark | 备注（可选） |
---
## 错误处理
### 常见错误响应
**验证码错误:**
```json
{
"code": 400,
"msg": "验证码错误，请重新输入！",
"data": null
}
```
**文件已过期:**
```json
{
"code": 400,
"msg": "上传文件不存在或已过期，请重新上传！",
"data": null
}
```
**配置未设置:**
```json
{
"code": 400,
"msg": "百度OCR配置未设置，请联系管理员！",
"data": null
}
```
**识别失败:**
```json
{
"code": 400,
"msg": "识别失败，请稍后再试！",
"data": null
}
```
---
## 使用场景
### 场景1: 获取识别结果的准确度信息
```javascript
// 前端代码示例
const response = await fetch('/marriage/ocr/parse', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
mobile: '18888888888',
smsCode: '123456',
uploadId: 'xxxxx'
})
});
const result = await response.json();
const wifeNameData = result.data.parsed_detailed.wifeName;
console.log('女方姓名:', wifeNameData.word);
console.log('平均准确度:', wifeNameData.probability.average + '%');
console.log('最小准确度:', wifeNameData.probability.min);
// 根据准确度判断是否需要人工审核
if (wifeNameData.probability.average < 50) {
alert('识别准确度较低，请人工审核');
}
```
### 场景2: 在图片上标注识别结果位置
```javascript
// 使用location信息在图片上绘制识别结果的位置框
const location = result.data.parsed_detailed.husbandId.location;
canvas.drawRect({
x: location.left,
y: location.top,
width: location.width,
height: location.height,
strokeStyle: 'red',
lineWidth: 2
});
```
### 场景3: 向后兼容 - 获取简化结果
```javascript
// 仍然可以使用 parsed 字段获取简化的文本结果
const simpleParsed = result.data.parsed;
console.log('男方姓名:', simpleParsed.husbandName);
console.log('女方姓名:', simpleParsed.wifeName);
console.log('结婚证号:', simpleParsed.marriageNo);
console.log('登记日期:', simpleParsed.registerDate);
```
---
## 重要说明
1. **概率值范围**: 0-100，越高表示识别准确度越高
2. **位置坐标**: 以图片左上角为原点 (0, 0)，单位为像素
3. **日期格式**: 自动转换为 "YYYY-MM-DD" 格式
4. **证号格式**: 仅保留数字部分
5. **文件有效期**: 上传后10分钟内有效
6. **向后兼容**: 原有的 `parsed` 字段保持不变，可继续使用
---
## 集成建议
1. **可信度检查**: 使用 `probability.average` 判断识别质量，建议设置 60% 以上为合格
2. **异常处理**: 对于低置信度的字段，建议提示用户进行人工审核或重新上传
3. **性能优化**: `parsed_detailed` 字段包含完整信息，客户端可按需使用
4. **安全性**: 敏感信息（如身份证号）应在服务端进行加密处理
5. **日志记录**: 建议记录识别结果和概率值，用于后续模型优化和问题追溯