将 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 密钥。将该密钥保留在服务端；不要将 clientKey 带入新的 JSON 请求体。

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

此示例是 Enterprise 请求，因为它保留了 recaptchaType 的默认值。如果目标使用标准 v3，请显式选择标准 v3；不要将所有 CapSolver 任务类型都映射到默认的 Enterprise。

CapSolver ProxyLess 任务在这里没有直接对应的无代理模式：solvethree 要求调用方提供代理输入。如果当前集成不管理代理，就需要修改集成，而不仅仅是重命名字段。也不要将 SOCKS 代理配置复制到新请求中；solvethree 接受 HTTP 和 HTTPS 代理 URL。

先使用单个代理，以明确求解和提交所用的路由。如果改用 proxyCandidates，请提供最多十二个不同的 HTTP 或 HTTPS 代理 URL，且不含路径、查询参数或片段。候选代理允许服务尝试其他出口，但不保证代理或目标可用。

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，检查 errorCode 和 error，并停止轮询该任务。求解失败会退款。不要盲目地用未修改的无效输入重试，也不要认为每次失败都意味着余额不足。

分阶段迁移期间，为每个任务 ID 标记其提供商。通过 CapSolver 完成现有 CapSolver 任务，并通过 solvethree 处理新的 solvethree 任务。在适配器中统一两者的结果，而不是将旧提供商的任务 ID 发送到新 API。

向预期目标提交 reCAPTCHA 结果时，使用 solution.token。同时保留返回的 userAgent 和 secChUa，并使用求解成功时使用的代理进行提交。如果现有适配器仅返回令牌字符串，请修改它，将这些信息一直传递给提交客户端。

如果就绪令牌被拒绝，请先检查发出的应用请求，再付费进行另一次求解。确认请求包含的是新令牌，而不是任务 ID 或旧令牌，并且提交时使用了返回的浏览器身份、求解成功时使用的代理和预期的目标 URL。ready 任务表示已生成解决结果，并不代表目标接受了你的后续请求。

迁移后的示例包含用于恢复的 requestId。为每个新的逻辑任务生成一个值，并将它与完全一致的请求输入一起保存。它必须包含 1–64 个 ASCII 字母、数字、下划线或连字符。使用相同的任务请求重复使用它会返回现有任务；使用不同输入则会产生冲突。

如果创建超时，已有任务 ID 时就查询该任务，否则使用相同的 requestId 重新提交相同的请求体。响应丢失并不能证明创建失败。不要仅仅因为客户端停止等待就生成新 ID。

客户端超时应涵盖 reCAPTCHA 默认最长 15 秒的创建等待时间以及网络开销。GET 轮询默认不等待即返回，并接受最大为 15000 的 waitMs。将 waitMs 放在 URL 查询参数中，而不是任务 JSON 中，并在轮询超时中同样留出该等待时间。