Cloudflare Turnstile API 接入：授权测试完整流程

提交 websiteURL 和 websiteKey，保存 taskId 并轮询响应 Token；了解前置条件及与官方测试 Key 的区别。

适用于授权自动化测试、风控 QA 与浏览器集成。请仅在有权测试的站点和业务流程中使用。

这个接入流程做什么

将有权测试的页面 URL 与组件 sitekey 提交到 SolveHub 任务 API，保存返回的 taskId，持续查询同一任务，并且只在 status=completed 时读取 solution.value。

这是付费第三方接入，不会签发 Cloudflare 官方的虚拟测试 Token。如果只需在自有页面测试 Turnstile 组件，无需解题服务时可使用 Cloudflare 官方测试 Key。

前置条件

注册并验证邮箱。控制台开放自助服务时，可开通账户取得首把 Key；否则绑定 SolveHub 提供的 Key。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}。完成后读取 solution.value，不能仅凭 HTTP 200 判定完成。failed 和 cancelled 结束流程；uncertain 继续核对原任务。客户端截止时间到达不会取消任务，也不会释放预占金额。

按自有应用支持的流程使用结果，并保留应用服务端验证。不要把 SolveHub Key 放进浏览器 JavaScript。Turnstile 字段文档说明可选 cdata、action 与代理参数。

常见失败原因

错误的 websiteKey 或 URL 会造成上下文不一致。仅在组件实际提供时填写 cdata/action。在本地排查 API 错误码与请求编号。402 检查余额；429 降低并发；503 在有限重试预算内用相同键与请求体重试。

下一步

使用 Python 客户端或 Node.js 客户端。并发测试前阅读安全轮询，并查看实时价格。