PRODUCT TEST WORKSPACE

Imperva Captcha

Captcha verification product

IMPERVA

01 / CREATE

创建任务

编辑器默认填入必填字段及一组条件字段。可选字段在下方文档列出,也可一键填入。

02 / REQUEST

请求预览

POST /api/validator/create.cgi
{
  "productCode" : "IMPERVA",
  "adapter" : {
    "websiteURL" : "https://example.com/register",
    "incapsulaScriptUrl" : "/_Incapsula_Resource?SWJIYLWA=YOUR_CURRENT_SCRIPT_ID",
    "incapsulaCookies" : "incap_ses_YOUR_ID=YOUR_SESSION_VALUE; visid_incap_YOUR_ID=YOUR_VISITOR_VALUE",
    "proxyType" : "http",
    "proxyAddress" : "YOUR_PROXY_HOST",
    "proxyPort" : 8080
  }
}

03 / RESULT

响应示例

EXAMPLE
Task ID —
{
  "code" : 0,
  "msg" : "操作成功",
  "data" : {
    "taskId" : "11111111-1111-4111-8111-111111111111",
    "productCode" : "IMPERVA",
    "state" : "SUCCEEDED",
    "solution" : {
      "domains" : {
        "https://site-example.com" : {
          "cookies" : {
            "___utmvc" : "EXAMPLE____UTMVC"
          }
        }
      }
    }
  }
}

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

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

04 / API REFERENCE

Imperva Captcha · API

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

Content-Type: application/json
apiKey: YOUR_API_KEY

请求示例

POST /api/validator/create.cgi · JSONC
{
  "productCode": "IMPERVA", // 产品编码,必须与 adapter 参数匹配。
  "adapter": { // 产品专属参数对象。
    "websiteURL": "https://example.com/register", // 实际受 Imperva 保护的完整页面 URL;脚本和 Cookie 必须来自该目标的同一会话。
    "websiteKey": "YOUR_WEBSITEKEY", // 仅兼容历史客户端,Imperva 不使用此字段;site key 不能代替必需的脚本、Cookie 或代理。
    "incapsulaScriptUrl": "/_Incapsula_Resource?SWJIYLWA=YOUR_CURRENT_SCRIPT_ID", // 从当前目标页面或网络请求取得新鲜的 Incapsula 脚本 URL 或路径,保留查询参数,例如 /_Incapsula_Resource?SWJIYLWA=...;不能使用 site key 代替。
    "incapsulaCookies": "incap_ses_YOUR_ID=YOUR_SESSION_VALUE; visid_incap_YOUR_ID=YOUR_VISITOR_VALUE", // 同一次新鲜目标会话的 Cookie 请求头字符串,包含实际签发的 incap_ses_*、visid_incap_* 等值;原样保留,不要复制示例 Cookie。
    "reese84UrlEndpoint": "YOUR_REESE84URLENDPOINT", // 可选,取自目标网络请求中的实际 Reese84 端点,通常以 ?d=目标主机 结尾;不存在时省略,不要猜测。
    "userAgent": "YOUR_BROWSER_USER_AGENT", // 取得该会话时实际使用的 User-Agent;使用结果 Cookie 时保持一致,上游返回 User-Agent 时按其要求使用。
    "proxyType": "http", // 上游必需的代理协议:http、socks4 或 socks5;当前 Imperva 接入没有文档化的免代理模式。
    "proxyAddress": "YOUR_PROXY_HOST", // 可达的代理主机名或 IP,不包含端口或认证信息;采集挑战、处理挑战及后续访问使用同一代理出口。
    "proxyPort": 8080, // 代理 TCP 端口,1 至 65535 的整数;不是 URL 或 host:port 字符串。
    "proxyLogin": "YOUR_PROXYLOGIN", // 该代理需要认证时的用户名,不是 Nex Captcha API Key。
    "proxyPassword": "YOUR_PROXYPASSWORD" // 该代理需要认证时的密码,原样保留认证值。
  }
}

请求头: 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": "IMPERVA", // 产品编码,必须与 adapter 参数匹配。
    "state": "SUCCEEDED", // 任务状态:CREATED、SUBMITTING、PROCESSING、SUCCEEDED、FAILED、EXPIRED。
    "solution": { // SUCCEEDED 时的产品答案;处理中或失败时为空对象。
      "domains": { // 按目标域名分组的验证结果。
        "https://site-example.com": { // 产品返回的答案字段,按目标网站的验证协议使用。
          "cookies": { // 目标域名对应的验证 Cookie。
            "___utmvc": "EXAMPLE____UTMVC" // 产品返回的答案字段,按目标网站的验证协议使用。
          }
        }
      }
    }
  }
}

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

请求参数说明

字段类型必填说明
productCodestring是产品编码,必须与 adapter 参数匹配。
adapterobject是产品专属参数对象。
adapter.websiteURLstring是实际受 Imperva 保护的完整页面 URL;脚本和 Cookie 必须来自该目标的同一会话。
adapter.websiteKeystring否仅兼容历史客户端,Imperva 不使用此字段;site key 不能代替必需的脚本、Cookie 或代理。
adapter.incapsulaScriptUrlstring是从当前目标页面或网络请求取得新鲜的 Incapsula 脚本 URL 或路径,保留查询参数,例如 /_Incapsula_Resource?SWJIYLWA=...;不能使用 site key 代替。
adapter.incapsulaCookiesstring是同一次新鲜目标会话的 Cookie 请求头字符串,包含实际签发的 incap_ses_*、visid_incap_* 等值;原样保留,不要复制示例 Cookie。
adapter.reese84UrlEndpointstring否可选,取自目标网络请求中的实际 Reese84 端点,通常以 ?d=目标主机 结尾;不存在时省略,不要猜测。
adapter.userAgentstring否取得该会话时实际使用的 User-Agent;使用结果 Cookie 时保持一致,上游返回 User-Agent 时按其要求使用。
adapter.proxyTypestring是上游必需的代理协议:http、socks4 或 socks5;当前 Imperva 接入没有文档化的免代理模式。
adapter.proxyAddressstring是可达的代理主机名或 IP,不包含端口或认证信息;采集挑战、处理挑战及后续访问使用同一代理出口。
adapter.proxyPortinteger是代理 TCP 端口,1 至 65535 的整数;不是 URL 或 host:port 字符串。
adapter.proxyLoginstring否该代理需要认证时的用户名,不是 Nex Captcha API Key。
adapter.proxyPasswordstring否该代理需要认证时的密码,原样保留认证值。

响应参数说明

字段类型说明
codeinteger业务返回码,0 表示成功,其他值表示错误。
msgstring结果说明,成功时可能为空。
dataobject | null响应数据,接口报错时可能为 null。
data.taskIdstring创建任务返回的任务 ID。
data.productCodestring产品编码,必须与 adapter 参数匹配。
data.statestring任务状态:CREATED、SUBMITTING、PROCESSING、SUCCEEDED、FAILED、EXPIRED。
data.solutionobjectSUCCEEDED 时的产品答案;处理中或失败时为空对象。
data.failureobject | omitted仅 FAILED 或 EXPIRED 返回的公开诊断,不含上游原始消息;按失败处理指引操作。
data.failure.codestring失败编码
data.failure.nextActionstring下一步
data.solution.domainsobject按目标域名分组的验证结果。
data.solution.domains.https://site-example.comobject产品返回的答案字段,按目标网站的验证协议使用。
data.solution.domains.https://site-example.com.cookiesobject目标域名对应的验证 Cookie。
data.solution.domains.https://site-example.com.cookies.___utmvcstring产品返回的答案字段,按目标网站的验证协议使用。

响应

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

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