Scarnox · Blog

Captcha-solver-API: hoe hij werkt en hoe je hem aanroept

Een captcha-solver-API is een webdienst die je via HTTP aanroept. Je stuurt de details van een captcha, dat zijn het tasktype, de sitekey van de pagina en de URL van de pagina, en hij geeft een token terug dat de doelsite accepteert als bewijs dat de uitdaging is gehaald. Het Scarnox-eindpunt werkt zo en het is synchroon, dus één verzoek geeft je het antwoord.

Deze gids behandelt het verzoek, de respons, de foutstructuur en de details die bepalen of een integratie in productie standhoudt. Als je eerst een uitvoerbaar script wilt, begin dan met PopularCaptcha oplossen in Python.

Wat de API wel en niet doet

Je code vindt de captcha op een pagina, leest de sitekey en stuurt die naar de solver. De solver geeft een token terug. Je code schrijft dat token in het formulierveld dat de site verwacht en dient het formulier in.

De solver laadt je pagina niet, klikt nergens op en dient je formulier niet in. Hij produceert alleen het token. Als je die grens in gedachten houdt, is de rest van de integratie makkelijker te doorgronden: alles over je sessie, cookies en timing van verzoeken blijft in je eigen code.

Vandaag is het enige live tasktype PopularCaptcha, zonder proxy, dat is PopularCaptchaTaskProxyless. Andere captchatypen staan op de routekaart. De gids over captchatypen laat zien welke welke is.

Het eindpunt

Stuur een POST-verzoek naar:

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

De body beschrijft de taak:

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

De drie verplichte velden zijn:

captcha_type: het tasktype. Voor live oplossingen vandaag is dit PopularCaptchaTaskProxyless.
site_key: de sitekey die van de pagina is gelezen. PopularCaptcha-sitekeys zijn UUID's.
site_url: de URL van de pagina waar de captcha verschijnt. Gebruik de echte pagina, niet de homepage, omdat het token is gebonden aan de pagina die de widget toonde.

Er bestaan drie optionele velden. proxy neemt een waarde in de vorm http://user:pass@host:port en wordt gebruikt met de proxy-tasktypes. rqdata en is_invisible zijn voor specifieke widgetvarianten. De volledige lijst met tasktypes en velddetails staat in de API-referentie.

Synchroon betekent geen polling

De aanroep blokkeert totdat het token klaar is. Je hoeft niet te pollen, en er is in deze flow geen tweede "resultaat ophalen"-verzoek. Zet de time-out van je HTTP-client op ongeveer 185 seconden, zodat een trage oplossing niet op een netwerkfout lijkt.

In Python met de bibliotheek requests ziet dat er zo uit:

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()

Lees de sleutel uit een omgevingsvariabele in plaats van hem in het script te zetten. Iedereen die de broncode kan lezen, mag je saldo niet kunnen gebruiken.

De respons lezen

Een geslaagde oplossing geeft een errorId van 0, het token binnen solution, en een veld cost:

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

Een mislukte oplossing geeft een errorId die niet 0 is, plus een machineleesbare errorCode en een voor mensen leesbare errorDescription:

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

Controleer bij elke aanroep errorId in de body. Ga er niet van uit dat een voltooid HTTP-verzoek betekent dat je een token hebt. De belangrijkste regel is deze: je betaalt alleen wanneer errorId 0 is. Mislukte oplossingen zijn gratis. Voor actuele tarieven zie de prijzenpagina.

Levensduur van het token

PopularCaptcha-tokens verlopen binnen ongeveer twee minuten. Dien het token in zodra je het ontvangt. Sla tokens niet op voor later gebruik, en los niet vooraf op voordat het formulier wordt ingediend. Als je code verschillende stappen uitvoert tussen het ophalen van het token en het posten van het formulier, verplaats de oplossing dan naar het laatste moment.

Het token in het formulier zetten

De meeste sites lezen het PopularCaptcha-antwoord uit een formulierveld dat h-captcha-response heet. Veel sites accepteren ook g-recaptcha-response met dezelfde waarde, dus beide meesturen is een veelgebruikte veilige keuze:

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

Als het formulier het token niet accepteert, ligt de oorzaak meestal in een sitekey of paginaURL die niet overeenkomt met de pagina waarop de widget echt stond. Controleer de waarden dubbel voordat je de solver de schuld geeft.

Foutafhandeling

Een productie-integratie heeft een korte lijst gewoontes nodig:

Controleer errorId en log errorCode elke keer. De code is wat de support eerst zal vragen.
Probeer mislukte oplossingen opnieuw met een kleine backoff. Omdat mislukte oplossingen gratis zijn, kost een nieuwe poging je geen oplossing, maar een strakke lus verspilt nog steeds tijd en kan je eigen snelheidslimieten raken.
Zet de client-time-out op ongeveer 185 seconden, en behandel een time-out als fout om opnieuw te proberen, niet als succes.
Houd het token en het verzenden van het formulier dicht bij elkaar in de tijd, want het token verloopt snel.

De gids over opnieuw proberen en foutafhandeling gaat dieper in op elk van deze punten.

Aan de slag

Maak een account aan en je kunt beginnen met gratis proefcredit, zonder creditcard. Voer daarna het verzoek hierboven uit tegen een testpagina die je beheert, en controleer dat het formulier het token accepteert voordat je het aan iets belangrijks koppelt.