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:
solvedpozostajefalse. Odpowiedź na handshake nie jest rozwiązaniem challenge'a i nigdy nie zmienia kosztu wywołania. Płacisz za wykonany request.datato rzeczywista treść, a nie strona z challenge'em. To jedyny przypadek, kiedysolved: falsenie oznacza, że body wymaga eskalacji, i dlatego to pole istnieje.cookieto 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: truez polami danego dostawcy oraz zretry: "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:
hcaptchairecaptchato 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.
cloudflarepojawia 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:
- Inny punkt wyjścia. Przypnij identyfikator proxy zwrócony w odpowiedzi z ominięciem. Zobacz Reuse a Proxy Across Requests.
- Inny User-Agent. Odpowiedzi Browser zwracają użyty
userAgent. Odsyłaj go razem z cookie. - 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.
Powiązane
- Chronione strony: Który silnik wybrać dla danego poziomu ochrony
- Endpointy API: Dokumentacja requestów i response'ów dla wszystkich czterech endpointów
- Ponowne użycie proxy w wielu requestach: Przypinanie węzła wyjściowego, do którego jest powiązany clearance
- Smart Fetch (Auto): Jak
meta.solvedwpisuje się w drabinę - Nagłówki odpowiedzi: Gdzie widoczny jest koszt kredytowy wywołania