Header phản hồi

Mọi response từ FourA API đều bao gồm một tập hợp nhỏ các header tùy chỉnh. Chúng hữu ích cho việc truy xuất, hỗ trợ, đối soát thanh toán và phân tích sau sự kiện.

Các header do FourA thiết lập

X-Foura-Request-Id

Mỗi lệnh gọi tới POST /api/auto/, POST /api/single/, POST /api/proxy/ hoặc POST /api/browser/ đều được gắn thẻ bằng một UUID. Header này được thiết lập ngay cả khi xác thực thất bại, do đó bạn cũng có thể tương quan các lệnh gọi bị cấu hình sai.

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/1.1 200 OK
X-Foura-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
X-FourA-Credits: 2
Content-Type: application/json
...

Khi nào nên sử dụng

• Ticket hỗ trợ: đính kèm request ID và chúng tôi có thể tìm thấy chính xác lệnh gọi trong hệ thống ghi nhận.
• Log của riêng bạn: lưu nó cạnh dòng log ứng dụng của bạn. Nếu khách hàng phàn nàn "dữ liệu bị sai lúc 14:32", bạn có thể replay lại chính xác request đó.
• Truy xuất trên dashboard: ID tương tự xuất hiện trong Activity feed cho các key mà bạn quản lý, nhờ đó bạn có thể mở hàng tương ứng và kiểm tra request cũng như response đã ghi lại.

Ví dụ: ghi log ở phía bạn

import logging
import requests

log = logging.getLogger(__name__)

def fetch(url, api_key):
    resp = requests.post(
        "https://eu.api.foura.ai/api/single/",
        headers={"X-API-Key": api_key, "Content-Type": "application/json"},
        json={"method": "GET", "url": url},
    )
    request_id = resp.headers.get("X-Foura-Request-Id", "no-id")
    credits = resp.headers.get("X-FourA-Credits", "0")
    log.info("foura request_id=%s url=%s status=%s credits=%s", request_id, url, resp.status_code, credits)
    resp.raise_for_status()
    return resp.json()

async function fetchPage(url, apiKey) {
  const resp = await fetch('https://eu.api.foura.ai/api/single/', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ method: 'GET', url })
  });

  const requestId = resp.headers.get('X-Foura-Request-Id') || 'no-id';
  const credits = resp.headers.get('X-FourA-Credits') || '0';
  console.log(`foura request_id=${requestId} url=${url} status=${resp.status} credits=${credits}`);

  return resp.json();
}

X-FourA-Credits

X-FourA-Credits báo cáo chi phí credit của lệnh gọi mà bạn vừa thực hiện. Đây là công cụ đo đếm, không phải hóa đơn: header phản ánh mức độ tiêu hao của công việc bất kể kết quả ra sao. Lớp thanh toán trên dashboard chỉ tính các kết quả có thể tính phí vào gói của bạn (xem Request Outcomes để biết kết quả nào bị tính phí).

Tham chiếu chi phí

/api/auto/ không thêm một hàng tính phí riêng. Chi phí credit của nó là tổng số các lệnh gọi phụ mà nó thực hiện nội bộ (một replay đơn lẻ trên một mục tiêu đã warm có thể hoàn thành ở mức 2, một cold solve trên một trang web khó có thể tiêu tốn nhiều hơn). Giá trị X-FourA-Credits trên auto response bằng với meta.credits trong body và theo dõi chi phí của toàn bộ tiến trình.

Tại sao lại có cả trường header và body?

Header rất tiện lợi: bạn có thể đọc nó trước khi phân tích cú pháp body, ghi log cạnh dòng request của bạn, hoặc tính tổng qua nhiều lệnh gọi mà không cần phân tích cú pháp JSON. meta.credits (Auto) của body hoặc metadata theo engine (các dashboard Single, Proxy, Browser) chứa cùng một con số, nhưng có thể đọc được bên trong response envelope.

Hành vi Cache

API không thiết lập Cache-Control hoặc ETag trên các response. Mọi lệnh gọi đều đi tới backend. Nếu bạn cần cache, hãy thêm nó ở phía bạn.

Các Response Header của mục tiêu

Các header mà trang web mục tiêu trả về không nằm trên response của FourA API. Chúng được trả về bên trong JSON envelope dưới dạng trường headers. Đối với các endpoint Single và Proxy, đây là một mảng các đối tượng header trên mỗi hop (một mục nhập cho mỗi bước chuyển hướng). Đối với endpoint Browser, đó là một đối tượng phẳng chứa các response header cuối cùng.

{
  "status": 200,
  "headers": [
    { "Content-Type": "text/html; charset=utf-8", "Server": "..." }
  ],
  "data": "<!doctype html>...",
  "total_time": 0.42
}

Nếu bạn cần một header mục tiêu cụ thể, hãy đọc nó từ trường headers của envelope, không phải từ HTTP response của bản thân lệnh gọi API.

Liên quan

• API Endpoints: Hình dạng của request và response envelope
• API Errors: Cách các error response được cấu trúc
• Request Outcomes: Những kết quả nào bị tính phí
• Activity Log: Lịch sử theo mỗi request được lập chỉ mục bằng request ID