Captcha Ruler

Appearance

API 规范 ​

业务方代理服务需要代理 captcha-async 异步打码的两个接口，以及业务验证结果反馈接口。代理层负责 Bearer Token 认证，并将请求转发到 Captcha Ruler 中转服务。

认证映射 ​

业务侧请求携带 Authorization: Bearer <api-key>，代理服务验证后将其映射为中转服务所需的 header：

业务侧中转服务
Authorization: Bearer <api-key>env-kit + x-product-name

代理服务根据 token 查找对应的 env-kit 和 x-product-name 值，替换到转发请求的 header 中。

接口一：提交验证码破解任务（异步） ​

提交验证码信息后立即返回 task_id，不等待结果。

请求 ​

POST /api/v1/captcha/create
Authorization: Bearer <api-key>
Content-Type: application/json
json
{
  "captcha_type": "reCAPTCHA_V2",
  "mode": "token",
  "page_url": "https://example.com",
  "provider": "auto",
  "captcha_param": {
    "site_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  },
  "proxy": {
    "scheme": "http",
    "host": "1.2.3.4",
    "port": "8080",
    "username": "user",
    "password": "pass"
  },
  "user_agent": "Mozilla/5.0 ..."
}

请求体字段说明：

字段类型必填说明
captcha_typestring是验证码类型：reCAPTCHA_V2 / reCAPTCHA_V3 / hCaptcha / Turnstile / FunCaptcha / DataDome
modestring是打码模式：token / recognition
page_urlstring是目标网站 URL
providerstring否指定服务商：auto / 2captcha / nopecha，默认 auto
captcha_paramobject是验证码参数（因类型而异，见下方）
proxyobject否代理配置（DataDome 类型必填）
user_agentstring否浏览器 User-Agent

响应 ​

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "task_id": "INT-20260320-A1B2C3D4"
  },
  "time": "2026-06-11T10:00:00Z"
}

接口二：查询异步打码任务结果 ​

根据 task_id 查询打码结果。若任务仍在处理中，会实时向第三方查询当前状态。

请求 ​

GET /api/v1/captcha/result/{task_id}
Authorization: Bearer <api-key>

响应 ​

业务方代理返回给扩展 / SDK的统一格式如下。

中转服务原始响应与转换 ​

业务方直接代理接口 GET /api/v1/captcha/result/{task_id} 。

打码处理中（data.status: "processing"，无 result）：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "task_id": "2072247499519004672",
    "provider": "nopecha",
    "provider_task_id": "t97tkq4km4...",
    "status": "processing"
  },
  "time": "2026-07-01 09:14:39"
}

成功解码（data.status: "success"，data.result.token 非空）：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "task_id": "2072247499519004672",
    "provider": "nopecha",
    "provider_task_id": "t97tkq4km4...",
    "status": "success",
    "result": {
      "token": "P1_eyJhbGciOiJI..."
    }
  },
  "time": "2026-07-01 09:15:12"
}

接口三：提交业务验证结果反馈 ​

业务端使用打码结果后，回传真实验证结果用于统计通过率和向平台申请退款。

请求 ​

POST /api/v1/captcha/feedback
Authorization: Bearer <api-key>
Content-Type: application/json
json
{
  "task_id": "INT-20260320-A1B2C3D4",
  "is_business_success": true
}
字段类型必填说明
task_idstring是任务 ID
is_business_successboolean是业务验证是否成功

响应 ​

json
{
  "code": 0,
  "msg": "success",
  "data": null,
  "time": "2026-06-11T10:01:00Z"
}

统一响应格式 ​

所有接口响应均为以下结构：

json
{
  "code": 0,
  "msg": "string",
  "data": {},
  "time": "ISO 8601 时间戳"
}
字段说明
code0 成功，非 0 失败
msg状态说明
data响应数据（失败时为 null）
time服务端时间戳

错误处理 ​

代理层自身的错误（认证失败、限流等）使用标准 HTTP 状态码：

状态码含义
401Token 无效或缺失
403无权限访问
429请求过于频繁

中转服务返回的 HTTP 错误码含义：

状态码含义
400请求格式错误
404任务不存在
422参数校验失败
502打码失败或超时

中转服务返回的错误直接透传给业务侧。

Copyright © 2026