サイトチェック

要求したページへの到達途中でターゲットがBotチェックを実行した場合、FourAはそれを通知します。Botチェックに遭遇したすべてのrequestには、システム名、チェックがクリアされたかどうか、および（クリアされた場合）次回の呼び出しでチェックをスキップするために再利用できるクリアランスペイロードを含むフィールドが返されます。

このページでは、それらのフィールドについて解説します。戦略については、保護されたサイトを参照してください。

フィールドの場所

エンドポイント	フィールド	含まれる条件
`POST /api/single/`	`defense` (object)	response内でBotチェックが認識された場合
`POST /api/proxy/`	`defense` (object)	同上、応答した試行によって報告されます
`POST /api/browser/`	`defenseSolved` (boolean) および `defenses` (object)	常に（読み込まれたページ上）。何も認識されなかった場合、`defenseSolved` は `false` となり、`defenses` は空になります。
`POST /api/auto/`	`meta.solved` (boolean)	ラダーが開始された後のすべての応答。ラダー内のいずれかでチェックがクリアされた場合は `true` となります。バリデーションに失敗したbodyや解決できないホストは、ラダーの前に処理されるため `meta` は含まれません。

フィールドが存在しない場合は、何も認識されなかったことを意味します。defense がないことをエラーと解釈しないでください。

SingleおよびProxyでのレポートには unblocker が必要です（デフォルトで有効）。unblocker: false を指定した場合、受信したそのままのページを要求することになるため、Singleはチャレンジをそのまま返し、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` がチャレンジページである可能性があることを意味します。
`present`	string[]	この response で認識されたすべてのシステム。`vendor` よりも多くの名前が含まれる場合があり、まだ誰もクリアしていない名前が含まれることもあります。
`ms`	number	チェックのクリアに費やされたミリ秒数。クリア時のみ。
`hashes`	number	チャレンジが要求した計算処理量。クリア時のみ。
`complexity`	number	チャレンジが申告した難易度。クリア時、かつチャレンジが難易度を報告する場合のみ。
`answers`	number	単一ではなく複数の回答を要求するチャレンジに対して提供された、承認済み回答の数。クリア時のみ。
`retry`	string	クリアではなくリトライから body が返された場合に存在します。現在、唯一の値は `refusal-cookies` です。以下を参照してください。
`cookie`	string	再送信する jar。クリアによって得られた clearance、または拒否によって発行された session。

solved: false は分岐処理を行うべきケースです。FourA はチャレンジページをコンテンツとして提示することは決してないため、このフラグは body の解析ではなくエスカレーションが必要であることを示すシグナルとなります。

`retry: "refusal-cookies"`

パズルを実行しないサイトもあります。最初の request を拒否し、拒否時に cookie を設定し、それらの cookie を送り返したユーザーに実際のページを提供します。eBay の商品ページが代表的な例です。

この場合、FourA が自動的にそれらを再送信し、ページを返します。このとき response には retry: "refusal-cookies" が含まれます。

{
  "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 を再生するのと同じ方法でこれを再生すると、以降のページでは拒絶がスキップされます。
1つの request で再試行と clear の両方が発生する場合があります。再試行の応答が FourA でクリア可能な challenge であった場合、ベンダー固有のフィールドを含む solved: true と、それに加えて retry: "refusal-cookies" が返されます。

再試行によってコンテンツが取得され、その過程でシステムが認識されなかった場合、vendor は unknown になります。その場合、present は空の配列になります。

Browser での `defenses`

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

フィールド	タイプ	説明
`defenseSolved`	boolean	ページの読み込み中にシステムが検出され、最終ページでそのクリアランスが保持されている場合は `true`。このフラグによって、呼び出しコストが5クレジットか10クレジットかが決まります。
`defenses.present`	string[]	最終レスポンスだけでなく、ページ読み込み中の任意の時点で認識されたすべてのシステム。チェックは過去に発生した事象であり、実際のページが届く頃にはチャレンジレスポンスは既に消去されています。
`defenses.cleared`	string[]	最終ページがクリアランスを保持しているシステム。

present に存在し cleared に到達しない名前は、FourA が認識できるもののまだ完了できないシステムです。これらによって呼び出し料金が上がることはありません。

ベンダー

`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 独自のチェックおよびアクセス拒否ページ
`amazon`	Amazon のロボットチェック
`google`	Google 検索の JavaScript チェック
`hcaptcha`	hCaptcha
`recaptcha`	reCAPTCHA
`unknown`	システムは認識されませんでした。ベンダーではなくリトライを報告するためにレコードが存在する `retry` と共にある場合にのみ表示されます。

現在クリア可能な対象

エンドポイント	クリア対象
Single, Proxy	`sgcaptcha`, `ebay-splashui`。どちらも視覚的ではなく計算による処理のため、ブラウザは関与しません。
Browser	`cloudflare`, `sgcaptcha`

リスト内のその他の項目はすべて認識および報告のみが行われます。FourA がクリアできる項目が増えるにつれてこの分類は変更されるため、この表から推測するのではなく solved を確認してください。

エッジケースに関する2つの注意点:

hcaptcha および recaptcha は通常のフォームウィジェットでもあります。これらはレスポンスが実際にブロックされた場合 (403, 429, または 503) にのみ報告されるため、フォーム内に認証ウィジェットがある購入手続きページでは防御として報告されません。
Cloudflare の背後にあること自体は防御ではありません。cloudflare は、サイトが Cloudflare を使用しているからではなく、レスポンスに実際のチャレンジまたは Bot Management のアーティファクトが存在する場合に表示されます。

クリアランスの再利用

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

初回の呼び出しにはクリアのコストがかかります。以降の各リプレイは通常価格の通常リクエストとなります。

リプレイが失敗する原因は主に3つあります。

異なるイグジット。 クリア時のレスポンスから返された proxy ID を固定してください。Reuse a Proxy Across Requestsを参照してください。
異なる User-Agent。 Browser レスポンスは使用した userAgent を返します。cookie と一緒に送り返してください。
有効期限切れ。 クリアランスにはターゲットによって設定された独自の有効期間があります。SiteGround はサイト全体で約30日間持続しますが、Cloudflare のクリアランスは通常はるかに短くなります。クリアランスはキャッシュとして扱ってください。リプレイで再びチャレンジが返され始めたら、新規呼び出しを1回実行して新しいクリアランスを取得してください。

コスト

チェックのクリアにより価格が変動するのは Browser のみです。

Engine	Base	Cleared defense
Single	1 (`unblocker` 使用時は 2)	変更なし
Proxy	2 (`unblocker` 使用時は 4)	変更なし
Browser	5	10

Browser はソルバーが有効でシステムが実際にクリアされた場合のみ 10 が課金されます。システムが認識されたもののクリアされなかった場合は、チェックのないページと同一の 5 が課金されます。

HTTP 200 で返された FourA が認識するチェックページ（Amazon のロボットチェック、Reddit の検証ページ、Google Search の JavaScript チェックなど）は、どのエンドポイントでも課金されません。レスポンスの X-FourA-Check-Page にその詳細が記載されます。

`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 によりラダーがチャレンジページを受け入れて完了とみなすのを防ぎます。

サイトチェック

フィールドの場所

SingleおよびProxyにおける defense

retry: "refusal-cookies"

Browser での defenses