企业官网建设流程全解析

适用场景与接口价值

健康证（从业人员健康检查合格证）在餐饮、食品、公共卫生等行业中属于必须核验的证件。传统的人工录入方式耗时费力，且容易出错。通过OCR（光学字符识别）接口，可以自动从证件图片中提取姓名、发证机关、办证日期、发证日期、体检日期、有效日期共6个关键字段，大幅提升信息采集效率。

典型的应用场景包括：

• HR入职材料自动录入：批量处理新员工健康证，自动填入人事系统。
• 餐饮门店证件管理：定期核验员工健康证有效期，避免证件过期。
• 监管平台数据对接：将纸质健康证数字化，用于合规检查。

接口能力边界

本接口为健康证识别（ocr-health-cert），提供结构化信息提取，不包含证书真伪验证（如防伪水印、印章鉴别）。接口QPS限制为2次/秒，适合中小规模调用。支持两种图片输入方式：

• URL方式：传入公网可访问的图片直链（jpg/png）。
• Base64方式：将图片文件转换为Base64编码字符串（可含data:image/xxx;base64,前缀）。

图片格式仅支持JPEG和PNG，建议图片分辨率不低于600x400像素，证件区域完整且无反光、遮挡。

鉴权与请求头

所有请求均需携带Authorization头，格式为Bearer <你的 API Key>。API Key需在开发者后台获取。

另外，Content-Type建议显式设为application/json，虽然接口默认接受JSON，但明确声明可避免部分HTTP客户端自动猜测错误。

请求参数详解

请求体为JSON对象，包含两个必填字段：

参数细节注意事项

• input_type 错误：如果传入非url/base64的值（如image），服务器会返回参数校验错误。
• URL不可访问：使用URL方式时，确保图片链接无需额外鉴权且指向图片资源本身（非网页）。若链接返回404或非图片内容，接口会报错。
• Base64过大：Base64编码会增大数据体积约1/3，建议图片大小控制在2MB以内，否则可能触发请求体超限。

curl 调用示例

以下示例使用URL方式识别健康证（请替换YOUR_API_KEY为真实Key）：

curl -sS -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"input_type": "url", "input_data": "https://example.com/health-cert.jpg"}' \ "https://v1.apizero.cn/api/ocr-health-cert"

若使用Base64方式，先获取图片的Base64字符串（例如通过base64 health.jpg命令），然后构造JSON：

# 假设图片Base64字符串保存在变量 $B64_STR 中 curl -sS -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"input_type\": \"base64\", \"input_data\": \"$B64_STR\"}" \ "https://v1.apizero.cn/api/ocr-health-cert"

注意：在命令行中嵌入Base64字符串时，若字符串包含特殊字符（如+、/），需使用双引号包裹并转义内部引号。建议将JSON写入文件然后用-d @file.json方式发送。

Python 代码接入示例

使用requests库调用，更便于集成到后端服务：

import requests import base64 API_URL = "https://v1.apizero.cn/api/ocr-health-cert" API_KEY = "your_api_key_here" # 方式一：URL上传 def recognize_by_url(image_url): headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } payload = { "input_type": "url", "input_data": image_url } resp = requests.post(API_URL, json=payload, headers=headers) return resp.json() # 方式二：Base64上传 def recognize_by_base64(image_path): with open(image_path, "rb") as f: b64_str = base64.b64encode(f.read()).decode("utf-8") # 不含 data:image 前缀 headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } payload = { "input_type": "base64", "input_data": b64_str } resp = requests.post(API_URL, json=payload, headers=headers) return resp.json() # 调用示例 result = recognize_by_url("https://example.com/health-cert.jpg") print(result)

说明：

• Base64方式建议不添加data:image/jpeg;base64,前缀，接口兼容两种形式，但去掉前缀可减少传输体积。
• 若图片较大（例如超过1MB），建议先压缩再转换为Base64，避免请求超时。

返回值解读

成功时HTTP状态码为200，响应体JSON结构如下：

{ "code": 0, "msg": "成功", "request_id": "req_abc123", "data": { "name": "张三", "issued_by": "XX市卫生健康委员会", "date_of_handling": "2024-01-15", "date_of_issue": "2024-01-20", "date_of_medical_examination": "2024-01-10", "valid_date": "2025-01-19" } }

字段含义

注意：部分字段可能因图片质量或证件版式差异而缺失。例如老版健康证可能没有“有效日期”，此时valid_date会返回空字符串或null。建议业务层做兼容处理。

日期一致性校验

正常逻辑下，日期应满足：体检日期 ≤ 办证日期 ≤ 发证日期 ≤ 有效日期。如果业务需要校验，可在拿到返回值后自行比对。

常见错误与状态码

特别说明：业务错误码（如1001、1002）均通过200状态码返回，需通过code字段判断。不要单纯依赖HTTP状态码。

工程化注意事项

1. 图片预处理

• 裁剪与矫正：如果原始图片包含过多背景，先裁剪至证件区域，或使用透视变换矫正倾斜。
• 色彩增强：健康证底色多为白色或浅色，可适当提高对比度使文字更清晰。
• 去噪：对于扫描件，先进行椒盐噪声滤波。

2. 批量调用与限流

QPS上限为2，如果需并发处理大量图片，建议使用信号量或队列控制并发数。例如Python中使用asyncio.Semaphore(2)或threading.Semaphore(2)。调用间隔至少500ms。

3. 重试机制

对于返回code非0或HTTP 429/5xx的情况，建议采用指数退避重试（如第一次等待1秒，第二次2秒，第三次4秒，最多重试3次）。注意区分可重试错误与不可重试错误（如参数错误不应重试）。

4. 数据缓存

同一张图片短时间内重复识别结果应一致，可将request_id或图片哈希值作为缓存键，避免重复调用（缓解QPS压力）。

5. 隐私合规

健康证包含个人姓名、体检信息，属于敏感数据。使用Base64方式时，确保图片数据不在传输过程中泄露（如使用HTTPS）。存储识别结果时需遵循相关数据保护法规（如《个人信息保护法》）。

参考文档

• 健康证识别API官方文档：https://apizero.cn/aidocs/ocr-health-cert
• 原始文档Markdown：https://apizero.cn/aidocs/ocr-health-cert/raw.md