Scarnox · Blog

API solvera captcha: jak działa i jak je wywołać

API solvera captcha to usługa webowa, którą wywołujesz przez HTTP. Wysyłasz jej szczegóły captcha, czyli typ zadania, sitekey strony i adres strony, a ona zwraca token, który docelowa strona akceptuje jako dowód, że wyzwanie zostało pokonane. Endpoint Scarnox działa w ten sposób i jest synchroniczny, więc jedno żądanie daje odpowiedź.

Ten przewodnik omawia żądanie, odpowiedź, format błędów oraz szczegóły, które decydują o tym, czy integracja wytrzyma na produkcji. Jeśli najpierw chcesz gotowy skrypt, zacznij od jak rozwiązać PopularCaptcha w Pythonie.

Co API robi, a czego nie robi

Twój kod znajduje captcha na stronie, odczytuje jego sitekey i wysyła go do solvera. Solver zwraca token. Twój kod wpisuje ten token w pole formularza, którego oczekuje strona, i wysyła formularz.

Solver nie ładuje Twojej strony, niczego nie klika i nie wysyła formularza. Produkuje wyłącznie token. Pamiętanie o tej granicy ułatwia rozumowanie o reszcie integracji: wszystko, co dotyczy sesji, ciasteczek i czasu żądań, pozostaje w Twoim kodzie.

Obecnie jedynym działającym typem zadania jest PopularCaptcha bez proxy, czyli PopularCaptchaTaskProxyless. Inne typy captcha są w planach. Przewodnik o typach captcha wymienia, który jest który.

Endpoint

Wyślij żądanie POST na adres:

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

Treść żądania opisuje zadanie:

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

Trzy wymagane pola to:

Istnieją trzy pola opcjonalne. proxy przyjmuje wartość w formacie http://user:pass@host:port i jest używane przy typach zadań z proxy. rqdata i is_invisible dotyczą konkretnych wariantów widżetu. Pełna lista typów zadań i szczegóły pól znajdują się w dokumentacji API.

Synchroniczność oznacza brak odpytywania

Wywołanie blokuje się, aż token będzie gotowy. Nie odpytujesz serwera i w tym przepływie nie ma drugiego żądania "pobierz wynik". Ustaw timeout klienta HTTP na około 185 sekund, aby wolne rozwiązanie nie wyglądało jak błąd sieci.

W Pythonie z biblioteką requests wygląda to tak:

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

Odczytuj klucz ze zmiennej środowiskowej, a nie wpisuj go do skryptu. Ktokolwiek może przeczytać kod źródłowy, nie powinien móc korzystać z Twojego salda.

Odczytywanie odpowiedzi

Udane rozwiązanie zwraca errorId równe 0, token w polu solution i pole cost:

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

Nieudane rozwiązanie zwraca errorId inne niż 0, a także czytelny dla maszyny errorCode i czytelny dla człowieka errorDescription:

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

Sprawdzaj errorId w treści odpowiedzi przy każdym wywołaniu. Nie zakładaj, że zakończone żądanie HTTP oznacza, że masz token. Najważniejsza zasada jest taka: płacisz tylko wtedy, gdy errorId wynosi 0. Nieudane rozwiązania są bezpłatne. Aktualne stawki znajdziesz na stronie cennika.

Czas życia tokenu

Tokeny PopularCaptcha wygasają po około dwóch minutach. Prześlij token od razu po jego otrzymaniu. Nie buforuj tokenów do późniejszego użycia i nie rozwiązuj captcha z wyprzedzeniem przed wysłaniem formularza. Jeśli między otrzymaniem tokenu a wysłaniem formularza Twój kod wykonuje kilka kroków, przenieś rozwiązanie na sam koniec.

Wstawianie tokenu do formularza

Większość serwisów odczytuje odpowiedź PopularCaptcha z pola formularza o nazwie h-captcha-response. Wiele z nich akceptuje też g-recaptcha-response z tą samą wartością, więc wysyłanie obu jest częstym i bezpiecznym wyborem:

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

Jeśli formularz nie akceptuje tokenu, przyczyną jest zwykle sitekey lub adres strony, które nie pasują do strony, na której faktycznie był widżet. Sprawdź wartości, zanim obwinisz solver.

Obsługa błędów

Integracja produkcyjna wymaga kilku stałych nawyków:

Przewodnik o ponawianiu i obsłudze błędów rozwija każdy z tych punktów.

Pierwsze kroki

Załóż konto, a zaczniesz od darmowego kredytu próbnego, bez karty. Następnie uruchom powyższe żądanie na stronie testowej, którą kontrolujesz, i sprawdź, czy formularz akceptuje token, zanim podłączysz to do czegokolwiek ważnego.

Następne kroki