首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >身份证信息提取 API 接口文档(数据鱼API)

身份证信息提取 API 接口文档(数据鱼API)

原创
作者头像
用户12862874
发布于 2026-11-21 22:00:16
发布于 2026-11-21 22:00:16
70
举报

接口简介

「身份证信息提取」是数据鱼API平台提供的中国居民身份证号解析接口,Base 路径 /api/idcard,共 3 个端点。服务按 GB 11643-1999 校验 18 位结构,用 ISO 7064 MOD11-2 验校验码,解析行政区划、出生日期、年龄、性别、生肖与星座,并给出合规及风险标记;15 位号码会先补「19」转成 18 位。实现为纯离线计算,不落库原号,analyze 默认返回脱敏号码。

它解决的是「拿到一串号码后如何结构化」的问题,不核验姓名、照片或签发机关,也不连接公安人口库。analyze 返回完整解析,validate 只判断号码是否可能是真实号码,ping 用于探活。两个业务端点均为 POST,号码应放在请求体,不要拼进 URL,以免进入浏览器历史、代理日志与 Referer。

身份证号属于敏感个人信息,接口能力越直接,调用方的合规责任越重。本文只描述接口行为,不构成法律意见;实际接入应有明确业务目的、合法依据与最小化采集策略。

端点总览

方法

路径

说明

鉴权

GET

/api/idcard/ping

健康检查

需要

POST

/api/idcard/analyze

解析号码,返回地区、生日、年龄、性别、生肖、星座与风险

需要

POST

/api/idcard/validate

校验号码结构、校验位与生日

需要

通用约定

鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011,无效返回 4013,3 条路由包括 ping 都需要 Key。响应统一为 {code, msg, data},code 为 0 表示成功;缺少 id_card 返回 4001,analyze 的号码格式非法返回 4002,路由不存在为 4040,方法不允许为 4050。

analyze 与 validate 均为 POST,参数放在 JSON body 或表单中,参数名统一为 id_card。服务端调用应走 HTTPS,API Key 只保存在服务端;不要在前端直接调用,也不要把完整号码写进访问日志、埋点或错误上报。

核心端点详解

号码解析(POST /analyze)

用途:把 15 位或 18 位身份证号拆成可读字段,并附带风险与场景合规判断。

参数

类型

必填

说明

id_card

string

是

15 位或 18 位身份证号码

scene

string

否

finance、game、social,影响合规判定

raw

bool

否

是否返回原号,默认 false,只返回脱敏号

check_at

string

否

参考时间,ISO8601,用于年龄、未来生日与游戏禁玩时段

返回字段

类型

说明

idcard

string

默认脱敏号;raw=true 时为原号

masked

string

固定脱敏号,保留前 6 后 4

version

string

15 或 18

is_valid_format

bool

18 位长度、字符与末位 X 是否合法

checksum_ok

bool

MOD11-2 校验位是否一致

region

object

province、city、district、code 与 region_known

birthday

string

出生日期,YYYY-MM-DD

age / age_stage

int / string

周岁与年龄段

gender

string

male 或 female

zodiac / constellation

string

生肖与星座

compliance

object

is_adult、game_ban_window、needs_manual_review

risk

object

score(0-100)、level、hit_rules

格式非法时返回 HTTP 400、code 4002,但 data 仍给出同一结构,is_valid_format=false、risk=100/block;校验码不匹配不会让 analyze 报错,而是 code 0、checksum_ok=false、risk=100。调用方不能只看 code,还要检查 is_valid_format 与 checksum_ok,或直接以 risk.level 是否 block 作为拦截条件。

行政区划码内嵌 303 条,覆盖直辖市与主要城市的区县,未收录时 region_known=false,risk 至少 15。region 只来自号码前六位,不能当作现住址或户籍证明。18 位生日限定在 1900 年至当前年,未来生日记 100 分;15 位号码固定补 19,因此只能表示 1900 年代出生。

年龄按 check_at 或当前时间计算周岁,生日未到减一岁;age_stage 分为 minor_under_8、minor_8_16、minor_16_18、adult、senior。日期边界、闰日与 check_at 时区会影响结果。scene=finance 时,校验位错误或地区未知会置 needs_manual_review;scene=game 时按参考小时判断 22:00 至次日 08:00 的禁玩窗口,并给出 is_adult。risk 在 20、50、80 分处分 medium、high、block,黑名单测试号、格式错误、校验位错误与未来生日直接 100 分。

代码语言:javascript
复制
POST /api/idcard/analyze?api_key=YOUR_KEY
Content-Type: application/json

{"id_card":"110101199001011237","scene":"finance","check_at":"2026-01-01T00:00:00+08:00"}

其余端点要点

  • POST /validate:只收 id_card,返回 {valid, error}。它校验长度、字符、校验位与生日,不检查地区码是否收录,也不检查测试号黑名单。
  • validate 对非法号码仍返回 code 0,valid=false 时 error 取值包括 invalid_length、invalid_chars、checksum_mismatch、invalid_birthday;id_card 为空则返回 4001。它不返回解析字段,适合表单前置拦截。
  • GET /ping:需要 Key,返回 version=1.0、服务器时间与 msg=pong,只能用于探活。

数据与限制

  • 号码范围:仅支持 15 位与 18 位中国居民身份证号,不处理港澳台证件、护照、外国人永久居留身份证等其他证件。
  • 地区范围:内嵌 303 条行政区划码,不是全国全量区县表;未收录并不代表号码伪造,只是无法解析到区县。
  • 解析字段:不含姓名、民族、照片、签发机关、有效期与详细住址,不能据此完成实名认证。
  • 批量能力:无批量参数、无分页、无历史查询;文档没有速率限制与配额,生产接入需自建限流与重试。
  • 15 位号码:补「19」后按 18 位处理,出生年份只有两位,跨世纪出生者应优先使用 18 位。
  • 数据时效:行政区划调整后旧码可能对应历史名称,region 结果可能滞后,不能作为现住址或户籍证明。
  • 文档差异:API.md 的响应示例仍是 valid、area、中文性别等旧字段,与当前实现不一致,接入应以实际返回为准。
  • 该接口属于数据鱼API平台开发工具类接口,定位是号码结构解析、格式校验与风险提示。

典型使用场景

  • 已获得用户授权的表单中,输入身份证号后自动带出生日、性别与籍贯,减少重复填写。
  • 内部数据治理时对授权数据集做格式与校验位检查,标记明显错误的号码。
  • 游戏或金融场景用 scene 参数获取未成年标记、禁玩时段或人工复核提示,再由业务规则复核;数据鱼API 只提供判断依据,不替代实名核验与合规审查。
  • 数据分析场景对已脱敏、已获授权的号码做年龄段与性别分布统计,不保留原号。

注意事项

  • 身份证号是敏感个人信息。采集前应有明确目的与合法依据,遵循最小必要原则,向用户告知用途、保存期限与共享范围,并取得相应同意。
  • 除非确有必要,保持 raw=false 使用脱敏号;需要原号时应单独授权、加密存储并设置访问审计与短保留期。
  • 禁止在应用日志、埋点、错误上报、URL 与缓存中记录完整身份证号;确需留痕时应加密或掩码。
  • 校验通过不等于身份真实。is_valid_format 与 checksum_ok 只说明号码符合编码规则,不能证明证件真实、有效,也不能证明操作者就是持证人。
  • region、age、zodiac 均为派生信息,可能因行政区划调整、日期口径与算法差异而不准,不应作为户籍、年龄或身份的法定依据。
  • risk 是启发式评分,不是信用或司法结论;黑名单只覆盖少量公开测试号,不能据此认定号码伪造。
  • 未成年人信息、批量查询与跨境传输属于更高风险场景,应在上线前完成合规评估,不要仅凭接口可用就默认可以采集。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 号码解析(POST /analyze)
  • 其余端点要点
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档