Testy witryn

Gdy cel uruchamia weryfikację antybotową w drodze do żądanej strony, FourA Cię o tym informuje. Każde żądanie, które na nią natrafi, zwraca pole określające system, informację, czy weryfikacja została zaliczona, oraz (w przypadku powodzenia) token clearance do ponownego użycia, aby kolejne wywołanie ją pominęło.

Ta strona stanowi dokumentację referencyjną dla tych pól. Informacje o strategii znajdziesz w sekcji Protected sites.

Gdzie znajduje się to pole

Endpoint Pole Obecne, gdy
POST /api/single/ defense (object) W odpowiedzi rozpoznano weryfikację botów
POST /api/proxy/ defense (object) Tak samo, zgłaszane przez próbę, która zwróciła odpowiedź
POST /api/browser/ defenseSolved (boolean) i defenses (object) Zawsze, na stronie, która się załadowała. defenseSolved ma wartość false, a defenses jest puste, gdy niczego nie rozpoznano.
POST /api/auto/ meta.solved (boolean) Przy każdej odpowiedzi po uruchomieniu sekwencji ladder. true, gdy weryfikacja została zaliczona na dowolnym etapie ladder. Odpowiedź na błąd walidacji body lub brak rozwiązania nazwy hosta jest zwracana przed sekwencją ladder, bez meta.

Brak pola oznacza, że niczego nie rozpoznano. Nie traktuj braku pola defense jako błędu.

W Single i Proxy raportowanie wymaga opcji unblocker, która jest domyślnie włączona. Przy unblocker: false żądasz strony dokładnie w takiej postaci, w jakiej nadeszła, więc Single zwraca challenge w stanie nienaruszonym, a Browser renderuje go bez rozwiązywania.

defense w Single i Proxy

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "hashes": 1048576,
    "complexity": 20,
    "cookie": "_I_=<clearance>"
  }
}
Pole Typ Opis
vendor string System, którego dotyczy ten rekord: ten, który został rozwiązany, lub główny napotkany. Zobacz listę dostawców poniżej.
solved boolean true oznacza, że weryfikacja powiodła się, a data to właściwa strona. false oznacza, że data może być stroną z wyzwaniem.
present string[] Wszystkie systemy rozpoznane w tej odpowiedzi. Może zawierać więcej nazw niż vendor, w tym nazwy, których nikt jeszcze nie obsługuje.
ms number Milisekundy poświęcone na rozwiązanie weryfikacji. Tylko przy udanym rozwiązaniu.
hashes number Nakład pracy obliczeniowej wymagany przez wyzwanie. Tylko przy udanym rozwiązaniu.
complexity number Trudność zadeklarowana przez wyzwanie. Tylko przy udanym rozwiązaniu i tylko wtedy, gdy wyzwanie ją zgłasza.
answers number Liczba dostarczonych zaakceptowanych odpowiedzi dla wyzwań wymagających kilku zamiast jednej. Tylko przy udanym rozwiązaniu.
retry string Obecne, gdy treść pochodzi z ponowienia zamiast z rozwiązania: refusal-cookies, amazon-continue, reddit-js-check lub verify-challenge. Zobacz poniżej.
cookie string Cookie jar do powtórzenia: autoryzacja uzyskana po rozwiązaniu lub sesja zwrócona przy odmowie.

solved: false to przypadek, na którym warto oprzeć rozgałęzienie logiki. FourA nigdy nie zwraca strony z wyzwaniem jako treści, więc ta flaga sygnalizuje, że treść wymaga eskalacji, a nie parsowania.

retry: "refusal-cookies"

Niektóre witryny nie wyświetlają wyzwania. Odrzucają pierwsze żądanie, ustawiają pliki cookie przy odmowie i serwują właściwą stronę każdemu, kto odeśle te pliki z powrotem. Strony produktów w serwisie eBay to klasyczny przykład.

W takiej sytuacji FourA odsyła je automatycznie i przekazuje Ci stronę. Odpowiedź zawiera wtedy retry: "refusal-cookies":

{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "akamai",
    "solved": false,
    "present": ["akamai"],
    "retry": "refusal-cookies",
    "cookie": "bm_sv=...; dp1=..."
  }
}

Należy to interpretować następująco:

  • solved pozostaje false. Odpowiedź na handshake nie jest rozwiązaniem challenge'a i nigdy nie zmienia kosztu wywołania. Płacisz za wykonany request.
  • data to rzeczywista treść, a nie strona z challenge'em. To jedyny przypadek, kiedy solved: false nie oznacza, że body wymaga eskalacji, i dlatego to pole istnieje.
  • cookie to sesja zwrócona przez witrynę. Odtwórz ją tak samo, jak clearance, a kolejne strony pominą odmowę.
  • W ramach jednego requestu może wystąpić zarówno retry, jak i rozwiązanie challenge'a. Jeśli odpowiedź po retry okazała się challenge'em, który FourA potrafi rozwiązać, otrzymasz solved: true z polami danego dostawcy oraz z retry: "refusal-cookies" obok nich.

vendor przyjmuje wartość unknown, gdy retry zwrócił treść i po drodze nie rozpoznano żadnego systemu. W takim przypadku present jest pustą tablicą.

retry: "amazon-continue"

Amazon czasami odpowiada jednoliniową weryfikacją botów: niewielką stroną, która prosi o kliknięcie, aby kontynuować zakupy, z wypełnioną już odpowiedzią. Przy włączonym unblocker (wartość domyślna) Single i Proxy klikają ten przycisk na tym samym węźle wyjściowym, w ramach Twojego timeout_ms, i ponownie żądają strony z ustawionymi przez niego plikami cookie. Gdy to odblokuje stronę, response zawiera retry: "amazon-continue":

{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "akamai",
    "solved": false,
    "present": ["akamai", "amazon"],
    "retry": "amazon-continue",
    "cookie": "ak_bmsc=...; ..."
  }
}

Traktuj to jak ponowienie żądania po odrzuceniu plików cookie. solved pozostaje false, data to właściwa strona, opłata jest naliczana za wykonane żądanie, a cookie to magazyn cookie do ponownego użycia na kolejnych stronach. Szukaj amazon w present zamiast w vendor: strona weryfikacyjna często ustawia cookie rozpoznawane również przez FourA, a vendor wskazuje pierwszy system na liście.

Obrazkowa wersja tej samej weryfikacji, w której człowiek musi odczytać odpowiedź, jest raportowana i pozostawiana bez zmian. Podobnie dzieje się w przypadku kliknięcia, które jedynie ponownie wywołuje weryfikację. W obu przypadkach za tę stronę nie jest naliczana opłata (zobacz Ile to kosztuje).

retry: "reddit-js-check"

Reddit czasami odpowiada lekką weryfikacją: niewielką stroną zawierającą ukryty formularz i skrypt, który go wypełnia. Przy włączonym unblocker (wartość domyślna), Single i Proxy wysyłają ten formularz przez ten sam węzeł wyjściowy w ramach Twojego timeout_ms i ponownie żądają Twojej strony z ustawionymi plikami cookie. Gdy strona zostanie w ten sposób otwarta, response zawiera retry: "reddit-js-check":

{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "reddit",
    "solved": false,
    "present": ["reddit"],
    "retry": "reddit-js-check",
    "cookie": "edgebucket=...; ..."
  }
}

Traktuj to jak ponowienie amazon-continue. solved pozostaje false, data to wlasciwa strona, oplata jest naliczana za wykonany request, a cookie to magazyn do powtorzenia na kolejnych stronach. Gdy weryfikacja stale powraca, FourA pozostawia strone bez zmian, a ta strona nie podlega oplacie.

retry: "verify-challenge"

Niektore witryny otwieraja sie z wlasna, krotka strona weryfikacyjna: spinnerem i skryptem przekierowujacym do wlasciwej strony po zakonczeniu sprawdzania. Przy wlaczonej opcji unblocker (domyslnie), Single i Proxy przeprowadzaja te weryfikacje na tym samym wezle wyjsciowym, w ramach Twojego timeout_ms, i ponownie prosza o Twoja strone z ustawionym plikiem cookie. Gdy to otworzy strone, response zawiera retry: "verify-challenge":

{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "verify-challenge",
    "solved": false,
    "present": ["verify-challenge"],
    "retry": "verify-challenge",
    "cookie": "token=..."
  }
}

Traktuj to jak ponowienie reddit-js-check. solved pozostaje false, data to rzeczywista strona, opłata jest naliczana za wykonane request, a cookie to magazyn do powtórzenia na kolejnych stronach. Gdy strona weryfikacyjna powróci bez odpowiedzi, opłata nie jest naliczana.

defenses w Browser

{
  "status": 200,
  "body": "<!doctype html>...",
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {
    "present": ["cloudflare"],
    "cleared": ["cloudflare"]
  }
}
Pole Typ Opis
defenseSolved boolean true, gdy system został napotkany podczas ładowania, a jego autoryzacja (clearance) jest utrzymana na stronie końcowej. Jest to flaga decydująca o tym, czy wywołanie kosztuje 5 czy 10 kredytów.
defenses.present string[] Każdy system rozpoznany w dowolnym momencie ładowania strony, nie tylko w ostatecznej odpowiedzi. Test (check) to zdarzenie, które miało miejsce, a do momentu nadejścia właściwej strony odpowiedź na wyzwanie (challenge response) dawno minęła.
defenses.cleared string[] Systemy, których autoryzację (clearance) posiada strona końcowa.

Nazwa w present, która nigdy nie trafia do cleared, to system, który FourA rozpoznało, ale nie uzyskało dla niego clearance: taki, którego jeszcze nie potrafi ukończyć, lub jeden z nielicznych, które Browser obsługuje w inny sposób (zobacz Co jest obecnie rozwiązywane). Takie przypadki nigdy nie podnoszą kosztu wywołania.

Dostawcy

Wartość vendor System
cloudflare Wyzwania Cloudflare i zarządzanie botami
sgcaptcha Weryfikacja strony SiteGround
datadome DataDome
perimeterx PerimeterX
akamai Akamai Bot Manager
incapsula Imperva Incapsula
awswaf Wyzwanie AWS WAF
ebay-splashui Własne wyzwanie eBay
reddit Własne strony sprawdzania i odmowy serwisu Reddit
verify-challenge Własna strona sprawdzania witryny przekierowująca dalej po zakończeniu weryfikacji
amazon Weryfikacja botów serwisu Amazon
hcaptcha hCaptcha
recaptcha reCAPTCHA
unknown Nie rozpoznano żadnego systemu. Pojawia się tylko obok retry, gdzie rekord istnieje w celu zaraportowania ponowienia próby (retry), a nie dostawcy.

Co jest obecnie rozwiązywane

Endpoint Rozwiązuje
Single, Proxy sgcaptcha, ebay-splashui. Oba mają charakter obliczeniowy, a nie wizualny, więc przeglądarka nie bierze w tym udziału.
Browser cloudflare, sgcaptcha

Kilka kolejnych jest obsługiwanych bez uzyskiwania clearance. Single i Proxy klikają jednoprzyciskową weryfikację botów Amazon i zgłaszają ją jako retry: "amazon-continue", przesyłają prosty test strony Reddit i zgłaszają go jako retry: "reddit-js-check", a także przechodzą własną stronę sprawdzania witryny i zgłaszają ją jako retry: "verify-challenge". Browser czeka do 10 sekund, aż ta sama strona sprawdzania przekieruje dalej. Browser klika przycisk Amazon i czeka, aż strona sensora Akamai, strona wyzwania AWS WAF, sprawdzanie urządzenia DataDome lub własna strona wyzwania eBay samoczynnie załaduje kolejną stronę, po czym zwraca tę stronę. Jeśli ta strona nigdy nie nadejdzie, Browser zwraca stronę, którą trzymał, wewnątrz twojego timeout_ms. W Browser te nazwy pojawiają się w defenses.present, nigdy w cleared, a wywołanie kosztuje 5.

Wszystko inne z listy jest rozpoznawane i raportowane, nic więcej. Ten podział ulega zmianie, w miarę jak FourA uczy się rozwiązywać kolejne z nich, dlatego sprawdzaj solved zamiast polegać na tej tabeli.

Dwie uwagi na temat przypadków brzegowych:

  • hcaptcha i recaptcha to również zwykłe widżety formularzy. Są zgłaszane tylko wtedy, gdy odpowiedź rzeczywiście Cię zablokowała (403, 429 lub 503), więc strona kasy z widżetem weryfikacyjnym w formularzu nie zgłasza zabezpieczenia.
  • Sama obecność za Cloudflare nie jest zabezpieczeniem. cloudflare pojawia się, gdy w odpowiedzi występuje rzeczywisty challenge lub artefakt zarządzania botami, a nie dlatego, że witryna korzysta z Cloudflare.

Ponowne użycie clearance

defense.cookie to główny cel tego pola. Clearance jest powiązany z węzłem wyjściowym, który go uzyskał, oraz nagłówkiem User-Agent, który go wygenerował, więc ponowne użycie go przez tę samą parę sprawia, że weryfikacja nie jest uruchamiana ponownie.

import requests

API = "https://eu.api.foura.ai"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

# 1) First call pays for the clear.
first = requests.post(f"{API}/api/proxy/", headers=H, json={
    "maxTries": 5,
    "request": {"method": "GET", "url": "https://example.com/catalog"},
}).json()

defense = first.get("defense", {})
if defense.get("solved"):
    clearance = defense["cookie"]
    exit_id = first["proxy"]

    # 2) Follow-up pages skip the check: same exit, same clearance.
    for page in range(2, 6):
        r = requests.post(f"{API}/api/single/", headers=H, json={
            "method": "GET",
            "url": f"https://example.com/catalog?page={page}",
            "proxy": exit_id,
            "headers": [["Cookie", clearance]],
        }).json()
        print(page, r["status"])

Pierwsze wywołanie ponosi koszt ominięcia zabezpieczeń. Każde ponowne użycie (replay) to zwykły request w standardowej cenie.

Trzy rzeczy mogą zepsuć ponowne użycie:

  1. Inny punkt wyjścia. Przypnij identyfikator proxy zwrócony w odpowiedzi z ominięciem. Zobacz Reuse a Proxy Across Requests.
  2. Inny User-Agent. Odpowiedzi Browser zwracają użyty userAgent. Odsyłaj go razem z cookie.
  3. Wygaśnięcie. Przepustki (clearances) mają własny czas ważności, ustalany przez cel. SiteGround utrzymuje go przez około 30 dni dla całej witryny; clearance Cloudflare jest zwykle znacznie krótszy. Traktuj clearance jak cache: gdy powtórzone requesty znowu zaczną zwracać wyzwania, wykonaj jedno świeże wywołanie i pobierz nowe dane.

Ile to kosztuje

Ominięta weryfikacja zmienia cenę wyłącznie w Browser:

Engine Baza Ominięte zabezpieczenie
Single 1 (2 z unblocker) Bez zmian
Proxy 2 (4 z unblocker) Bez zmian
Browser 5 10

Browser nalicza 10 tylko wtedy, gdy solver był włączony, a zabezpieczenie zostało rzeczywiście ominięte. System, który został rozpoznany, ale nie ominięty, kosztuje 5, czyli tyle samo, co strona bez żadnych zabezpieczeń.

Strona weryfikacji lub odmowy rozpoznana przez FourA i zwrócona ze statusem HTTP 200 (na przykład weryfikacja bota na Amazonie, strona weryfikacyjna Reddita lub wyzwanie na eBayu) nie jest fakturowana na żadnym punkcie końcowym. Odpowiedzi Single, Proxy i Browser podają jej nazwę w X-FourA-Check-Page.

Połącz to z validate

defense informuje o napotkaniu weryfikacji. validate wskazuje FourA, jak wygląda właściwa strona, dzięki czemu request może zakończyć się błędem zamiast zwróceniem strony pośredniej (interstitial), która przypadkowo zwraca HTTP 200.

{
  "method": "GET",
  "url": "https://example.com/product/42",
  "validate": {
    "data": {"accept": ["Add to cart"], "fail": ["Just a moment"]}
  }
}

W POST /api/auto/ to validate zapobiega sytuacji, w której drabina uzna stronę z wyzwaniem za pomyślny wynik.

Aktualizacja: 11 listopada 2026