Den Solver aus einem Next.js Route Handler aufrufen

• Verwenden Sie Node.js 22+ und das offizielle JavaScript-SDK. Folgen Sie der Installation per Paket-URL in der Dokumentation; gehen Sie nicht davon aus, dass ein Paket in der npm-Registry verfügbar ist.
• Setzen Sie SOLVETHREE_API_KEY, CAPTCHA_SITE, SOLVETHREE_PROXY und INTEGRATION_KEY in der Serverumgebung. Versehen Sie keinen der beiden geheimen Schlüssel mit dem Präfix NEXT_PUBLIC_.
• Aktivieren Sie vor dem Aufruf der Route ein Profil für den Zielhostnamen in Ihrem Workspace. Das Setzen von CAPTCHA_SITE erstellt kein Profil; siehe Websiteprofil einrichten.
• Ersetzen Sie die Aktion login im Beispiel durch die für Ihre Integration erforderliche Aktion. Die Anfrage verwendet einen Proxy und standardmäßig reCAPTCHA Enterprise v3; die Felder type und url sind nicht erforderlich.

Speichern Sie das Beispiel in app/api/captcha/route.js. Es exportiert HTTP-Handler für den App Router und wählt ausdrücklich die Node.js-Laufzeit für das SDK aus. Behalten Sie es als Serverroute bei, die zur Anfragezeit ausgeführt wird, nicht als statisch generierte Ressource.

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 ruft createTask mit waitMs: 0 auf und gibt dadurch die Task-Antwort zurück, ohne auf eine Lösung zu warten. Speichern Sie die zurückgegebene Task-ID. GET benötigt diese vorhandene ID und ruft getTask auf; es erstellt niemals einen Task.

GET fordert eine Wartezeit von bis zu 15 Sekunden an und bricht die Anfrage separat nach 25 Sekunden ab. POST bricht die Anfrage nach 20 Sekunden ab. Diese Grenzen gelten für jede einzelne Anfrage, nicht für die Lebensdauer des Tasks.

Verwenden Sie für den Browserzugriff die tatsächliche serverseitige Authentifizierung Ihrer Anwendung, statt INTEGRATION_KEY zu verteilen. Authentifizierung allein reicht nicht aus: Wenn Sie beliebige Task-IDs von authentifizierten Benutzern akzeptieren, können diese weiterhin die Ergebnisse anderer Benutzer anfordern.

1. 1.

   Erstellung dem Aufrufer zuordnen

   Nachdem ein authentifizierter POST einen Task erstellt hat, speichern Sie dessen ID mit einer Zuordnung zum authentifizierten Benutzer oder Mandanten, bevor Sie sie zurückgeben. Ordnen Sie auch die logische requestId diesem Eigentümer zu, damit die Eigentumszuordnung bei der Wiederherstellung erhalten bleibt.

2. 2.

   Eigentumszuordnung vor dem Abruf prüfen

   Authentifizieren Sie bei GET den Aufrufer und prüfen Sie die übergebene ID anhand dieser Eigentumszuordnung, bevor Sie getTask aufrufen. Weisen Sie IDs zurück, die nicht dem Aufrufer gehören, und geben Sie Ergebnisse erst nach erfolgreicher Prüfung zurück.

Behalten Sie Website, Aktion und Proxy unter serverseitiger Kontrolle, sofern Ihre Anwendung den Aufrufern nicht ausdrücklich erlaubt, diese auszuwählen. Die festen Umgebungswerte in diesem Beispiel verhindern, dass der Client diese Eingaben ändert.

1. 1.

   Tasks ohne Endstatus weiter abfragen

   Rufen Sie bei pending oder solving dieselbe ID erneut ab und beachten Sie dabei die Gesamtfrist Ihrer Anwendung. Eine abgelaufene GET-Wartezeit ist kein Grund, einen weiteren Task zu erstellen.

2. 2.

   Bei ready oder failed aufhören

   Nur ready enthält eine verwendbare Lösung. Beenden Sie bei failed die Abfragen und prüfen Sie errorCode und error; fehlgeschlagene Lösungsversuche werden erstattet. Behandeln Sie nicht erfolgreiche HTTP-Antworten, bevor Sie eine Antwort als Task interpretieren. Der catch-Handler der Route ersetzt nicht die Prüfung des zurückgegebenen Task-Status.

3. 3.

   Erstellung nach einem Verbindungstimeout wiederherstellen

   Wählen und speichern Sie vor POST eine x-request-id. Wenn Sie eine Task-ID erhalten haben, rufen Sie den Task darüber ab. Falls die Antwort auf die Erstellung verloren gegangen ist, wiederholen Sie POST mit derselben Anfrage-ID und unveränderten Task-Eingaben, um den vorhandenen Task wiederherzustellen. Anfrage-IDs erlauben 1–64 ASCII-Buchstaben, Ziffern, Unterstriche oder Bindestriche; die Wiederverwendung einer ID für andere Eingaben führt zu einem Konflikt.

Ein Task mit dem Status ready bedeutet, dass solvethree eine Lösung generiert hat, nicht, dass das Ziel sie akzeptiert hat. Das SDK übermittelt sie nicht für Sie. Verwenden Sie bei der Übermittlung die zurückgegebenen Werte userAgent und secChUa mit dem erfolgreichen Proxy – in diesem Beispiel mit einem einzelnen Proxy also dem konfigurierten Proxy. Wechseln Sie nicht zu einer anderen Browseridentität oder IP.

Ziehen Sie bei Anfragefehlern oder endgültigen Fehlschlägen die API-Fehlerreferenz heran, bevor Sie für einen weiteren Lösungsversuch bezahlen. Unveränderte ungültige Eingaben werden durch erneute Versuche nicht gültig.