做过需要实名的业务，比如提现、注册、办理某种服务，绕不开的一步是校验用户填的姓名和身份证号是不是对得上。自己拿身份证号算校验位只能判断格式，判断不了真假，所以必须调第三方的实名认证接口。

接口校验的是什么

主流接口做的是「二要素」或「三要素」核验。二要素是姓名加身份证号，三要素再加上手机号。返回通常只有三种结果：一致、不一致、库中无此号。注意它返回的不是「这个人真实存在」，而是「和权威库里的记录能对上」。

POST /verify/idcard
{ "name": "张三", "idcard": "110101199001011234" }

合规先于技术

这一点必须先说。身份证信息属于个人敏感信息，调用实名接口要有明确业务场景和用户授权，不能用「接口便宜」为理由随便抓一批数据去撞库。

技术上的基本要求：传输必须走 HTTPS，身份证号在日志里要脱敏，别把明文写进日志文件或者数据库的普通字段里。存储时至少加密，并且和业务数据分开。

常见返回码的含义

  • 一致：姓名与号码匹配。
  • 不一致：两者不匹配，可能是打错字，也可能是伪造。
  • 无此号：号码不存在于库中，注意有些服务商把这种情况也归入不一致。
  • 库维护中 / 超时：不是业务问题，要按系统错误处理，不能直接判失败。

这最后一条最容易出事。用户明明是本人，因为服务商半夜维护被拒了，如果直接提示「认证失败」，投诉就来了。正确做法是把超时和无此号区分开，超时返回「请稍后重试」。

接入时的实际问题

一是限流。多数按每分钟调用次数计费，并发提交时要做队列，别让用户狂点按钮。二是有偿调用，每次核验都要花钱，所以前端要加图形验证码或频率限制，防止有人拿你的接口刷量。

三是幂等。同一个用户重复提交，第二次应该直接返回上次结果，不必再花钱查一遍。给核验记录加唯一索引，按用户加证件号做去重。

别忘了兜底

接口不可能 100% 可用，要准备人工审核通道。遇到超时、服务商故障这种非用户原因，让用户可以提交人工核验材料，避免业务卡死。同时记录每次调用的请求时间、返回码和耗时，方便和账单核对，也便于排查是服务商的问题还是自己的问题。