# Tài liệu tham khảo API endpoint

> URL: https://foura.ai/vi/docs/api/endpoints
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Tài liệu tham chiếu cho tất cả các endpoint API của FourA với các tham số request và định dạng response.

## Base URL

```
https://eu.api.foura.ai/api
```

## Xác thực

Mọi request đều yêu cầu API key của bạn trong header `X-API-Key`:

```bash
curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'
```

Tạo và quản lý API key trong [Dashboard](https://foura.ai/dashboard). Các key sử dụng tiền tố `pk_live_`.

## Response Headers

Response từ `/api/*` chứa hai correlation header:

| Header | Value | Description |
|--------|-------|-------------|
| `X-FourA-Request-Id` | UUID | ID duy nhất được gán cho request. Được trả về trên mọi response, bao gồm 4xx và 5xx, ngoại trừ body mà FourA hoàn toàn không thể đọc: `400 Invalid JSON in request body` và `413` bị từ chối trước khi ID được gán. Hãy ghi log giá trị này ở phía bạn. |
| `X-FourA-Credits` | integer | Số credit đã dùng cho request này. Được trả về trên mọi response đã đến engine, bất kể thành công hay thất bại (vì công việc đều đã được thực thi). Một lệnh gọi bị FourA từ chối trước khi có engine xử lý (thiếu hoặc không hợp lệ key, giới hạn gói hoặc nền tảng, target hoặc proxy ID bị từ chối) sẽ không có header này. Xem [Request Outcomes](https://foura.ai/docs/api/outcomes) để biết những kết quả nào bị tính phí. |

Cùng request ID này sẽ liên kết với bản xem trước payload của request và response trong [Activity Log](https://foura.ai/docs/dashboard/activity-log) của Dashboard (lưu trong 24 giờ, 200 bản ghi gần nhất cho mỗi key), giúp bạn có thể tra cứu chính xác request sau đó và phát lại từ Activity trực tiếp vào [Playground](https://foura.ai/docs/dashboard/playground). Hãy đính kèm ID này khi liên hệ hỗ trợ để xác định request trong vài giây.

```bash
$ curl -i -X POST https://eu.api.foura.ai/api/single/ \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"method": "GET", "url": "https://example.com"}'

HTTP/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
x-foura-credits: 2
...
```

Xem [Response Headers](https://foura.ai/docs/api/response-headers) để biết danh sách đầy đủ và mẹo sử dụng.

## Các endpoint

> **Sử dụng các endpoint này qua MCP?** [`@fouradata/mcp` server](https://foura.ai/docs/mcp/server) đóng gói cả bốn endpoint dưới dạng các công cụ MCP gốc (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) với cùng cấu trúc đầu vào kèm tùy chọn `offload_large` để xử lý response lớn tiết kiệm token. Điểm khác biệt: `foura_browser` không có trường `lean`, và `foura_proxy` hiện chưa hỗ trợ các trường [exit location](#exit-location).

FourA cung cấp bốn request endpoint, mỗi endpoint được tối ưu hóa cho một kịch bản khác nhau:

| Endpoint | Phù hợp nhất cho |
|----------|------------------|
| `POST /auto/` | Tìm nạp thông minh. Bạn truyền một URL, FourA chọn đường dẫn tiết kiệm chi phí nhất có thể hoạt động (proxy xoay vòng hoặc trình duyệt, cộng với request trực tiếp bằng `forceProxy: false`) và ghi nhớ phương án hiệu quả cho từng host. |
| `POST /single/` | Request HTTP nhanh, trang tĩnh, API |
| `POST /proxy/` | Các trang web được bảo vệ với tính năng xoay vòng proxy tự động, tùy chọn giới hạn quốc gia hiển thị với đích đến |
| `POST /browser/` | Các trang render bằng JavaScript, SPA |
| `GET /profiles` | Danh mục profile trình duyệt cho `single` và `proxy`. Công khai, không cần API key. |

Để xem hướng dẫn chi tiết hơn về thời điểm nên chọn từng loại, hãy xem [Choosing the Right Endpoint](https://foura.ai/docs/guides/choosing-task-type) và [Smart Fetch guide](https://foura.ai/docs/guides/smart-fetch).

## Giới hạn URL đích

Các đích phân giải thành dải IP riêng tư, loopback hoặc dải IP dành riêng (RFC 5735, RFC 6598, các khối IPv6 dành riêng) sẽ bị từ chối với mã 400 trước khi request rời FourA. Chỉ các hostname và IP công khai mới được chuyển tiếp.

```json
{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }
```

Target trỏ đến host API của chính FourA (`eu.api.foura.ai` hoặc `api.foura.ai`) cũng bị từ chối với mã 400 trên cả bốn endpoint, trước khi bất kỳ dữ liệu nào được fetch hoặc tính phí. URL chứa khoảng trắng hoặc ký tự điều khiển bên trong cũng bị từ chối với mã 400 tương tự trên Single, Proxy và Auto; hãy encode khoảng trắng thành `%20` (Browser fetch theo cách của Chrome). Trang duy nhất mà FourA fetch là [`/inspect`](https://foura.ai/docs/api/inspect).

```json
{ "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL." }
```

---

## Smart Fetch (Auto)

`POST /api/auto/`

Bạn truyền một URL cùng các quy tắc `validate` tùy chọn. FourA duyệt qua từng bậc thang tối ưu chi phí (proxy xoay vòng, sau đó đến trình duyệt đầy đủ) và dừng lại ở bậc đầu tiên trả về response mà các quy tắc của bạn chấp nhận. Với `forceProxy: false`, một lượt thăm dò trực tiếp giá rẻ sẽ chạy trước. Với các lệnh gọi lặp lại đến cùng một host, session đã khởi tạo sẵn sẽ được phát lại, giúp lượt gọi thứ hai có chi phí thấp.

Bạn không cần tinh chỉnh số lần thử lại, kích thước pool hay số lượng proxy. FourA tự học các thông số này theo từng host.

### Request Body

| Tham số | Loại | Bắt buộc | Mặc định | Mô tả |
|-----------|------|----------|---------|-------------|
| `url` | string | Có | - | URL đích |
| `method` | string | Không | `"GET"` | Phương thức HTTP |
| `headers` | [string, string][] | Không | - | Headers gửi đến đích, dưới dạng các cặp [name, value]. Mọi bậc thang đều gửi chúng ngoại trừ bậc trình duyệt. `Cookie` bạn gửi sẽ đến site nguyên vẹn, và cookie của session đã lưu chỉ được thêm vào cạnh nó với những tên bạn chưa gửi. `userAgent` của session đã lưu sẽ thay thế `User-Agent` của bạn. Bậc proxy sẽ bỏ qua các header điều kiện như `If-None-Match` trừ khi `validate.status.accept` của bạn liệt kê `304`. |
| `data` | any | Không | - | Request body cho các request không phải GET |
| `validate` | object | Không | - | Tiêu chí thành công, cùng cấu trúc với `validate` của Single Request (xem bên dưới). Cho cơ chế auto biết một trang thực tế trông như thế nào để nó phân biệt nội dung với trang thử thách. |
| `returnSession` | boolean | Không | `true` | Bao gồm session thành công (`proxy`, `cookies`, `userAgent`) trong response để bạn có thể phát lại qua `/api/single/` hoặc `/api/browser/`. |
| `forceProxy` | boolean | Không | `true` | Luôn định tuyến qua proxy xoay vòng. Đặt `false` để cho phép đường dẫn trực tiếp rẻ hơn khi mục tiêu cho phép (một số cơ chế bảo vệ nghiêm ngặt hơn với lưu lượng proxy). |
| `timeout_ms` | integer | Không | `120000` | Tổng thời gian tối đa cho toàn bộ lệnh gọi, tính bằng mili giây. Mọi lượt thử con đều chạy trong giới hạn này. Tối thiểu `5000`, tối đa `180000`. |
| `ignoreProxies` | string[] | Không | - | Các proxy ID cần tránh trong mỗi lượt thử con. Sử dụng các ID được trả về từ những response `/api/auto/` hoặc `/api/proxy/` trước đó. |
| `followRedirects` | integer | Không | `5` | Số lần chuyển hướng tối đa cần theo dõi trên các bậc thang giá rẻ. `0` để tắt. Tối đa `20`. |
| `exitClass` | string | Không | - | `standard` hoặc `premium`, như trên [Proxy Request](#exitclass). `premium` cho phép lệnh gọi leo thang lên exit node cao cấp khi pool tiêu chuẩn không thể truy cập trang. Yêu cầu gói dịch vụ có hỗ trợ premium exit. Xem [exitClass trên Smart Fetch](#exitclass-on-smart-fetch). |

### Response

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2,
    "attemptsByEngine": {"single": 1, "proxy": 0, "browser": 0},
    "browserRequests": 0
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}
```

| Trường | Loại | Mô tả |
|-------|------|-------------|
| `status` | number | Mã trạng thái HTTP từ máy chủ đích. |
| `data` | string | Nội dung response dưới dạng văn bản, bất kể bậc thang nào xử lý. Trang JSON sẽ trả về dưới dạng chuỗi JSON, bạn tự parse dữ liệu này. |
| `headers` | array hoặc object | Các response header từ máy chủ đích. Bậc Single và Proxy trả về một mảng chứa đối tượng header của từng chặng; bậc Browser trả về một đối tượng phẳng. |
| `meta.rung` | string | Bậc thang xử lý và trả về response. Một trong số: `probe` (request trực tiếp chi phí thấp, chỉ dùng với `forceProxy: false`), `proxy` (proxy xoay vòng), `browser` (kết xuất trình duyệt đầy đủ), `cache` (phiên hoạt động sẵn được phát lại), `warmup` (trang khởi đầu của trang web được tải trước và cookie của nó mở URL sâu), hoặc `fail` (không có bậc nào tạo ra response hợp lệ). |
| `meta.solved` | boolean | Cho biết liệu trang có cần bước bổ sung (trang xác thực thử thách) và đã hoàn thành trong lần gọi này hay không. |
| `meta.attempts` | number | Số lượt thử phụ đã thực hiện trước khi thành công. |
| `meta.credits` | number | Tổng số credit đã dùng cho lệnh gọi này. Trùng khớp với `X-FourA-Credits`. |
| `meta.attemptsByEngine` | object | Số lượng request đã gửi đến `single`, `proxy` và `browser`. Request trình duyệt bị gói cước của bạn từ chối vẫn được tính, vì request đã được gửi đi. |
| `meta.browserRequests` | number | Số lượng request trình duyệt đã tiêu tốn hạn ngạch trong ngày của bạn. Request trình duyệt bị gói cước của bạn từ chối sẽ không tính. |
| `meta.exitClass` | string | Loại điểm ra (exit) phục vụ, xuất hiện khi request chỉ định một `exitClass`: `premium` hoặc `standard`. Giá trị tương tự cũng xuất hiện trong response header `X-FourA-Exit-Class`. |
| `session.proxy` | string | ID đã mã hóa của proxy phục vụ response. Sử dụng lại ID này trên request Single hoặc Browser. Xuất hiện khi `returnSession` là `true`. |
| `session.cookies` | array | Cookie để phát lại, mỗi cookie có tối thiểu `name` và `value`. Bậc Browser trả lại kho cookie của trình duyệt. Bậc Proxy hoặc lượt thăm dò trực tiếp chỉ trả lại các cookie dùng để mở trang (chẳng hạn cookie do trang kiểm tra của web đặt), không bao giờ trả lại mọi cookie mà trang đã đặt, do đó danh sách có thể rỗng. Xuất hiện khi `returnSession` là `true`. |
| `session.userAgent` | string | User-Agent được dùng trong lần thử thành công. Xuất hiện khi `returnSession` là `true`. |
| `error` | string | Thông báo lỗi nếu lệnh gọi thất bại. |
| `attemptReport` | object | Khi lệnh gọi thất bại: danh sách các engine request không nhận được trang, phân loại theo nguyên nhân. Xem [Smart Fetch](https://foura.ai/docs/guides/smart-fetch). |

### Ví dụ

```bash
curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'
```

### Lưu ý

- Auto đóng vai trò là một điều phối viên. Nó gọi Single, Proxy, hoặc Browser trong nội bộ và chuyển tiếp API key của bạn tới từng lệnh gọi con. Lệnh gọi Auto được tính là một request trong [Activity Log](https://foura.ai/docs/dashboard/activity-log) và trên Tổng quan của bạn, với tổng số credit từ các lệnh gọi con của nó; các lệnh gọi con được liệt kê bên dưới dưới dạng các lần thử, và chúng không bao giờ được tính là các request riêng lẻ.
- Truyền `validate.data.accept` với một chuỗi con mà chỉ trang web thực tế mới có. Không có chuỗi này, auto không thể phân biệt giữa mã 200 thực sự và trang trung gian thử thách được trả về với status 200.
- Một trang đã bị xóa là câu trả lời của trang web, không phải là một sự từ chối. Khi hai exit trả về cùng một mã `404` hoặc `410` và `validate` của bạn không chấp nhận nó, lệnh gọi sẽ kết thúc với `status` đó cùng với một `error` bắt đầu bằng `the site answered`. Liệt kê status đó trong `validate.status.accept` và Auto sẽ phân phối response đầu tiên có status đó đáp ứng phần còn lại của `validate` của bạn. Điều tương tự cũng áp dụng cho bất kỳ status nào khác bạn liệt kê ở đó, ngoại trừ `403`, `429`, `503` và `202`, là các mã mà các trang web cũng gửi kèm với một trang thử thách.
- `timeout_ms` giới hạn thời gian cho toàn bộ lệnh gọi. Lần truy cập đầu tiên khi chưa có cache tới một trang web được bảo vệ có thể mất hàng chục giây; các session ấm được tái sử dụng thường hoàn thành trong vòng chưa đầy một giây.

### exitClass trên Smart Fetch

`exitClass` hoạt động trên Smart Fetch giống như trên [Proxy Request](#exitclass): một định mức cho phép, không phải là một chỉ thị bắt buộc. Auto sẽ thử pool tiêu chuẩn trước. Khi pool tiêu chuẩn không thể truy cập trang và request có chỉ định `premium`, Auto sẽ mở trang trong một trình duyệt thông qua một premium exit. Session được tạo ra ở đó sẽ phục vụ các lệnh gọi sau này của bạn tới cùng trang web mà cũng chỉ định `premium`; các lệnh gọi không chỉ định nó sẽ không bao giờ sử dụng session này.

Hết hạn mức không phải là một lỗi. Khi lưu lượng premium trong gói của bạn đã dùng hết cho chu kỳ thanh toán, lệnh gọi vẫn tiếp tục trong pool tiêu chuẩn và `meta.exitClass` sẽ thông báo `standard`. Trên một gói không có premium exit, một lệnh gọi gửi `exitClass: premium` sẽ bị từ chối với một `403` mang `X-FourA-Limit: plan_limit_premium`, trước khi bất kỳ tác vụ nào được thực hiện.

Lưu lượng premium được đo lường giống như trên Proxy Request. Một trang được mở trong trình duyệt sẽ tải nhiều thứ hơn là chỉ bản thân trang đó, vì vậy một trang Smart Fetch premium sử dụng nhiều lưu lượng premium hơn so với cùng trang đó được tìm nạp bởi Proxy Request. Để hạn chế điều đó, một trang Smart Fetch premium sẽ tải mà không có hình ảnh, phông chữ và phương tiện đa phương tiện, cũng như không có script từ các nhà cung cấp quảng cáo, phân tích và yêu cầu chấp thuận đã biết.

---

## Single Request

`POST /api/single/`

Gửi một HTTP request với các đặc tính truyền dẫn thực tế giống như trình duyệt, mà không cần khởi chạy một trình duyệt thực sự. Đây là endpoint nhanh nhất.

### Request Body

| Tham số | Loại | Bắt buộc | Mặc định | Mô tả |
|-----------|------|----------|---------|-------------|
| `method` | string | Có | - | Phương thức HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| `url` | string | Có | - | URL đích. Sử dụng `{ts}` ở bất kỳ vị trí nào trong URL để chèn timestamp hiện tại nhằm vô hiệu hóa cache. |
| `headers` | [string, string][] | Không | - | Các header tùy chỉnh dưới dạng các cặp [name, value] |
| `unblocker` | boolean | Không | `true` | Gửi các header trình duyệt thực tế (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Bật theo mặc định. Đặt `false` và FourA sẽ không thêm header trình duyệt nào, chỉ gửi những header bạn truyền vào. |
| `timeout_ms` | number | Không | 15000 | Thời gian chờ tổng thể tính bằng ms (tối đa: 120000) |
| `connect_timeout_ms` | number | Không | 5000 | Thời gian chờ kết nối tính bằng ms |
| `accept_timeout_ms` | number | Không | 5000 | Thời gian chờ chấp nhận kết nối tính bằng ms (thời gian chờ kết nối được chấp nhận) |
| `server_response_timeout_ms` | number | Không | 15000 | Thời gian chờ máy chủ phản hồi tính bằng ms (thời gian chờ byte đầu tiên) |
| `dns_cache_timeout_sec` | number | Không | 120 | TTL của cache DNS tính bằng giây (tối đa: 240) |
| `followRedirects` | number | Không | vô hiệu hóa | Số lượng chuyển hướng tối đa cần theo dõi (0-20). Bỏ qua để vô hiệu hóa. |
| `tryJsonData` | boolean | Không | false | Phân tích cú pháp body của response thành JSON nếu có thể |
| `returnBuffer` | boolean | Không | false | Trả về buffer thô thay vì chuỗi đã giải mã |
| `data` | any | Không | - | Request body (chuỗi hoặc đối tượng, tự động tuần tự hóa thành JSON) |
| `proxy` | string | Không | - | ID proxy từ response trước đó, để cố định cùng một điểm thoát. Truyền lại chính xác chuỗi opaque này. Địa chỉ proxy thô sẽ bị từ chối với `400 Invalid proxy format`. Một số ID không thể ghim: xem [Ghim điểm thoát](#pinning-an-exit). |
| `browser` | string | Không | Chrome | Trình duyệt giả lập: Chrome, Edge, Safari, Firefox hoặc Tor. Xem [Browser profile](#browser-profiles). |
| `os` | string | Không | - | Hệ điều hành giả lập: Windows, macOS, Android hoặc iOS. Tên dòng hệ điều hành sẽ chấp nhận bất kỳ phiên bản nào của nó. |
| `version` | string | Không | newest | Phiên bản trình duyệt giả lập, theo danh mục liệt kê. Bản khớp mới nhất sẽ được chọn khi có nhiều bản phù hợp. |
| `profile` | string | Không | - | ID profile chính xác từ `GET /api/profiles`, thay vì dùng ba trường trên. |
| `validate` | object | Không | - | Quy tắc xác thực response (xem bên dưới) |

### Browser profiles

Theo mặc định, một request sẽ hiển thị Google Chrome mới nhất. Một số đích chấp nhận một trình duyệt nhất định và từ chối trình duyệt khác, do đó `browser`, `os` và `version` sẽ thu hẹp danh mục các profile đã đo lường, và `profile` sẽ chọn một profile theo ID.

```json
{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}
```

Quy tắc:

- Việc lựa chọn yêu cầu `unblocker` (bật theo mặc định). Khi `unblocker` tắt, không có browser header nào được gửi, do đó request sẽ bị từ chối thay vì áp dụng một nửa.
- Khi có nhiều hồ sơ khớp, phiên bản mới nhất sẽ được ưu tiên.
- Một tổ hợp mà danh mục không thể cung cấp sẽ trả về lỗi nêu rõ các tùy chọn khả dụng, và một `profile` id không xác định sẽ trả về `unknown profile '<id>'`. Request không bao giờ được gửi dưới dạng một trình duyệt khác.
- Bốn trường tương tự cũng khả dụng bên trong đối tượng `request` của `POST /proxy/`.

`GET /api/profiles` trả về toàn bộ danh mục và không cần API key:

```json
{
  "profiles": [
    { "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
  ],
  "default": "..."
}
```

`osFamily` là giá trị để lọc khi xây dựng bộ chọn; `os` giữ tên bản phát hành để hiển thị.

### Quy tắc xác thực

Đối tượng `validate` cho phép bạn định nghĩa các điều kiện thành công và thất bại. Nếu một điều kiện `fail` khớp, request sẽ được xử lý như thất bại. Nếu các điều kiện `accept` được thiết lập, chỉ các response khớp mới được coi là thành công.

```json
{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
```

| Trường | Kiểu | Mô tả |
|-------|------|-------------|
| `validate.status.accept` | number[] | Các mã trạng thái HTTP được chấp nhận |
| `validate.status.fail` | number[] | Các mã trạng thái HTTP bị từ chối |
| `validate.headers.accept` | object | Response hợp lệ khi có ít nhất một cặp khớp trên bất kỳ bước chuyển hướng nào. Khóa và giá trị được khớp không phân biệt hoa thường, dựa trên một phần chuỗi. |
| `validate.headers.fail` | object | Các cặp key-value của header gây ra lỗi |
| `validate.data.accept` | string[] | Response hợp lệ khi body chứa ít nhất một trong các chuỗi này |
| `validate.data.fail` | string[] | Các chuỗi trong response body gây ra lỗi |

### Ví dụ

```bash
curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://example.com/products",
    "timeout_ms": 10000
  }'
```

Response:

```json
{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "...", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342
}
```

Khi mục tiêu chạy bước kiểm tra bot trước khi trả về body, response cũng mang theo một đối tượng `defense` nêu rõ nhà cung cấp và liệu quá trình kiểm tra đã được vượt qua hay chưa:

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}
```

| Trường | Loại | Mô tả |
|-------|------|-------------|
| `status` | number | Mã trạng thái HTTP từ máy chủ đích |
| `headers` | array | Một đối tượng cho mỗi chặng chuyển hướng. Mỗi đối tượng có trường `result` chứa dòng trạng thái kèm mọi header phản hồi. Các header có nhiều giá trị (`Set-Cookie`, `Link`, `WWW-Authenticate`) được trả về dưới dạng mảng chuỗi. |
| `data` | string/object | Nội dung body của phản hồi (là JSON nếu `tryJsonData` là true) |
| `total_time` | number | Tổng thời gian thực hiện request tính theo giây |
| `proxy` | string | ID đã mã hóa của proxy mà request đi qua (chỉ xuất hiện khi `proxy` được cung cấp trong request). Sử dụng lại ID này trong lệnh gọi tiếp theo để ghim cùng một cổng ra. |
| `defense` | object | Xuất hiện khi mục tiêu thực hiện kiểm tra bot trên request này, hoặc khi lần thử lại bằng cookie của chính trang web trả về nội dung. `defense.solved` cho biết quy trình kiểm tra đã được vượt qua hay chưa, `defense.retry` cho biết lần thử lại có lấy được nội dung hay không. Xem [Kiểm tra trang web](https://foura.ai/docs/api/site-checks) để biết từng trường và danh sách đầy đủ các hệ thống. |
| `error` | string | Thông báo lỗi nếu request thất bại |

---

## Proxy Request

`POST /api/proxy/`

Định tuyến request của bạn qua các proxy luân phiên và tự động thử lại khi gặp lỗi. Tùy chọn giới hạn phạm vi chọn proxy theo danh sách các quốc gia gửi request đi hiển thị với đích đến.

### Body của Request

| Tham số | Loại | Bắt buộc | Mặc định | Mô tả |
|-----------|------|----------|---------|-------------|
| `request` | object | Có | - | Body của một request đơn lẻ (các trường tương tự như Single Request ở trên) |
| `timeout_ms` | number | Không | 45000 | Thời gian timeout tổng thể cho tất cả các lần thử tính bằng ms (tối đa: 120000) |
| `maxTries` | number | Không | 5 | FourA sẽ dừng bắt đầu các lần thử mới khi đã có số lần thất bại này (tối đa: 90). Các lần thử chạy song song, do đó số lần hoàn tất có thể nhiều hơn con số này một chút. |
| `ignoreProxies` | string[] | Không | - | Danh sách ID proxy cần loại trừ khỏi rotation (sử dụng các ID được trả về từ các response trước) |
| `exitCountries` | string[] | Không | - | Danh sách cho phép nghiêm ngặt gồm các mã quốc gia hai chữ cái hiển thị với đích đến (ví dụ: `["CZ", "GB"]`). Các giá trị được cắt khoảng trắng, chuyển thành chữ hoa và loại bỏ trùng lặp. Các exit thuộc standard pool không rõ quốc gia sẽ bị loại trừ, và standard pool không bao giờ fallback về một quốc gia không được yêu cầu. Exit premium cũng sẽ đi ra từ một trong những quốc gia được liệt kê. |
| `exitClass` | string | Không | - | `standard` hoặc `premium`. `premium` cho phép request nâng cấp lên exit premium khi standard pool gặp khó khăn trên mục tiêu được bảo vệ. Yêu cầu gói dịch vụ có bao gồm exit premium. |
| `exitState` | string | Không | - | Vùng mà exit đi ra. Cần `exitClass: premium` và chính xác một quốc gia trong `exitCountries`. Xem [Vị trí exit](#exit-location). |
| `exitCity` | string | Không | - | Thành phố mà exit đi ra. Cần `exitClass: premium` và chính xác một quốc gia trong `exitCountries`. |
| `exitAsn` | string | Không | - | Mạng mà exit đi ra, theo số AS, ví dụ `8866`. Cần `exitClass: premium` và chính xác một quốc gia trong `exitCountries`. |
| `exitOs` | string | Không | - | `windows`, `android`, `ios` hoặc `mac`: loại thiết bị mà địa chỉ thuộc về. Cần `exitClass: premium`. |
| `exitLifetimeMin` | integer | Không | - | Số phút exit giữ địa chỉ của nó, từ `3` đến `1440`. Cần `exitClass: premium`. |

### Phạm vi exitCountries

Việc lựa chọn sử dụng metadata quốc gia hiển thị với đích đến mới nhất hiện có, thường được làm mới trong khoảng mười phút. Đây không phải là tra cứu vị trí địa lý theo thời gian thực trong lúc gửi request. Không suy đoán quốc gia phục vụ từ địa chỉ host của proxy.

Nếu pool hiện tại không có kết quả khớp với các quốc gia được yêu cầu và request không chỉ định `exitClass: premium`, response sẽ trả về HTTP 200 kèm theo error envelope:

```json
{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}
```

Giữ nguyên scope được yêu cầu và thử lại sau. Chỉ thay đổi hoặc mở rộng phạm vi này khi yêu cầu quốc gia trong quy trình làm việc của bạn thay đổi một cách rõ ràng.

### Ví dụ

```bash
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 3,
    "exitCountries": ["CZ", "GB"],
    "request": {
      "method": "GET",
      "url": "https://example.com/prices"
    }
  }'
```

Response:

```json
{
  "status": 200,
  "headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
  "data": "<!doctype html>...",
  "total_time": 1.204,
  "proxy": "A1B2C3",
  "exitCountry": "CZ",
  "total": 2.341
}
```

| Trường | Loại | Mô tả |
|-------|------|-------------|
| `proxy` | string | Định danh đã mã hóa của proxy được sử dụng. Tái sử dụng giá trị này trên Single request hoặc Browser request bằng cách truyền vào trường `proxy`, hoặc bỏ qua nó trong Proxy request tiếp theo qua `ignoreProxies`. |
| `exitCountry` | string | Mã quốc gia hai chữ cái hiển thị với đích đến của proxy đã xử lý request. Chỉ xuất hiện khi request có thiết lập `exitCountries`, bất kể lớp exit nào đã xử lý nó. Luôn xác minh rằng đó là một trong các mã bạn đã yêu cầu trước khi tin cậy response. |
| `exitClass` | string | Lớp exit nào đã xử lý request này, xuất hiện trên response thành công khi request có chỉ định một lớp. `premium` nghĩa là exit premium đã trả về body; `standard` nghĩa là pool standard đã xử lý. Một lệnh gọi thất bại không phục vụ nội dung nào, do đó nó không chứa `exitClass`; đọc `attemptReport` để biết các lần thử đã gặp phải điều gì. |
| `total` | number | Tổng thời gian thực tế bên ngoài tính bằng giây (float). Bao gồm chọn proxy, thử lại và lần thử thành công. `total_time` chỉ tính riêng request bên trong; `total` luôn >= `total_time`. |
| `profile` | string | Profile trình duyệt mà cơ chế rotation đã chọn, **chỉ** xuất hiện khi nó khác với profile bạn yêu cầu. Vắng mặt nghĩa là request đã gửi đi chính xác như thiết lập ban đầu. Truyền lại id dưới dạng `profile` trong các lệnh gọi tiếp theo để giữ nguyên trình duyệt hoạt động hiệu quả. |
| `error` | string | Thông báo lỗi nếu request thất bại. Khi không khớp scope, `code` là `no_eligible_proxy` và `details.exitCountries` trả lại scope đã chuẩn hóa. |
| `attemptReport` | object | Xuất hiện trên **mọi** lệnh gọi Proxy thất bại. Đếm những gì các lần thử gặp phải, để một pool bị chặn, một pool ngừng hoạt động và một quy tắc `validate` không bao giờ khớp không bị đọc nhầm thành cùng một lỗi. Xem bên dưới. |
| `request` | object | Xuất hiện trên một lệnh gọi Proxy thất bại: request mà FourA đã thực thi, với các giá trị mặc định được điền vào và `ignoreProxies` của bạn như khi bạn gửi đi. |

Tất cả các trường response của Single Request cũng được bao gồm, trong đó có `defense`: một lần thử proxy gặp phải kiểm tra bot sẽ báo cáo tương tự như Single.

### Lý do Lệnh gọi Proxy Thất bại

`Download maxTry limit reached` hiển thị giống nhau bất kể các lần thử diễn ra theo cách nào, vì vậy mọi response Proxy thất bại đều mang theo một `attemptReport` bên cạnh lỗi:

```json
{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
```

| Trường | Loại | Mô tả |
|-------|------|-------------|
| `total` | integer | Số lần thử đã thực hiện |
| `noResponse` | integer | Exit không phản hồi, do đó không bao giờ kết nối được đến trang web |
| `defense` | integer | Trang web đã phản hồi và phát hiện kiểm tra bot trên phản hồi đó |
| `contentRejected` | integer | HTTP 200, không có kiểm tra bot, chỉ bị từ chối bởi `validate.data` của bạn |
| `statusRejected` | integer | Trang web đã phản hồi, không có kiểm tra bot, bị từ chối bởi `validate.status` của bạn |
| `other` | integer | Đã phản hồi, và không thuộc trường hợp nào ở trên |
| `vendors` | string[] | Các nhà cung cấp kiểm tra bot được nhận diện ở bất kỳ đâu trong tác vụ |
| `profilesTried` | string[] | Các hồ sơ trình duyệt mà tác vụ đã gửi, theo thứ tự sử dụng lần đầu. `default` có nghĩa là request của bạn được gửi đi nguyên vẹn. |
| `summary` | string | Một câu được tạo từ số lượng thống kê, an toàn để ghi log |

Chuỗi `error` không thay đổi, vì vậy client khớp với chuỗi này vẫn tiếp tục hoạt động. Hướng dẫn xử lý cho từng số đếm: [Lý do proxy request hết số lần thử](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

### exitClass

Một số mục tiêu từ chối các exit trong pool tiêu chuẩn bất kể đã thử bao nhiêu lần. `exitClass: premium` thông báo cho Proxy rằng nó có thể leo thang request đó lên **premium exit** ngoài pool tiêu chuẩn, thay vì chỉ xoay vòng bên trong pool đó.

```json
{
  "exitClass": "premium",
  "request": { "method": "GET", "url": "https://example.com/report" }
}
```

Có ba điều cần lưu ý trước khi bạn gửi request.

**Đây là một hạn mức cho phép, không phải chỉ thị bắt buộc.** Pool tiêu chuẩn vẫn cạnh tranh xử lý request và thường sẽ thành công trước. Một exit premium chỉ tham gia khi pool đã dùng hết một khoảng ngân sách ngắn cho request hoặc phía đích từ chối rõ ràng. Request mà pool tiêu chuẩn phản hồi thành công trước khi thử bất kỳ exit premium nào sẽ được tính là lượt thành công thông thường và không tốn lưu lượng premium của bạn. Khi một exit premium đã được thử nghiệm, lưu lượng của nó sẽ được tính như mô tả bên dưới.

**Exit premium vẫn tuân theo `exitCountries`.** Với danh sách quốc gia, exit premium sẽ xuất phát từ một trong các quốc gia đó và `exitCountry` trong response sẽ chỉ định cụ thể, tương tự như với pool tiêu chuẩn.

**Response cho biết chính xác thành phần nào đã phục vụ bạn.** Khi bạn chỉ định một class, response sẽ trả về `exitClass`:

```json
{
  "status": 200,
  "exitClass": "premium",
  "proxy": "Y2QXVK",
  "data": "..."
}
```

`premium` có nghĩa là một exit cao cấp đã trả về phần body. `standard` có nghĩa là pool tiêu chuẩn đã trả về, đây cũng là kết quả bạn nhận được khi không thể lấy được exit cao cấp, và khi lưu lượng cao cấp đi kèm trong gói của bạn (cộng với phần mua thêm) đã dùng hết trong chu kỳ thanh toán. Cả hai trường hợp đều không phải là lỗi, và bạn có thể đối soát lưu lượng cao cấp dựa trên các giá trị này cho từng request thay vì dựa trên số liệu hàng tháng. Cùng một giá trị này cũng được gửi trong response header `X-FourA-Exit-Class` (xem [Response Headers](https://foura.ai/docs/api/response-headers#x-foura-exit-class)).

**Lưu lượng cao cấp được đo trên mạng.** Một lượt thử cao cấp sẽ tính lượng dữ liệu đã gửi và nhận khi đi qua mạng, được nén và mã hóa trong quá trình truyền, bất kể nó có trả về trang của bạn hay không. Một lượt thử vẫn đang chạy khi một exit khác đã phản hồi sẽ bị dừng ngay lập tức, và lưu lượng nó đã tải cho đến thời điểm đó cũng được tính. Lưu lượng cao cấp được tính vào hạn mức cao cấp và cũng nằm trong tổng băng thông của bạn: cùng một lượng byte đó, được báo cáo hai lần, không bao giờ cộng dồn lại với nhau. Khi một exit cao cấp đã phân phối trang, lưu lượng của nó là toàn bộ lưu lượng của request, vì vậy trang đó không bị tính lại dưới dạng lưu lượng tiêu chuẩn. Trang [Usage & Limits](https://foura.ai/docs/dashboard/quota) của bạn hiển thị tổng lưu lượng, tỷ lệ cao cấp trong đó, và hạn mức cao cấp dùng để đối chiếu.

Việc bỏ qua trường này và gửi `standard` đều giữ request ở pool tiêu chuẩn: chỉ `premium` mới cho phép dùng exit cao cấp. Một request thành công có chỉ định class sẽ nhận lại `exitClass` trong response, còn request bỏ qua trường này thì không.

**Hết hạn mức không phải là lỗi.** Một request chỉ định `premium` sau khi đã dùng hết hạn mức vẫn tiếp tục hoạt động: pool tiêu chuẩn sẽ phục vụ nó và response sẽ trả về `standard`. Ngoại lệ duy nhất là request chỉ định một [exit location](#exit-location): pool tiêu chuẩn không thể đáp ứng yêu cầu này, vì vậy nó bị từ chối.

`exitClass: premium` cần một gói dịch vụ có bao gồm các exit cao cấp. Trên gói không có các exit này, request sẽ không bao giờ tiêu tốn exit cao cấp: nó bị từ chối với mã 403 kèm `X-FourA-Limit: plan_limit_premium` (xem [Rate Limits](https://foura.ai/docs/api/rate-limits#plan-limits)), trước khi bất kỳ tác vụ nào được thực hiện.


### Vị trí exit

Một exit cao cấp có thể xuất phát từ một địa điểm bên trong một quốc gia, và giữ địa chỉ đó bao lâu tùy theo nhu cầu của bạn:

```json
{
  "exitClass": "premium",
  "exitCountries": ["BG"],
  "exitCity": "sofia",
  "exitLifetimeMin": 15,
  "request": { "method": "GET", "url": "https://example.com/" }
}
```

Response chỉ rõ cổng thoát và quốc gia xuất phát:

```json
{
  "status": 200,
  "exitClass": "premium",
  "exitCountry": "BG",
  "proxy": "1EM4GZY",
  "data": "..."
}
```

ID `proxy` đó giữ lại toàn bộ thông tin này. Truyền nó vào Single hoặc Browser và request sẽ xuất phát từ cùng một vị trí, không cần thêm trường nào khác bên cạnh. Xem [Ghim Exit](#pinning-an-exit).

Quy tắc:

- Bất kỳ trường nào trong số `exitState`, `exitCity`, `exitAsn`, `exitOs` và `exitLifetimeMin` đều gửi request qua các exit premium duy nhất. Pool standard sẽ không được thử, vì nó không thể đáp ứng các trường này.
- Chúng yêu cầu `exitClass: premium`. Nếu không có, request sẽ bị từ chối với mã 400 chỉ rõ tên trường.
- `exitState`, `exitCity` và `exitAsn` tồn tại trong một quốc gia, vì vậy chúng cần chính xác một quốc gia trong `exitCountries`. `exitOs` và `exitLifetimeMin` có thể đi kèm với nhiều quốc gia: exit sẽ chọn một trong số đó, và `exitCountry` trong response sẽ cho biết là quốc gia nào.
- `exitState`, `exitCity`, `exitAsn` và `exitOs` cần một gói dịch vụ hỗ trợ geo targeting cũng như premium exit.
- Khi không còn lưu lượng premium, request sẽ bị từ chối với mã 403 mang `X-FourA-Limit: plan_limit_premium`, vì pool standard không thể xử lý.
- Nếu không có exit premium nào phản hồi cho vị trí đó, response sẽ là một envelope lỗi tương tự như mục trong [phạm vi exitCountries](#exitcountries-scoping), với lỗi `No premium exit answered for this request` và `code: no_eligible_proxy`. `details.exitCountries` sẽ xuất hiện khi bạn đã gửi danh sách quốc gia.

Các từ này là những từ mà [cổng proxy](https://foura.ai/docs/api/proxy-port) chấp nhận cho `state`, `city`, `asn` và `os`.

### Luân chuyển Browser Profile

Proxy luân chuyển các exit. Khi một trang web từ chối trình duyệt mà FourA cung cấp thay vì từ chối exit xuất phát, Proxy cũng sẽ chuyển sang một nhóm trình duyệt khác từ danh mục. Cơ chế này không làm tăng thêm số lần thử: việc luân chuyển chỉ thay đổi nội dung gửi đi khi retry, chứ không quyết định việc có retry hay không.

Proxy cũng ghi nhớ, trong một khoảng thời gian, nhóm trình duyệt mà một trang web đã chấp nhận gần nhất, để lệnh gọi sau đến cùng trang web đó có thể bắt đầu với nhóm đó thay vì mặc định. Response nêu tên nhóm này trong `profile`, tương tự như đối với bất kỳ nhóm nào mà cơ chế luân chuyển đã chọn.

Một giá trị `profile`, `browser`, `os` hoặc `version` rõ ràng trên `request` bên trong của bạn sẽ không bao giờ bị ghi đè, và một request mang header `User-Agent` hoặc `Cookie` riêng cũng vậy, vì quyền truy cập được liên kết với chữ ký đã đạt được nó.

---

## Browser Request

`POST /api/browser/`

Mở URL của bạn trong một phiên trình duyệt Chrome. Trang sẽ tải, JavaScript được thực thi, và bạn nhận được HTML hiển thị đầy đủ kèm theo cookie jar.

### Request Body

| Tham số | Loại | Bắt buộc | Mặc định | Mô tả |
|-----------|------|----------|---------|-------------|
| `url` | string | Có | - | URL đích |
| `headers` | object | Không | - | Header tùy chỉnh dưới dạng các cặp key-value |
| `cookies` | array | Không | - | Cookie cần thiết lập: `[{name, value, domain?}]` |
| `userAgent` | string | Không | - | Chuỗi User-Agent tùy chỉnh |
| `unblocker` | boolean | Không | `true` | Hoàn thành bước kiểm tra mà trang yêu cầu trước khi tải (trang thử thách challenge hoặc cổng chặn tương tự). Bật theo mặc định. Đặt `false` để kết xuất nguyên trạng bất kỳ nội dung nào trang trả về, bao gồm cả trang challenge. |
| `proxy` | string | Không | - | Proxy ID từ response trước đó, dùng để cố định cùng một exit node. Truyền lại chính xác chuỗi opaque này. Địa chỉ proxy thô sẽ bị từ chối với `400 Invalid proxy format`. |
| `timeout_ms` | number | Không | 30000 | Thời gian chờ tải trang tính bằng ms (tối đa: 120000) |
| `checkStatus` | number | Không | - | Trạng thái HTTP mong đợi (request sẽ thất bại nếu nhận mã khác) |
| `checkText` | string | Không | - | Văn bản bắt buộc phải xuất hiện trong trang đã kết xuất |
| `lean` | boolean | Không | `false` | Bỏ qua hình ảnh, font chữ, media và các request gửi đến các dịch vụ quảng cáo, phân tích, chấp thuận cookie và mạng xã hội đã biết. Bản thân trang web, script và style nội bộ, cùng mọi tài nguyên cần cho bước xác minh vẫn sẽ được tải. Dùng tùy chọn này để giảm lưu lượng dữ liệu tiêu tốn, ví dụ như qua một exit node premium cố định. |

### Khớp đồng hồ trình duyệt với exit node

Trang web có thể đọc múi giờ của trình duyệt và so sánh với quốc gia của IP mà nó nhìn thấy. Sự không khớp là một trong những tín hiệu đơn giản nhất mà hệ thống phát hiện bot sử dụng, và bạn hoàn toàn có thể loại bỏ nó mà không mất chi phí gì.

Bạn không cần làm gì cả. FourA tự động đọc quốc gia từ `proxy` ID và trình duyệt sẽ báo cáo múi giờ tương ứng với quốc gia đó.

- Đó là quốc gia của **exit node**, nghĩa là quốc gia mà trang đích nhìn thấy, không phải nơi đặt máy chủ proxy. Hai thông tin này thường xuyên khác nhau.
- Khi FourA không xác định được quốc gia của exit node, hệ thống sẽ giữ nguyên đồng hồ trình duyệt thay vì đoán. Một exit node premium sẽ có quốc gia xác định khi bạn yêu cầu thông qua `exitCountries` trên [Proxy Request](#exit-location).
- Chỉ có đồng hồ tuân theo quốc gia. `Accept-Language` và nội dung trang web phân phát không bị thay đổi, do đó trang sẽ không tự động đổi ngôn ngữ.

### Tham số `userAgent`

Khi gửi `userAgent`, chính xác chuỗi đó sẽ là nội dung mà trang web, worker và máy chủ đích nhìn thấy. FourA cũng tự suy ra các client hints tương ứng (`sec-ch-ua`, `sec-ch-ua-platform`, `navigator.platform` và các giá trị high-entropy mà hệ thống phát hiện yêu cầu theo tên), tránh trường hợp request khai báo một trình duyệt trong header nhưng JavaScript lại báo một trình duyệt khác.

Giá trị `userAgent` trong response chính là giá trị đã được gửi đi. Điều này rất quan trọng khi bạn sử dụng lại clearance: cookie `cf_clearance` được liên kết chặt chẽ với exit node và User-Agent đã vượt qua kiểm tra, vì vậy hãy gửi lại chuỗi mà response trả về, không dùng chuỗi bạn nghĩ là đã sử dụng. Xem [Site checks](https://foura.ai/docs/api/site-checks).

Gửi một chuỗi không phải Chromium (ví dụ như một Firefox User-Agent) và chuỗi đó sẽ được giữ nguyên dạng, không đính kèm danh sách thương hiệu Chromium.

### Ví dụ

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spa-app",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'
```

Response:

```json
{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<!doctype html>...",
  "cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {"present": ["cloudflare"], "cleared": ["cloudflare"]}
}
```

| Trường | Kiểu | Mô tả |
|-------|------|-------------|
| `status` | number | HTTP status code từ target |
| `headers` | object | Response header |
| `body` | string or object | Toàn bộ nội dung trang đã render. Là chuỗi HTML khi content-type là HTML; là object khi trang trả về JSON và được tự động parse. |
| `cookies` | array | Toàn bộ object cookie từ trang. Mỗi cookie bao gồm `name`, `value`, `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite`, cùng các thuộc tính cookie khác. |
| `userAgent` | string | Browser User-Agent đã dùng |
| `defenseSolved` | boolean | `true` nếu gặp cơ chế chống bot và đã vượt qua thực sự trong lệnh gọi này, `false` trong trường hợp còn lại. Xác định lệnh gọi tốn 5 hay 10 credit. |
| `defenses` | object | `present` liệt kê mọi vendor được phát hiện trong quá trình tải trang, `cleared` liệt kê những vendor mà trang cuối cùng đã vượt qua. Một vendor có thể xuất hiện trong `present` nhưng không bao giờ xuất hiện trong `cleared`. Xem [Kiểm tra trang web](https://foura.ai/docs/api/site-checks). |
| `proxy` | string | ID đã mã hóa của proxy mà request đi qua (chỉ khi có `proxy` trong request). Tái sử dụng giá trị này trong các lệnh gọi tiếp theo để giữ nguyên IP đầu ra. |
| `error` | string | Thông báo lỗi nếu request thất bại |

---

## Ghim IP đầu ra

Giá trị `proxy` trong request Single hoặc Browser sẽ ghim IP đầu ra mà lệnh gọi trước đó đã sử dụng. Gửi lại chính xác chuỗi ID ẩn danh này, tuyệt đối không gửi địa chỉ proxy. ID từ một Proxy request từng chỉ định quốc gia, địa điểm hoặc thời gian tồn tại sẽ giữ nguyên các thiết lập đó, do đó request được ghim không cần trường nào khác.

Có ba giá trị bị từ chối, tất cả đều trả về mã 400:

| Lỗi | Ý nghĩa |
|-------|---------|
| `Invalid proxy format` | Giá trị này không phải là ID do FourA phát hành. Nhập địa chỉ proxy thô sẽ rơi vào lỗi này. |
| `Proxy not found` | ID đã được giải mã, nhưng không còn trỏ đến IP đầu ra khả dụng nào. Hãy lấy ID mới từ một lệnh gọi khác. |
| `Managed exit: this proxy id cannot be pinned to a request` | IP đầu ra tồn tại, nhưng không phải là địa chỉ FourA hỗ trợ giữ mở cho một request cụ thể. ID của IP đầu ra premium rơi vào lỗi này khi gói của bạn không còn dung lượng lưu lượng premium. Hãy tái sử dụng session trả về nó, hoặc chạy lệnh gọi qua `POST /api/proxy/` và nhận bất kỳ IP đầu ra nào hệ thống chọn. |

IP đầu ra premium được ghim sẽ được tính là lưu lượng premium. Response trả về `X-FourA-Exit-Class: premium` để bạn có thể theo dõi theo từng request, và lưu lượng qua IP đầu ra đó được tính vào lưu lượng premium trên trang [Sử dụng & Giới hạn](https://foura.ai/docs/dashboard/quota) cũng như tính vào tổng băng thông, bất kể trang web có trả về nội dung bạn muốn hay không. Tính năng ghim yêu cầu gói dịch vụ của bạn hỗ trợ IP đầu ra premium và còn hạn mức; nếu không, ID sẽ bị từ chối kèm lỗi managed-exit 400 ở trên.

## HTTP Status Code

| Mã | Ý nghĩa |
|------|---------|
| 200 | Request đã hoàn thành (kiểm tra `status` bên trong để xem response từ đích) |
| 400 | Body của request không hợp lệ, tham số sai, IP đích nằm trong dải riêng tư/bảo lưu, đích nằm trên host API của chính FourA, URL chứa khoảng trắng chưa được mã hóa (Single, Proxy, Auto), hoặc proxy ID không thể ghim. Trên Single, Proxy và Browser, trường không vượt qua xác thực sẽ được nêu tên: `Invalid request: <field>: <reason>`, tối đa năm trường. Không tính phí. Auto trả lời cho lỗi tương tự bằng HTTP 200 và `status: 400` trong body. |
| 401 | Thiếu hoặc API key không hợp lệ |
| 403 | Endpoint hoặc một tham số không nằm trong gói của bạn. `X-FourA-Limit` sẽ nêu cụ thể: `plan_limit_feature` hoặc `plan_limit_premium`. |
| 404 | `Not Found`: không có endpoint nào tại đường dẫn đó. |
| 413 | Body JSON của request vượt quá 100 KB. Phản hồi không phải là JSON và không chứa `X-FourA-Request-Id`. |
| 429 | Giới hạn gói (có header `X-FourA-Limit`) hoặc hạn mức chia sẻ mỗi phút của nền tảng (không có header) |
| 500 | Lỗi máy chủ nội bộ |
| 502 | `Upstream unavailable`: FourA không thể kết nối tới engine của mình. `Malformed JSON from backend`: engine đã phản hồi nhưng FourA không thể đọc phản hồi đó. Hãy thử lại. |
| 503 | Dịch vụ tạm thời bị vô hiệu hóa hoặc quá tải, `API key check temporarily unavailable` khi FourA tạm thời không thể xác thực key của bạn (thử lại sau `Retry-After`), hoặc `Backend service unavailable` khi một engine đang khởi động lại. Trên Browser, một trang sẽ chờ tối đa 10 giây để có browser rảnh khi tất cả đều bận, và nhận `Backend service unavailable` nếu không có browser nào rảnh trong khoảng thời gian đó. |
| 504 | `Upstream timeout`. Engine không hoàn thành trong khoảng thời gian cho phép của request này. Hãy tăng `timeout_ms` hoặc thử lại. |

## Các bước tiếp theo

- [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch): Khi nào nên để FourA tự chọn đường dẫn cho bạn
- [Chọn endpoint phù hợp](https://foura.ai/docs/guides/choosing-task-type): Khi nào nên tự chọn Single, Proxy, hoặc Browser bằng tay
- [Xác thực](https://foura.ai/docs/getting-started/authentication): Quản lý API key của bạn
- [Xử lý lỗi](https://foura.ai/docs/api/errors): Xử lý lỗi một cách linh hoạt
- [Kiểm tra trang web](https://foura.ai/docs/api/site-checks): Đọc trường `defense` và phát lại clearance
- [Lý do request Proxy hết số lần thử](https://foura.ai/docs/troubleshooting/proxy-attempt-report): Đọc `attemptReport` và xử lý theo đó
- [Rate Limit](https://foura.ai/docs/api/rate-limits): Tìm hiểu về giới hạn request
- [Khởi động nhanh](https://foura.ai/docs/getting-started/quick-start): Request đầu tiên của bạn trong 30 giây
