适用场景从准备到风控的身份确认身份证二要素核验姓名 18 位身份证号是线上业务最基础的身份比对手段。接入该接口前需先明确其适用边界仅用于验证用户提供的姓名与身份证号是否与公安权威库中的记录一致。以下场景最为常见用户准备实名社交、金融、电商平台在准备或首次绑定时要求用户填写真实身份信息核验通过后才允许使用完整功能。交易风控大额转账、提现或敏感操作前二次核验操作者身份降低账户被盗用风险。账户绑定与变更修改手机号、邮箱或解绑银行卡时需确认操作人就是账户持有人。内容发布审核部分平台对发布敏感内容的用户进行身份认证防止匿名冒用。所有场景都有一个共同前提必须在获得被核验人授权后调用否则可能违反相关个人信息保护法规。接口能力边界明确能做什么与不能做什么许多开发者刚接触二要素核验时容易误解接口的返回能力。以下分点说明能做的校验传入的姓名和身份证号是否匹配公安权威库。秒级返回核验结果通常不超过 500ms。在响应中脱敏显示身份证号如110***********002X便于前端展示比对。提供统一的valid布尔字段和带有具体含义的result_code100 表示一致其他值表示不一致或异常。不能做的不返回户籍信息接口不会返回出生地、户籍地址、民族、性别等身份信息。这符合“最小必要”原则减少数据泄露风险。不返回照片不支持人像比对。不判断身份号码合法性接口假设你传入的号码格式正确18 位末位可为 X如果传入格式错误如位数不对接口会因格式校验失败而报错而非进行核验。不提供多维评分仅返回一致/不一致无分险等级或置信度评分。不承诺 100% 覆盖率尽管对接公安库但偏远地区或特殊历史数据可能存在极少数无法比对的情况此时接口会返回不一致或系统异常。了解这些边界后才能合理设计业务逻辑例如不应将核验通过用作唯一的“安全判断”而应结合其他风控因子如设备指纹、行为轨迹形成综合决策。接口鉴权与请求参数鉴权方式所有请求必须通过 HTTP Header 携带 API KeyAuthorization: Bearer 你的 API Key无需额外的签名或时间戳但生产环境中务必将 API Key 存储在服务端环境变量中避免前端暴露。当前接口 QPS 限制为5 次/秒超过后会返回限流错误。请求体格式接口仅接受POST JSON请求地址POST https://v1.apizero.cn/api/idcard-2c Content-Type: application/json请求体 JSON 结构字段类型必填说明namestring是真实姓名中文建议不超过 30 个汉字idcardstring是18 位身份证号码末位可为大写 X示例{ name: 张三, idcard: 11010519491231002X }注意idcard中字母 X 需大写name不能包含空格或特殊符号。可复制的 curl 示例以下示例使用环境变量APIZERO_API_KEY存储 Key请直接复制替换export APIZERO_API_KEYyour_actual_api_key_here curl -sS \ -X POST \ -H Authorization: Bearer $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {name: 张三, idcard: 11010519491231002X} \ https://v1.apizero.cn/api/idcard-2c若在 Windows 命令提示符中运行可使用以下格式注意变量替换与引号转义curl -sS -X POST -H Authorization: Bearer YOUR_KEY -H Content-Type: application/json -d {\name\:\张三\,\idcard\:\11010519491231002X\} https://v1.apizero.cn/api/idcard-2c返回值解读正常响应状态码为200JSON 结构如下{ code: 0, msg: 成功, request_id: abc123, data: { idcard: 110***********002X, name: 张三, result_code: 100, valid: true, message: 一致 } }字段说明字段类型说明codeinteger业务状态码0 表示请求成功非 0 表示异常msgstring对code的中文描述request_idstring单次请求的唯一流水号用于排查问题data.idcardstring脱敏后的身份证号前 3 后 4 位保留中间用星号替代data.namestring返回传入的姓名原文便于前端比对data.result_codeinteger核验结果代码。100一致101不一致102未查到该身份证号103参数格式错误其他为系统异常data.validbooleantrue 表示核验一致false 表示不一致或无法核验data.messagestring描述核验结果如“一致”、“不一致”、“未查到”等关键设计点valid字段是result_code的简化版前端可直接使用。但后端建议优先检查code是否为 0确保请求成功再判断valid是否 true。常见错误与处理HTTP 状态码code含义处理建议401-API Key 缺失或无效检查AuthorizationHeader 格式确认 Key 未过期400103请求参数格式错误如 idcard 非 18 位在前端校验身份证号长度与格式确保 X 为大写429-QPS 超限超过 5/s加入重试机制间隔至少 200ms 再发下一次请求500999服务端内部错误稍后重试若持续失败联系技术支持2000, data.validfalse核验不一致或未查到根据result_code给出不同提示例如“身份信息不匹配” vs “该身份证号未登记”注意name中包含生僻字或被核验人姓名发生变更如改名、户籍更正时核验仍可能返回不一致。建议在 UI 上提示用户确认信息是否与当前身份证一致。工程化注意事项1. 缓存策略同一idcardname在短时间内如 24 小时内核验通过后业务上可认为身份已可信不必重复调用接口。可设计一个内存缓存如 RedisTTL 设为 6–24 小时减少 QPS 消耗。但注意缓存有效期取决于业务风险容忍度支付类场景建议每次调用。2. 错误重试与幂等API 本身是幂等的两次相同请求会返回同样的结果不考虑网络抖动。对于 429 或 500 错误建议使用指数退避重试例如重试 3 次间隔 1s → 2s → 4s。注意不要重试 4XX 错误如 400 参数错误。3. 数据脱敏与日志接口返回的data.idcard已经是脱敏形式但在业务日志中仍需注意避免明文记录name 完整idcard即使入参中有。建议在日志中仅记录request_id和valid或者使用同样的脱敏规则前 3 后 4 位保留后再记录。4. 并发控制QPS 限制 5 次/秒单机多线程调用时需自行限流。可使用信号量如 Go 的semaphore或线程池控制并发数。如果业务并发超过 5/s可考虑对多个 API Key 做轮询需要获取多个 Key但更推荐异步排队或降低调用频率。5. 前端交互设计参考文档接口官方文档身份证二要素核验 API 文档原始 Markdown 文档原始文档本文仅作技术参考资料实际调用请以最新文档为准。