Scarnox · Blog

Captcha-Solver-API: so funktioniert sie und so rufen Sie sie auf

Eine Captcha-Solver-API ist ein Webdienst, den Sie per HTTP aufrufen. Sie senden die Angaben zu einem Captcha, also den Aufgabentyp, den Sitekey der Seite und die Seiten-URL, und sie gibt ein Token zurück, das die Zielwebsite als Nachweis akzeptiert, dass die Challenge bestanden wurde. Der Scarnox-Endpunkt funktioniert so und ist synchron, eine Anfrage liefert Ihnen also die Antwort.

Dieser Leitfaden behandelt die Anfrage, die Antwort, das Fehlerformat und die Details, die darüber entscheiden, ob eine Integration im Produktivbetrieb hält. Wenn Sie zuerst ein lauffähiges Skript wollen, beginnen Sie mit PopularCaptcha in Python lösen.

Was die API tut und was nicht

Ihr Code findet das Captcha auf einer Seite, liest seinen Sitekey aus und sendet ihn an den Solver. Der Solver gibt ein Token zurück. Ihr Code schreibt dieses Token in das Formularfeld, das die Website erwartet, und sendet das Formular ab.

Der Solver lädt Ihre Seite nicht, klickt nichts an und sendet Ihr Formular nicht ab. Er erzeugt nur das Token. Diese Grenze im Kopf zu behalten, macht den Rest der Integration leichter nachvollziehbar: Alles, was Ihre Sitzung, Cookies und das Anfrage-Timing betrifft, bleibt in Ihrem Code.

Heute ist der einzige Live-Aufgabentyp PopularCaptcha, proxyless, also PopularCaptchaTaskProxyless. Andere Captcha-Typen sind in Planung. Der Leitfaden Captcha-Typen erklärt zeigt, welcher was ist.

Der Endpunkt

Senden Sie eine POST-Anfrage an:

POST https://api.scarnox.com/api/tasks/create
Authorization: Bearer scarnox_YOURAPIKEY
Content-Type: application/json

Der Body beschreibt die Aufgabe:

{
  "captcha_type": "PopularCaptchaTaskProxyless",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "site_url": "https://example.com/signup"
}

Die drei Pflichtfelder sind:

Es gibt drei optionale Felder. proxy nimmt einen Wert im Format http://user:pass@host:port entgegen und wird mit den Proxy-Aufgabentypen verwendet. rqdata und is_invisible sind für bestimmte Widget-Varianten gedacht. Die vollständige Liste der Aufgabentypen und Felddetails steht in der API-Referenz.

Synchron heißt: kein Polling

Der Aufruf blockiert, bis das Token bereit ist. Sie fragen nicht wiederholt ab, und in diesem Ablauf gibt es keine zweite Anfrage "Ergebnis abrufen". Setzen Sie das Timeout Ihres HTTP-Clients auf etwa 185 Sekunden, damit eine langsame Lösung nicht wie ein Netzwerkfehler aussieht.

In Python mit der Bibliothek requests sieht das so aus:

import requests

r = requests.post(
    "https://api.scarnox.com/api/tasks/create",
    headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
    json={
        "captcha_type": "PopularCaptchaTaskProxyless",
        "site_key": "10000000-ffff-ffff-ffff-000000000001",
        "site_url": "https://example.com/signup",
    },
    timeout=185,
)
data = r.json()

Lesen Sie den Schlüssel aus einer Umgebungsvariable, statt ihn in das Skript zu schreiben. Wer den Quellcode lesen kann, sollte Ihr Guthaben nicht nutzen können.

Die Antwort lesen

Eine erfolgreiche Lösung liefert ein errorId von 0, das Token innerhalb von solution und ein Feld cost:

{"errorId": 0, "solution": {"token": "..."}, "cost": ...}

Eine fehlgeschlagene Lösung liefert ein errorId ungleich 0, dazu einen maschinenlesbaren errorCode und eine für Menschen lesbare errorDescription:

{"errorId": 1, "errorCode": "...", "errorDescription": "..."}

Prüfen Sie errorId im Body bei jedem Aufruf. Gehen Sie nicht davon aus, dass eine abgeschlossene HTTP-Anfrage bedeutet, dass Sie ein Token haben. Die wichtigste Regel ist diese: Sie werden nur berechnet, wenn errorId gleich 0 ist. Fehlgeschlagene Lösungen sind kostenlos. Die aktuellen Tarife finden Sie auf der Preisseite.

Lebensdauer des Tokens

PopularCaptcha-Tokens laufen innerhalb von etwa zwei Minuten ab. Reichen Sie das Token ab, sobald Sie es erhalten. Speichern Sie Tokens nicht zur späteren Verwendung zwischen und lösen Sie nicht vor dem Absenden des Formulars im Voraus. Wenn Ihr Code zwischen dem Erhalt des Tokens und dem Absenden des Formulars mehrere Schritte ausführt, verschieben Sie die Lösung auf den letzten Moment.

Das Token ins Formular bringen

Die meisten Websites lesen die Antwort von PopularCaptcha aus einem Formularfeld namens h-captcha-response. Viele akzeptieren außerdem g-recaptcha-response mit demselben Wert, daher ist es eine übliche und sichere Wahl, beides zu senden:

requests.post("https://example.com/signup", data={
    "email": "you@example.com",
    "h-captcha-response": token,
    "g-recaptcha-response": token,
})

Akzeptiert das Formular das Token nicht, liegt die Ursache meist an einem Sitekey oder einer Seiten-URL, die nicht zu der Seite passen, auf der das Widget tatsächlich war. Prüfen Sie die Werte noch einmal, bevor Sie dem Solver die Schuld geben.

Fehlerbehandlung

Eine Produktivintegration braucht einige feste Gewohnheiten:

Der Leitfaden Wiederholungen und Fehlerbehandlung für Captcha-Solver geht auf jeden dieser Punkte genauer ein.

Erste Schritte

Erstellen Sie ein Konto und starten Sie mit einer kostenlosen Testphase, ganz ohne Karte. Führen Sie dann die obige Anfrage gegen eine Testseite aus, die Ihnen gehört, und prüfen Sie, dass das Formular das Token akzeptiert, bevor Sie es mit etwas Wichtigem verbinden.

Nächste Schritte