CapSolverのreCAPTCHA連携をsolvethreeに移行する

solvethree はデフォルトで reCAPTCHA v3 Enterprise を使用し、標準の v3 にも対応しています。ほかに公開されている製品は Kasada と Ticketmaster TMPT です。reCAPTCHA v2、hCaptcha、Turnstile、ブラウザー拡張機能による解答には対応していないため、すべての CapSolver 連携を置き換えられるわけではありません。

reCAPTCHA タスクを送信する前に、コンソールで対象サイトを設定し、ワークスペースで有効なプロファイルを利用できることを確認してください。ホスト名とアクションを送信しても、そのプロファイルは作成されません。CapSolver の websiteKey フィールドを削除すれば、残りのリクエストだけで十分だと考えないでください。

移行前のリクエストは、CapSolver の clientKey とプロバイダー固有のタスクエンベロープを使用しています。

{
  "clientKey": "CAPSOLVER_API_KEY",
  "task": {
    "type": "ReCaptchaV3Task",
    "websiteURL": "https://accounts.example.com/login",
    "websiteKey": "PUBLIC_SITE_KEY",
    "pageAction": "login",
    "isEnterprise": true,
    "proxy": "http://user:[email protected]:8080"
  }
}

solvethree では、以下のフラットなボディを POST https://api.solvethree.com/v1/tasks に送信します。Authorization ヘッダーには、Bearer に続けてワークスペースの API キーを設定してください。キーはサーバー側で保持し、新しい JSON ボディに clientKey を引き継がないでください。

{
  "site": "accounts.example.com",
  "action": "login",
  "proxy": "http://user:[email protected]:8080",
  "requestId": "example_login_001"
}

この例では recaptchaType をデフォルトのままにしているため、Enterprise リクエストになります。対象サイトが標準の v3 を使用している場合は、明示的に選択してください。CapSolver のすべてのタスクタイプを Enterprise のデフォルトに置き換えないでください。

CapSolver の ProxyLess タスクに直接対応するプロキシ不要の方式は、ここにはありません。solvethree では呼び出し側がプロキシを指定する必要があります。現在の連携でプロキシを管理していない場合、必要なのはフィールド名の変更ではなく、連携の変更です。また、SOCKS プロキシの設定を新しいリクエストにコピーしないでください。solvethree が受け付けるのは HTTP と HTTPS のプロキシ URL です。

解答と送信に使用する経路が明確になるよう、まずは単一のプロキシから始めてください。代わりに proxyCandidates を使用する場合は、パス、クエリ、フラグメントを含まない、互いに異なる HTTP または HTTPS のプロキシ URL を最大 12 個指定します。候補を指定するとサービスが別の出口経路を試せますが、プロキシや対象サイトが動作することを保証するものではありません。

CapSolver は clientKey と taskId を指定した getTaskResult で非同期の結果を取得します。solvethree は Bearer 認証を使用する GET /v1/tasks/:id で取得します。HTTP 呼び出しだけでなく、結果のパーサーも更新してください。CapSolver のステータスフィールドとエラーフィールドは、別の仕様に基づいています。

1. 1.

   最初に HTTP レスポンスを確認する

   成功時のペイロードを読み取る前に、成功以外の HTTP レスポンスを処理してください。HTTP リクエストのエラーと解答タスクの失敗は、別々に処理する必要があります。

2. 2.

   作成時に返されたタスクを確認する

   reCAPTCHA の作成はデフォルトで最大 15 秒待機するため、レスポンスがすでに終了状態になっている場合があります。使用可能な解答が含まれるのは ready の場合だけです。タスクが pending または solving の場合は、返された solvethree のタスク ID で取得してください。

3. 3.

   ready または failed でポーリングを停止する

   ready の場合は、解答を送信処理のコードに渡します。failed の場合は、errorCode と error を確認し、そのタスクのポーリングを停止します。解答に失敗した場合は返金されます。無効な入力を変更せずにむやみに再試行したり、すべての失敗が残高不足を意味すると考えたりしないでください。

段階的な移行中は、各タスク ID にプロバイダーを示すタグを付けて保持してください。既存の CapSolver タスクは CapSolver で完了させ、新しい solvethree タスクは solvethree で処理します。旧プロバイダーのタスク ID を新しい API に送信するのではなく、アダプターでそれぞれの結果を正規化してください。

reCAPTCHA の結果を意図した対象に送信する際は、solution.token を使用します。返された userAgent と secChUa も保持し、送信には成功したプロキシを使用してください。既存のアダプターがトークン文字列だけを返す場合は、これらの情報を送信側のクライアントまで引き継ぐように変更してください。

ready 状態のトークンが拒否された場合は、別の解答に料金を支払う前に、送信するアプリケーションのリクエストを確認してください。タスク ID や古いトークンではなく新しいトークンが含まれていること、送信に返されたブラウザー識別情報、成功したプロキシ、意図した対象 URL が使用されていることを確認します。ready 状態のタスクは解答が生成されたことを意味し、その後のリクエストを対象サイトが受け入れたことを意味するものではありません。

移行後の例には、復旧用の requestId が含まれています。新しい論理タスクごとに生成し、リクエスト入力を変更せずに一緒に保持してください。使用できるのは、1–64 文字の ASCII 英数字、アンダースコア、ハイフンです。同じタスクリクエストで再利用すると既存のタスクが返され、異なる入力で使用すると競合が発生します。

作成がタイムアウトした場合は、タスク ID があればそのタスクを取得し、なければ同じボディを同じ requestId で再送信してください。レスポンスが失われても、作成に失敗したとは限りません。クライアントが待機をやめたという理由だけで、新しい ID を生成しないでください。

クライアントのタイムアウトには、reCAPTCHA 作成時のデフォルトの待機時間である最大 15 秒に加え、ネットワークのオーバーヘッドも考慮してください。GET によるポーリングはデフォルトでは待機せずに返り、最大 15000 の waitMs を指定できます。waitMs はタスクの JSON ではなく URL クエリに指定し、ポーリングのタイムアウトにもその待機時間を考慮してください。