在 Express 中使用 CAPTCHA 求解器

使用 Node.js 22 或更高版本以及 Express 5。请按照文档中的 tarball 安装方式安装官方 JavaScript SDK，不要假定它已发布到 npm 注册表。示例在处理函数之外创建一个 Solvethree 客户端。

• SOLVETHREE_API_KEY：你的工作区 API 密钥。请将其保留在服务器端。
• INTEGRATION_KEY：供受信任的内部调用方使用的独立密钥。示例要求通过 x-integration-key 请求头传入它；不要将其分发给浏览器客户端。如果已有身份验证中间件，请使用它，而不是示例中的共享密钥校验。
• CAPTCHA_SITE：目标主机名，而非完整 URL。创建任务前，请为工作区设置已激活的站点配置；发送主机名不会创建配置。
• SOLVETHREE_PROXY：用于此目标的代理。示例提供单个代理，并将操作固定为 login。如果目标使用其他操作，请在服务器端修改。

此请求使用默认的 reCAPTCHA Enterprise 配置。它需要 site、action 和代理，而不是 type 或 url。如果尚未配置目标，请参阅站点配置设置。

// npm install express and the official solvethree SDK tarball.
import express from 'express';
import { Solvethree, SolvethreeError } from '@solvethree/sdk';
const app = express();
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const secret = process.env.INTEGRATION_KEY;
if (!secret) throw new Error('Set INTEGRATION_KEY');
app.use((request, response, next) => {
  if (request.get('x-integration-key') !== secret) return response.sendStatus(401);
  next();
});
app.post('/captcha/tasks', async (request, response) => {
  const task = await client.createTask({
    site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
    requestId: request.get('x-request-id'),
  }, { waitMs: 0, signal: AbortSignal.timeout(20000) });
  response.json(task);
});
app.get('/captcha/tasks/:id', async (request, response) => {
  response.json(await client.getTask(request.params.id, { waitMs: 15000, signal: AbortSignal.timeout(25000) }));
});
app.use((error, request, response, next) => {
  if (error instanceof SolvethreeError) return response.status(502).json({ requestId: error.requestId, taskId: error.taskId });
  response.status(400).json({ error: 'Invalid task input or ID' });
});
app.listen(3000);

两个路由都受身份验证校验保护。POST 处理函数从服务器配置而非请求体读取主机名、操作和代理。只有可选的创建标识符来自调用方。

1. 1.

   创建前分配请求 ID

   发送包含 1–64 个 ASCII 字母、数字、下划线或连字符的 x-request-id。将其与逻辑请求一并保存，以便在连接超时时恢复创建的任务。

2. 2.

   向 /captcha/tasks 发送一次 POST

   处理函数使用 waitMs: 0 调用 createTask 并返回任务。请保存其 ID。成功响应表示已有任务，但不一定已有解决方案。

3. 3.

   使用 GET 获取状态

   调用 /captcha/tasks/:id。状态为 pending 或 solving 时继续获取；不要通过重复发送 POST 来检查进度。状态为 ready 或 failed 时停止。

4. 4.

   仅使用已就绪的解决方案

   使用同一配置的代理和预期目标，将令牌与返回的 userAgent 和 secChUa 一起提交。SDK 不会代你提交。任务就绪表示已生成解决方案，而不表示目标已接受你的应用请求。

POST SDK 调用通过 AbortSignal 设置 20 秒时限。GET 在 25 秒的 SDK 调用时限内允许等待任务 15 秒。GET 响应仍可能处于非终态；请检查其状态，不要将等待结束视为求解失败。

创建超时并不能证明 solvethree 拒绝了请求。如果收到了任务 ID，请获取该任务。否则，使用相同的请求 ID 和未更改的任务输入重新创建，以恢复已有任务。将该 ID 用于不同输入会产生冲突。如果未保留请求 ID，新的 POST 可能会创建独立任务。

Express 5 会将异步处理函数中被拒绝的 Promise 转交给错误处理中间件。示例针对 SolvethreeError 返回 HTTP 502，仅提供其请求和任务标识符，而不暴露原始错误、凭据或解决方案。其兜底 HTTP 400 是通用响应；它不会精确区分所有非 SDK 错误，包括超时错误。

读取成功载荷前，请先处理 HTTP 错误。另外，获取到的任务可能处于 failed 状态：请检查其 errorCode 和 error，然后停止轮询。求解失败会退款，但原样重试无效输入并不能解决问题。请使用 API 错误参考诊断报告的失败。