קריאה לשירות הפתרון מתוך Route Handler של Next.js

• השתמשו ב-Node.js 22+ וב-SDK הרשמי ל-JavaScript. פעלו לפי הוראות ההתקנה מכתובת 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. היא מייצאת מטפלי HTTP של App Router ובוחרת במפורש בסביבת הריצה Node.js עבור ה-SDK. השאירו אותה כנתיב שרת שמופעל בזמן הבקשה, ולא כמשאב שנוצר באופן סטטי.

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 קורא ל-createTask עם waitMs: 0, ולכן מחזיר את תגובת המשימה בלי להמתין לפתרון. שמרו את מזהה המשימה שהוחזר. GET דורש את המזהה הקיים הזה וקורא ל-getTask; הוא לעולם אינו יוצר משימה.

GET מבקש המתנה של עד 15 שניות, עם ביטול נפרד של הבקשה לאחר 25 שניות. בקשת POST מתבטלת לאחר 20 שניות. המגבלות האלה חלות על כל בקשה, לא על משך חיי המשימה.

לגישה מהדפדפן, השתמשו במנגנון האימות האמיתי של היישום בצד השרת במקום להפיץ את INTEGRATION_KEY. אימות לבדו אינו מספיק: קבלת כל מזהה משימה ממשתמש מאומת עדיין תאפשר לו לבקש תוצאה של מישהו אחר.

1. 1.

   שייכו את היצירה לקורא

   לאחר ש-POST מאומת יוצר משימה, שמרו את המזהה שלה בשיוך למשתמש המאומת או לדייר לפני החזרתה. שייכו גם את requestId הלוגי לאותו בעלים, כדי שרשומת הבעלות לא תאבד במהלך השחזור.

2. 2.

   בדקו בעלות לפני האחזור

   ב-GET, אמתו את הקורא ובדקו את המזהה שסופק מול רשומת הבעלות לפני הקריאה ל-getTask. דחו מזהים שאינם שייכים לקורא, והחזירו תוצאות רק לאחר שהבדיקה הצליחה.

השאירו את האתר, הפעולה והפרוקסי בשליטת השרת, אלא אם היישום שלכם מתיר במפורש לקוראים לבחור אותם. ערכי הסביבה הקבועים שבדוגמה מונעים מהלקוח לשנות את ערכי הקלט האלה.

1. 1.

   המשיכו לתשאל משימות שטרם הגיעו למצב סופי

   במצב pending או solving, אחזרו שוב את אותו מזהה, בכפוף למועד הסיום הכולל שקבעתם ביישום. סיום ההמתנה של GET אינו סיבה ליצור משימה נוספת.

2. 2.

   עצרו במצב ready או failed

   רק ready מכיל פתרון שמיש. במצב failed, הפסיקו לתשאל ובדקו את errorCode ואת error; על פתרונות שנכשלו ניתן החזר. טפלו בתגובות HTTP שאינן מציינות הצלחה לפני פירוש התגובה כמשימה. מטפל ה-catch של הנתיב אינו מחליף את בדיקת סטטוס המשימה שהוחזרה.

3. 3.

   שחזרו יצירה לאחר חריגה מזמן החיבור

   בחרו ושמרו x-request-id לפני POST. אם קיבלתם מזהה משימה, אחזרו אותה. אם תגובת היצירה אבדה, חזרו על POST עם אותו מזהה בקשה ועם קלט משימה ללא שינוי כדי לשחזר את המשימה הקיימת. מזהי בקשות יכולים להכיל 1–64 אותיות ASCII, ספרות, קווים תחתונים או מקפים; שימוש חוזר במזהה עם קלט שונה יוצר התנגשות.

משימה במצב ready מציינת ש-solvethree יצר פתרון, לא שהיעד קיבל אותו. ה-SDK אינו שולח אותו עבורכם. בעת השליחה, השתמשו ב-userAgent וב-secChUa שהוחזרו יחד עם הפרוקסי שהצליח — הפרוקסי המוגדר בדוגמה הזו, המשתמשת בפרוקסי יחיד. אל תעברו לזהות דפדפן או לכתובת IP שאינן קשורות לפתרון.

במקרה של שגיאות בקשה או כשלים סופיים, היעזרו במדריך שגיאות ה-API לפני שתשלמו על פתרון נוסף. ניסיון חוזר עם קלט לא תקין שלא השתנה לא יתקן אותו.