Next.js Route Handler से सॉल्वर को कॉल करें

• Node.js 22+ और आधिकारिक JavaScript SDK इस्तेमाल करें। दस्तावेज़ में दिए पैकेज-URL से इंस्टॉल करने के निर्देशों का पालन करें; यह न मानें कि npm रजिस्ट्री पैकेज उपलब्ध है।
• सर्वर एनवायरनमेंट में SOLVETHREE_API_KEY, CAPTCHA_SITE, SOLVETHREE_PROXY और INTEGRATION_KEY सेट करें। किसी भी सीक्रेट के नाम में NEXT_PUBLIC_ प्रीफ़िक्स न लगाएँ।
• रूट कॉल करने से पहले अपने वर्कस्पेस में लक्षित होस्टनाम के लिए प्रोफ़ाइल सक्रिय करें। CAPTCHA_SITE सेट करने से प्रोफ़ाइल नहीं बनती; साइट प्रोफ़ाइल सेटअप देखें।
• उदाहरण के login ऐक्शन की जगह अपने इंटीग्रेशन के लिए आवश्यक ऐक्शन रखें। अनुरोध एक प्रॉक्सी इस्तेमाल करता है और डिफ़ॉल्ट रूप से reCAPTCHA Enterprise v3 चुनता है; इसमें type या url फ़ील्ड की ज़रूरत नहीं है।

उदाहरण को app/api/captcha/route.js में रखें। यह App Router HTTP हैंडलर एक्सपोर्ट करता है और SDK के लिए स्पष्ट रूप से Node.js रनटाइम चुनता है। इसे अनुरोध के समय चलने वाला सर्वर रूट ही रखें, स्टैटिक रूप से जनरेट किया गया रिसोर्स नहीं।

import { Solvethree, SolvethreeError } from '@solvethree/sdk';
export const runtime = 'nodejs';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
function authorized(request) {
  const key = process.env.INTEGRATION_KEY;
  return Boolean(key) && request.headers.get('x-integration-key') === key;
}
function failure(error) {
  return error instanceof SolvethreeError
    ? Response.json({ requestId: error.requestId, taskId: error.taskId }, { status: 502 })
    : Response.json({ error: 'Invalid task input or ID' }, { status: 400 });
}
export async function POST(request) {
  if (!authorized(request)) return new Response('Unauthorized', { status: 401 });
  try {
    return Response.json(await client.createTask({
      site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
      requestId: request.headers.get('x-request-id') ?? undefined,
    }, { waitMs: 0, signal: AbortSignal.timeout(20000) }));
  } catch (error) { return failure(error); }
}
export async function GET(request) {
  if (!authorized(request)) return new Response('Unauthorized', { status: 401 });
  const id = new URL(request.url).searchParams.get('id');
  if (!id) return Response.json({ error: 'Provide id' }, { status: 400 });
  try {
    return Response.json(await client.getTask(id, { waitMs: 15000, signal: AbortSignal.timeout(25000) }));
  } catch (error) { return failure(error); }
}

POST, waitMs: 0 के साथ createTask कॉल करता है, इसलिए यह समाधान की प्रतीक्षा किए बिना टास्क का रिस्पॉन्स लौटा देता है। लौटाया गया टास्क ID सहेजें। GET के लिए वही मौजूदा ID आवश्यक है और वह getTask कॉल करता है; वह कभी टास्क नहीं बनाता।

GET अधिकतम 15 सेकंड की प्रतीक्षा का अनुरोध करता है और अनुरोध को बंद करने की अलग सीमा 25 सेकंड है। POST अनुरोध को बंद करने की सीमा 20 सेकंड है। ये सीमाएँ हर अनुरोध पर लागू होती हैं, टास्क के पूरे जीवनकाल पर नहीं।

ब्राउज़र से ऐक्सेस के लिए INTEGRATION_KEY वितरित करने के बजाय अपने ऐप्लिकेशन का वास्तविक सर्वर-साइड प्रमाणीकरण इस्तेमाल करें। केवल प्रमाणीकरण पर्याप्त नहीं है: प्रमाणित उपयोगकर्ता से कोई भी टास्क ID स्वीकार करने पर वह अब भी किसी और का परिणाम माँग सकता है।

1. 1.

   टास्क बनाते समय उसे कॉल करने वाले से जोड़ें

   प्रमाणित POST से टास्क बनने के बाद उसका ID लौटाने से पहले उसे प्रमाणित उपयोगकर्ता या टेनेंट के साथ सहेजें। लॉजिकल requestId को भी उसी स्वामी से जोड़ें, ताकि रिकवरी के दौरान स्वामित्व का रिकॉर्ड न खोए।

2. 2.

   प्राप्त करने से पहले स्वामित्व जाँचें

   GET पर कॉल करने वाले को प्रमाणित करें और getTask कॉल करने से पहले दिए गए ID को स्वामित्व के उस रिकॉर्ड से मिलाएँ। जिन ID का स्वामी कॉल करने वाला नहीं है, उन्हें अस्वीकार करें और जाँच सफल होने के बाद ही परिणाम लौटाएँ।

साइट, ऐक्शन और प्रॉक्सी को सर्वर के नियंत्रण में रखें, जब तक आपका ऐप्लिकेशन स्पष्ट रूप से कॉल करने वालों को इन्हें चुनने की अनुमति न देता हो। इस उदाहरण के निश्चित एनवायरनमेंट मान क्लाइंट को ये इनपुट बदलने से रोकते हैं।

1. 1.

   अंतिम स्थिति तक न पहुँचे टास्क को पोल करते रहें

   pending या solving के लिए अपने ऐप्लिकेशन की कुल समय-सीमा के भीतर उसी ID को फिर से प्राप्त करें। GET की प्रतीक्षा पूरी होना नया टास्क बनाने का कारण नहीं है।

2. 2.

   ready या failed पर रुकें

   केवल ready में उपयोग करने योग्य समाधान होता है। failed पर पोलिंग रोकें और errorCode तथा error जाँचें; असफल समाधानों की राशि वापस कर दी जाती है। किसी रिस्पॉन्स को टास्क मानने से पहले असफल HTTP रिस्पॉन्स संभालें। रूट का catch हैंडलर लौटाए गए टास्क की स्थिति जाँचने का विकल्प नहीं है।

3. 3.

   कनेक्शन टाइमआउट के बाद टास्क बनाने के अनुरोध की रिकवरी करें

   POST से पहले x-request-id चुनें और सहेजें। यदि आपको टास्क ID मिल गया था, तो उसे प्राप्त करें। यदि टास्क बनाने का रिस्पॉन्स खो गया था, तो मौजूदा टास्क की रिकवरी के लिए उसी अनुरोध ID और बिना बदले टास्क इनपुट के साथ POST दोहराएँ। अनुरोध ID में 1–64 ASCII अक्षर, अंक, अंडरस्कोर या हाइफ़न हो सकते हैं; अलग इनपुट के लिए उसी ID को दोबारा इस्तेमाल करने पर कॉन्फ़्लिक्ट होता है।

ready टास्क का अर्थ है कि solvethree ने समाधान जनरेट किया है, यह नहीं कि लक्ष्य ने उसे स्वीकार कर लिया है। SDK उसे आपकी ओर से सबमिट नहीं करता। सबमिट करते समय लौटाए गए userAgent और secChUa के साथ सफल प्रॉक्सी इस्तेमाल करें—इस एकल-प्रॉक्सी उदाहरण में कॉन्फ़िगर की गई प्रॉक्सी। किसी असंबंधित ब्राउज़र पहचान या IP पर स्विच न करें।

अनुरोध की त्रुटियों या अंतिम विफलताओं के लिए किसी और समाधान का भुगतान करने से पहले API त्रुटि संदर्भ देखें। अमान्य इनपुट को बिना बदले दोबारा भेजने से वे ठीक नहीं होंगे।