接口定位与功能边界综合风控评分接口服务于准备、登录、下单、领券等需要快速识别风险的业务环节。调用方传入手机号、IP、邮箱中的任意一个或多个维度接口在秒级时间内返回 0 到 100 的整数风险分同时输出放行、二次验证或拦截的业务建议。接口的输入并不要求三个字段全部齐全只传手机号或只传邮箱时也可以完成评分。但需要明确每个维度都对应独立的检测信号传入维度越完整风险判断的覆盖面越广。接口具备三项典型能力手机号维度识别虚拟运营商号段与物联网卡号段这类号码常被用于批量准备和养号IP 维度识别代理、VPN、机房 IDC IP以及私有地址等异常网络环境邮箱维度识别一次性临时邮箱、MX 记录异常和本地部分异常。调用方需要理解该接口输出的是风险评分与结论建议而不是用户的完整画像数据。是否执行拦截、是否需要人工审核最终由业务侧根据自身策略决定。请求方式与鉴权接口采用 POST 方法请求体为 JSON 格式。项目说明请求地址https://v1.apizero.cn/api/risk-score请求方法POSTContent-Typeapplication/json鉴权方式Header 中携带 API KeyQPS 限制2 次/秒鉴权 Header 参数为Authorization类型为 string必填。实际调用时应在请求头中加入Authorization字段并填入调用方持有的 API Key同时设置Content-Type: application/json。QPS 限制为 2 次/秒意味着在默认配额下单秒并发请求不应超过 2 次。超出限制时接口通常会返回限流错误具体表现以文档为准。请求体字段逐一解析请求体是一个 JSON 对象所有字段均为选填但业务上建议至少传入一个可检测的维度。{ mobile: 17012345678, ip: 47.88.1.1, email: abcguerrillamail.com, scene: register }mobile手机号类型string是否必填否支持格式11 位手机号或 13 位物联网卡号接口会对手机号做号段级识别重点判断是否为虚拟运营商号段或物联网卡号段。这些号码在实名管控和活跃特征上与普通运营商号码存在差异常出现在薅羊毛、批量养号等场景中。手机号参数只支持合法号码格式传入不满足位数要求的字符串时信号检测会返回校验失败。ipIP 地址类型string是否必填否支持格式IPv4 或 IPv6接口支持直接传入self作为 IP 值此时会检测调用方自身的出口 IP。该用法在服务端无法获取客户端真实 IP、或不方便透传 IP 的架构中较为实用。传入 IP 后接口会判断其是否属于代理、VPN、数据中心 IP并识别运营商归属。需要注意的是47.88.x.x这类机房 IP 在返回中可能被标记为is_datacenter: true即使它不是恶意 IP也会在风险评分中产生权重。email邮箱地址类型string是否必填否识别范围临时邮箱、MX 记录、格式合法性接口会对邮箱域名做临时邮箱库匹配并检查域名是否存在有效 MX 记录。若域名命中已知的临时邮箱服务商风险信号会直接拉高。scene业务场景类型string是否必填否默认值register可选值register / login / order / couponscene 字段用于告知接口当前请求所属的业务环节。不同场景下同一批风险信号对整体评分的影响权重可能不同例如准备场景更关注手机号与邮箱的可疑性而支付场景可能更关注 IP 的可信度。curl 接入示例以下为完整的 curl 调用示例实际使用时需要将Authorization的取值替换为真实 API Keycurl -sS \ -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {mobile: 17012345678, ip: 47.88.1.1, email: abcguerrillamail.com, scene: register} \ https://v1.apizero.cn/api/risk-score若只需要检测单个维度可以只传对应字段curl -sS \ -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {ip: self, scene: login} \ https://v1.apizero.cn/api/risk-score第二种写法在服务端无法获取用户真实 IP 时可以快速获得当前出口 IP 的风险等级。响应数据与判定逻辑接口成功时返回 HTTP 200顶层包含code、msg、data和request_id四个字段。code为 0 表示业务成功request_id可用于链路追踪与问题排查。核心决策字段data对象中最重要的三个字段为risk_score、risk_level和decision。字段类型含义risk_scorenumber0 到 100 的整数风险分数值越高风险越大risk_levelstring风险等级如 critical / high / medium / low具体枚举以文档为准decisionstring业务建议如 reject / review / pass具体枚举以文档为准risk_score是三个维度信号按权重叠加后的综合结果decision则是基于风险分映射出的动作建议。业务方可以将decision作为默认策略也可以自定义阈值。信号明细 signalssignals对象按mobile、ip、email三个维度分别展示检测结果每个维度内部包含该维度的独立风险评级。以响应示例中的 email 信号为例{ email: { checked: true, is_disposable: true, has_mx: true, risk: high } }这里的is_disposable: true表示该邮箱属于一次性临时邮箱has_mx: true表示域名存在 MX 记录同样可以通过其他字段判断临时邮箱特征。risk字段是维度级风险等级与最终风险分相关但不直接等同。IP 信号中常见字段is_datacenter是否为机房 IDC IPis_proxy是否为代理 IPis_private是否为内网保留地址isp运营商信息。手机号信号中常见字段number_type号码类型如普通号、虚拟运营商号、物联网卡号carrier运营商名称input_mask脱敏后的手机号可用于日志记录。命中规则 hit_ruleshit_rules数组列出本次请求命中的具体风控规则每条包含规则编码、描述与权重。例如{ code: MOBILE_MVNO, desc: 虚拟运营商号段170实名宽松薅羊毛高发, weight: 35 }通过hit_rules业务方可以知道风险分是由哪些因素构成的进而在日志中沉淀风险原因或在二次验证页面展示对应的校验手段。一个完整的返回结构{ code: 0, msg: 成功, request_id: k9x2p4mabc12, data: { risk_score: 88, risk_level: critical, decision: reject, scene: register, checked: { email: true, ip: true, mobile: true }, signals: { mobile: { checked: true, valid: true, number_type: mvno, carrier: 虚拟运营商, input_mask: 170****5678, risk: high }, ip: { checked: true, valid: true, is_datacenter: true, is_proxy: false, is_private: false, isp: 阿里云, risk: medium }, email: { checked: true, valid_format: true, is_disposable: true, has_mx: true, is_trusted: false, risk: high } }, hit_rules: [ { code: MOBILE_MVNO, desc: 虚拟运营商号段170实名宽松薅羊毛高发, weight: 35 }, { code: EMAIL_DISPOSABLE, desc: 一次性/临时邮箱域名典型用于注册套利, weight: 35 }, { code: IP_DATACENTER, desc: 机房/IDC IP非真实用户网络脚本批量常用, weight: 30 } ] } }异常与错误处理实际调用中常见的问题集中在以下几个方面。鉴权失败Authorization缺失、为空或格式错误时接口无法识别调用者身份通常返回 401 或业务错误码。排查顺序建议为确认请求头名称是否为Authorization确认 API Key 是否完整复制没有多余空格确认使用的 Key 与接口所属服务一致。参数格式错误手机号不是 11 位、IP 不是合法 IPv4/IPv6、邮箱缺少符号等都会导致对应维度无法正常检测。此时应检查signals中对应维度的valid或valid_format字段快速定位格式问题。建议在业务侧先做基础格式校验过滤明显非法输入再调用接口避免将脏数据透传到风控系统。限流与超时接口 QPS 为 2 次/秒。在准备高峰或批量任务场景中如果并发超过限制则可能出现 429 限流或请求排队。应对方式在调用层增加本地限流或信号量控制并发对非实时性要求低的任务采用队列削峰对限流错误进行退避重试避免反复触发阈值。超时时间建议设置为 3 到 5 秒。风控接口属于在线决策路径超时过长会影响主流程体验超时后可根据业务策略选择放行并异步复核或默认执行二次验证。返回 code 非 0顶层code不为 0 时应结合具体错误码判断失败原因。接口文档中会列出各错误码对应的含义集成时应将常见错误码映射到统一的异常处理逻辑中。工程化集成注意事项1. 动态阈值risk_score是连续值而decision是离散建议。不同业务对风险的容忍度不同社区类产品可能只拦截 90 分以上的请求金融或交易类业务则可能对 70 分以上的请求就要求二次验证。建议将阈值配置在配置中心而不是硬编码在代码里方便灰度调整。2. 缓存与降级对于相同手机号或 IP 的短时间重复请求可以使用本地缓存或 Redis 短暂缓存评分结果降低接口 QPS 压力。缓存时间建议不超过 5 分钟因为 IP 和号码的风险状态可能动态变化。当风控接口超时或不可用时业务侧应有明确的降级策略允许通过但降低信任等级改为短信验证码二次校验进入人工审核队列。降级策略需要事先定义并经过评审不能在故障发生时临时决定。3. 日志与审计每次调用都应记录关键信息请求时间与耗时传入的 mobile / ip / email返回的 risk_score、decision、request_id后续业务动作放行、拦截、人工审核。request_id是排查问题的重要线索当与文档团队沟通返回结果异常时应一并提供该值。4. 隐私与安全手机号和邮箱属于敏感信息在日志中应做脱敏处理。接口响应中已经提供input_mask字段作为展示用脱敏值业务侧写日志时优先使用该字段。5. 场景字段的合理使用scene字段不宜随意填写应按实际业务动作传值。如果业务侧无法区分具体场景可以统一使用默认值register但得到的风险评分可能不完全贴合当前环节。典型接入流程一个标准的接入流程可以概括为以下步骤业务侧预处理手机号、IP、邮箱格式过滤空值与非法值至少携带一个有效维度发起 POST 请求解析返回的risk_score与decision根据业务策略映射为放行、二次验证或拦截动作将request_id与业务订单号关联存储对risk_level为 high 或 critical 的请求做后续跟踪。对于只传 IP 且传值为self的调用应确保部署环境出口 IP 稳定否则重复请求可能得到不同结果。常见误用提醒将risk_level等同于decision两者有相关性但 decision 是接口给出的操作建议业务方可以基于 risk_level 自定义动作把signals中某个维度的风险直接当作整体风险整体评分是多个维度的加权结果仅依据单个信号做决策可能误伤用户在拦截逻辑中依赖desc文案desc是面向人工阅读的说明文字程序逻辑应绑定code而不是desc。参考文档综合风控评分接口文档https://apizero.cn/aidocs/risk-score原始 Markdown 文档https://apizero.cn/aidocs/risk-score/raw.md