身份证二要素核验接口接入教程：参数、请求示例与返回字段解读
实名核验是注册、下单、账户绑定等业务里经常遇到的一环。身份证二要素核验用于判断「真实姓名 + 18 位身份证号」是否与公安权威库一致。本文按“准备 -> 最小请求 -> 返回值 -> 错误处理 -> 工程化”的顺序，把这个接口从第一次调用讲清楚。
一、适用场景与能力边界
典型使用场景：
- 注册实名：用户填写姓名与身份证号后做一致性校验。
- 下单风控：高风险交易前补充身份一致性判断。
- 账户绑定：绑定实名信息时校验填写是否匹配。
需要明确的能力边界：
| 项目 | 说明 |
|---|---|
| 核验对象 | 真实姓名 + 18 位身份证号 |
| 返回内容 | 仅返回是否一致，不返回任何额外户籍信息 |
| 身份证号回显 | 响应中脱敏回显 |
| 返回速度 | 素材描述为秒级返回，具体时延以文档与实际调用为准 |
| 授权要求 | 需在取得被核验人授权后调用 |
也就是说，这个接口只回答“一致 / 不一致”，不能用来查询地址、出生日期、照片等衍生信息，业务设计时不要把核验接口当成信息查询接口使用。
二、调用前需要准备什么
- 接口地址与方法：
POST https://v1.apizero.cn/api/idcard-2c。 - 鉴权方式：素材未给出具体鉴权字段与 Header 名称，以文档为准。接入前请先在文档中确认 API Key 的传递位置（Header 或参数）。
- 请求参数：
name（真实姓名）、idcard（18 位身份证号）。 - 请求编码：建议使用
application/x-www-form-urlencoded或 JSON，具体以文档为准。 - 合规前提：确认已获得被核验人的授权，并准备好授权留存的说明。
三、最小请求示例
下面是一个可复制的 curl 模板。其中鉴权字段与请求体格式请按文档替换，示例中的YOUR_API_KEY、姓名和身份证号均为占位内容。
curl -X POST 'https://v1.apizero.cn/api/idcard-2c' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: YOUR_API_KEY' \ --data-urlencode 'name=张三' \ --data-urlencode 'idcard=110101199001011234'如果文档要求以 JSON 提交，可改为：
curl -X POST 'https://v1.apizero.cn/api/idcard-2c' \ -H 'Content-Type: application/json' \ -H 'Authorization: YOUR_API_KEY' \ -d '{"name":"张三","idcard":"110101199001011234"}'两点提醒：
- 身份证号必须是 18 位，调用前先做格式校验，避免把明显不合法的数据发到服务端。
- 姓名与身份证号需与用户提交内容保持一致，不要自行去空格以外的任何“修正”。
四、返回字段解读
素材仅说明“返回是否一致”以及“身份证号脱敏回显”，未给出完整响应体字段名。因此字段名、状态码枚举、错误码含义以文档为准。接入时建议按以下方式处理：
- 先看 HTTP 状态码，区分网络层失败与业务层失败。
- 再解析响应体中的“是否一致”字段，映射为业务枚举，例如
MATCH/MISMATCH。 - 读取脱敏后的身份证号用于日志与页面回显，不要期望拿到完整号码。
- 对响应体做容错解析：字段缺失时按“核验失败”处理，不要默认放行。
一个防御式解析的伪代码示例（字段名请替换为文档中的实际名称）：
import requests def verify(name: str, idcard: str, api_key: str) -> str: resp = requests.post( "https://v1.apizero.cn/api/idcard-2c", headers={"Authorization": api_key}, data={"name": name, "idcard": idcard}, timeout=5, ) if resp.status_code != 200: return "ERROR" data = resp.json() matched = data.get("matched") # 字段名以文档为准 if matched is True: return "MATCH" if matched is False: return "MISMATCH" return "ERROR"五、常见错误与排查思路
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 401 / 403 | 鉴权信息缺失或错误 | 核对 API Key 与传递位置，以文档为准 |
| 参数错误 | name或idcard缺失、身份证号非 18 位 | 调用前做必填与格式校验 |
| 返回不一致 | 姓名与号码不匹配 | 提示用户核对，不要自动重试 |
| 超时 | 网络或服务端处理耗时 | 设置合理超时，配合重试策略 |
| 响应体解析失败 | 字段名与预期不符 | 以文档字段名为准，做容错解析 |
特别注意：“不一致”不是错误，而是正常的业务结果。不要把不一致当成异常抛给用户，也不要因此触发自动重试。
六、工程化注意事项
- 日志脱敏：请求与响应中的身份证号必须脱敏落盘，避免明文进入日志系统。
- 超时与重试：只对网络超时和 5xx 做有限次重试，业务结果类响应不重试。
- 幂等设计：核验是只读判断，可按“姓名+身份证号”做短时缓存，但缓存时长需结合业务合规要求确定。
- 授权留存：保留用户授权记录，明确核验目的与范围。
- 失败兜底：核验失败时给出人工复核或补充材料通道，而不是直接拒绝。
- 监控告警：对错误率、超时率单独打点，便于定位问题。
参考文档
- 接口文档