Cloudflare Turnstile API 導入：許可されたテストの手順

websiteURL と websiteKey を送信し、taskId を保存してトークンを取得。前提条件と公式テストキーとの違いを説明します。

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

この連携の役割

テスト権限のあるページ URL とコンポーネントの sitekey を SolveHub のタスク API に送信します。返された taskId を保存し、同じタスクを照会して status=completed のときだけ solution.value を読み取ります。

これは有料のサードパーティ連携であり、Cloudflare 公式のダミーテストトークンを発行する機能ではありません。自社の Turnstile ウィジェット自体のテストなら、必要に応じて Cloudflare 公式テストキーを使用できます。

前提条件

登録してメールを認証します。コンソールでセルフサービスが利用できる場合は有効化して最初の Key を取得し、それ以外は SolveHub 発行の Key を紐付けます。tasks 権限、有効期限、利用可能残高を確認します。送信前に GET /v1/prices を照会してください。有効な種類でも直ちに処理枠があるとは限りません。

最小リクエスト

task.json に権限のあるテスト環境の値を設定します。

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

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H "Authorization: Bearer $SOLVEHUB_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: authorized-test-0001' \
  --data-binary @task.json

成功時は HTTP 202 と taskId が返ります。キー、元の本文、taskId を保存します。新しい論理テストには新しいキーを使い、同じリクエストの再送ではキーを維持してください。

結果の照会と利用

2〜3 秒ごとに GET /v1/tasks/{taskId} を照会します。HTTP 200 だけで完了と判断せず、完了状態で solution.value を読み取ります。failed と cancelled は終了状態です。uncertain は同じタスクの確認を続けます。クライアントの期限切れはタスクの取消や予約額の解放を意味しません。

管理下のアプリが提供するフローで結果を利用し、アプリ側のサーバー検証を行います。SolveHub Key をブラウザー JavaScript に渡さないでください。任意の cdata、action、プロキシ設定は Turnstile 仕様を参照してください。

よくある失敗

websiteKey や URL の誤りはコンテキストの不一致につながります。cdata/action はコンポーネントから渡された場合のみ送信します。エラーとリクエスト ID をローカルで調査し、402 は残高、429 は並列数を確認します。503 は回数制限を設け、同じキーと本文で再送します。

次のステップ

Python または Node.js のクライアントを使えます。並列実行前に安全なポーリングを読み、料金を確認してください。