适用场景与核心能力在业务安全对抗中准备薅羊毛、批量养号、营销作弊等风险行为往往依托虚拟号段、代理 IP 或临时邮箱实施。综合风控评分 API 提供了一站式的统一信号评估能力开发者只需传入手机号、IP 地址和邮箱中的任意组合即可秒级返回 0-100 的风险分以及明确的决策建议放行/二次验证/拦截。该接口适用于以下典型场景用户准备识别虚拟运营商号段、临时邮箱拦截机器准备。登录保护检测 IP 是否来自代理或数据中心防止撞库攻击。订单与券排查批量下单或刷券行为的风险。内容发布对可疑 IP 或邮箱发帖进行二次验证。接口能力边界请求方式POST接口地址https://v1.apizero.cn/api/risk-scoreQPS 限制2 次/秒超过会返回限流错误需在客户端实现退避策略鉴权方式通过 HTTP 头部Authorization或X-API-Key传入密钥文档中以X-API-Key示例三路信号手机号虚拟运营商、物联网卡、IP代理/VPN/数据中心、邮箱临时邮箱、MX 异常决策输出decision字段枚举值pass放行、review二次验证、reject拦截请求参数详解接口采用 JSON 格式的请求体所有字段均为可选但至少应提供一个信号源才能进行有效评分。参数名类型必填说明示例mobilestring否11 位手机号或 13 位物联网卡号。系统自动识别虚拟运营商号段如 170、171、物联网卡如 1064917012345678ipstring否IPv4 或 IPv6 地址。特殊值self表示检测调用方自身 IP由服务器获取连接来源47.88.1.1emailstring否邮箱地址。检测是否为临时邮箱域名、MX 记录是否正常abcguerrillamail.comscenestring否业务场景标识影响风控告警阈值。枚举值register准备login登录order下单coupon券。默认值为registerregister注意mobile字段支持 11 位手机号及 13 位物联网卡号长度不符合时接口将返回invalid_parameter错误ip字段传入self时可省略真实 IP由服务端自动获取请求来源 IP 进行分析。请求 HeadersHeader 名必填类型说明Authorization是string鉴权凭证格式为Bearer your-api-key。也可使用X-API-Key头部传值Content-Type是string必须为application/json可复制的请求示例curl下面是一个完整的 curl 示例同时传入手机号、IP 和邮箱场景为准备。请将$APIZERO_API_KEY替换为您的真实密钥curl -sS \ -X POST \ -H X-API-Key: $APIZERO_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使用 Python 封装带错误处理对于工程化集成建议封装成独立函数统一处理网络异常和限流退避import requests import time import json API_URL https://v1.apizero.cn/api/risk-score API_KEY your_api_key_here # 建议从环境变量读取 def risk_score(mobileNone, ipNone, emailNone, sceneregister, retries3): headers { X-API-Key: API_KEY, Content-Type: application/json } payload {} if mobile: payload[mobile] mobile if ip: payload[ip] ip if email: payload[email] email payload[scene] scene for attempt in range(retries): try: resp requests.post(API_URL, jsonpayload, headersheaders, timeout5) if resp.status_code 200: return resp.json() elif resp.status_code 429: # 限流等待后重试 wait_time 2 ** attempt time.sleep(wait_time) continue else: # 其他业务错误直接返回 return resp.json() except requests.exceptions.RequestException as e: if attempt retries - 1: raise time.sleep(1) return None响应字段全面解读成功的响应HTTP 200包含以下字段结构下面以示例中的返回为蓝本逐层解析{ code: 0, msg: 成功, request_id: k9x2p4mabc12, data: { checked: { email: true, ip: true, mobile: true }, decision: reject, hit_rules: [ { code: MOBILE_MVNO, desc: 虚拟运营商号段170实名宽松薅羊毛高发, weight: 35 }, { code: EMAIL_DISPOSABLE, desc: 一次性/临时邮箱域名典型用于注册套利, weight: 35 }, { code: IP_DATACENTER, desc: 机房/IDC IP非真实用户网络脚本批量常用, weight: 30 } ], risk_level: critical, risk_score: 88, scene: register, signals: { email: { checked: true, email: abcguerrillamail.com, has_mx: true, is_disposable: true, is_trusted: false, risk: high, valid_format: true }, ip: { checked: true, ip: 47.88.x.x, is_datacenter: true, is_private: false, is_proxy: false, isp: 阿里云, province: , risk: medium, valid: true }, mobile: { carrier: 虚拟运营商, checked: true, input_mask: 170****5678, number_type: mvno, risk: high, valid: true } } } }顶层字段code整型0 表示成功非 0 表示失败。非 0 时msg携带错误描述。msg字符串状态描述。request_id每次请求的唯一标识便于追踪问题。data对象核心评分结果。data 内部字段字段类型说明checkedobject本次实际参与检查的信号维度布尔值表示是否被评估decisionstring建议决策pass、review、rejecthit_rulesarray命中的风控规则列表包含code规则代码、desc描述、weight权重 0-100risk_levelstring风险等级safe、low、medium、high、criticalrisk_scoreinteger综合风险分 0-100数字越高风险越大scenestring请求传入的场景值signalsobject每个信号的详细评估结果signals 子字段每个维度的信号对象中包含以下字段以 mobile 为例checked该信号是否被分析carrier运营商名称移动/联通/电信/虚拟运营商input_mask脱敏后的手机号number_type号码类型如normal、mvno虚拟运营商、iot物联网risk该维度的风险等级low/medium/highvalid格式是否合法IP 信号额外包含is_datacenter、is_proxy、isp等字段邮箱信号额外包含is_disposable、has_mx、is_trusted等字段。常见错误与处理建议HTTP 状态码返回 codemsg 示例常见原因处理方式20040000参数错误: mobile 长度必须为 11 或 13传入的mobile格式不正确检查参数长度和内容20040001缺少 API Key未携带鉴权头部添加Authorization或X-API-Key20040002无效的 API Key密钥错误或已过期核实密钥42940003请求频率过高超过 QPS 限制实现本地排队或退避重试20050001服务内部错误服务端异常重试连续失败需上报注意即使 HTTP 状态码为 200业务逻辑错误仍会通过code非 0 表示务必优先检查code而非状态码。工程化注意事项限流控制QPS 为 2/s建议在客户端使用令牌桶或固定窗口限制请求速率。对于高并发场景可增加本地缓存对相同特征如同一 IP 或手机号在一段时间内复用结果。重试策略对 429 限流错误采用指数退避如 1s、2s、4s 重试对 5xx 错误可重试 1-2 次但需设置整体超时。缓存设计同一用户的手机号、IP 短时间内不会变化可设置 5-10 分钟的 TTL 缓存减少重复调用。注意缓存粒度按 mobileipemailscene 四元组做键。字段校验在上传前先校验手机号格式11 位数字、IP 格式正则 IPv4/IPv6避免无效请求浪费 QPS。日志与告警记录每次请求的request_id、命中规则、决策结果便于事后溯源发现连续返回非pass时触发告警。异步处理对于非实时风控场景如订单审核可放入消息队列异步调用降低接口压力。业务决策落地建议接口返回的decision可直接用于控制流程pass放行业务操作。review要求用户完成二次验证如短信验证码、图形验证码并记录risk_score作为辅助参考。reject直接拦截返回友好的提示如“操作太频繁请稍后再试”并记录日志。若risk_score在 70-100 区间但decision为review可考虑升级为人工审核或转入无感验证如增加行为分析。参考文档综合风控评分接口文档原始接口定义本文所有示例均基于公开 API 事实卡编写请以实际文档为准。接口地址、参数说明如有更新优先查阅官方文档。