适用场景与接口能力边界运营商三要素核验接口用于一次性校验「姓名 手机号 身份证号」三者是否一致广泛应用于账户实名认证、风控准入、身份一致性校验等场景。接口仅返回核验结论一致/不一致/无法核验不返回、不存储任何明文个人信息开发者可在取得信息主体授权后合规调用。能力边界单次核验仅支持一组三要素不支持批量。QPS限制为5次/秒以账号维度超出限制会返回频率控制错误。接口只反馈核验结果不提供运营商归属地、在网时长等衍生信息。接口参数与鉴权请求方式HTTP方法POST请求地址https://v1.apizero.cn/api/carrier-3cHeader参数参数名是否必须类型说明Authorization是stringBearer 你的API KeyContent-Type否string请求体格式默认application/json请求体字段字段名类型是否必须说明别名namestring是真实姓名中文realname / xmmobilestring是11位手机号phone / sjidcardstring是18位身份证号末位X兼容大小写id_card / sf示例请求体{ name: 张三, mobile: 13800138000, idcard: 110101199001011234 }curl接入示例以下是一个可直接复制的curl请求请将$APIZERO_API_KEY替换为你实际的API Keycurl -sS \ -X POST \ -H Authorization: Bearer $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { name: 李四, mobile: 13912345678, idcard: 320102199003074567 } \ https://v1.apizero.cn/api/carrier-3c注意此处使用的手机号、姓名、身份证号均为测试数据实际调用请使用真实用户信息。Python接入示例import requests url https://v1.apizero.cn/api/carrier-3c payload { name: 王五, mobile: 13698765432, idcard: 110101199501011234 } headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json } response requests.post(url, jsonpayload, headersheaders) print(response.json())返回值解读成功响应HTTP 200{ code: 0, msg: 成功, request_id: abc123, data: { name: 张三, mobile: 138****0000, idcard: 110***********001X, match: true, result: 三要素一致 } }字段类型说明codeint业务状态码0表示成功msgstring状态描述request_idstring本次请求的全局唯一标识data.namestring脱敏后的姓名data.mobilestring脱敏后的手机号data.idcardstring脱敏后的身份证号data.matchbool核验是否匹配data.resultstring核验结论描述核验结论说明三要素一致→ matchtrue信息不一致→ matchfalse无法核验→ matchfalse运营商数据不足常见错误与排错指南错误类型总览错误表现典型原因解决方向HTTP 401Authorization头缺失或API Key无效检查Header格式和Key有效性HTTP 400请求体JSON格式错误或参数类型不符使用JSON校验工具检查payloadHTTP 429超过QPS限制5次/秒增加调用间隔或实现限流重试code非0业务层校验失败根据code字段定位具体问题网络超时代理/防火墙/出口IP问题检查网络连通性1. 鉴权失败HTTP 401现象返回{code:401, msg:Unauthorized}。排查步骤确认Authorization头格式为Bearer API Key注意Bearer后面有一个空格。检查API Key是否已过期或未生效控制台可查询状态。检查是否有额外的空格或换行符。对比curl命令中的Header写法-H Authorization: Bearer $APIZERO_API_KEY。2. 参数缺失或格式错误HTTP 400现象返回{code:400, msg:参数错误}并可能附带errors字段详细说明。常见原因name字段包含数字或特殊符号仅允许中文。mobile位数不足11位或包含非数字字符。idcard位数不是18位含X时大小写混用。请求体JSON语法错误如尾逗号、双引号未转义。验证方法使用curl -d ...前先通过管道| jq .检查JSON合法性echo {name:张三,mobile:13800138000,idcard:110101199001011234} | jq3. 业务核验错误code非0接口在HTTP 200下也可能返回非0的code常见code如下codemsg含义处理建议1001当日的可调用量已用尽检查账户剩余次数或次月重置1002姓名格式不合法确认name为纯中文1003手机号格式不合法检查手机号是否为11位数字1004身份证号格式不合法校验身份证校验位算法1005调用频次超限降低请求频率QPS限制5次/秒2001运营商无数据无法核验该号码可能为虚拟运营商或携号转网2002身份信息被运营商标记异常建议换用其他核验通道9999系统内部错误间隔重试若持续出现请联系技术支持排错示例假设请求正常但返回{code:2001, msg:运营商无数据, data:{match:false}}表示该号码对应的运营商数据库暂未收录三要素并非参数错误。此时应在业务层兜底例如降级为二要素核验或人工审核。4. QPS超限HTTP 429现象频繁请求时收到{code:429, msg:请求过于频繁}。解决方案在客户端实现令牌桶或滑动窗口限流确保每秒不超过5次。对429响应做指数退避重试例如等待1秒、2秒、4秒…。若业务峰值需要更高QPS联系服务提供商申请调整。5. 数据脱敏与隐私合规官网接口文档明确接口不存储明文数据响应中data.name、data.mobile、data.idcard均为脱敏后的字符串。开发者不应将原始请求参数或脱敏后结果明文打印到日志中尤其是身份证号和手机号。建议在日志中只保留request_id用于问题追溯。6. 网络层错误现象curl返回curl: (28) Connection timed out。排查检查服务器是否可访问公网。验证目标IP是否被防火墙/安全组拦截。使用curl -v详细查看握手阶段。如果使用代理确认http_proxy / https_proxy环境变量正确。工程化注意事项必做检查清单参数白名单校验在调用前对idcard做18位长度和校验位检查ISO 7064:1983, MOD 11-2算法可提前拦截大量格式错误请求节省维护复杂度。别名兼容接口文档允许name/realname/xm、mobile/phone/sj、idcard/id_card/sf多组别名。建议在SDK或中间件中统一映射为规范字段名后提交避免因别名未识别导致的参数缺失。请求去重使用request_id做幂等判断避免重复请求产生额外计费。错误码分级告警对于1001余额不足和9999系统错误应触发P0告警对于2001无数据属于正常业务错误无需告警。合规声明在调用接口前确保已获得用户明确授权并在隐私政策中说明数据流转。重试策略建议import time import requests def call_with_retry(url, headers, payload, max_retries3): for attempt in range(max_retries): try: resp requests.post(url, jsonpayload, headersheaders, timeout5) if resp.status_code 429: time.sleep(2 ** attempt) continue return resp except requests.exceptions.Timeout: if attempt max_retries - 1: raise time.sleep(1) return None参考文档接口文档https://apizero.cn/aidocs/carrier-3c原始文档Markdownhttps://apizero.cn/aidocs/carrier-3c/raw.md
适用场景与接口能力边界运营商三要素核验接口用于一次性校验「姓名 手机号 身份证号」三者是否一致广泛应用于账户实名认证、风控准入、身份一致性校验等场景。接口仅返回核验结论一致/不一致/无法核验不返回、不存储任何明文个人信息开发者可在取得信息主体授权后合规调用。能力边界单次核验仅支持一组三要素不支持批量。QPS限制为5次/秒以账号维度超出限制会返回频率控制错误。接口只反馈核验结果不提供运营商归属地、在网时长等衍生信息。接口参数与鉴权请求方式HTTP方法POST请求地址https://v1.apizero.cn/api/carrier-3cHeader参数参数名是否必须类型说明Authorization是stringBearer 你的API KeyContent-Type否string请求体格式默认application/json请求体字段字段名类型是否必须说明别名namestring是真实姓名中文realname / xmmobilestring是11位手机号phone / sjidcardstring是18位身份证号末位X兼容大小写id_card / sf示例请求体{ name: 张三, mobile: 13800138000, idcard: 110101199001011234 }curl接入示例以下是一个可直接复制的curl请求请将$APIZERO_API_KEY替换为你实际的API Keycurl -sS \ -X POST \ -H Authorization: Bearer $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { name: 李四, mobile: 13912345678, idcard: 320102199003074567 } \ https://v1.apizero.cn/api/carrier-3c注意此处使用的手机号、姓名、身份证号均为测试数据实际调用请使用真实用户信息。Python接入示例import requests url https://v1.apizero.cn/api/carrier-3c payload { name: 王五, mobile: 13698765432, idcard: 110101199501011234 } headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json } response requests.post(url, jsonpayload, headersheaders) print(response.json())返回值解读成功响应HTTP 200{ code: 0, msg: 成功, request_id: abc123, data: { name: 张三, mobile: 138****0000, idcard: 110***********001X, match: true, result: 三要素一致 } }字段类型说明codeint业务状态码0表示成功msgstring状态描述request_idstring本次请求的全局唯一标识data.namestring脱敏后的姓名data.mobilestring脱敏后的手机号data.idcardstring脱敏后的身份证号data.matchbool核验是否匹配data.resultstring核验结论描述核验结论说明三要素一致→ matchtrue信息不一致→ matchfalse无法核验→ matchfalse运营商数据不足常见错误与排错指南错误类型总览错误表现典型原因解决方向HTTP 401Authorization头缺失或API Key无效检查Header格式和Key有效性HTTP 400请求体JSON格式错误或参数类型不符使用JSON校验工具检查payloadHTTP 429超过QPS限制5次/秒增加调用间隔或实现限流重试code非0业务层校验失败根据code字段定位具体问题网络超时代理/防火墙/出口IP问题检查网络连通性1. 鉴权失败HTTP 401现象返回{code:401, msg:Unauthorized}。排查步骤确认Authorization头格式为Bearer API Key注意Bearer后面有一个空格。检查API Key是否已过期或未生效控制台可查询状态。检查是否有额外的空格或换行符。对比curl命令中的Header写法-H Authorization: Bearer $APIZERO_API_KEY。2. 参数缺失或格式错误HTTP 400现象返回{code:400, msg:参数错误}并可能附带errors字段详细说明。常见原因name字段包含数字或特殊符号仅允许中文。mobile位数不足11位或包含非数字字符。idcard位数不是18位含X时大小写混用。请求体JSON语法错误如尾逗号、双引号未转义。验证方法使用curl -d ...前先通过管道| jq .检查JSON合法性echo {name:张三,mobile:13800138000,idcard:110101199001011234} | jq3. 业务核验错误code非0接口在HTTP 200下也可能返回非0的code常见code如下codemsg含义处理建议1001当日的可调用量已用尽检查账户剩余次数或次月重置1002姓名格式不合法确认name为纯中文1003手机号格式不合法检查手机号是否为11位数字1004身份证号格式不合法校验身份证校验位算法1005调用频次超限降低请求频率QPS限制5次/秒2001运营商无数据无法核验该号码可能为虚拟运营商或携号转网2002身份信息被运营商标记异常建议换用其他核验通道9999系统内部错误间隔重试若持续出现请联系技术支持排错示例假设请求正常但返回{code:2001, msg:运营商无数据, data:{match:false}}表示该号码对应的运营商数据库暂未收录三要素并非参数错误。此时应在业务层兜底例如降级为二要素核验或人工审核。4. QPS超限HTTP 429现象频繁请求时收到{code:429, msg:请求过于频繁}。解决方案在客户端实现令牌桶或滑动窗口限流确保每秒不超过5次。对429响应做指数退避重试例如等待1秒、2秒、4秒…。若业务峰值需要更高QPS联系服务提供商申请调整。5. 数据脱敏与隐私合规官网接口文档明确接口不存储明文数据响应中data.name、data.mobile、data.idcard均为脱敏后的字符串。开发者不应将原始请求参数或脱敏后结果明文打印到日志中尤其是身份证号和手机号。建议在日志中只保留request_id用于问题追溯。6. 网络层错误现象curl返回curl: (28) Connection timed out。排查检查服务器是否可访问公网。验证目标IP是否被防火墙/安全组拦截。使用curl -v详细查看握手阶段。如果使用代理确认http_proxy / https_proxy环境变量正确。工程化注意事项必做检查清单参数白名单校验在调用前对idcard做18位长度和校验位检查ISO 7064:1983, MOD 11-2算法可提前拦截大量格式错误请求节省维护复杂度。别名兼容接口文档允许name/realname/xm、mobile/phone/sj、idcard/id_card/sf多组别名。建议在SDK或中间件中统一映射为规范字段名后提交避免因别名未识别导致的参数缺失。请求去重使用request_id做幂等判断避免重复请求产生额外计费。错误码分级告警对于1001余额不足和9999系统错误应触发P0告警对于2001无数据属于正常业务错误无需告警。合规声明在调用接口前确保已获得用户明确授权并在隐私政策中说明数据流转。重试策略建议import time import requests def call_with_retry(url, headers, payload, max_retries3): for attempt in range(max_retries): try: resp requests.post(url, jsonpayload, headersheaders, timeout5) if resp.status_code 429: time.sleep(2 ** attempt) continue return resp except requests.exceptions.Timeout: if attempt max_retries - 1: raise time.sleep(1) return None参考文档接口文档https://apizero.cn/aidocs/carrier-3c原始文档Markdownhttps://apizero.cn/aidocs/carrier-3c/raw.md
