适用场景与问题背景在准备、登录、下单、领券等核心业务环节黑产团伙常利用虚拟运营商号段、代理IP、临时邮箱进行批量养号或薅羊毛。传统做法是人工维护黑名单或自建规则引擎但维护维护复杂度高、响应慢。综合风控评分 API 提供三个维度的信号手机号、IP、邮箱返回 0~100 风险分以及明确的决策建议放行pass、二次验证challenge、拦截reject让业务方无需自建复杂模型即可快速接入反欺诈能力。接口能力边界单次调用可同时检测三项mobile手机号/物联网卡号、ipIPv4/IPv6、email邮箱。各项为可选参数可按需传入。支持多场景通过scene参数区分register、login、order、couponAPI 内部会自适应阈值权重。结果包含信号层明细不仅给出总分还给出每条数据源的具体风险标签如MOBILE_MVNO、IP_DATACENTER、EMAIL_DISPOSABLE及权重方便业务侧二次加工。QPS 限制2 次/秒适合在线实时决策。超出限制会返回 429。鉴权与请求参数Header 鉴权接口使用Authorization头部传递 API Key从控制台获取格式为Bearer your_api_key或使用X-API-Keycurl 示例中使用的就是后者。实际生产中建议统一使用Authorization: Bearer key更规范。请求体JSON字段类型必填说明mobilestring否11 位手机号或 13 位物联网卡号。传此字段会检查是否属于虚拟运营商/物联网卡号段ipstring否IPv4/IPv6 地址。传self可自动获取调用者出口 IPemailstring否邮箱地址。检测是否为临时邮箱、MX 记录是否异常scenestring否业务场景默认register。取值register/login/order/coupon至少应传一个检测维度否则接口会返回参数校验错误。curl 可复现实例假设已设置环境变量API_KEY以下命令检测一个高风险场景虚拟运营商号段 机房IP 临时邮箱curl -sS -X POST \ -H X-API-Key: $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响应示例已格式化{ code: 0, msg: 成功, request_id: k9x2p4mabc12, data: { risk_score: 88, risk_level: critical, decision: reject, scene: register, checked: { mobile: true, ip: true, email: true }, signals: { mobile: { checked: true, input_mask: 170****5678, valid: true, number_type: mvno, carrier: 虚拟运营商, risk: high }, ip: { checked: true, ip: 47.88.x.x, valid: true, isp: 阿里云, is_datacenter: true, is_proxy: false, is_private: false, risk: medium, province: }, email: { checked: true, email: abcguerrillamail.com, valid_format: true, has_mx: true, is_disposable: 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} ] } }返回字段深度解读字段路径类型含义codeint业务状态码0 表示成功msgstring对应文字信息request_idstring唯一请求标识可用于问题排查data.risk_scoreint综合风险分 0-100越高越危险data.risk_levelstring等级safe/low/medium/high/criticaldata.decisionstring业务决策pass/challenge/rejectdata.hit_rules[]array命中规则列表每条含code、desc、weight权重 1-100总和 100data.signalsobject各信号的详细检测结果见下方子表signals 子字段说明mobile字段类型含义checkedbool是否检测了手机号input_maskstring脱敏手机号中间四位隐藏validbool号码格式是否有效number_typestringnormal/mvno/iotcarrierstring运营商名称riskstringlow/medium/highip字段类型含义checkedbool是否检测 IPipstring脱敏后的 IP部分隐藏validboolIP 格式是否有效ispstring所属运营商/云厂商is_datacenterbool是否为机房 IPis_proxybool是否为代理/VPN IPis_privatebool是否为内网 IPriskstring风险等级email字段类型含义checkedbool是否检测邮箱emailstring完整邮箱原样返回valid_formatbool格式是否合法has_mxbool是否有 MX 记录is_disposablebool是否为临时/一次性邮箱is_trustedbool是否属于可信域名库riskstring风险等级常见错误处理HTTP状态码业务codemsg原因处理方式4011001认证失败API Key 无效或未传检查 Header 中的 Authorization/X-API-Key4002001参数校验失败请求体 JSON 格式错误或未传任何检测字段确保至少填一个字段且 JSON 合法4002002场景值不在允许范围内scene 字段值非法仅传register/login/order/coupon4293001请求频率过高超过 2 QPS 限制限流降级等待后重试5004001服务内部错误服务端异常重试若持续则联系技术支持注意所有错误响应也包含code和msg以及request_id便于日志追踪。工程化封装注意事项1. 网络层超时与重试API 要求在 500ms 以内通常几十 ms但网络波动可能引起超时。建议设置连接超时 3s、读超时 5s。对于 429 和 5xx 错误实施指数退避重试最多 3 次间隔 1s/2s/4s。2. 限流保护单实例 QPS 上限为 2多实例部署时要确保总请求不超过限制。可使用令牌桶或信号量控制本地频率或借助网关集中限流。3. 缓存策略同一手机号/IP/邮箱的短时间重复查询如 1 分钟内可以缓存上次结果但注意风险会随时间变化缓存不宜过长。对于 blacklist 级别的拦截可以缓存 15-30 分钟。4. 降级预案当 API 不可用如超时或 5xx时建议采取保守策略对风险较高的场景准备默认拦截 人工审核对低风险场景如登录可放行。5. 工程代码示例Pythonimport requests import time import logging logger logging.getLogger(__name__) class RiskScoreClient: def __init__(self, api_key: str, base_url: str https://v1.apizero.cn/api/risk-score): self.headers { Authorization: fBearer {api_key}, Content-Type: application/json } self.url base_url self.max_retries 3 self.retry_delays [1, 2, 4] def query(self, mobile: str None, ip: str None, email: str None, scene: str register) - dict: payload {k: v for k, v in [(mobile, mobile), (ip, ip), (email, email), (scene, scene)] if v is not None} for attempt in range(self.max_retries): try: resp requests.post(self.url, jsonpayload, headersself.headers, timeout(3, 5)) if resp.status_code 429: logger.warning(Rate limited, retrying after %ss, self.retry_delays[attempt]) time.sleep(self.retry_delays[attempt]) continue resp.raise_for_status() data resp.json() if data.get(code) ! 0: logger.error(API error: %s, data.get(msg)) return data except requests.exceptions.Timeout: logger.warning(Timeout on attempt %d, attempt1) if attempt self.max_retries - 1: time.sleep(self.retry_delays[attempt]) else: raise except requests.exceptions.RequestException as e: logger.error(Request failed: %s, e) if attempt self.max_retries - 1: time.sleep(self.retry_delays[attempt]) else: raise # 降级返回默认拒绝决策 return { code: -1, msg: service unavailable, data: {decision: reject, risk_score: 100} }6. Java 代码片段使用 HttpClientimport java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; public class RiskScoreClient { private static final String URL https://v1.apizero.cn/api/risk-score; private final String apiKey; private final HttpClient client; public RiskScoreClient(String apiKey) { this.apiKey apiKey; this.client HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(3)) .build(); } public String query(String mobile, String ip, String email, String scene) throws Exception { // 构建 JSON 请求体使用 Jackson 等库序列化 String body String.format( {\mobile\:\%s\,\ip\:\%s\,\email\:\%s\,\scene\:\%s\}, mobile ! null ? mobile : , ip ! null ? ip : , email ! null ? email : , scene ! null ? scene : register); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(URL)) .header(Authorization, Bearer apiKey) .header(Content-Type, application/json) .POST(HttpRequest.BodyPublishers.ofString(body)) .timeout(Duration.ofSeconds(5)) .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); return response.body(); } }总结综合风控评分 API 通过一次调用即可整合三大风险信号配合工程化封装重试、限流、降级能稳定支撑在线业务。建议在接入前先使用 curl 验证 Key 和参数再逐步替换为客户端 SDK 或自行封装的工具类。参考文档原始文档https://apizero.cn/aidocs/risk-score/raw.md接口文档页https://apizero.cn/aidocs/risk-score
从 curl 到工程封装：综合风控评分 API 集成实战
适用场景与问题背景在准备、登录、下单、领券等核心业务环节黑产团伙常利用虚拟运营商号段、代理IP、临时邮箱进行批量养号或薅羊毛。传统做法是人工维护黑名单或自建规则引擎但维护维护复杂度高、响应慢。综合风控评分 API 提供三个维度的信号手机号、IP、邮箱返回 0~100 风险分以及明确的决策建议放行pass、二次验证challenge、拦截reject让业务方无需自建复杂模型即可快速接入反欺诈能力。接口能力边界单次调用可同时检测三项mobile手机号/物联网卡号、ipIPv4/IPv6、email邮箱。各项为可选参数可按需传入。支持多场景通过scene参数区分register、login、order、couponAPI 内部会自适应阈值权重。结果包含信号层明细不仅给出总分还给出每条数据源的具体风险标签如MOBILE_MVNO、IP_DATACENTER、EMAIL_DISPOSABLE及权重方便业务侧二次加工。QPS 限制2 次/秒适合在线实时决策。超出限制会返回 429。鉴权与请求参数Header 鉴权接口使用Authorization头部传递 API Key从控制台获取格式为Bearer your_api_key或使用X-API-Keycurl 示例中使用的就是后者。实际生产中建议统一使用Authorization: Bearer key更规范。请求体JSON字段类型必填说明mobilestring否11 位手机号或 13 位物联网卡号。传此字段会检查是否属于虚拟运营商/物联网卡号段ipstring否IPv4/IPv6 地址。传self可自动获取调用者出口 IPemailstring否邮箱地址。检测是否为临时邮箱、MX 记录是否异常scenestring否业务场景默认register。取值register/login/order/coupon至少应传一个检测维度否则接口会返回参数校验错误。curl 可复现实例假设已设置环境变量API_KEY以下命令检测一个高风险场景虚拟运营商号段 机房IP 临时邮箱curl -sS -X POST \ -H X-API-Key: $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响应示例已格式化{ code: 0, msg: 成功, request_id: k9x2p4mabc12, data: { risk_score: 88, risk_level: critical, decision: reject, scene: register, checked: { mobile: true, ip: true, email: true }, signals: { mobile: { checked: true, input_mask: 170****5678, valid: true, number_type: mvno, carrier: 虚拟运营商, risk: high }, ip: { checked: true, ip: 47.88.x.x, valid: true, isp: 阿里云, is_datacenter: true, is_proxy: false, is_private: false, risk: medium, province: }, email: { checked: true, email: abcguerrillamail.com, valid_format: true, has_mx: true, is_disposable: 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} ] } }返回字段深度解读字段路径类型含义codeint业务状态码0 表示成功msgstring对应文字信息request_idstring唯一请求标识可用于问题排查data.risk_scoreint综合风险分 0-100越高越危险data.risk_levelstring等级safe/low/medium/high/criticaldata.decisionstring业务决策pass/challenge/rejectdata.hit_rules[]array命中规则列表每条含code、desc、weight权重 1-100总和 100data.signalsobject各信号的详细检测结果见下方子表signals 子字段说明mobile字段类型含义checkedbool是否检测了手机号input_maskstring脱敏手机号中间四位隐藏validbool号码格式是否有效number_typestringnormal/mvno/iotcarrierstring运营商名称riskstringlow/medium/highip字段类型含义checkedbool是否检测 IPipstring脱敏后的 IP部分隐藏validboolIP 格式是否有效ispstring所属运营商/云厂商is_datacenterbool是否为机房 IPis_proxybool是否为代理/VPN IPis_privatebool是否为内网 IPriskstring风险等级email字段类型含义checkedbool是否检测邮箱emailstring完整邮箱原样返回valid_formatbool格式是否合法has_mxbool是否有 MX 记录is_disposablebool是否为临时/一次性邮箱is_trustedbool是否属于可信域名库riskstring风险等级常见错误处理HTTP状态码业务codemsg原因处理方式4011001认证失败API Key 无效或未传检查 Header 中的 Authorization/X-API-Key4002001参数校验失败请求体 JSON 格式错误或未传任何检测字段确保至少填一个字段且 JSON 合法4002002场景值不在允许范围内scene 字段值非法仅传register/login/order/coupon4293001请求频率过高超过 2 QPS 限制限流降级等待后重试5004001服务内部错误服务端异常重试若持续则联系技术支持注意所有错误响应也包含code和msg以及request_id便于日志追踪。工程化封装注意事项1. 网络层超时与重试API 要求在 500ms 以内通常几十 ms但网络波动可能引起超时。建议设置连接超时 3s、读超时 5s。对于 429 和 5xx 错误实施指数退避重试最多 3 次间隔 1s/2s/4s。2. 限流保护单实例 QPS 上限为 2多实例部署时要确保总请求不超过限制。可使用令牌桶或信号量控制本地频率或借助网关集中限流。3. 缓存策略同一手机号/IP/邮箱的短时间重复查询如 1 分钟内可以缓存上次结果但注意风险会随时间变化缓存不宜过长。对于 blacklist 级别的拦截可以缓存 15-30 分钟。4. 降级预案当 API 不可用如超时或 5xx时建议采取保守策略对风险较高的场景准备默认拦截 人工审核对低风险场景如登录可放行。5. 工程代码示例Pythonimport requests import time import logging logger logging.getLogger(__name__) class RiskScoreClient: def __init__(self, api_key: str, base_url: str https://v1.apizero.cn/api/risk-score): self.headers { Authorization: fBearer {api_key}, Content-Type: application/json } self.url base_url self.max_retries 3 self.retry_delays [1, 2, 4] def query(self, mobile: str None, ip: str None, email: str None, scene: str register) - dict: payload {k: v for k, v in [(mobile, mobile), (ip, ip), (email, email), (scene, scene)] if v is not None} for attempt in range(self.max_retries): try: resp requests.post(self.url, jsonpayload, headersself.headers, timeout(3, 5)) if resp.status_code 429: logger.warning(Rate limited, retrying after %ss, self.retry_delays[attempt]) time.sleep(self.retry_delays[attempt]) continue resp.raise_for_status() data resp.json() if data.get(code) ! 0: logger.error(API error: %s, data.get(msg)) return data except requests.exceptions.Timeout: logger.warning(Timeout on attempt %d, attempt1) if attempt self.max_retries - 1: time.sleep(self.retry_delays[attempt]) else: raise except requests.exceptions.RequestException as e: logger.error(Request failed: %s, e) if attempt self.max_retries - 1: time.sleep(self.retry_delays[attempt]) else: raise # 降级返回默认拒绝决策 return { code: -1, msg: service unavailable, data: {decision: reject, risk_score: 100} }6. Java 代码片段使用 HttpClientimport java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; public class RiskScoreClient { private static final String URL https://v1.apizero.cn/api/risk-score; private final String apiKey; private final HttpClient client; public RiskScoreClient(String apiKey) { this.apiKey apiKey; this.client HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(3)) .build(); } public String query(String mobile, String ip, String email, String scene) throws Exception { // 构建 JSON 请求体使用 Jackson 等库序列化 String body String.format( {\mobile\:\%s\,\ip\:\%s\,\email\:\%s\,\scene\:\%s\}, mobile ! null ? mobile : , ip ! null ? ip : , email ! null ? email : , scene ! null ? scene : register); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(URL)) .header(Authorization, Bearer apiKey) .header(Content-Type, application/json) .POST(HttpRequest.BodyPublishers.ofString(body)) .timeout(Duration.ofSeconds(5)) .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); return response.body(); } }总结综合风控评分 API 通过一次调用即可整合三大风险信号配合工程化封装重试、限流、降级能稳定支撑在线业务。建议在接入前先使用 curl 验证 Key 和参数再逐步替换为客户端 SDK 或自行封装的工具类。参考文档原始文档https://apizero.cn/aidocs/risk-score/raw.md接口文档页https://apizero.cn/aidocs/risk-score
