Dokumentacja › Referencja API › Testy stron

Testy stron

Gdy cel uruchamia weryfikację botów w drodze do żądanej strony, FourA Cię o tym informuje. Każde request, które na nią natrafi, zwraca pole z nazwą systemu, informacją, czy weryfikacja została zaliczona, oraz (w przypadku zaliczenia) danymi clearance do ponownego użycia, aby kolejne wywołanie ją pominęło.

Ta strona stanowi dokumentację referencyjną tych pól. Strategie opisano 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) To samo, raportowane przez próbę, która zwróciła odpowiedź
POST /api/browser/ defenseSolved (boolean) i defenses (object) Zawsze, na załadowanej stronie. defenseSolved ma wartość false, a defenses jest puste, gdy niczego nie rozpoznano.
POST /api/auto/ meta.solved (boolean) W każdej odpowiedzi po uruchomieniu drabiny. true, gdy weryfikacja została zaliczona na dowolnym etapie drabiny. Treść niespełniająca walidacji lub nierozpoznana nazwa hosta są obsługiwane przed drabiną, bez meta.

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

W trybach 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 bez zmian, 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ą wyzwania.
present string[] Każdy system rozpoznany w tej odpowiedzi. Może zawierać więcej nazw niż vendor, w tym nazwy, których nikt jeszcze nie obsługuje.
ms number Milisekundy spędzone na rozwiązywaniu 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 rozwiązań zamiast jednego. Tylko przy udanym rozwiązaniu.
retry string Obecne, gdy treść pochodzi z ponowienia, a nie z rozwiązania weryfikacji. Obecnie jedyną wartością jest refusal-cookies. Zobacz poniżej.
cookie string Magazyn cookie do powtórzenia: autoryzacja uzyskana po rozwiązaniu lub sesja zwrócona przy odmowie.

solved: false to przypadek, dla którego warto utworzyć osobną gałąź logiki. FourA nigdy nie zwraca strony wyzwania jako właściwej treści, więc ta flaga sygnalizuje, że treść wymaga eskalacji, a nie parsowania.

retry: "refusal-cookies"

Niektóre witryny nie uruchamiają testów logicznych. Odrzucają pierwsze żądanie, ustawiają pliki cookie przy odmowie i serwują właściwą stronę każdemu, kto odeśle te pliki cookie z powrotem. Strony przedmiotów w serwisie eBay są tego sztandarowym przykładem.

W takiej sytuacji FourA odsyła je automatycznie i zwraca docelową 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 oznacza rozwiązania challenge i nigdy nie zmienia kosztu wywołania. Płacisz za wykonany request.
  • data to rzeczywista treść, a nie strona z challenge. To jedyny przypadek, kiedy solved: false nie oznacza, że treść wymaga eskalacji, dlatego to pole istnieje.
  • cookie to sesja zwrócona przez stronę. Przekaż ją ponownie tak samo, jak clearance, a kolejne strony pominą odmowę dostępu.
  • Ponowienie (retry) i clear mogą wystąpić w ramach jednego requesta. Jeśli odpowiedź na retry okazała się challenge, który FourA potrafi rozwiązać, otrzymasz solved: true z polami danego dostawcy oraz retry: "refusal-cookies" obok nich.

vendor ma wartość unknown, gdy retry zwróciło treść i po drodze nie rozpoznano żadnego systemu. present jest wtedy pustą tablicą.

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 podczas ładowania napotkano system ochronny, a jego autoryzacja (clearance) została zachowana na końcowej stronie. Ta flaga decyduje 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 końcowej odpowiedzi. Weryfikacja to zdarzenie z przeszłości, a w momencie nadejścia właściwej strony odpowiedź z wyzwaniem (challenge) już dawno minęła.
defenses.cleared string[] Systemy, których autoryzację posiada strona końcowa.

Nazwa w present, która nigdy nie trafia do cleared, oznacza system, który FourA potrafi rozpoznać, ale którego nie potrafi jeszcze ukończyć. Takie przypadki nigdy nie podnoszą kosztu wywołania.

Dostawcy

Wartość vendor System
cloudflare Wyzwania Cloudflare i bot management
sgcaptcha Weryfikacja SiteGround
datadome DataDome
perimeterx PerimeterX
akamai Akamai Bot Manager
incapsula Imperva Incapsula
awswaf Wyzwanie AWS WAF
ebay-splashui Własne wyzwanie serwisu eBay
reddit Własna weryfikacja i strony odmowy serwisu Reddit
amazon Weryfikacja robotów serwisu Amazon
google Weryfikacja JavaScript w Google Search
hcaptcha hCaptcha
recaptcha reCAPTCHA
unknown Nie rozpoznano żadnego systemu. Pojawia się wyłącznie obok retry, gdzie wpis istnieje w celu zaraportowania ponowienia (retry), a nie dostawcy.

Co jest obecnie rozwiązywane

Endpoint Rozwiązuje
Single, Proxy sgcaptcha, ebay-splashui. Oba są obliczeniowe, a nie wizualne, więc nie wymagają przeglądarki.
Browser cloudflare, sgcaptcha

Wszystko inne z listy jest tylko rozpoznawane i raportowane. Ten podział zmienia się w miarę jak FourA uczy się obsługiwać kolejne systemy, dlatego należy sprawdzać solved zamiast polegać na tej tabeli.

Dwie uwagi dotyczące przypadków brzegowych:

  • hcaptcha i recaptcha to również zwykłe widżety formularzy. Są raportowane 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 ochrony.
  • Sama obecność za Cloudflare nie jest uznawana za ochronę. cloudflare pojawia się, gdy w odpowiedzi występuje rzeczywiste wyzwanie lub element bot-managementu, a nie dlatego, że strona korzysta z Cloudflare.

Ponowne użycie autoryzacji (clearance)

defense.cookie stanowi główny cel tego pola. Autoryzacja jest powiązana z węzłem wyjściowym (exit) i nagłówkiem User-Agent, przy użyciu których została uzyskana. Odtworzenie jej z 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 rozwiązania zabezpieczenia. Każde ponowienie (replay) to zwykły request w standardowej cenie.

Trzy rzeczy unieważniają replay:

  1. Inny punkt wyjścia. Przypnij identyfikator proxy zwrócony w odpowiedzi z rozwiązanym zabezpieczeniem. Zobacz Reuse a Proxy Across Requests.
  2. Inny User-Agent. Odpowiedzi Browser zwracają użyty userAgent. Odsyłaj go z powrotem razem z cookie.
  3. Wygaśnięcie. Rozwiązania zabezpieczeń mają swój czas ważności określony przez cel. W SiteGround trwa on około 30 dni dla całej witryny; clearance w Cloudflare jest zazwyczaj znacznie krótszy. Traktuj clearance jak cache: gdy kolejne zapytania zaczną ponownie zwracać challenge, wykonaj jedno nowe wywołanie i pobierz nowy token.

Koszt

Rozwiązane zabezpieczenie zmienia cenę tylko w silniku Browser:

Engine Base Cleared defense
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 faktycznie rozwiązane. System, który został rozpoznany, ale nie rozwiązany, kosztuje 5, czyli tyle samo, co strona bez żadnych zabezpieczeń.

Strona z weryfikacją rozpoznana przez FourA i zwrócona ze statusem HTTP 200 (na przykład robot check na Amazonie, strona weryfikacji Reddita lub test JavaScript w Google Search) nie jest rozliczana na żadnym endpoint; odpowiedź wskazuje ją w X-FourA-Check-Page.

Połącz z validate

defense informuje, że napotkano weryfikację. validate wskazuje FourA, jak wygląda właściwa strona, dzięki czemu request może zakończyć się błędem zamiast zwracać stronę pośrednią (interstitial) ze statusem HTTP 200.

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

W przypadku POST /api/auto/ parametr validate zapobiega zaakceptowaniu strony z wyzwaniem przez mechanizm eskalacji i uznaniu jej za sukces.

Powiązane

Aktualizacja: 30 września 2026
← Nagłówki odpowiedzi (Response Headers) Port proxy →