如何解决 Queue-it 验证码

简要说明

• 当前的 Queue-it CAPTCHA 集成应作为 BotDeflector 工作流处理，而不是纯文本识别。
• 当您拥有页面 URL、BotDeflector 域名和挑战 flowToken 时，使用 AntiBotdeflectorTaskProxyLess；异步结果通过 solution.token 返回。
• 当视觉挑战提供前景和背景图像时，使用 VisionEngine 与 module: "botdeflector"；此请求直接返回识别坐标。
• websiteURL 和 domain 是 BotDeflector 的独立字段，可能包含不同的主机名。从授权的浏览器会话中捕获两者。
• 在解决过程中保持 Queue-it 浏览器会话打开，因为返回的结果属于生成输入的挑战上下文。
• 仅在您拥有、测试或明确授权自动化的 Queue-it 实现上使用此工作流。

Queue-it 虚拟等待室在流量高峰（如票务发布、产品发布和库存有限的活动）期间控制访问。当前集成中使用的 CAPTCHA 不仅是包含字符的图片：BotDeflector 提供了一个挑战流程，可能需要令牌结果或视觉坐标。

此更新指南通过 CapSolver 说明了两种支持的路径。令牌路径是捕获 flowToken 的默认集成；当浏览器显示对应的前景和背景挑战图像时，使用 VisionEngine 路径。CapSolver 的 CAPTCHA API 文档指南 说明了共享任务生命周期和错误模型。

Queue-it CAPTCHA 流程有何变化？

当前的 Queue-it 工作流应建模为 BotDeflector 而非独立的 OCR 表单。BotDeflector 挑战包含绑定会话的输入，预期输出取决于集成路径：

这些模式不可互换。令牌模式不接受 Base64 图像作为 flowToken 的替代品，而视觉识别模式不返回最终的 BotDeflector 令牌。检查您授权浏览器会话中的挑战实现，并选择与可用数据匹配的路径。

Queue-it 的流量等待室和 CAPTCHA 求解器使用不同的队列。等待室决定访客何时可以继续，而 CapSolver API 处理挑战任务。请求队列术语表 提供了区分应用队列与 API 任务轮询的有用背景。

前提条件

创建任务前请准备以下内容：

• 存储在环境变量或密钥管理器中的 CapSolver API 密钥。
• 您有权测试的 Queue-it 页面和 BotDeflector 挑战。
• 挑战出现的确切页面 URL。
• 对于令牌模式：从同一浏览器会话中捕获的 BotDeflector domain 和当前 flowToken。
• 对于视觉模式：Base64 编码的前景和背景挑战图像。
• 可向 https://api.capsolver.com 发送 JSON 请求的 HTTP 客户端。

不要将生产环境的 API 密钥直接放在源代码中。示例使用 YOUR_API_KEY、FLOW_TOKEN_FROM_PAGE 和示例域作为占位符。

如何在令牌模式下解决 Queue-it BotDeflector

令牌模式使用 AntiBotdeflectorTaskProxyLess，然后轮询 getTaskResult 直到 CapSolver 返回 solution.token。字段名称和响应结构遵循当前 BotDeflector 令牌模式文档。

步骤 1：捕获 BotDeflector 输入

从同一授权浏览器会话中捕获以下值：

• websiteURL：BotDeflector 挑战运行的完整页面 URL。
• domain：该挑战所需的 BotDeflector 域名。
• flowToken：BotDeflector 流暴露的当前挑战令牌。

不要假设 domain 仅仅是 websiteURL 的主机名。官方任务定义将其视为独立输入，它们可能不使用相同的域名。

步骤 2：创建令牌任务

将捕获的值发送到 createTask：

curl --request POST 'https://api.capsolver.com/createTask' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "AntiBotdeflectorTaskProxyLess",
      "websiteURL": "https://queue.example.com/waitingroom/",
      "domain": "challenge.example.net",
      "flowToken": "FLOW_TOKEN_FROM_PAGE"
    }
  }'

成功创建响应包含任务 ID：

{
  "errorId": 0,
  "errorCode": "",
  "errorDescription": "",
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

在存储 taskId 之前检查 errorId。如果任务创建失败，请记录 errorCode 和 errorDescription，而不要记录 API 密钥或完整挑战令牌。

步骤 3：轮询 BotDeflector 令牌

将返回的任务 ID 发送到 getTaskResult：

curl --request POST 'https://api.capsolver.com/getTaskResult' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
  }'

继续轮询直到响应状态为 processing。如果 API 返回非零 errorId 或失败状态，请立即停止。当任务就绪时，从 solution.token 读取令牌：

{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006",
  "status": "ready",
  "solution": {
    "token": "BOTDEFLECTOR_TOKEN"
  }
}

步骤 4：将令牌返回到同一浏览器流程

将返回的令牌传递给同一 Queue-it 浏览器会话使用的 BotDeflector 集成点。在捕获 flowToken 和应用结果之间不要创建新的浏览器上下文。会话更改、导航或挑战刷新可能会使上下文失效，并需要新任务。

确切的注入或提交点属于您正在测试的 Queue-it 实现。从您自己的应用程序集成中捕获它，而不是依赖通用选择器。

领取您的 CapSolver 奖励代码

立即提升您的自动化预算！
在充值 CapSolver 账户时使用奖励代码 CAP26，每次充值可获得额外 5% 奖励——无限制。
现在在您的 CapSolver 仪表板 中领取

令牌模式的完整 Python 示例

以下示例创建一个 BotDeflector 任务，使用有限超时轮询，并返回 solution.token。它使用占位符挑战值，因为真实的 flowToken 必须来自您的授权浏览器会话。

import os
import time

import requests


API_BASE = "https://api.capsolver.com"
API_KEY = os.environ["CAPSOLVER_API_KEY"]


def solve_botdeflector(website_url, domain, flow_token, timeout=120):
    create_response = requests.post(
        f"{API_BASE}/createTask",
        json={
            "clientKey": API_KEY,
            "task": {
                "type": "AntiBotdeflectorTaskProxyLess",
                "websiteURL": website_url,
                "domain": domain,
                "flowToken": flow_token,
            },
        },
        timeout=30,
    )
    create_response.raise_for_status()
    created = create_response.json()

    if created.get("errorId"):
        raise RuntimeError(
            f"createTask failed: {created.get('errorCode')} - "
            f"{created.get('errorDescription')}"
        )

    task_id = created["taskId"]
    deadline = time.monotonic() + timeout

    while time.monotonic() < deadline:
        time.sleep(2)
        result_response = requests.post(
            f"{API_BASE}/getTaskResult",
            json={"clientKey": API_KEY, "taskId": task_id},
            timeout=30,
        )
        result_response.raise_for_status()
        result = result_response.json()

        if result.get("errorId"):
            raise RuntimeError(
                f"getTaskResult failed: {result.get('errorCode')} - "
                f"{result.get('errorDescription')}"
            )

        if result.get("status") == "ready":
            return result["solution"]["token"]

        if result.get("status") == "failed":
            raise RuntimeError("BotDeflector task failed")

    raise TimeoutError(f"BotDeflector task {task_id} 超过 {timeout}s")


token = solve_botdeflector(
    website_url="https://queue.example.com/waitingroom/",
    domain="challenge.example.net",
    flow_token="FLOW_TOKEN_FROM_PAGE",
)
print(token)

有关环境变量、请求处理和可重用客户端结构的更多细节，请参阅 Python CAPTCHA API 集成指南。

何时对 Queue-it BotDeflector 挑战使用 VisionEngine

仅当挑战暴露 BotDeflector 识别模块所需的视觉资源时，才使用 VisionEngine。此路径接受前景 image 和 imageBackground，然后在初始 createTask 响应中返回点击坐标。

此请求使用 type: "VisionEngine" 和 module: "botdeflector"：

curl --request POST 'https://api.capsolver.com/createTask' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "VisionEngine",
      "module": "botdeflector",
      "image": "BASE64_FOREGROUND_IMAGE",
      "imageBackground": "BASE64_BACKGROUND_IMAGE",
      "websiteURL": "https://queue.example.com/waitingroom/"
    }
  }'

根据当前 VisionEngine 文档，此任务直接返回识别数据；不需要单独的 getTaskResult 请求。成功响应的结构如下：

{
  "errorId": 0,
  "errorCode": "",
  "errorDescription": "",
  "status": "ready",
  "solution": {
    "points": [[123, 88], [244, 84], [174, 70]]
  },
  "taskId": "TASK_ID"
}

将返回的点应用到同一坐标空间中的视觉挑战，与提交的图像相同。缩放、裁剪或使用不同尺寸的截图可能会移动目标位置并导致错误交互。

VisionEngine 处理识别步骤；它不替代周围的浏览器状态管理。如果页面需要后续令牌交换，请在同一个授权会话中继续该交换。

常见 Queue-it BotDeflector 集成问题

任务已创建但从未变为就绪状态

确认 flowToken 是当前的，并且属于同一页面会话。同时验证 websiteURL 和 domain 是独立捕获的，而不是从一个主机名构造的。使用有限轮询并在 API 错误时停止，而不是无限循环。

返回的令牌被拒绝

被拒绝的令牌通常表示在捕获挑战输入后页面状态发生了变化。在结果应用之前保持 cookies、浏览器上下文、URL 和挑战状态稳定。如果挑战刷新，请捕获新的 flowToken 并创建新任务。

VisionEngine 返回点但点击失败

发送原始挑战图像而不进行调整，并在相同尺寸上应用坐标。检查浏览器自动化是否引入了设备像素比缩放、CSS 调整或裁剪的截图。

集成在脚本中工作但在 CI 中失败

比较本地和 CI 环境中的浏览器版本、视口设置、时间、cookies 和密钥可用性。对于更广泛的测试清单，请参阅 自动化 QA 中的 CAPTCHA 处理。

负责任的使用

仅在您拥有、运营的 QA 环境或站点所有者明确授权的工作流中使用 Queue-it 和 BotDeflector 自动化。CAPTCHA 求解 API 不授予访问权限或覆盖站点的条款、队列规则、速率限制或授权要求。

保持测试量有限，除非是经过批准的测试，否则避免高需求的公共活动，并仅记录最小的诊断数据。API 密钥、cookies、flowToken 值和返回的令牌应被视为机密，并从截图、分析和长期日志中排除。

结论

现在 Queue-it CAPTCHA 处理需要 BotDeflector 了解的集成。使用 AntiBotdeflectorTaskProxyLess 进行会话令牌流程，并从 solution.token 读取结果；仅当挑战提供用于坐标识别的前景和背景图像时，才使用 VisionEngine 和 botdeflector 模块。

关键实现规则是保留从挑战捕获到结果提交的原始浏览器上下文。对于授权的 Queue-it 测试，CapSolver 通过同一任务 API 提供了两种记录的 BotDeflector 路径。

常见问题

Q: 我应该为 Queue-it BotDeflector 令牌模式使用哪种任务类型？

当您拥有 websiteURL、domain 和当前 flowToken 时，使用 AntiBotdeflectorTaskProxyLess。轮询 getTaskResult 并从 solution.token 中读取完成值。

Q: Queue-it BotDeflector 令牌模式是否需要 CAPTCHA 图像？

不需要。令牌模式任务使用页面 URL、BotDeflector 域名和 flowToken。如果挑战反而暴露了用于视觉识别的前景图像和背景图像，请使用单独的 VisionEngine 路径。

Q: 我何时应使用 VisionEngine botdeflector 模块？

当视觉识别步骤提供 image 和 imageBackground 时，使用 VisionEngine 与 module: "botdeflector"。API 在 createTask 响应中直接返回 solution.points。

Q: 为什么 BotDeflector 域名可能与 Queue-it 页面 URL 不同？

BotDeflector 将 websiteURL 和 domain 定义为独立任务字段，因此挑战服务可能使用与可见的 Queue-it 页面不同的主机名。从活动集成中捕获这两个值。
Q: 我可以将返回的 BotDeflector 令牌用于另一个浏览器会话吗？

不应假设可以重复使用。将令牌应用于生成挑战输入的同一授权浏览器流程；如果页面或挑战刷新，请捕获新的输入并创建新任务。

Q: 是否允许自动处理 Queue-it 验证码？

只有在您拥有系统或已获得明确授权进行测试或自动化时才允许。请遵守网站的条款、访问控制、队列策略、速率限制和适用法律。