身份证解析

解析单个身份证号

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/idcard/query JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
idcard	string	是	18 位身份证号
scene	string	否	场景：finance / game / social；传其它值 → 400（scene 非法）
raw	boolean	否	是否返回原始号码，默认 false 返回脱敏号
check_at	string	否	参考时间（ISO8601），用于年龄计算与 game 场景禁玩时段判断，默认当前时间；无法解析 → 400（check_at 非法）

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.idcard	string	身份证号
data.masked	string	脱敏后的号码
data.is_valid_format	boolean	格式是否有效
data.checksum_ok	boolean	校验位是否正确
data.region	object	地区
data.region.province	string	省份
data.region.city	string	城市
data.region.district	string	区县
data.region.code	string	6 位行政区划代码
data.region.region_known	boolean	地区是否识别成功
data.birthday	string	出生日期
data.age	integer	年龄
data.age_stage	string	年龄段
data.gender	string	性别
data.zodiac	string	生肖
data.constellation	string	星座
data.compliance	object	合规信息
data.compliance.is_adult	boolean	是否成年
data.compliance.game_ban_window	boolean	游戏禁玩时段：仅 scene=game 时返回布尔值（22:00-08:00 为 true），其他场景为 null
data.compliance.needs_manual_review	boolean	是否需要人工复核
data.risk	object	风险信息
data.risk.score	integer	评分
data.risk.level	string	等级
data.risk.hit_rules	array	命中规则
data.risk.hit_rules[]	string	命中规则

请求示例

返回示例

{"msg":"success","code":200,"data":{"age":36,"risk":{"level":"block","score":100,"hit_rules":["checksum_mismatch","seq_sequential"]},"gender":"male","idcard":"110101********1237","masked":"110101********1237","region":{"city":"北京市","code":"110101","district":"东城区","province":"北京市","region_known":true},"zodiac":"马","birthday":"1990-01-01","age_stage":"adult","compliance":{"is_adult":true,"game_ban_window":null,"needs_manual_review":false},"checksum_ok":false,"constellation":"摩羯座","is_valid_format":true}}

健康检查

服务存活探测

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

GET http://www.shujuyu.cn/v1/api/idcard/ping JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息，固定为 pong
data	object	业务数据
data.version	string	服务版本
data.time	string	数据时间

请求示例

返回示例

{"msg":"pong","code":200,"data":{"time":"2026-10-22 22:41:43","version":"1.0"}}

批量解析

批量解析身份证号

调用方式：在接口地址后拼接 ?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。

POST http://www.shujuyu.cn/v1/api/idcard/batch JSON

请求参数

参数名	类型	必填	说明
key	string	是	您的API密钥，可在个人中心获取
idcards	array	是	身份证号数组，最多 10 个，超出直接报错（4002）
scene	string	否	场景：finance / game / social；传其它值 → 400（scene 非法）
raw	boolean	否	是否返回原始号码，默认 false 返回脱敏号
check_at	string	否	参考时间（ISO8601），用于年龄计算与 game 场景禁玩时段判断，默认当前时间；无法解析 → 400（check_at 非法）

返回参数说明

参数名	类型	说明
code	integer	状态码，200 表示成功
msg	string	返回消息
data	object	业务数据
data.total	integer	总条数
data.returned	integer	本次实际返回条数
data.valid	integer	有效数量
data.invalid	integer	无效数量
data.max_score	integer	最高分
data.max_level	string	最高风险等级
data.level_counts	object	各等级数量
data.level_counts.low	integer	低风险数量
data.level_counts.medium	integer	中风险数量
data.level_counts.high	integer	高风险数量
data.level_counts.block	integer	拦截级数量
data.truncated	boolean	保留字段，当前恒为 false（超过 10 条时直接返回 4002 错误，不会截断）
data.max_limit	integer	允许返回的最大条数
data.list	array	数据列表
data.list[]	object	列表中的单条记录
data.list[].idcard	string	身份证号
data.list[].masked	string	脱敏后的号码
data.list[].is_valid_format	boolean	格式是否有效
data.list[].checksum_ok	boolean	校验位是否正确
data.list[].region	object	地区
data.list[].region.province	string	省份
data.list[].region.city	string	城市
data.list[].region.district	string	区县
data.list[].region.code	string	6 位行政区划代码
data.list[].region.region_known	boolean	地区是否识别成功
data.list[].birthday	string	出生日期
data.list[].age	integer	年龄
data.list[].age_stage	string	年龄段
data.list[].gender	string	性别
data.list[].zodiac	string	生肖
data.list[].constellation	string	星座
data.list[].compliance	object	合规信息
data.list[].compliance.is_adult	boolean	是否成年
data.list[].compliance.game_ban_window	boolean	游戏禁玩时段：仅 scene=game 时返回布尔值（22:00-08:00 为 true），其他场景为 null
data.list[].compliance.needs_manual_review	boolean	是否需要人工复核
data.list[].risk	object	风险信息
data.list[].risk.score	integer	评分
data.list[].risk.level	string	等级
data.list[].risk.hit_rules	array	命中规则
data.list[].risk.hit_rules[]	string	命中规则
data.list[].error	string	仅单条解析失败时返回该字段，此时 risk.hit_rules 含 engine_error

请求示例

返回示例

{"msg":"success","code":200,"data":{"list":[{"age":36,"risk":{"level":"block","score":100,"hit_rules":["checksum_mismatch","seq_sequential"]},"gender":"male","idcard":"110101********1234","masked":"110101********1234","region":{"city":"北京市","code":"110101","district":"东城区","province":"北京市","region_known":true},"zodiac":"马","birthday":"1990-01-01","age_stage":"adult","compliance":{"is_adult":true,"game_ban_window":null,"needs_manual_review":false},"checksum_ok":false,"constellation":"摩羯座","is_valid_format":true},{"age":36,"risk":{"level":"block","score":100,"hit_rules":["checksum_mismatch"]},"gender":"male","idcard":"110105********9056","masked":"110105********9056","region":{"city":"北京市","code":"110105","district":"朝阳区","province":"北京市","region_known":true},"zodiac":"马","birthday":"1990-03-07","age_stage":"adult","compliance":{"is_adult":true,"game_ban_window":null,"needs_manual_review":false},"checksum_ok":false,"constellation":"双鱼座","is_valid_format":true}],"total":2,"valid":2,"invalid":0,"returned":2,"max_level":"block","max_limit":10,"max_score":100,"truncated":false,"level_counts":{"low":0,"high":0,"block":2,"medium":0}}}

产品说明

产品概述

中国大陆身份证号解析，校验格式、提取归属地、出生日期、性别。

使用场景

数据查询：快速集成身份证号解析到您的应用中

业务系统：将身份证号解析数据嵌入业务流程

开发工具：通过 API 接口获取数据查询数据

数据分析：基于身份证号解析数据进行分析和决策

费用计算

按次计费单价

¥0.002 / 次

每次调用接口从账户余额中扣除相应费用，VIP 用户可享折扣

扣费优先级

免费额度

次数包

余额扣费

计费方式详解

1 免费额度

· 接口每日免费额度已关闭
· VIP 用户月度免费额度：
· 个人版：每月 5000 次，本接口月上限 5000 次
· 专业版：每月 30000 次，本接口月上限 30000 次
· 企业版：每月 200000 次，本接口月上限 200000 次
· 账户如有注册/活动赠送的免费次数，会优先于接口免费额度扣减
· VIP 月度免费额度仅适用于单次售价不高于 ¥0.0800/次的接口；接口每日免费额度按接口配置执行
VIP 月度免费额度每月重置，未使用部分不累计至下月。

2 次数包

预付费购买固定调用次数，最高可省 20%（相对按次付费），用完为止。
次数包为独立计费，不与 VIP 折扣叠加。
请在有效期内使用，过期后未使用的次数不可再用。

3 余额扣费

按次从账户余额扣除费用；所有用户可享量折扣，VIP 用户额外享 VIP 折扣。
扣费公式：实际扣费 = 接口单价 × (1 - VIP 折扣比例 - 量折扣比例)，并受总折扣上限和最低利润率保护约束
VIP 折扣：个人版9折专业版8折企业版7折
量折扣：月付费调用 ≥1000 次享 2%、月付费调用 ≥10000 次享 5%、月付费调用 ≥20000 次享 10%
· 量折扣按账号当月全部接口的付费调用次数统计，达到更高档位时按更高档位计算
总折扣上限：VIP 折扣 + 量折扣合计不超过 50%
最低利润率保护：折后价不得低于成本价 × (1 + 15%)；若接口售价本身低于该保护价，则取消折扣并按售价计费
余额不足时调用将失败，请及时充值。

次数包方案

方案名称	调用次数	价格	折算单价	比按次付费节省	有效期
100次调用包	100 次	¥0.2	¥0.0020/次	-	365 天
500次调用包	500 次	¥0.95	¥0.0019/次	省5%	365 天
1000次调用包	1000 次	¥1.8	¥0.0018/次	省10%	365 天
5000次调用包	5000 次	¥8.5	¥0.0017/次	省15%	365 天
10000次调用包	10000 次	¥16	¥0.0016/次	省20%	365 天

VIP 权益对比

等级	每月免费次数	本接口月免费上限	折扣	VIP 折后单价
免费版	按接口配置	—	-	¥0.002/次
个人版	5000 次	5000 次	10%	¥0.0018/次
专业版	30000 次	30000 次	20%	¥0.0016/次
企业版推荐	200000 次	200000 次	30%	¥0.0014/次

* VIP 月度免费额度每月重置。每月免费次数为账号级 VIP 月额度，本接口月免费上限为其中对本接口的限制（接口可单独设置上限或关闭）。VIP 折扣仅适用于余额扣费方式，VIP 折后单价不含量折扣。本接口已关闭接口级月度免费额度（不影响 VIP 月度免费额度）。接口每日免费额度已关闭。

费用计算示例

* 以下示例未包含量折扣，量折扣按账号当月全部接口的付费调用量另行计算。

示例1：普通用户按次付费

调用 1000 次，费用 = 0.002 × 1000 = ¥2.00

示例2：个人版用户按次付费（仅 VIP 折扣，已考虑最低利润率保护）

调用 1000 次，折扣约 10%，费用 = 0.002 × (1 - 10%) × 1000 ≈ ¥1.80

示例3：购买「500次调用包」次数包

支付 ¥0.95，获得 500 次调用，折算单价 ¥0.0019/次

同等次数按次付费需 ¥1.00，次数包可节省 ¥0.05

错误码说明

错误码	说明	解决方案
200	请求成功	-
400000	请求参数错误	检查参数名、格式与取值
401000	认证失败	检查 Authorization: Bearer 密钥是否正确、是否过期
402000	账户余额不足	充值后重试
403000	无访问权限	确认密钥权限、接口范围与 IP 白名单是否满足要求
404001	接口或端点不存在	检查 API 与端点的请求路径
409000	请求冲突	请稍后重试
422000	参数校验失败	检查参数格式与取值
429000	请求频率或额度超限	降低调用频率，或升级套餐提升额度
500000	服务器内部错误	携带响应中的 request_id 联系技术支持
502000	服务暂时不可用	稍后重试
503000	服务暂时不可用	稍后重试
504000	请求超时	稍后重试

更新日志

暂无更新日志