# Testy witryn

> URL: https://foura.ai/pl/docs/api/site-checks
> Updated: 2026-11-11
> Index: https://foura.ai/llms.txt

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](https://foura.ai/docs/guides/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

```json
{
  "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"`:

```json
{
  "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"`:

```json
{
  "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](#what-it-costs)).

### `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"`:

```json
{
  "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"`:

```json
{
  "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

```json
{
  "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](#what-gets-cleared-today)). 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.

```python
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](https://foura.ai/docs/how-to/reuse-a-proxy).
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.

```json
{
  "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](https://foura.ai/docs/guides/protected-sites): Który silnik wybrać dla danego poziomu ochrony
- [Endpointy API](https://foura.ai/docs/api/endpoints): Dokumentacja requestów i response'ów dla wszystkich czterech endpointów
- [Ponowne użycie proxy w wielu requestach](https://foura.ai/docs/how-to/reuse-a-proxy): Przypinanie węzła wyjściowego, do którego jest powiązany clearance
- [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch): Jak `meta.solved` wpisuje się w drabinę
- [Nagłówki odpowiedzi](https://foura.ai/docs/api/response-headers): Gdzie widoczny jest koszt kredytowy wywołania
