从 Laravel 调用 CAPTCHA API
使用 Laravel 的 HTTP 客户端创建 solvethree 任务，然后按 ID 获取该任务。将 API 密钥和代理凭据保留在服务器上。HTTP 响应成功还不够：使用求解结果前，请先读取任务状态。
本页内容
配置站点和服务器凭据
- 1.
启用站点配置文件
在控制台中设置目标主机名，确保工作区中有已激活的 reCAPTCHA 配置。在任务中发送主机名不会创建配置。请参阅站点配置设置。
- 2.
添加服务器配置
将示例中的
solvethree条目添加到config/services.php的现有数组中。在服务器环境中设置SOLVETHREE_API_KEY、CAPTCHA_SITE和SOLVETHREE_PROXY。不要将这些值放入浏览器代码；CAPTCHA_SITE是主机名，而不是完整 URL。 - 3.
匹配目标操作
示例发送
login。请将其改为预期目标请求所使用的操作。示例提供一个proxy；不要同时发送proxyCandidates。
创建服务，分别提供创建和获取方法
<?php
// app/Services/CaptchaApi.php — configure services.solvethree in config/services.php.
namespace App\Services;
use Illuminate\Support\Facades\Http;
use InvalidArgumentException;
final class CaptchaApi
{
private function client()
{
return Http::baseUrl('https://api.solvethree.com/v1')
->withToken(config('services.solvethree.key'))
->acceptJson()->asJson()->connectTimeout(10)->timeout(25);
}
public function create(string $requestId): array
{
if (!preg_match('/^[A-Za-z0-9_-]{1,64}$/', $requestId)) {
throw new InvalidArgumentException('Invalid logical request ID');
}
// The caller keeps this requestId; do not generate another on a timeout.
return $this->client()->post('/tasks?waitMs=0', [
'site' => config('services.solvethree.site'),
'action' => 'login',
'proxy' => config('services.solvethree.proxy'),
'requestId' => $requestId,
])->throw()->json();
}
public function retrieve(string $taskId): array
{
if (!preg_match('/^[A-Za-z0-9_-]{1,128}$/', $taskId)) {
throw new InvalidArgumentException('Invalid task ID');
}
return $this->client()->get('/tasks/'.rawurlencode($taskId), ['waitMs' => 15000])
->throw()->json();
}
}
// config/services.php entry:
// 'solvethree' => ['key' => env('SOLVETHREE_API_KEY'),
// 'site' => env('CAPTCHA_SITE'), 'proxy' => env('SOLVETHREE_PROXY')],
// Invoke from your authenticated controller/job. Poll retrieve only while pending
// or solving; ready contains the solution, failed is terminal. Never use retry()
// on create without preserving both this ID and the exact original inputs.withToken 将工作区密钥作为 Bearer 身份验证凭据发送。POST 请求体采用扁平结构：site、action、proxy 和 requestId 都是顶层字段。不要为 reCAPTCHA 添加 type 或 url 字段。省略 recaptchaType 时，会使用文档中规定的默认值 enterprise-v3。
两个方法都在 json() 前调用 throw()。Laravel 的 HTTP 客户端默认不会因非成功 HTTP 响应而抛出异常，因此这样可以防止调用者将 HTTP 错误载荷当作成功的任务响应。该服务设置了连接和请求超时，并且有意不自动重试 POST。
保存任务 ID 并检查状态
- 1.
每次逻辑求解只创建一次任务
在经过身份验证的控制器或作业中，调用
create前先保存由调用者生成的requestId。它必须包含 1–64 个 ASCII 字母、数字、下划线或连字符。另行保存返回的任务 ID：逻辑请求 ID 用于恢复创建请求；retrieve接受的是任务 ID。 - 2.
查询现有任务
使用已保存的任务 ID 调用
retrieve。如果状态为pending或solving，请安排稍后再次获取，而不是在控制器中密集循环。为调用者设置总体等待截止时间；服务的 HTTP 超时限制的是每个请求，而不是求解的生命周期。达到该截止时间并不是创建新任务的理由。 - 3.
处理终态结果
对于
failed，停止获取并检查errorCode和error；求解失败会退款。对于ready，使用返回的求解令牌。提交时，使用返回的userAgent和secChUa身份信息，以及求解时使用的同一代理。就绪的求解结果仍需由目标接受。
区分 HTTP 错误与任务失败。非成功 HTTP 响应由 throw() 处理；包含 failed 的成功响应需要在任务层面处理。不要原样重试无效输入，也不要假定每次失败都意味着余额不足。请参阅 API 错误处理。
恢复超时的创建请求，无需再次付费求解
连接超时无法说明 solvethree 是否已创建任务。如果已有任务 ID，则获取该任务。否则，使用相同的 requestId 和完全相同的任务输入再次创建，以恢复现有任务。
运行您的第一个任务。
使用 $5 工作区额度开始体验。