PRODUCT TEST WORKSPACE

Friendly Captcha

Captcha verification product

FRIENDLY_CAPTCHA

02 / REQUEST

请求预览

POST /api/validator/create.cgi

{
  "productCode" : "FRIENDLY_CAPTCHA",
  "adapter" : {
    "websiteURL" : "https://example.com/register",
    "websiteKey" : "YOUR_WEBSITEKEY"
  }
}

03 / RESULT

响应示例

EXAMPLE

Task ID —

{
  "code" : 0,
  "msg" : "操作成功",
  "data" : {
    "taskId" : "11111111-1111-4111-8111-111111111111",
    "productCode" : "FRIENDLY_CAPTCHA",
    "state" : "SUCCEEDED",
    "solution" : {
      "token" : "EXAMPLE_TOKEN"
    }
  }
}

响应仅为示例，不是真实任务结果。提交前请替换请求中的所有示例值。

状态为 SUCCEEDED 后读取 data.solution。答案字段因产品而异，其他状态可能返回空对象。

04 / API REFERENCE

Friendly Captcha · API

创建和查询任务时，将 API Key 统一放在 HTTP apiKey 请求头中；JSON 请求体只包含业务参数。

Content-Type: application/json
apiKey: YOUR_API_KEY

结果及使用方法

TOKEN

按本产品的集成方式使用 solution.token，不要填入其他验证码产品字段。遵循目标提交方式，并保持结果中要求的 User-Agent。取得 Token 不代表目标接受验证。

有条件支持的流程

纯 HTTP 提交 HTTP_SUBMIT
浏览器应用识别结果 BROWSER_RESULT

前提条件

优先使用与实际挑战匹配的原生验证码产品，不默认使用通用 GRID。先确认产品及版本并读取模型和指引；目标允许时选 HTTP_SUBMIT，否则在浏览器支持回填原生结果时选 BROWSER_RESULT。页面出现图片网格不代表产品就是 GRID。取得真实参数；缺少参数时报告阻塞，不能猜测。
按目标集成使用原生结果：回填规定的 Token 响应字段或回调；产品返回挑战标识与证明或答案字段时，按契约成组替换或提交。保持目标会话及绑定条件，不混用新旧挑战字段，不仅替换图片，也不假设识别服务能生成任意可移植的验证码与答案。
从同一目标及当前挑战取得新鲜参数。遵守具体产品的域名、动作、挑战或会话、IP、User-Agent 及有效期要求，不假设结果可以通用。返回 Cookie 仅用于对应域名。
示例使用占位值，不是可直接运行的挑战。已说明结果字段不代表目标验证已通过，也不代表完成了实时可用性测试。不要提交未支持的字段。
SUCCEEDED 仅表示已取得识别结果；还需分别确认目标网站接受验证、目标业务操作成功。识别服务无法观察这两个结果。

参数来源

字段	参数来源
`websiteURL`	从实际目标页面、控件配置或接入协议读取，确认具体产品与版本；不能替换为占位值或其他网站的 key。
`websiteKey`	从实际目标页面、控件配置或接入协议读取，确认具体产品与版本；不能替换为占位值或其他网站的 key。
`version`	从实际目标页面、控件配置或接入协议读取，确认具体产品与版本；不能替换为占位值或其他网站的 key。
`moduleScript`	从当前目标挑战、会话或其接入协议读取新鲜值，不复用示例或其他挑战的值。
`nomoduleScript`	从当前目标挑战、会话或其接入协议读取新鲜值，不复用示例或其他挑战的值。

请求示例

POST /api/validator/create.cgi · JSONC

{
  "productCode": "FRIENDLY_CAPTCHA", // 产品编码，必须与 adapter 参数匹配。
  "adapter": { // 产品专属参数对象。
    "websiteURL": "https://example.com/register", // 目标网站完整 URL。
    "websiteKey": "YOUR_WEBSITEKEY", // 目标站点的 CAPTCHA site key。
    "version": "YOUR_VERSION", // Friendly Captcha 版本。
    "moduleScript": "YOUR_MODULESCRIPT", // Friendly Captcha module 脚本地址。
    "nomoduleScript": "YOUR_NOMODULESCRIPT" // Friendly Captcha nomodule 脚本地址。
  }
}

请求头: apiKey: YOUR_API_KEY

注释用于说明字段，复制后得到不含注释的标准 JSON。

响应示例

POST /api/validator/query.cgi · JSONC

{
  "code": 0, // 业务返回码，0 表示成功，其他值表示错误。
  "msg": "操作成功", // 结果说明，成功时可能为空。
  "data": { // 响应数据，接口报错时可能为 null。
    "taskId": "11111111-1111-4111-8111-111111111111", // 创建任务返回的任务 ID。
    "productCode": "FRIENDLY_CAPTCHA", // 产品编码，必须与 adapter 参数匹配。
    "state": "SUCCEEDED", // 任务状态：CREATED、SUBMITTING、PROCESSING、SUCCEEDED、FAILED、EXPIRED。
    "solution": { // SUCCEEDED 时的产品答案；处理中或失败时为空对象。
      "token": "EXAMPLE_TOKEN" // 提交到目标网站的验证令牌。
    }
  }
}

创建任务返回任务 ID 和初始状态。下方为查询接口的完成结果，也可通过 WebSocket 接收答案。

请求参数说明

字段	类型	必填	说明
`productCode`	string	是	产品编码，必须与 adapter 参数匹配。
`adapter`	object	是	产品专属参数对象。
`adapter.websiteURL`	string	是	目标网站完整 URL。
`adapter.websiteKey`	string	是	目标站点的 CAPTCHA site key。
`adapter.version`	string	否	Friendly Captcha 版本。
`adapter.moduleScript`	string	否	Friendly Captcha module 脚本地址。
`adapter.nomoduleScript`	string	否	Friendly Captcha nomodule 脚本地址。

响应参数说明

字段	类型	说明
`code`	integer	业务返回码，0 表示成功，其他值表示错误。
`msg`	string	结果说明，成功时可能为空。
`data`	object \| null	响应数据，接口报错时可能为 null。
`data.taskId`	string	创建任务返回的任务 ID。
`data.productCode`	string	产品编码，必须与 adapter 参数匹配。
`data.state`	string	任务状态：CREATED、SUBMITTING、PROCESSING、SUCCEEDED、FAILED、EXPIRED。
`data.solution`	object	SUCCEEDED 时的产品答案；处理中或失败时为空对象。
`data.failure`	object \| omitted	仅 FAILED 或 EXPIRED 返回的公开诊断，不含上游原始消息；按失败处理指引操作。
`data.failure.code`	string	失败编码
`data.failure.nextAction`	string	下一步
`data.solution.token`	string	提交到目标网站的验证令牌。

响应

HTTP 业务响应包含 code、msg 和 data；code 为 0 表示成功。WebSocket 使用独立的消息结构。

-1317: API Key 无效。
-1100 / -1101: 请求参数错误或缺失。
-1401: 余额不足，请充值后再创建任务
-1400 / -1001: 系统或创建任务错误。

API文档