反爬虫防御

当目标在你请求页面的过程中运行机器人检查时，FourA 会告知你。每个遇到检查的 request 都会返回一个字段，说明该系统名称、检查是否已清除，以及 (如果已清除) 你可以重放的 clearance，以便下次调用跳过它。

本页面是这些字段的参考文档。有关策略，请参阅处理反机器人保护。

字段位置

Endpoint	字段	出现条件
`POST /api/single/`	`defense` (对象)	在 response 中识别到机器人检查时
`POST /api/proxy/`	`defense` (对象)	同上，由提供响应的尝试报告
`POST /api/browser/`	`defenseSolved` (布尔值) 和 `defenses` (对象)	在页面加载期间识别到机器人检查时
`POST /api/auto/`	`meta.solved` (布尔值)	始终存在。当在 ladder 的某处清除了检查时为 `true`。

缺失意味着未识别到任何内容。不要将缺失的 defense 视为失败。

报告需要 unblocker (默认开启)。使用 unblocker: false 时，你请求的是页面的原始状态，因此 Single 会原封不动地返回 challenge，而 Browser 会渲染但不会解决它。

Single 和 Proxy 上的 `defense`

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "hashes": 1048576,
    "complexity": 20,
    "cookie": "_I_=<clearance>"
  }
}

字段	类型	描述
`vendor`	string	此记录涉及的系统: 已通过的系统，或遇到的主要系统。请参阅下方的供应商列表。
`solved`	boolean	`true` 表示已通过检查，并且 `data` 是真实页面。`false` 表示 `data` 可能是质询 (challenge) 页面。
`present`	string[]	此 response 中识别出的每个系统。可以包含比 `vendor` 更多的名称，也可以包含尚无人通过的名称。
`ms`	number	通过检查所花费的毫秒数。仅在通过时存在。
`hashes`	number	质询要求的计算工作量。仅在通过时存在。
`complexity`	number	质询声明的难度。仅在通过时且仅在质询报告难度时存在。
`answers`	number	提供的已接受答案的数量，适用于需要多个答案而不是一个答案的质询。仅在通过时存在。
`cookie`	string	通过后获得的凭证 (clearance)，可用于重放。仅在通过时存在。

solved: false 是值得进行分支判断的情况。FourA 从未将未解决的质询作为内容提供，因此该标志向您发出信号，表明 body 需要升级处理而不是解析。

Browser 上的 `defenses`

{
  "status": 200,
  "body": "<!doctype html>...",
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {
    "present": ["cloudflare"],
    "cleared": ["cloudflare"]
  }
}

字段	类型	描述
`defenseSolved`	boolean	当在加载过程中遇到防护系统且最终页面包含清除该防护的凭据时为 `true`。此标志决定该调用消耗15还是30个积分。
`defenses.present`	string[]	在页面加载的任何时刻(不仅是最终响应)识别出的所有系统。检查已经发生，当真实页面到达时质询响应早已结束。
`defenses.cleared`	string[]	最终页面包含其清除凭据的系统。

出现在 present 但从未到达 cleared 的名称是指 FourA 可以识别但尚未能绕过的系统。这些系统绝不会增加调用成本。

供应商

`vendor` 值	系统
`cloudflare`	Cloudflare 质询和机器人管理
`sgcaptcha`	SiteGround 站点检查
`datadome`	DataDome
`perimeterx`	PerimeterX
`akamai`	Akamai Bot Manager
`incapsula`	Imperva Incapsula
`awswaf`	AWS WAF 质询
`ebay-splashui`	eBay 原生质询
`hcaptcha`	hCaptcha
`recaptcha`	reCAPTCHA

目前支持清除的内容

Endpoint	清除系统
Single, Proxy	`sgcaptcha`, `ebay-splashui`。两者均属于计算型而非视觉型，因此不涉及浏览器。
Browser	`cloudflare`, `sgcaptcha`

列表中的其他所有内容均仅作识别和报告。随着 FourA 学会清除更多系统，此分类会发生变化，因此请读取 solved，而不要仅根据此表进行假设。

关于边缘情况的两点说明：

hcaptcha 和 recaptcha 同样是普通的表单组件。它们仅在响应实际拦截您时(403、429 或 503)才会报告，因此包含验证码字段的结账页面表单不会报告为防御系统。
使用 Cloudflare 本身并不属于防御。只有当响应中存在真实的质询或机器人管理痕迹时才会显示 cloudflare，而不是因为站点使用了 Cloudflare。

重放清除凭据

defense.cookie 是该字段的核心所在。清除凭据与其对应的出口和 User-Agent 绑定，因此通过相同的组合进行重放就不会再次触发检查。

import requests

API = "https://eu.api.foura.ai"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

# 1) First call pays for the clear.
first = requests.post(f"{API}/api/proxy/", headers=H, json={
    "maxTries": 5,
    "request": {"method": "GET", "url": "https://example.com/catalog"},
}).json()

defense = first.get("defense", {})
if defense.get("solved"):
    clearance = defense["cookie"]
    exit_id = first["proxy"]

    # 2) Follow-up pages skip the check: same exit, same clearance.
    for page in range(2, 6):
        r = requests.post(f"{API}/api/single/", headers=H, json={
            "method": "GET",
            "url": f"https://example.com/catalog?page={page}",
            "proxy": exit_id,
            "headers": [["Cookie", clearance]],
        }).json()
        print(page, r["status"])

首次调用承担清除（拦截）的费用。每次重放都是按普通价格计费的普通请求。

导致重放失败的三个因素：

不同的出口。 固定清除响应返回的 proxy ID。请参阅在请求间重用 Proxy。
不同的 User-Agent。 Browser 响应会返回它们使用的userAgent。请将其与 cookie 一起发送回去。
过期。 清除状态具有自己的生命周期，由目标设定。SiteGround 针对整个站点的周期约为 30 天，Cloudflare 清除周期通常要短得多。将清除状态视为缓存：当重放再次开始返回挑战时，请运行一次全新调用并获取新的状态。

计费方式

成功清除的检查仅会更改 Browser 的价格：

引擎	基础	成功清除防御
Single	1（包含 `unblocker` 时为 2）	无变化
Proxy	5（包含 `unblocker` 时为 10）	无变化
Browser	15	30

Browser 仅在求解器开启且系统真正被清除时收取 30 的费用。被识别但未被清除的系统收费为 15，与完全没有检查的页面相同。

与 `validate` 搭配使用

defense 告知您遇到了检查。validate 告知 FourA 真实页面的外观，这使得请求能够失败，而不是向您返回恰好带有 HTTP 200 状态码的插页式页面。

{
  "method": "GET",
  "url": "https://example.com/product/42",
  "validate": {
    "data": {"accept": ["Add to cart"], "fail": ["Just a moment"]}
  }
}

在 POST /api/auto/ 上，validate 用于阻止 ladder 接受 challenge 页面并直接判定为完成。

反爬虫防御

字段位置

Single 和 Proxy 上的 defense

Browser 上的 defenses

供应商