PRODUCT TEST WORKSPACE
reCAPTCHA Enterprise
Captcha verification product
RECAPTCHA_ENTERPRISE02 / REQUEST
請求預覽
POST /api/validator/create.cgi
{
"productCode" : "RECAPTCHA_ENTERPRISE",
"adapter" : {
"websiteURL" : "https://example.com/register",
"websiteKey" : "YOUR_WEBSITEKEY"
}
}
03 / RESULT
響應示例
Task ID
—
{
"code" : 0,
"msg" : "操作成功",
"data" : {
"taskId" : "11111111-1111-4111-8111-111111111111",
"productCode" : "RECAPTCHA_ENTERPRISE",
"state" : "SUCCEEDED",
"solution" : {
"gRecaptchaResponse" : "EXAMPLE_GRECAPTCHARESPONSE",
"token" : "EXAMPLE_TOKEN"
}
}
}
響應僅爲示例,不是真實任務結果。提交前請替換請求中的所有示例值。
狀態爲 SUCCEEDED 後讀取 data.solution。答案字段因產品而異,其他狀態可能返回空對象。
04 / API REFERENCE
reCAPTCHA Enterprise · API
建立與查詢任務時,將 API Key 統一放在 HTTP apiKey 請求標頭中;JSON 請求本文只包含業務參數。
Content-Type: application/json apiKey: YOUR_API_KEY
請求示例
{
"productCode": "RECAPTCHA_ENTERPRISE", // 產品編碼,必須與 adapter 參數匹配。
"adapter": { // 產品專屬參數對象。
"websiteURL": "https://example.com/register", // 從實際目標頁面、控件設定或接入協定讀取,確認具體產品與版本;不能替換為佔位值或其他網站的 key。
"websiteKey": "YOUR_WEBSITEKEY", // 從實際目標頁面、控件設定或接入協定讀取,確認具體產品與版本;不能替換為佔位值或其他網站的 key。
"pageAction": "YOUR_PAGEACTION", // 取自目標 execute 設定的實際 v3 動作。v2 為歷史相容保留此欄位,但它不能替代 data-s 或 enterprisePayload.s,也不能用於選擇產品版本。
"apiDomain": "YOUR_APIDOMAIN", // 從實際目標頁面、控件設定或接入協定讀取,確認具體產品與版本;不能替換為佔位值或其他網站的 key。
"isEnterprise": false, // RECAPTCHA_V3_ENTERPRISE 上游標記始終為 true,舊請求傳 false 也不會降級;RECAPTCHA_V3 保持原有選填標記行為。Enterprise 控件應選明確的 v2 Enterprise 產品,此標記不能補足會話參數。
"minScore": 0.3, // 根據實際題目及產品欄位含義設定。這些是識別選項,不能隨意猜測來修復失敗請求。
"userAgent": "YOUR_BROWSER_USER_AGENT", // 讀取取得目前挑戰時實際使用的 User-Agent;產品要求一致時保持不變。
"appId": "YOUR_APPID", // 從實際目標頁面、控件設定或接入協定讀取,確認具體產品與版本;不能替換為佔位值或其他網站的 key。
"isInvisible": false, // 從實際目標頁面、控件設定或接入協定讀取,確認具體產品與版本;不能替換為佔位值或其他網站的 key。
"cookies": "challenge_cookie=CURRENT_VALUE", // v2/v2 Enterprise 可選的目前挑戰 Cookie 請求標頭字串,格式為 key=value; key2=value2,取自對應目標上下文;不需要時省略。v3 不公開此欄位。
"proxyType": "http", // v2/v2 Enterprise 可選代理協定:http、socks4 或 socks5。提供任一代理欄位時,proxyType、proxyAddress、proxyPort 必須齊全;全部省略保留無代理模式。目前 v3 沒有已確認的代理任務。
"proxyAddress": "YOUR_PROXY_HOST", // 可達的代理主機名稱或 IP,不含協定、連接埠及認證資訊。目標要求 IP 綁定時,識別端與目標瀏覽器必須使用相同的實際出口;僅為瀏覽器設定代理並不足夠。
"proxyPort": 8080, // 代理 TCP 連接埠,1 至 65535 的整數;僅在提供代理參數時必填。
"proxyLogin": "YOUR_PROXYLOGIN", // 呼叫方已設定代理的可選認證使用者名稱,不要編造憑證。
"proxyPassword": "YOUR_PROXYPASSWORD", // 同一個已設定代理的可選認證密碼。
"enterprisePayload": { // 目前 grecaptcha.enterprise.render 設定的可選附加 JSON 物件,存在 s 字串時一併攜帶,保持與挑戰匹配。Enterprise v2 不使用 recaptchaDataSValue;此欄位不是已確認的 v3 參數。
"s": "CURRENT_ENTERPRISE_S_VALUE"
}
}
}
請求標頭: apiKey: YOUR_API_KEY
註解用於說明欄位,複製後取得不含註解的標準 JSON。
響應示例
{
"code": 0, // 業務回傳碼,0 表示成功,其他值表示錯誤。
"msg": "操作成功", // 結果說明,成功時可能為空。
"data": { // 回應資料,介面報錯時可能為 null。
"taskId": "11111111-1111-4111-8111-111111111111", // 創建任務返回的任務 ID。
"productCode": "RECAPTCHA_ENTERPRISE", // 產品編碼,必須與 adapter 參數匹配。
"state": "SUCCEEDED", // 任務狀態:CREATED、SUBMITTING、PROCESSING、SUCCEEDED、FAILED、EXPIRED。
"solution": { // SUCCEEDED 時的產品答案;處理中或失敗時為空物件。
"gRecaptchaResponse": "EXAMPLE_GRECAPTCHARESPONSE", // 提交至目標網站的驗證權杖。
"token": "EXAMPLE_TOKEN" // 提交至目標網站的驗證權杖。
}
}
}
建立任務會回傳任務 ID 和初始狀態。下方為查詢介面的完成結果,也可透過 WebSocket 接收答案。
請求參數說明
| 字段 | 類型 | 必填 | 說明 |
|---|---|---|---|
productCode | string | 是 | 產品編碼,必須與 adapter 參數匹配。 |
adapter | object | 是 | 產品專屬參數對象。 |
adapter.websiteURL | string | 是 | 從實際目標頁面、控件設定或接入協定讀取,確認具體產品與版本;不能替換為佔位值或其他網站的 key。 |
adapter.websiteKey | string | 是 | 從實際目標頁面、控件設定或接入協定讀取,確認具體產品與版本;不能替換為佔位值或其他網站的 key。 |
adapter.pageAction | string | 否 | 取自目標 execute 設定的實際 v3 動作。v2 為歷史相容保留此欄位,但它不能替代 data-s 或 enterprisePayload.s,也不能用於選擇產品版本。 |
adapter.apiDomain | string | 否 | 從實際目標頁面、控件設定或接入協定讀取,確認具體產品與版本;不能替換為佔位值或其他網站的 key。 |
adapter.isEnterprise | boolean | 否 | RECAPTCHA_V3_ENTERPRISE 上游標記始終為 true,舊請求傳 false 也不會降級;RECAPTCHA_V3 保持原有選填標記行為。Enterprise 控件應選明確的 v2 Enterprise 產品,此標記不能補足會話參數。 |
adapter.minScore | number | 否 | 根據實際題目及產品欄位含義設定。這些是識別選項,不能隨意猜測來修復失敗請求。 |
adapter.userAgent | string | 否 | 讀取取得目前挑戰時實際使用的 User-Agent;產品要求一致時保持不變。 |
adapter.appId | string | 否 | 從實際目標頁面、控件設定或接入協定讀取,確認具體產品與版本;不能替換為佔位值或其他網站的 key。 |
adapter.isInvisible | boolean | 否 | 從實際目標頁面、控件設定或接入協定讀取,確認具體產品與版本;不能替換為佔位值或其他網站的 key。 |
adapter.cookies | string | 否 | v2/v2 Enterprise 可選的目前挑戰 Cookie 請求標頭字串,格式為 key=value; key2=value2,取自對應目標上下文;不需要時省略。v3 不公開此欄位。 |
adapter.proxyType | string | 否 | v2/v2 Enterprise 可選代理協定:http、socks4 或 socks5。提供任一代理欄位時,proxyType、proxyAddress、proxyPort 必須齊全;全部省略保留無代理模式。目前 v3 沒有已確認的代理任務。 |
adapter.proxyAddress | string | 否 | 可達的代理主機名稱或 IP,不含協定、連接埠及認證資訊。目標要求 IP 綁定時,識別端與目標瀏覽器必須使用相同的實際出口;僅為瀏覽器設定代理並不足夠。 |
adapter.proxyPort | integer | 否 | 代理 TCP 連接埠,1 至 65535 的整數;僅在提供代理參數時必填。 |
adapter.proxyLogin | string | 否 | 呼叫方已設定代理的可選認證使用者名稱,不要編造憑證。 |
adapter.proxyPassword | string | 否 | 同一個已設定代理的可選認證密碼。 |
adapter.enterprisePayload | object | 否 | 目前 grecaptcha.enterprise.render 設定的可選附加 JSON 物件,存在 s 字串時一併攜帶,保持與挑戰匹配。Enterprise v2 不使用 recaptchaDataSValue;此欄位不是已確認的 v3 參數。 |
回應參數說明
| 字段 | 類型 | 說明 |
|---|---|---|
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.gRecaptchaResponse | string | 提交至目標網站的驗證權杖。 |
data.solution.token | string | 提交至目標網站的驗證權杖。 |
響應
HTTP 業務響應包含 code、msg 和 data;code 爲 0 表示成功。WebSocket 使用獨立的消息結構。
- -1317
- API Key 無效。
- -1100 / -1101
- 請求參數錯誤或缺失。
- -1401
- 餘額不足,請儲值後再建立任務
- -1400 / -1001
- 系統或創建任務錯誤。