Reutilizar um proxy entre requisições

Saiba como manter a mesma saída de proxy em requisições seguintes, para que renderizações de JavaScript, chamadas de API e coletas paginadas saiam todas do mesmo IP.

Por que reutilizar um proxy

Ao acessar um alvo pela primeira vez, o FourA escolhe um proxy funcional para você. Uma resposta do Proxy ou Auto inclui o ID do proxy utilizado. Envie esse ID de volta em requisições posteriores e:

  • Páginas seguintes chegam pela mesma saída, mantendo cookies de sessão e rate limits coerentes para o alvo.
  • Uma coleta com escopo de país permanece dentro da sua allowlist sem precisar de uma nova seleção.
  • O endpoint econômico POST /api/single/ repete o tráfego por um proxy cuja descoberta você já pagou, com o custo do Single em vez do Proxy.

O ID do proxy é uma string base36 opaca (algo como A1B2C3). Nunca um IP bruto.

Onde o ID fica em uma resposta

Endpoint Campo Quando está presente
POST /api/auto/ session.proxy Quando returnSession for true (o padrão)
POST /api/single/ proxy (nível superior) Somente quando a requisição forneceu um campo proxy
POST /api/proxy/ proxy (nível superior) Sempre, em caso de sucesso
POST /api/browser/ proxy (nível superior) Somente quando a requisição forneceu um campo proxy

Para obter uma saída nova sem fixar nenhuma, comece com Auto ou Proxy. Ambos descobrem uma saída funcional e retornam o ID dela para você.

Padrão 1: Auto descobre, Single repete

Ideal para alvos desconhecidos. O Auto percorre a sequência de tentativas uma vez, e depois o Single reutiliza a sessão bem-sucedida para cada página seguinte.

import requests

API = "https://eu.api.foura.ai"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

# Step 1: discover a working exit with Auto.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
}).json()

session = r.get("session") or {}
proxy = session.get("proxy")
user_agent = session.get("userAgent")

# Step 2: paginate with Single, reusing the same exit, User-Agent and cookies.
for sku in ("43", "44", "45"):
    body = {"method": "GET", "url": f"https://example.com/product/{sku}"}
    if proxy:
        body["proxy"] = proxy
    headers = []
    if user_agent:
        headers.append(["User-Agent", user_agent])
    if session.get("cookies"):
        headers.append(["Cookie", "; ".join(f"{c['name']}={c['value']}" for c in session["cookies"])])
    if headers:
        body["headers"] = headers
    p = requests.post(f"{API}/api/single/", headers=H, json=body).json()
    print(sku, p["status"])

Leia a sessão com .get(). Uma sessão obtida por uma busca simples via proxy possui proxy e nenhum userAgent, e algumas respostas não trazem nenhum session.

A chamada Auto custa o que sua hierarquia consumir. Cada chamada Single subsequente custa 2 créditos (Single com unblocker, o padrão).

Padrão 2: O Proxy descobre, o Browser renderiza pela mesma saída

Use isso quando o destino precisar ver um país de saída específico e o conteúdo final exigir JavaScript.

# Step 1: pick a country-scoped exit with Proxy.
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "exitCountries": ["FR", "GB"],
    "request": {"method": "GET", "url": "https://example.com/pricing"}
  }'
# Response includes: "proxy": "A1B2C3", "exitCountry": "FR"

# Step 2: render the JS-heavy page through THAT exit.
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/pricing",
    "proxy": "A1B2C3",
    "timeout_ms": 20000
  }'

Não chame /api/proxy/ novamente para atualizar a seleção. Uma nova chamada pode escolher um exit diferente e anular o objetivo da fixação. Se o exit fixado parar de funcionar, execute uma nova chamada /api/proxy/ para escolher um novo e continue com ele.

Padrão 3: Ignorar um exit queimado

Se um exit que funcionava começar a retornar recusas ou páginas de verificação, instrua o FourA a evitá-lo na próxima seleção.

{
  "maxTries": 5,
  "ignoreProxies": ["A1B2C3"],
  "request": { "method": "GET", "url": "https://example.com/data" }
}

ignoreProxies aceita uma lista de IDs de proxy de respostas anteriores. Funciona em /api/proxy/ e /api/auto/. A lista é respeitada em cada nova tentativa interna, portanto, uma única chamada com ignoreProxies nunca escolhe as saídas queimadas.

Quanto Tempo Dura uma Sessão Fixada

A própria saída permanece ativa enquanto o proxy subjacente estiver íntegro, normalmente de minutos a horas. Se um replay começar a retornar desafios, bloqueios ou redirecionamentos inesperados, a saída provavelmente foi rotacionada ou o destino renovou sua liberação.

Duas opções quando isso acontecer:

  1. Nova chamada /api/auto/ para a mesma URL. O Auto descobrirá uma nova sessão funcional; descarte os IDs anteriores.
  2. Nova chamada /api/proxy/ com ignoreProxies: ["<burned-id>"] se você quiser continuar fixando manualmente.

Cookies de sessão de uma resposta do Auto também expiram de acordo com o cronograma do próprio destino. Alguns sites mantêm a liberação por horas; outros por minutos. Trate a sessão como um cache, não como um token durável.

Quando um ID Não Fixa

Três erros 400 podem retornar de um valor proxy, e eles significam coisas diferentes:

Error O que aconteceu O que fazer
Invalid proxy format O valor não é um ID emitido pela FourA. Um endereço de proxy bruto cai aqui. Envie a string opaca de uma resposta, literalmente.
Proxy not found O ID foi decodificado, mas não resolve mais para uma saída ativa. Obtenha uma nova saída a partir de uma nova chamada Auto ou Proxy.
Managed exit: this proxy id cannot be pinned to a request O ID é uma saída premium, e o tráfego premium do seu plano para este período esgotou, ou seu plano não inclui saídas premium. Execute a chamada através de POST /api/proxy/ e use a saída que ele escolher, ou adicione tráfego premium e fixe novamente.

O terceiro caso retorna de um ID fornecido por uma chamada bem-sucedida, portanto você pode encontrá-lo sem ter feito nada de errado. Trate-o da mesma forma que trataria uma sessão expirada: use como fallback uma nova chamada de descoberta em vez de tentar o mesmo ID novamente.

Erros Comuns

  • Reutilizar um ID de proxy entre contas. Não compartilhe IDs entre contas: um ID que uma conta consegue fixar pode ser recusado para outra, por exemplo, uma saída premium em um plano sem tráfego premium.
  • Tentar decodificar o ID. A string base36 é opaca. Não faça parse dela, não remova caracteres, não converta para minúsculas. Envie-a de volta exatamente como recebida.
  • Fixar através de uma saída com rate limit. Se o destino aplicar rate limit por IP, afunilar muitas requests através de uma única saída causará bloqueios mais rápido. Para cargas de trabalho de alto volume, deixe o Auto ou o Proxy alternar entre várias saídas e fixe apenas quando o destino realmente exigir.
  • Fixar uma saída premium sem intenção. Um ID de uma chamada atendida por uma saída premium (exitClass: "premium" no Proxy ou Auto) fixa uma saída premium. Um ID de uma chamada Auto premium fixa uma saída premium no Single ou Browser, mas não necessariamente o endereço que o Auto usou. Cada replay através dele consome seu tráfego premium, e a response inclui X-FourA-Exit-Class: premium.
  • Enviar exitCountries em um plano sem geo targeting. A definição de escopo por país está incluída a partir do plano Startup. Em um plano sem esse recurso, uma chamada que envia exitCountries é recusada com um 403 e X-FourA-Limit: plan_limit_feature.
  • Ignorar exitCountries no acompanhamento. Se você fixar uma saída com escopo definido e depois chamar o Proxy novamente sem exitCountries, a chamada seguinte pode ocorrer através de um país diferente. Mantenha o escopo em cada chamada que precisar dele.
Atualizado em: 5 de novembro de 2026