Response Headers

Cada response da API da FourA inclui um pequeno conjunto de headers personalizados. Eles são úteis para rastreamento, suporte, reconciliação de faturamento e análise a posteriori.

Headers que a FourA Define

X-Foura-Request-Id

Cada chamada para POST /api/auto/, POST /api/single/, POST /api/proxy/ ou POST /api/browser/ é marcada com um UUID. O header é definido mesmo quando a autenticação falha, para que você possa correlacionar chamadas mal configuradas também.

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
...

Quando usar

• Tickets de suporte: inclua o ID do request e podemos encontrar a chamada exata em nossos registros.
• Seus próprios logs: armazene-o junto à linha de log da sua aplicação. Se uma reclamação de cliente disser "os dados estavam errados às 14:32", você pode refazer o request exato.
• Rastreamento no dashboard: o mesmo ID aparece no Activity feed para chaves que você gerencia, para que você possa abrir a linha correspondente e inspecionar o request e a response capturados.

Exemplo: log no seu lado

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 relata o custo em créditos da chamada que você acabou de fazer. É um medidor, não uma fatura: o header reflete o que o trabalho gastou independentemente do resultado. A camada de faturamento do dashboard apenas conta os resultados faturáveis no seu plano (veja Request Outcomes para saber quais resultados são faturáveis).

Referência de custo

/api/auto/ não adiciona uma linha faturável separada. Seu custo de créditos é a soma das subchamadas que fez internamente (um único replay em um alvo aquecido pode terminar em 2; uma resolução a frio em um site difícil pode gastar muito mais). O valor X-FourA-Credits na response auto é igual a meta.credits no body e rastreia o custo total da escada.

Por que um header e um campo no body?

O header é conveniente: você pode lê-lo antes de fazer o parse do body, registrá-lo próximo à linha do seu request ou somá-lo em várias chamadas sem o parse do JSON. O meta.credits do body (Auto) ou metadados por motor (dashboards Single, Proxy, Browser) contêm o mesmo número, mas legível dentro do envelope da response.

Comportamento de Cache

A API não define Cache-Control ou ETag nas responses. Toda chamada atinge o backend. Se você precisa de caching, adicione-o do seu lado.

Headers da Response do Alvo

Os headers que o site alvo retornou não estão na response da API da FourA. Eles retornam dentro do envelope JSON como o campo headers. Para os endpoints Single e Proxy, este é um array de objetos de header por salto (uma entrada por etapa de redirecionamento). Para o endpoint Browser, é um objeto plano dos headers da response final.

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

Se você precisar de um header do alvo específico, leia-o a partir do campo headers do envelope, não da response HTTP da própria chamada de API.

Relacionado

• API Endpoints: Formatos do envelope de request e response
• API Errors: Como as responses de erro são estruturadas
• Request Outcomes: Quais resultados são faturáveis
• Activity Log: Histórico por request indexado por ID de request