Cloudflare Interstitial（チャレンジページ）解決 API：clearance Cookie

SolveHub API で Cloudflare のチャレンジページを通過し、返却された clearance Cookie を同じ User-Agent とプロキシで再利用。フィールド、cURL 例、エラー。

許可された QA 自動化とブラウザー連携向けです。テスト権限のあるサイトと業務フローでのみ使用してください。

Cloudflare のブロックページに適用され、通常は後続の処理で cf_clearance Cookie を再利用する必要があります。websiteURL と HTTP プロキシの 3 フィールド proxyType,proxyAddress,proxyPort が必須です。任意の siteKey はページ上の Turnstile sitekey で、指定するとプラットフォームはこれをもとにショートカット経路を利用できます。デフォルトで指定しない場合はページ全体を解決します。source:true を指定すると、結果にチャレンジ後の HTML が返されます（取得に成功した場合）。method は GET または POST のみをサポートし、デフォルトは GET です。useragent は任意です。

ブラウザーの選択

任意の useragent で Chrome/Chromium または Firefox のファミリー、プラットフォーム、メジャーバージョンを選択できます。ノードにないバージョンを指定すると失敗します。省略時は既定のブラウザーを使用します。Cookie を再利用するときは、同じプロキシと実際に返却された solution.useragent を使用してください。

リクエストフィールド

外側の type と task は必須です。以下の task.* パスはすべて task オブジェクト内にあります。フィールド名は大文字と小文字が区別されます。長さの制限は UTF-8 のバイト数で計算されます。

フィールド	型	必須	制限	説明
`type`	文字列	はい	`interstitial` 固定	プラットフォームのタスクタイプ。
`task`	JSON オブジェクト	はい	≤ 7 MiB	このタイプのタスクパラメータ。
`task.type`	文字列	いいえ	指定する場合は `interstitial` であること	旧リクエスト形式との互換用。新規導入では省略できます。
`task.websiteURL`	HTTP(S) URL	はい	≤ 2048 バイト	解決対象ページの完全な URL。アカウント名やパスワードは含めません。
`task.siteKey`	文字列	いいえ	≤ 256 バイト	ページ上の Turnstile sitekey。指定するとショートカット経路を使用でき、省略するとページ全体を処理します。
`task.useragent`	文字列	いいえ	≤ 512 バイト	カスタムのブラウザ User-Agent。後続のリクエストでは、実際に返された `solution.useragent` を優先して使用してください。
`task.source`	真偽値	いいえ	`true` / `false`	結果にチャレンジ後の HTML を含めるよう要求します。返されるかどうかは実際の結果によります。
`task.method`	文字列	いいえ	`GET` / `POST`	ページのナビゲーションメソッド。省略時は `GET` を使用します。
`task.proxyType`	文字列	はい	`http` のみ	プロキシプロトコル。指定する場合は `http` である必要があります。
`task.proxyAddress`	文字列	はい	≤ 256 バイト	プロキシの IP またはホスト名。`proxyPort` と同時に指定する必要があります。
`task.proxyPort`	文字列	はい	1–5 バイト、数値 1–65535	プロキシのポート。引用符で囲んだ数字の文字列である必要があります。
`task.proxyLogin`	文字列	いいえ	≤ 256 バイト	プロキシに認証が必要な場合にユーザー名を指定します。アドレスとポートを指定せずに単独で指定することはできません。
`task.proxyPassword`	文字列	いいえ	≤ 256 バイト	プロキシに認証が必要な場合にパスワードを指定します。アドレスとポートを指定せずに単独で指定することはできません。

作成リクエストの例

{
  "type": "interstitial",
  "task": {
    "websiteURL": "https://example.com/protected",
    "siteKey": "0x4AAAAAAA_EXAMPLE",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080",
    "source": true
  }
}

cURL での呼び出し

例に含まれるキー、サイト情報、プロキシを実際の値に置き換えてください。Idempotency-Key は同一の業務リクエストに対して変更しないでください。

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-interstitial-0001' \
  --data-binary @- <<'JSON'
{
  "type": "interstitial",
  "task": {
    "websiteURL": "https://example.com/protected",
    "siteKey": "0x4AAAAAAA_EXAMPLE",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080",
    "source": true
  }
}
JSON

作成レスポンスと照会

作成に成功すると HTTP 202 が返され、status の初期値は通常 queued です。taskId を保存し、約 2–3 秒ごとに GET /v1/tasks/{taskId} を呼び出して照会します。このタイプの処理のソフトタイムリミットは 180 秒 です。ソフトタイムリミットを超えると uncertain になる場合があります。受理済みタスクの結果は引き続き確認できるため、クライアントは新しい冪等キーで安易に再作成しないでください。

結果フィールド

solution は status=completed の場合にのみ読み取ってください。下表はよく使われるフィールドを示しています。実際のフィールドは該当タスクのレスポンスを正とします。

フィールド	型	読み取り方法
`solution.cookies`	オブジェクト	解決セッションで生成された Cookie。`cf_clearance` を含む場合があります。
`solution.useragent`	文字列	Cookie および同じ送信元とあわせて再利用すべき User-Agent。
`solution.html`	文字列、任意	`source:true` をリクエストし、ページの取得に成功した場合にのみ含まれます。

completed になったら solution.cookies を読み取ります。cf_clearance が含まれている場合があります。同時に solution.useragent を読み取り、同じプロキシ IP、User-Agent、完全な Cookie セットを使用してアクセスを続けてください。solution.html は source:true を指定し、ページ内容の取得に成功した場合にのみ含まれます。結果イメージ：{"cookies":{"cf_clearance":"EXAMPLE_CLEARANCE"},"useragent":"Mozilla/5.0 ..."}。

失敗とトラブルシューティング

HTTP プロキシの 3 フィールドは必須です。返された Cookie を再利用できない場合は、プロキシの送信元、User-Agent、完全な Cookie セット、および対象ページの有効期限を確認してください。

作成リクエストでよくあるエラーは 400 INVALID_TASK、402 INSUFFICIENT_BALANCE、429 TASK_LIMIT_EXCEEDED、503 TYPE_UNAVAILABLE です。作成済みタスクが失敗した場合の公開エラーコードは TASK_FAILED または TASK_TIMEOUT で、uncertain には TASK_UNCERTAIN が対応します。詳細はプラットフォーム API リファレンスを参照してください。

処理時間はタスク作成の受理確認後に起算し、待ち行列の時間は差し引きません。ノードの現在のタイムアウトは約120秒、プラットフォームのソフト期限は通信と結果確認を含め180秒です。

対応 User-Agent