适用场景为什么需要身份证二要素核验在互联网应用中实名认证是合规与风控的基础环节。身份证二要素核验姓名身份证号广泛用于以下场景用户准备实名金融、社交、电商平台在开户或准备时核验用户身份真实性。交易风控大额转账、敏感操作前校验操作人身份。账号找回与绑定修改手机号、邮箱时通过身份核验防止盗用。合规要求符合《网络安全法》《个人信息保护法》对实名制的要求。二要素核验仅比对“姓名”和“身份证号”是否匹配不返回户籍信息因此既能满足业务需求又能最小化数据暴露风险。接口能力边界该接口为POST请求地址固定https://v1.apizero.cn/api/idcard-2c。输入真实姓名中文 18位身份证号末位可为X。输出valid布尔值表示一致与否result_code细分状态同时脱敏回显身份证号。限制QPS 5次/秒超出会限频需要提前获取API Key并配置在请求头中。声明仅返回是否一致不返回任何户籍、照片等额外信息调用前必须取得被核验人授权。鉴权与请求参数请求头参数名是否必须类型说明Authorization是stringBearer 你的API KeyContent-Type否string默认为application/json请求体JSON字段类型必填描述示例值namestring是真实姓名中文张三idcardstring是18位身份证号末位可为X大写11010519491231002X注意身份证号支持大小写X但建议在客户端统一转换为大写以免误判。curl 接入示例以下 curl 命令展示了如何调用该接口。请将YOUR_API_KEY替换为实际的秘钥。curl -sS -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {name:张三,idcard:11010519491231002X} \ https://v1.apizero.cn/api/idcard-2c响应示例成功且一致{ code: 0, msg: 成功, request_id: abc123, data: { idcard: 110***********002X, name: 张三, result_code: 100, valid: true, message: 一致 } }多语言代码举例Python (requests)import requests url https://v1.apizero.cn/api/idcard-2c headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json } payload { name: 张三, idcard: 11010519491231002X } response requests.post(url, jsonpayload, headersheaders) data response.json() print(data)JavaScript (axios)const axios require(axios); const url https://v1.apizero.cn/api/idcard-2c; const headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json }; const payload { name: 张三, idcard: 11010519491231002X }; axios.post(url, payload, { headers }) .then(res console.log(res.data)) .catch(err console.error(err));返回值详细解读{ code: 0, msg: 成功, request_id: abc123, data: { idcard: 110***********002X, // 脱敏身份证号 name: 张三, // 请求传入的姓名 result_code: 100, // 状态码 valid: true, // 是否一致 message: 一致 // 文字说明 } }result_code 枚举说明result_code含义100一致101不一致姓名与身份证号不匹配200身份证号格式错误201姓名格式错误含非中文字符202参数缺失300鉴权失败API Key无效或过期301QPS超限302内部错误当code不为0时msg会给出具体错误描述data可能为空。常见错误排查401 Unauthorized检查 Authorization 头是否包含Bearer前缀且 API Key 未过期。400 Bad Request可能是请求体 JSON 格式错误或字段缺失。请确保name和idcard均为字符串且idcard为18位。429 Too Many Requests超过 QPS 限制5次/秒。建议使用队列、重试或降低调用频率。错误码 200/201参数校验失败。检查身份证号长度、号码规则最后一位校验位及X姓名不应包含数字或特殊符号。错误码 101姓名与身份证号不一致代表核验结果失败。工程化注意事项1. 安全与合规在使用前必须取得被核验人明确授权并遵守《个人信息保护法》等法规。不要在日志、前端或第三方中回传完整的身份证号可使用响应的脱敏数据。API Key 应存储在服务端环境变量中切勿硬编码或暴露给客户端。2. 性能与限流每个 API Key 的 QPS 上限为5建议在服务端增加本地限流如令牌桶或失败重试机制退避策略。对于高并发场景如批量开户可申请提高 QPS或使用多个 Key 轮询。3. 结果缓存如果同一用户在同一会话中多次核验如重试可短期缓存结果例如5分钟避免重复调用 API。缓存 key 建议使用nameidcard的哈希值。注意缓存需设置合理 TTL且不能用于风控类的绝对时效校验。4. 异步与重试网络波动时建议采用指数退避重试如 1s、2s、4s 再尝试最多3次。对于code302内部错误可以重试但对于code101不一致则不应重试。5. 字段校验前置在调用 API 前先做本地校验身份证号长度、格式前6位地区码合理性、校验位算法姓名不能为空且全为中文。提前拦截明显无效的请求减少 API 调用浪费。参考文档接口文档https://apizero.cn/aidocs/idcard-2c原始 markdown 文档可离线查看https://apizero.cn/aidocs/idcard-2c/raw.md注本文仅作技术教程不涉及任何商业、用量说明或配额说明信息。
身份证二要素核验实战：从接入到工程化落地
适用场景为什么需要身份证二要素核验在互联网应用中实名认证是合规与风控的基础环节。身份证二要素核验姓名身份证号广泛用于以下场景用户准备实名金融、社交、电商平台在开户或准备时核验用户身份真实性。交易风控大额转账、敏感操作前校验操作人身份。账号找回与绑定修改手机号、邮箱时通过身份核验防止盗用。合规要求符合《网络安全法》《个人信息保护法》对实名制的要求。二要素核验仅比对“姓名”和“身份证号”是否匹配不返回户籍信息因此既能满足业务需求又能最小化数据暴露风险。接口能力边界该接口为POST请求地址固定https://v1.apizero.cn/api/idcard-2c。输入真实姓名中文 18位身份证号末位可为X。输出valid布尔值表示一致与否result_code细分状态同时脱敏回显身份证号。限制QPS 5次/秒超出会限频需要提前获取API Key并配置在请求头中。声明仅返回是否一致不返回任何户籍、照片等额外信息调用前必须取得被核验人授权。鉴权与请求参数请求头参数名是否必须类型说明Authorization是stringBearer 你的API KeyContent-Type否string默认为application/json请求体JSON字段类型必填描述示例值namestring是真实姓名中文张三idcardstring是18位身份证号末位可为X大写11010519491231002X注意身份证号支持大小写X但建议在客户端统一转换为大写以免误判。curl 接入示例以下 curl 命令展示了如何调用该接口。请将YOUR_API_KEY替换为实际的秘钥。curl -sS -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {name:张三,idcard:11010519491231002X} \ https://v1.apizero.cn/api/idcard-2c响应示例成功且一致{ code: 0, msg: 成功, request_id: abc123, data: { idcard: 110***********002X, name: 张三, result_code: 100, valid: true, message: 一致 } }多语言代码举例Python (requests)import requests url https://v1.apizero.cn/api/idcard-2c headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json } payload { name: 张三, idcard: 11010519491231002X } response requests.post(url, jsonpayload, headersheaders) data response.json() print(data)JavaScript (axios)const axios require(axios); const url https://v1.apizero.cn/api/idcard-2c; const headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json }; const payload { name: 张三, idcard: 11010519491231002X }; axios.post(url, payload, { headers }) .then(res console.log(res.data)) .catch(err console.error(err));返回值详细解读{ code: 0, msg: 成功, request_id: abc123, data: { idcard: 110***********002X, // 脱敏身份证号 name: 张三, // 请求传入的姓名 result_code: 100, // 状态码 valid: true, // 是否一致 message: 一致 // 文字说明 } }result_code 枚举说明result_code含义100一致101不一致姓名与身份证号不匹配200身份证号格式错误201姓名格式错误含非中文字符202参数缺失300鉴权失败API Key无效或过期301QPS超限302内部错误当code不为0时msg会给出具体错误描述data可能为空。常见错误排查401 Unauthorized检查 Authorization 头是否包含Bearer前缀且 API Key 未过期。400 Bad Request可能是请求体 JSON 格式错误或字段缺失。请确保name和idcard均为字符串且idcard为18位。429 Too Many Requests超过 QPS 限制5次/秒。建议使用队列、重试或降低调用频率。错误码 200/201参数校验失败。检查身份证号长度、号码规则最后一位校验位及X姓名不应包含数字或特殊符号。错误码 101姓名与身份证号不一致代表核验结果失败。工程化注意事项1. 安全与合规在使用前必须取得被核验人明确授权并遵守《个人信息保护法》等法规。不要在日志、前端或第三方中回传完整的身份证号可使用响应的脱敏数据。API Key 应存储在服务端环境变量中切勿硬编码或暴露给客户端。2. 性能与限流每个 API Key 的 QPS 上限为5建议在服务端增加本地限流如令牌桶或失败重试机制退避策略。对于高并发场景如批量开户可申请提高 QPS或使用多个 Key 轮询。3. 结果缓存如果同一用户在同一会话中多次核验如重试可短期缓存结果例如5分钟避免重复调用 API。缓存 key 建议使用nameidcard的哈希值。注意缓存需设置合理 TTL且不能用于风控类的绝对时效校验。4. 异步与重试网络波动时建议采用指数退避重试如 1s、2s、4s 再尝试最多3次。对于code302内部错误可以重试但对于code101不一致则不应重试。5. 字段校验前置在调用 API 前先做本地校验身份证号长度、格式前6位地区码合理性、校验位算法姓名不能为空且全为中文。提前拦截明显无效的请求减少 API 调用浪费。参考文档接口文档https://apizero.cn/aidocs/idcard-2c原始 markdown 文档可离线查看https://apizero.cn/aidocs/idcard-2c/raw.md注本文仅作技术教程不涉及任何商业、用量说明或配额说明信息。
