证件识别

指定证件类型并上传图像，返回结构化识别字段。

一、接口概览

服务 方法 路径 说明
证件字段识别 POST https://verifai.mocasa.com/idcr/api/v1/recognition 指定证件类型并上传图像，返回结构化识别结果

支持证件类型（card_type，大小写敏感）：

UMID、PRC、SSS、TINID、NATIONALID、DriverLicense、Passport、HealthID、VotersCard、PAGIBIGID

二、请求说明

2.1 Header

Header 必填 说明
X-API-Key 是 分配的业务密钥
Content-Type 是 application/json 或 multipart/form-data

建议始终使用 HTTPS。

2.2 图像要求

  • 大小：单张图像解码后约 10KB～10MB
  • 格式：jpg / jpeg / png / webp
  • 图像入参三选一：image_url、image_file、image_base64（不可混用）

2.3 请求示例

JSON 方式：

curl -sS -X POST "https://verifai.mocasa.com/idcr/api/v1/recognition" \
  -H "X-API-Key: sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"card_type":"Passport","image_url":"https://example.com/passport.jpg"}'

curl -sS -X POST "https://verifai.mocasa.com/idcr/api/v1/recognition" \
  -H "X-API-Key: sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d "{\"card_type\":\"Passport\",\"image_base64\":\"<BASE64_OR_DATA_URL>\"}"

multipart 方式：

curl -sS -X POST "https://verifai.mocasa.com/idcr/api/v1/recognition" \
  -H "X-API-Key: sk-your-api-key-here" \
  -F "card_type=Passport" \
  -F "image_file=@/path/to/passport.jpg"

curl -sS -X POST "https://verifai.mocasa.com/idcr/api/v1/recognition" \
  -H "X-API-Key: sk-your-api-key-here" \
  -F "card_type=Passport" \
  -F "image_url=https://example.com/passport.jpg"

curl -sS -X POST "https://verifai.mocasa.com/idcr/api/v1/recognition" \
  -H "X-API-Key: sk-your-api-key-here" \
  -F "card_type=Passport" \
  -F "image_base64=<BASE64_OR_DATA_URL>"

三、响应说明

统一响应结构：

字段 说明
request_id 本次请求唯一 ID
status success / error
result 识别结果对象（成功时）
error_message 错误信息（失败时）
pricing_strategy 计费策略标记

成功响应示例：

{
  "request_id": "01JQXYZ1234567890ABCDEF",
  "status": "success",
  "result": {
    "id_number": "",
    "full_name": "",
    "first_name": "",
    "middle_name": "",
    "last_name": "",
    "gender": "",
    "nationality": "",
    "date_of_birth": "",
    "place_of_birth": "",
    "date_of_issue": "",
    "date_of_expiry": "",
    "issuing_authority": "",
    "inferred_card_type_by_id": "",
    "null_ratio": 0.12
  },
  "error_message": null,
  "pricing_strategy": "PAY"
}

失败响应示例：

{
  "request_id": "01JQXYZ1234567890ABCDEF",
  "status": "error",
  "result": null,
  "error_message": "Bad request",
  "pricing_strategy": "FREE"
}

3.2 各证件类型说明及 result 字段键名一览

card_type 证件名称 result
Passport 护照 id_number, full_name, first_name, middle_name, last_name, gender, nationality, date_of_birth, place_of_birth, date_of_issue, date_of_expiry, issuing_authority
UMID 菲律宾统一多用途 ID（UMID） id_number, full_name, first_name, middle_name, last_name, gender, date_of_birth, address, postcode
SSS 菲律宾社保卡（SSS） id_number, full_name, date_of_birth
TINID 菲律宾税卡（TIN） id_number, full_name, date_of_birth, date_of_issue, address
DriverLicense 驾驶证 id_number, full_name, first_name, middle_name, last_name, nationality, gender, date_of_birth, weight, height, eyes_color, blood_type, address, date_of_expiry, agency_code, restrictions, conditions
NATIONALID 菲律宾国民身份证（PhilSys ID） id_number, full_name, first_name, middle_name, last_name, date_of_birth, gender, blood_type, address, marital_status, date_of_issue, place_of_birth
VotersCard 选民证 id_number, full_name, date_of_birth, civil_status, nationality, address, precinct_no
PRC 菲律宾专业人员执照（PRC） id_number, full_name, first_name, middle_name, last_name, occupation, date_of_issue, date_of_expiry
PAGIBIGID 菲律宾住房公积金卡（Pag-IBIG） id_number, full_name
HealthID 菲律宾健康保险卡（PhilHealth） id_number, full_name, gender, date_of_birth, address

3.3 常见字段含义与返回数据归一化说明

键名 含义
inferred_card_type_by_id 根据证件号码等形式由服务侧给出的辅助证件类型推断，不替代请求 JSON 中的 card_type，仅供参考。
null_ratio 识别结果中，该 card_type 模板定义字段里值为 null（或等价空）的个数 ÷ 模板字段总数。

常见字段含义（证件业务键）

键名 含义
id_number 证件主号码
full_name 全名
first_name / middle_name / last_name 姓名拆分
gender 性别
nationality 国籍
date_of_birth / date_of_issue / date_of_expiry 出生日期、签发日期、有效期截止日
place_of_birth 出生地
address 地址
postcode 邮政编码
issuing_authority 签发机关
blood_type 血型
marital_status / civil_status 婚姻或民事身份状况
occupation 职业
weight / height 体重、身高
eyes_color 眼睛颜色
agency_code 机构编码
restrictions / conditions 限制条件、身体条件等
precinct_no 选区或投票站相关编号

返回数据归一化说明（贵司对接时可作预期管理）

服务方对识别结果进行规范化与一致性处理，包括但不限于：

  • 日期：在可解析范围内统一为 **YYYY-MM-DD；无法解析或与校验规则不一致的日期字段为 **null。
  • 日期逻辑：对签发日、有效期、出生日等进行合理性校验；无法同时满足可信逻辑时，相关字段可能为 **null**。
  • 文本与号码：对姓名、号码、地址等做可读性与格式校验；无法确认为有效内容时可能为 **null**。