# 站点检查

> URL: https://foura.ai/zh/docs/api/site-checks
> Updated: 2026-11-11
> Index: https://foura.ai/llms.txt

当目标在访问请求页面的过程中运行 Bot 检查时，FourA 会进行提示。遇到检查的每个 request 都会返回一个字段，指明系统名称、检查是否已通过，以及（通过时）可用于重放以跳过下次调用的通关凭证。

本页是这些字段的参考文档。有关策略，请参阅 [受保护站点](https://foura.ai/docs/guides/protected-sites)。

## 字段位置

| Endpoint | 字段 | 出现条件 |
|----------|-------|--------------|
| `POST /api/single/` | `defense`（对象） | 响应中识别出 Bot 检查 |
| `POST /api/proxy/` | `defense`（对象） | 同上，由响应的重试上报 |
| `POST /api/browser/` | `defenseSolved`（布尔值）和 `defenses`（对象） | 始终存在于已加载的页面上。未识别到内容时，`defenseSolved` 为 `false` 且 `defenses` 为空。 |
| `POST /api/auto/` | `meta.solved`（布尔值） | 梯级流程启动后的每个响应均包含。若梯级流程中通过了检查，则为 `true`。校验失败的 body 或无法解析的 host 会在进入梯级流程前直接响应，不包含 `meta`。 |

字段缺失表示未识别到任何检查。不要将缺失 `defense` 视为失败。

在 Single 和 Proxy 上，上报需要启用 `unblocker`（默认开启）。使用 `unblocker: false` 表示请求原始返回页面，因此 Single 会原封不动返回质询，Browser 也会直接渲染而不进行解析。

## Single 和 Proxy 上的 `defense`

```json
{
  "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` 可能是质询页面。 |
| `present` | string[] | 此 response 中识别出的所有系统。可包含比 `vendor` 更多的名称，也可包含尚无人能绕过的系统名称。 |
| `ms` | number | 完成检查所耗费的毫秒数。仅在通过时提供。 |
| `hashes` | number | 质询所要求的计算工作量。仅在通过时提供。 |
| `complexity` | number | 质询声明的难度。仅在通过且质询报告了该值时提供。 |
| `answers` | number | 针对需要多个答案而非单个答案的质询，提供的已接受答案数量。仅在通过时提供。 |
| `retry` | string | 当 body 来自重试而非直接绕过时出现：`refusal-cookies`、`amazon-continue`、`reddit-js-check` 或 `verify-challenge`。请参阅下文。 |
| `cookie` | string | 用于重放的 jar：通过验证所获取的凭证，或拒绝访问时分配的 session。 |

`solved: false` 是值得进行逻辑分支处理的情况。FourA 绝不会将质询页面作为内容返回，因此该标志代表 body 需要升级处理而不是直接解析。

### `retry: "refusal-cookies"`

某些网站不运行验证谜题。它们会拒绝首次 request，在拒绝响应中设置 cookie，并在任何回传这些 cookie 时提供真实页面。eBay 的商品详情页就是典型案例。

发生这种情况时，FourA 会自动代您回传并在获取后交付页面。随后 response 将携带 `retry: "refusal-cookies"`：

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "akamai",
    "solved": false,
    "present": ["akamai"],
    "retry": "refusal-cookies",
    "cookie": "bm_sv=...; dp1=..."
  }
}
```

解读方式如下：

- **`solved` 保持为 `false`。**响应握手不属于清除 challenge，也绝不会改变调用成本。计费完全基于您发起的 request。
- **`data` 是真实内容**，而非 challenge 页面。这是 `solved: false` 不代表 body 需要升级处理的唯一情况，这也是该字段存在的原因。
- **`cookie` 是站点下发的会话。**像重放 clearance 一样重放该会话，后续页面即可跳过拦截。
- 单次 request 中可以同时发生重试和 clear。如果重试返回的内容是 FourA 能够清除的 challenge，您将获得包含厂商专属字段的 `solved: true`，**以及**并列的 `retry: "refusal-cookies"`。

当重试成功获取内容且过程中未识别出任何系统时，`vendor` 显示为 `unknown`。此时 `present` 为空数组。

### `retry: "amazon-continue"`

Amazon 有时会返回单按钮机器人验证：一个提示点击以继续购物的微型页面，且答案已预先填入。在启用 `unblocker`（默认开启）时，Single 和 Proxy 会在同一个出口、您的 `timeout_ms` 内点击该按钮，并携带其设置的 cookie 重新请求页面。成功打开页面后，response 会携带 `retry: "amazon-continue"`：

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "akamai",
    "solved": false,
    "present": ["akamai", "amazon"],
    "retry": "amazon-continue",
    "cookie": "ak_bmsc=...; ..."
  }
}
```

可以将其理解为因拒绝 cookie 而触发的重试。`solved`保持为`false`，`data`是真实页面，系统仅对您发起的 request 计费，而`cookie`是后续页面需复用的 cookie jar。请在`present`中查找`amazon`，而不是在`vendor`中查找：验证页面通常会设置一个 FourA 也能识别的 cookie，而`vendor`会指明列表中的第一个系统。

同一验证的图片版本（需要人工识别答案）会被直接上报并保留原样。仅重新加载该验证的点击操作也是如此。无论哪种情况，该页面均不计费（请参阅 [费用说明](#what-it-costs)）。

### `retry: "reddit-js-check"`

Reddit 有时会返回轻量级页面验证：一个包含隐藏表单和自动填充脚本的小型页面。在开启`unblocker`（默认配置）的情况下，Single 和 Proxy 会在同一个出口节点提交该表单（在您的`timeout_ms`内），并携带所设置的 cookie 重新请求您的目标页面。成功打开页面后，response 会携带`retry: "reddit-js-check"`：

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "reddit",
    "solved": false,
    "present": ["reddit"],
    "retry": "reddit-js-check",
    "cookie": "edgebucket=...; ..."
  }
}
```

可以将其视为一次 `amazon-continue` 重试。`solved` 保持为 `false`，`data` 是真实页面，系统仅按您发起的 request 计费，`cookie` 是在后续页面重放的 cookie jar。当该检查持续返回时，FourA 会原样保留页面，且该页面不计费。

### `retry: "verify-challenge"`

部分站点会先打开一个简短的自有检查页面：包含一个加载动画以及一段在检查完成后跳转至目标页面的脚本。启用 `unblocker`（默认值）后，Single 和 Proxy 会在同一个出口、在您的 `timeout_ms` 内完成该检查，并携带其设置的 cookie 重新请求目标页面。成功打开页面后，response 会包含 `retry: "verify-challenge"`：

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "verify-challenge",
    "solved": false,
    "present": ["verify-challenge"],
    "retry": "verify-challenge",
    "cookie": "token=..."
  }
}
```

可以将其视为 `reddit-js-check` 重试。`solved` 保持为 `false`，`data` 是真实页面，系统仅对您发起的 request 计费，`cookie` 是在后续页面重放的 cookie jar。当验证页面未获响应返回时，不计费。

## 浏览器中的 `defenses`

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

| 字段 | 类型 | 说明 |
|-------|------|-------------|
| `defenseSolved` | boolean | 当在加载过程中遇到某种系统且最终页面持有其 clearance 时为 `true`。该标志决定此调用扣除 5 还是 10 个积分。 |
| `defenses.present` | string[] | 页面加载过程中任何时刻识别出的所有系统，不仅限于最终 response。检查是曾经发生过的事实，当真实页面到达时，质询 response 早已不存在。 |
| `defenses.cleared` | string[] | 最终页面持有其 clearance 的系统列表。 |

如果某个名称出现在 `present` 中但未进入 `cleared`，说明 FourA 识别出了该系统但尚未获取其 clearance：可能是目前尚无法完成的系统，或者是 Browser 通过其他方式处理的少数系统之一（参见 [当前支持清除的系统](#what-gets-cleared-today)）。这些情况绝不会增加调用的费用。

## 供应商

| `vendor` 值 | 系统 |
|----------------|-----------|
| `cloudflare` | Cloudflare 质询与 Bot Management |
| `sgcaptcha` | SiteGround 站点检查 |
| `datadome` | DataDome |
| `perimeterx` | PerimeterX |
| `akamai` | Akamai Bot Manager |
| `incapsula` | Imperva Incapsula |
| `awswaf` | AWS WAF 质询 |
| `ebay-splashui` | eBay 自有质询 |
| `reddit` | Reddit 自有检查与拒绝页面 |
| `verify-challenge` | 网站自身的检查页面，检查完成后会自动跳转 |
| `amazon` | Amazon 机器人检查 |
| `hcaptcha` | hCaptcha |
| `recaptcha` | reCAPTCHA |
| `unknown` | 未识别到任何系统。仅与 `retry` 一同出现，该记录用于报告重试而非供应商。 |

### 当前支持清除的系统

| Endpoint | 清除范围 |
|----------|--------|
| Single, Proxy | `sgcaptcha`, `ebay-splashui`。两者皆为计算型而非视觉型验证，因此无需浏览器参与。 |
| Browser | `cloudflare`, `sgcaptcha` |

还有少数情况无需获取 clearance 即可处理。Single 和 Proxy 会自动点击 Amazon 的单按钮机器人检查并将其上报为 `retry: "amazon-continue"`，提交 Reddit 的轻量页面检查并上报为 `retry: "reddit-js-check"`，以及完成网站自身的检查页面并上报为 `retry: "verify-challenge"`。Browser 最多等待 10 秒以供该检查页面自动跳转。Browser 会点击 Amazon 的按钮，并在 Akamai 传感器页面、AWS WAF 质询页面、DataDome 设备检查或 eBay 自有质询页面自行加载下一页时保持等待，然后返回该页面。如果该页面始终未加载成功，Browser 会将当前停留在的页面放入你的 `timeout_ms` 中返回。在 Browser 上，这些名称仅出现在 `defenses.present` 中，绝不会出现在 `cleared` 中，调用费用为 5 积分。

列表中其余所有项仅做识别和上报，不执行其他操作。随着 FourA 支持清除更多系统，上述分类会发生变化，因此请以 `solved` 的实际值为准，切勿仅依据此表格进行推断。

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

- `hcaptcha` 和 `recaptcha` 也属于常规表单控件。仅当响应实际拦截了请求（403、429 或 503）时才会上报，因此包含验证控件的结账页面表单不会上报防御状态。
- 部署在 Cloudflare 之后并不算作防御。`cloudflare` 仅在响应中出现真实的质询或 Bot 管理标记时显示，而不是因为站点使用了 Cloudflare。

## 重放 Clearance

`defense.cookie` 是该字段的核心价值所在。Clearance 会与获取它的出口 IP 及 User-Agent 绑定，因此通过相同的组合进行重放，检查便不会再次触发。

```python
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"])
```

首次调用包含绕过验证的费用。之后的每次重放都是按普通价格计费的普通 request。

导致重放失效的三种情况：

1. **出口节点改变。** 请固定绕过验证 response 返回的 proxy ID。参见 [跨 Request 复用 Proxy](https://foura.ai/docs/how-to/reuse-a-proxy)。
2. **User-Agent 改变。** Browser response 会返回所使用的 `userAgent`。请将其与 cookie 一起回传。
3. **过期。** 验证通行证（clearance）有其自身的有效期，由目标站点决定。SiteGround 的全站有效期约为 30 天；Cloudflare 的 clearance 通常要短得多。请将 clearance 视为缓存：当重放再次触发 challenge 时，发起一次全新的调用并获取新的凭证。

## 计费标准

成功绕过验证仅会改变 Browser 的价格：

| 引擎 | 基础价格 | 成功绕过防御 |
|--------|------|-----------------|
| Single | 1（包含 `unblocker` 为 2） | 无变化 |
| Proxy | 2（包含 `unblocker` 为 4） | 无变化 |
| Browser | 5 | 10 |

Browser 仅在 solver 开启且实际成功绕过系统时收取 10。如果系统被识别但未成功绕过，费用为 5，与完全没有验证的页面相同。

FourA 识别出以 HTTP 200 返回的验证页面或拦截页面（例如 Amazon 的机器人检查、Reddit 的验证页面或 eBay 的 challenge 页面），在任何 endpoint 上均不计费。Single、Proxy 和 Browser response 会在 `X-FourA-Check-Page` 中标明。

## 配合 `validate` 使用

`defense` 提示遇到了验证。`validate` 告知 FourA 真实页面的特征，从而使 request 直接失败，而不是向你返回一个恰好带有 HTTP 200 的过渡页面。

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

在 `POST /api/auto/` 上，`validate` 可以防止阶梯策略误将质询页面视为成功完成。

## 相关内容

- [受保护站点](https://foura.ai/docs/guides/protected-sites)：各防护级别下应使用的引擎
- [API 端点](https://foura.ai/docs/api/endpoints)：全部 4 个 endpoint 的 request 与 response 参考
- [跨请求复用代理](https://foura.ai/docs/how-to/reuse-a-proxy)：固定 clearance 绑定的出口节点
- [智能抓取 (Auto)](https://foura.ai/docs/guides/smart-fetch)：`meta.solved` 如何融入阶梯策略
- [响应标头](https://foura.ai/docs/api/response-headers)：调用消耗的点数显示位置
