Node.js の Fetch で CAPTCHA API を連携

前提条件

サーバーやテスト実行環境で Node.js 22+ を使用します。外部 HTTP ライブラリは不要です。tasks 権限のある有効な Key、十分な残高、テスト権限のあるサイトが必要です。登録・メール認証後、利用可能ならセルフサービスを有効化するか発行済み Key を紐付けます。料金を確認してください。

ダウンロードと実行

下のリンクから nodejs-client.mjs を取得し、task.json に管理下のテストサイトの値を設定します。

{"type":"turnstile","task":{"websiteURL":"https://example.com/login","websiteKey":"REPLACE_WITH_SITE_KEY"}}

認証情報はリポジトリに保存せず環境変数で渡します。最初の送信前に論理タスク用の固定キーを保存してください。

export SOLVEHUB_API_KEY='sh_REPLACE_ME'
export SOLVEHUB_IDEMPOTENCY_KEY='persisted-authorized-test-0001'
export SOLVEHUB_TASK_FILE='task.json'
node nodejs-client.mjs

taskId が分かると直ちに stderr に表示し、完了した solution のみ stdout に出力します。業務記録に taskId を保存してください。この例は有料タスクを作成する場合があり、プレースホルダーだけでは動作しません。

既存タスクの再開

クライアント期限や不確定な結果では再作成せず、保存した ID を使います。

export SOLVEHUB_TASK_ID='SAVED_TASK_ID'
node nodejs-client.mjs

ID を取得できなかった場合は元のキーと本文を保持し、再送可能期間内に再試行します。別のタスクに古いキーを流用しないでください。

障害時の動作

リクエストのタイムアウトは 20 秒、全体 240 秒、照会間隔 3 秒です。再試行可能な障害は最大 3 回で、HTTP 日付を含む Retry-After に従います。待機が残りの予算を超える場合は停止します。これはクライアントの設定で処理時間の保証ではありません。

failed/cancelled で終了し、uncertain は照会を続けます。別の送信先に Key を渡さないよう HTTP リダイレクトを拒否します。タスク全文や認証情報は自動記録しません。実運用前に冪等性、エラー処理、API 仕様を確認してください。