Escolhendo o endpoint certo

A FourA oferece quatro request endpoints, cada um otimizado para um cenário diferente. Escolher o certo economiza tempo, reduz custos e melhora as taxas de sucesso.

Guia rápido de decisão

Use o endpoint auto quando:

• Você acessa um novo site e ainda não sabe do que ele precisa
• Você quer uma única chamada que lide com fallbacks diretos, de proxy rotacionado e de browser para você
• Você quer uma sessão que possa repetir de forma barata na próxima chamada para o mesmo host

Use o endpoint single quando:

• A página é renderizada no servidor (sem necessidade de JavaScript)
• Você precisa de velocidade máxima (geralmente menos de 1 segundo)
• Você acessa APIs ou páginas HTML estáticas de um host que você já sabe que funciona

Use o endpoint browser quando:

• A página depende de JavaScript para renderizar o conteúdo
• O conteúdo carrega após o carregamento inicial da página
• Você precisa do DOM totalmente renderizado

Use o endpoint proxy quando:

• O site alvo bloqueia ativamente as requests
• Você precisa rotacionar por múltiplos endereços IP
• Tentativas anteriores retornaram 403 ou páginas de CAPTCHA

Comparação de endpoints

Auto (POST /api/auto/)

O endpoint smart-fetch. Você passa uma URL e (idealmente) uma regra validate, e a FourA percorre uma escada consciente do custo: probe direto barato, proxy rotacionado, browser completo. O primeiro degrau que retorna uma response correspondente ao seu validate vence. Em chamadas repetidas para o mesmo host, uma sessão quente é repetida, então a segunda chamada é barata.

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"]}}
  }'

Tempo de response típico: 200ms (quente) a mais de 30s (resolução fria em um site difícil) Melhor para: Novos alvos, sites com proteção mista, "eu só quero a página"

Para um guia mais detalhado, veja o guia Smart Fetch.

Single (POST /api/single/)

A opção mais rápida. Envia uma request HTTP com características de rede realistas semelhantes a um browser, sem iniciar um processo de browser.

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/api/products"}'

Tempo de response típico: 200ms a 2s Melhor para: APIs, sites de notícias, blogs, páginas estáticas de produtos

Browser (POST /api/browser/)

Abre sua URL em uma instância do browser Chrome. A página carrega completamente, o JavaScript é executado, e você obtém o HTML final renderizado.

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": "data-table"
  }'

Tempo de response típico: 2s a 10s Melhor para: Single-page apps (SPAs), sites com lazy loading, conteúdo renderizado por JavaScript

Proxy (POST /api/proxy/)

Combina requests HTTP com rotação automática de proxy. Se a primeira tentativa falhar ou for bloqueada, a FourA tenta novamente através de proxies diferentes.

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,
    "request": {
      "method": "GET",
      "url": "https://example.com/pricing"
    }
  }'

Tempo de response típico: 1s a 5s Melhor para: Monitoramento de preços de e-commerce, agregação de viagens, sites com detecção de bots

Auto vs Manual

Quando você deve deixar o auto escolher, e quando você mesmo deve chamar Single, Proxy ou Browser?

Auto nem sempre é a escolha mais barata. Se você já sabe que um alvo funciona com Single e unblocker ativado, chamar Single diretamente pula o probe e custa 2 créditos. Auto no mesmo alvo custa o que a sua escada gastar.

Quando combinar abordagens

Alguns fluxos de trabalho se beneficiam do uso de múltiplos endpoints:

1. Descobrir com auto: passe uma regra validate e deixe a escada descobrir de qual degrau o site precisa.
2. Repetir com single: pegue o session.proxy, session.cookies e session.userAgent que o auto retornou, então chame Single com eles para as próximas páginas no mesmo host.
3. Fallback para browser: se o single começar a falhar, mude para renderização de browser.
4. Adicionar proxy: se você estiver sendo bloqueado (403 / CAPTCHA) sem auto, envolva sua request no endpoint proxy para rotação automática.

Essa abordagem progressiva mantém o custo baixo enquanto mantém as taxas de sucesso altas.

Dicas de performance

• Passe uma substring validate.data.accept em alvos protegidos. Sem ela, o auto não consegue diferenciar uma página real de um intersticial de desafio.
• Use o endpoint single por padrão para hosts conhecidos que funcionam e só faça upgrade quando necessário.
• Defina checkText em requests de browser para evitar esperar por conteúdo desnecessário.
• Defina maxTries em requests de proxy para controlar o comportamento de retry (o padrão é 5, o máximo é 90).
• Mantenha timeout_ms razoável: 10 a 15 segundos para a maioria das páginas, mais de 30s para execuções frias de auto contra sites protegidos.

Próximos passos

• Smart Fetch (Auto): O aprofundamento em /api/auto/
• API Endpoints: Referência completa de parâmetros
• Scrape a Dynamic Website: Guia passo a passo de request de browser
• Quick Start: Sua primeira request em 30 segundos