Escolhendo o endpoint certo

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

Guia Rápido de Decisão

Use o endpoint auto quando:

• Você estiver acessando um site novo e ainda não souber do que ele precisa
• Você quiser uma única chamada que gerencie fallbacks direto, com rotação de proxy e via browser para você
• Você quiser uma session que possa reutilizar com baixo custo na próxima chamada para o mesmo host

Use o endpoint single quando:

• A página for renderizada no servidor (sem necessidade de JavaScript)
• Você precisar de velocidade máxima (geralmente abaixo de 1 segundo)
• Você estiver acessando APIs ou páginas HTML estáticas de um host que você já sabe que funciona

Use o endpoint browser quando:

• A página depender de JavaScript para renderizar o conteúdo
• O conteúdo for carregado após o carregamento inicial da página
• Você precisar do DOM totalmente renderizado

Use o endpoint proxy quando:

• O site de destino bloquear requests ativamente
• Você precisar alternar entre múltiplos endereços IP
• Tentativas anteriores retornarem 403 ou páginas de verificação

Comparação de Endpoints

Auto (POST /api/auto/)

O endpoint de busca inteligente. Você envia uma URL e (idealmente) uma regra validate, e o FourA percorre uma escala que prioriza o custo: primeiro um proxy com rotação, depois um browser completo via proxy. Defina forceProxy: false para executar uma sondagem direta econômica e uma renderização direta via browser antes de ambos. O primeiro nível que retornar uma response correspondente ao seu validate vence. Em chamadas repetidas para o mesmo host, uma session ativa é reutilizada, tornando a segunda chamada econômica.

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 resposta típico: 200ms (warm) a 30s+ (resolução a frio em site difícil) Ideal para: Novos alvos, sites com proteção mista, "só quero a página"

Para um guia detalhado, consulte o guia do Smart Fetch.

Single (POST /api/single/)

A opção mais rápida. Envia uma request HTTP com características de rede realistas semelhantes às de um navegador, sem inicializar um processo de navegador.

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 resposta típico: 200ms a 2s Ideal 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 navegador Chrome. A página carrega completamente, o JavaScript é executado e você recebe 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 resposta típico: 2s a 10s Ideal 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, o FourA tenta novamente usando 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 resposta típico: 1s a 5s Ideal 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 modo auto escolher, e quando deve chamar Single, Proxy ou Browser manualmente?

O modo auto nem sempre é a opção mais barata. Se você já sabe que um destino funciona com Single e unblocker ativado, chamar Single diretamente pula o probe e custa 2 créditos. O modo auto no mesmo destino custa o total consumido por sua ladder.

Quando Combinar Abordagens

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

1. Descubra com auto: envie uma regra validate e deixe a ladder descobrir qual nível o site exige.
2. Repita com single: pegue o session.proxy, session.cookies e session.userAgent retornados pelo auto e chame Single com eles para as páginas seguintes no mesmo host.
3. Faça fallback para browser: se o single começar a falhar, mude para renderização via browser.
4. Adicione proxy: se você estiver recebendo recusas (403 ou uma página de verificação) sem o auto, envolva sua request no endpoint de proxy para rotação automática.

Essa abordagem progressiva mantém os custos baixos enquanto garante altas taxas de sucesso.

Dicas de Performance

• Passe uma substring validate.data.accept em destinos protegidos. O modo auto reconhece páginas de desafio comuns por conta própria, mas apenas a sua regra pode identificar uma página de verificação desconhecida ou uma página carregada sem o conteúdo necessário.
• Use o endpoint single por padrão para hosts que sabidamente funcionam e só faça upgrade quando necessário.
• Defina checkText em requests de browser para que uma página renderizada sem o seu conteúdo retorne como falha (checkText:<text> not found) em vez de sucesso. checkText não faz o FourA esperar mais tempo pelo texto.
• 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, 30s+ para execuções a frio com auto em sites protegidos.

Próximos Passos

• Smart Fetch (Auto): O guia detalhado sobre /api/auto/
• Endpoints da API: Referência completa de parâmetros
• Fazer Scraping de um Site Dinâmico: Guia passo a passo de requests com browser
• Início Rápido: Sua primeira request em 30 segundos