Node.js में hCaptcha Enterprise कैसे हल करें (capskip SDK)

Node.js में hCaptcha Enterprise हल करने के लिए साइट से नया rqdata लें और उसे sitekey तथा पेज URL के साथ capskip पैकेज के hcaptcha() method को data option के रूप में दें। method टास्क को CapSkip तक भेजता है, token तैयार होने तक poll करता है और उसे लौटा देता है। फिर token को नतीजे के User-Agent के साथ फ़ॉर्म पर post करें। CapSkip के दस्तावेज़ कहते हैं कि साइट हर rqdata एक चैलेंज के लिए जारी करती है और वह जल्दी expire हो जाता है, इसलिए हर टास्क को, और हर retry को, नया rqdata चाहिए। नीचे का कोड आपके अपने Windows PC पर चल रहे CapSkip hCaptcha सॉल्वर से बात करता है, और प्रति-हल कोई शुल्क नहीं लगता।

आपको क्या चाहिए

• CapSkip वर्ज़न 4.0.0 या उससे ऊपर, आपकी Windows मशीन पर इंस्टॉल। उस रिलीज़ में hCaptcha हल करने की सुविधा जुड़ी, Enterprise समेत, यहाँ इस्तेमाल हुए in.php फ़ॉर्मैट और createTask JSON फ़ॉर्मैट, दोनों में।
• Node.js 18 या बाद का और capskip पैकेज, वर्ज़न 1.6.0 या उसके बाद का, जिसमें पहली बार hcaptcha method आया। पैकेज Node.js 18 को अपनी न्यूनतम सीमा बताता है और उसकी अपनी कोई dependencies नहीं हैं, और form post में built-in fetch इस्तेमाल होता है। मैंने कोड सिर्फ़ 20.11.1, 24.22.0 और 25.2.1 पर चलाया।
• ऐसी साइट जो आपकी अपनी हो या जिसे ऑटोमेट करने की आपको अनुमति हो और जिस पर hCaptcha widget दिखता हो, और उस widget का sitekey।
• script से CapSkip तक पहुँचने का एक रास्ता। Local mode में CapSkip 127.0.0.1 पर रहता है और सिर्फ़ उसी डिवाइस से पहुँचा जा सकता है। Server mode में वह आपके नेटवर्क या पब्लिक IP पर भी सुनता है, इसलिए Windows VPS, किसी दूसरे PC या hosted platform पर चल रही script भी उसे इस्तेमाल कर सकती है, और इसके लिए CapSkip का administrator के रूप में चलना ज़रूरी है। इसे यहाँ चुनें: कनेक्शन सेटिंग्स.

स्थिति: मैंने कोड capskip 1.6.0 के साथ अपने बनाए दो mock सर्वर के सामने चलाया, एक CapSkip की जगह और एक ऐसी Enterprise साइट की जगह जो हर rqdata को एक ही बार स्वीकार करती है। वे नियम मेरे हैं, CapSkip दस्तावेज़ों और पैकेज के source से लिए गए। मैंने hCaptcha के जिन public दस्तावेज़ पेजों को पढ़ा, उनमें से किसी में rqdata का वर्णन नहीं है, इसलिए यहाँ rqdata के बारे में हर तथ्य CapSkip दस्तावेज़ों से आता है। कोई असली हल नहीं हुआ, इसलिए मैं नहीं बता सकता कि एक हल में कितना समय लगता है या कोई असली Enterprise साइट कैसे व्यवहार करती है।

चरण 1: sitekey, invisible flag और rqdata ढूँढें

एक खाली folder में npm install capskip चलाएँ। फिर चरण 1 से 4 के ब्लॉक उसी folder की hcaptcha-demo.js नाम की एक फ़ाइल में, दिखाए गए क्रम में कॉपी करें। चरण 4 तक कुछ नहीं चलता, जब तक आप चरण 2 के अंत में test line न जोड़ दें। recaptchaTimeout option hCaptcha के लिए SDK की poll सीमा है, सेकंड में। उसका डिफ़ॉल्ट 300 है, और छोटा 120 मैंने खुद चुना।

// npm install capskip
const { CapSkip, ApiException } = require("capskip");

const CAPSKIP = { host: "127.0.0.1", port: 8080 }; // Local mode; Server mode: your server
const SITE = "https://www.example.com"; // a site you may automate
const PAGE_URL = `${SITE}/login`; // the page the hCaptcha widget is on
// The SDK's default key. Use your own if API Key Validation is on in CapSkip.
const API_KEY = "capskip";
const PROXY = null; // for example "203.0.113.10:8080"; null means no proxy

const solver = new CapSkip({
  ...CAPSKIP,
  apiKey: API_KEY,
  recaptchaTimeout: 120, // poll limit in seconds for hCaptcha; the default is 300
});

sitekey आम तौर पर widget के container पर data-sitekey के रूप में होता है। जब कोई script widget बनाती है, तो hcaptcha.render() का sitekey option देखें, या hCaptcha iframe के पते में sitekey= parameter देखें। hCaptcha invisible widget गाइड बताती है कि invisible widget पर data-size का मान invisible होता है, और CapSkip के दस्तावेज़ कहते हैं कि ऐसे widget के लिए invisible=1 भेजें।

rqdata सबसे अलग चीज़ है। CapSkip के दस्तावेज़ कहते हैं कि कुछ Enterprise साइटें widget चलने से पहले hcaptcha.setData() के ज़रिए उसे rqdata मान देती हैं, और अगर पेज ऐसा करता है तो आप वह मान data के रूप में भेजते हैं। अगर नहीं करता, तो data फ़ील्ड न भेजें। वह मान कहाँ से आता है, यह साइट की मर्ज़ी है। वह पेज के HTML में हो सकता है या पेज की किसी रिक्वेस्ट के जवाब में आ सकता है, इसलिए पेज की scripts में उस call को खोजें जो उसे सेट करती है और string का पीछा करें। मैंने इसे किसी असली Enterprise साइट पर नहीं आज़माया, और नीचे की function वह रास्ता इस्तेमाल करती है जो मेरा mock देता है।

// Ask the site for a new challenge. The route and the field names are the
// site's choice; these are the ones in my test mock, so adapt them.
// If the sitekey is fixed in the page, return it as a constant here.
// If the site puts the values in the page HTML, fetch PAGE_URL and
// extract them here instead.
async function getChallenge() {
  const resp = await fetch(`${SITE}/api/challenge`);
  if (!resp.ok) throw new Error(`challenge failed: HTTP ${resp.status}`);
  const { sitekey, rqdata, invisible } = await resp.json();
  return { sitekey, rqdata, invisible: Boolean(invisible) };
}

चरण 2: टास्क सबमिट करें और token लें

एक call टास्क सबमिट करती है और नतीजे के लिए poll करती है। hcaptcha() method sitekey, पेज URL और एक options object लेता है: data rqdata है, invisible widget के लिए invisible true होता है और proxy हल के लिए proxy है। SDK इन्हें method=hcaptcha के साथ form fields के रूप में /in.php को भेजता है, और invisible को 1 के रूप में भेजता है। वह कोई userAgent option नहीं भेजता: दस्तावेज़ कहते हैं कि CapSkip उस option का इस्तेमाल तभी करता है जब वह उस ब्राउज़र से मेल खाता हो जिससे वह हल करता है, और नतीजे में वह User-Agent होता है जिसके साथ token मिला।

async function solve({ sitekey, rqdata, invisible }) {
  const options = {};
  // The Enterprise rqdata, fresh for this task. Skip it if the site has none.
  if (rqdata) options.data = rqdata;
  if (invisible) options.invisible = true; // data-size is invisible
  if (PROXY) options.proxy = PROXY;
  // Submits the task, polls until the token is ready, and returns the result.
  return solver.hcaptcha(sitekey, PAGE_URL, options);
}

SDK आपके लिए /res.php को poll करता है। पहला poll तुरंत जाता है, और उसके बाद का इंतज़ार चौथाई सेकंड से शुरू होता है, हर बार दोगुना होता है और 5 सेकंड पर बढ़ना रोक देता है। खाली body को तैयार नहीं गिना जाता: दस्तावेज़ कहते हैं कि इसका मतलब है कि नतीजा पहले ही पढ़ा जा चुका है या ID मौजूद नहीं है, और SDK का source जोड़ता है कि CapSkip submit के ठीक बाद एक भेजता है। सीमा पार होने पर call TimeoutException फेंकती है।

नतीजा एक बार ही दिया जाता है, और SDK उसे पूरा आपके लिए रख लेता है। code और token फ़ील्ड में एक ही string होती है। respKey वह दूसरा मान है जो hCaptcha token के साथ widget को देता है। दस्तावेज़ों के अनुसार ज़्यादातर साइटें उसे कभी नहीं पढ़तीं, और CapSkip के कुछ न भेजने पर SDK उसे खाली string पर सेट कर देता है। जिस User-Agent के साथ token मिला, उसके लिए userAgent पढ़ें।

चरण 1 और 2 को अकेले आज़माने के लिए आख़िरी पंक्ति के रूप में getChallenge().then(solve).then(console.log) जोड़ें और node hcaptcha-demo.js चलाएँ। आपको captchaId, code, userAgent, respKey और token वाला object दिखना चाहिए। अगला ब्लॉक जोड़ने से पहले उस पंक्ति को फिर हटा दें।

चरण 3: token को फ़ॉर्म तक पहुँचाएँ

ब्राउज़र का widget खुद दो छिपे textarea फ़ील्ड भरता है, h-captcha-response और उसकी प्रतिलिपि g-recaptcha-response। script के पास widget नहीं होता, इसलिए वह उन्हें फ़ॉर्म फ़ील्ड के रूप में भेजती है। CapSkip के दस्तावेज़ों के अनुसार इसका मतलब है: h-captcha-response हमेशा, g-recaptcha-response तब जब फ़ॉर्म में वह फ़ील्ड भी हो, और जवाब वाला User-Agent। नीचे का फ़ॉर्म एक स्थानापन्न है, क्योंकि आपकी साइट के अपने फ़ील्ड और अपना रास्ता हैं।

token एक ही बार चलते हैं, और CapSkip के दस्तावेज़ कहते हैं कि वे जारी होने के करीब दो मिनट बाद expire हो जाते हैं। hCaptcha के अपने दस्तावेज़ expired-input-response error के डिफ़ॉल्ट के रूप में 120 सेकंड बताते हैं। इसलिए पहले से हल न करें, और tokens का कोई pool न रखें। हर फ़ॉर्म सबमिशन के लिए हल करें, फिर post करें।

async function postForm(solved) {
  const form = new URLSearchParams({
    username: "demo", // the form's own fields
    "h-captcha-response": solved.token,
    // delete the next line if the form has no g-recaptcha-response field
    "g-recaptcha-response": solved.token,
  });
  // Send the User-Agent the reply names, not Node's default one.
  return fetch(PAGE_URL, {
    method: "POST",
    headers: { "User-Agent": solved.userAgent },
    body: form,
  });
}

चरण 4: हर कोशिश पर नए rqdata के साथ पूरा उदाहरण

आख़िरी ब्लॉक सब कुछ एक retry loop में जोड़ता है। इसे hcaptcha-demo.js के अंत में जोड़ें और node hcaptcha-demo.js से चलाएँ। हर कोशिश सबसे पहले getChallenge को call करती है, इसलिए हर टास्क के साथ अभी-अभी जारी किया गया rqdata जाता है। loop सिर्फ़ ERROR_CAPTCHA_UNSOLVABLE पर retry करता है, यानी उस टास्क के code पर जो हल नहीं हो सका। CapSkip के दस्तावेज़ दो ऐसी नाकामियों का नाम लेते हैं जिन्हें दोबारा भेजने पर वही नतीजा आता: poll पर ERROR_RECAPTCHA_INVALID_SITEKEY, जिसका मतलब है कि hCaptcha ने उस पेज के लिए sitekey ठुकरा दिया, और ERROR_PROXY_CONNECT_REFUSED। loop इन्हें, और बाकी हर error को, बिना बदले फिर से उठा देता है।

loop तब भी फिर चलता है जब साइट 200 से 299 के बाहर जवाब दे, क्योंकि ठुकराए गए token का मतलब पुराना rqdata हो सकता है। 403 के और कारण भी हो सकते हैं, जैसे login फ़ॉर्म में गलत password, इसलिए कोशिशें तीन पर रुक जाती हैं।

// ERROR_CAPTCHA_UNSOLVABLE is the one failure where a new task can help.
async function login() {
  for (let attempt = 1; attempt <= 3; attempt += 1) {
    const challenge = await getChallenge(); // a new rqdata for every attempt
    try {
      const solved = await solve(challenge);
      const resp = await postForm(solved);
      if (resp.ok) return resp;
      console.log(`attempt ${attempt}: the site answered HTTP ${resp.status}`);
    } catch (err) {
      // The message is the text of the app's reply: a bare code or small JSON.
      const unsolvable = err instanceof ApiException
        && err.message.includes("ERROR_CAPTCHA_UNSOLVABLE");
      if (!unsolvable) throw err;
      console.log(`attempt ${attempt}: ERROR_CAPTCHA_UNSOLVABLE`);
    }
  }
  throw new Error("hCaptcha not passed in 3 attempts");
}

login()
  .then(async (resp) => console.log(resp.status, await resp.text()))
  .catch((err) => {
    console.error(`${err.name}: ${err.message}`);
    if (err.cause) console.error(err.cause.code); // for example ECONNREFUSED
    process.exitCode = 1;
  });

SDK अपनी तीन नाकामियाँ जोड़ता है। ValidationException का मतलब है कि उसने call को कुछ भेजने से पहले ही ठुकरा दिया: खाली sitekey, ऐसा पेज URL जो absolute http या https नहीं है, गलत invisible मान, या ऐसा option जो CapSkip का hCaptcha API नहीं लेता, जैसे 2Captcha का domain। submit पर NetworkException का मतलब है कि CapSkip के पते पर किसी ने जवाब नहीं दिया, और TimeoutException का मतलब है कि poll की सीमा पार हो गई। नया टास्क इनमें से किसी को नहीं बदलता, इसलिए loop इन्हें फिर से फेंक देता है। ApiException के संदेश में app का जवाब text के रूप में होता है, इसलिए loop उसे includes() से मिलाता है।

mock के सामने script ने यह किया, Node.js 24.22.0 पर capskip 1.6.0 के साथ। Node.js 20.11.1 और 25.2.1 ने हर मामले को उन्हीं exit codes के साथ उसी तरह खत्म किया। harness ने सिर्फ़ पते बदले, और timeout वाली पंक्तियों में poll की सीमा।

आम errors

Proxies और Server mode

CapSkip hCaptcha के लिए proxy को ज़बरदस्ती नहीं लगाता। दस्तावेज़ कहते हैं कि टेस्टिंग और कभी-कभार के हल के लिए एक ही पता ठीक है, लेकिन hCaptcha उस नेटवर्क को भी स्कोर करता है जिससे token आता है, सिर्फ़ ब्राउज़र को नहीं, और एक ही IP से हलों की लगातार धारा वही चीज़ है जिसे पकड़ने के लिए उसकी rate limits बनी हैं। ज़्यादा मात्रा में app में Settings, Captcha types, hCaptcha, Configure Proxies के तहत proxy pool कॉन्फ़िगर करें। किसी ख़ास नेटवर्क से हल कराने के लिए टास्क के साथ proxy भेजें, जो PROXY सेटिंग करती है। टास्क के साथ भेजा गया proxy हमेशा list पर प्राथमिकता पाता है। CapSkip proxy को IP:PORT, LOGIN:PASSWORD@IP:PORT या IP:PORT:LOGIN:PASSWORD के रूप में स्वीकार करता है। अकेली proxy string proxytype HTTP के साथ जाती है। SOCKS5 के लिए proxy को ऐसे object के रूप में दें जिसमें type हो, जो HTTP, HTTPS, SOCKS5 या SOCKS5H लेता है, और uri हो। mock के सामने वह in.php पर proxytype SOCKS5 के रूप में पहुँचा। मैंने असली SOCKS5 हल नहीं आज़माया।

यह सेटिंग सिर्फ़ हल को बदलती है। सख़्त साइट के लिए दस्तावेज़ यह भी कहते हैं कि फ़ॉर्म उसी पते से सबमिट करें, लेकिन Node.js का built-in fetch हर रिक्वेस्ट के लिए proxy option नहीं देता, इसलिए यहाँ form post उसी PC से निकलता है जिस पर script चल रही है। मैंने proxy के ज़रिए form post नहीं आज़माया।

Server mode सिर्फ़ यह बदलता है कि सॉल्वर कहाँ बैठा है। CAPSKIP सेटिंग को server पर पॉइंट करें, तो script का बाकी हिस्सा जैसा है वैसा रहता है। Server mode के लिए CapSkip को administrator के रूप में चलाना ज़रूरी है, और स्थिर पब्लिक IP सबसे स्थिर रिमोट एक्सेस देता है। सॉल्वर तब भी आपका अपना हार्डवेयर है, बिना प्रति-हल शुल्क के। CapSkip तब हर पते से कनेक्शन स्वीकार करता है, इसलिए जिन्हें उस तक नहीं पहुँचना चाहिए उनके लिए Windows Firewall का block rule जोड़ें, और CapSkip में API Key Validation चालू करके API_KEY भरें। हल अब Windows VPS पर चलता है, इसलिए hCaptcha को उस मशीन का नेटवर्क दिखता है, या वह proxy जो आप देते हैं।

FAQ

चाहे साइट आपके सामने कुछ भी रखे, Node.js में hCaptcha Enterprise हल करना एक ही loop रहता है: नया rqdata, नया टास्क, और तुरंत post किया गया token। इसे अपनी खुद की Windows मशीन पर चल रहे कैप्चा सॉल्वर से चलाने का मतलब है कि हर retry पर प्रति-हल कोई शुल्क नहीं लगता। Node.js की और टूलिंग के लिए देखें: Node.js कैप्चा सॉल्वर पेज, और हर parameter की जानकारी यहाँ है: API दस्तावेज़ों का hCaptcha सेक्शन.