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文件