# Escolhendo o endpoint certo

> URL: https://foura.ai/pt/docs/guides/choosing-task-type
> Updated: 2026-11-05
> Index: https://foura.ai/llms.txt

O FourA oferece quatro endpoints de request, cada um otimizado para um cenário diferente. Escolher o endpoint 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 novo site e ainda não souber o que ele exige
- Você quiser uma única chamada que gerencie fallbacks com rotação de proxy e 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 conteúdo
- O conteúdo carregar 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 erro 403 ou páginas de verificação

## Comparação de Endpoints

### Auto (`POST /api/auto/`)

O endpoint de smart-fetch. Você envia uma URL e (idealmente) uma regra `validate`, e o FourA percorre uma sequência otimizada por custo: primeiro um proxy rotativo, depois um browser completo via proxy. Defina `forceProxy: false` e uma verificação direta econômica, além de uma renderização direta via browser, serão executadas antes de ambos. O primeiro nível que retornar uma response compatível com sua regra `validate` vence. Em chamadas repetidas para o mesmo host, uma warm session é reutilizada, tornando a segunda chamada econômica.

```bash
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:** 200 ms (warm) a 30s+ (cold solve em sites difíceis)
**Ideal para:** Novos alvos, sites com proteções mistas, "só preciso da página"

Para um passo a passo mais aprofundado, consulte o [guia do Smart Fetch](https://foura.ai/docs/guides/smart-fetch).

### Single (`POST /api/single/`)

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

```bash
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

### Navegador (`POST /api/browser/`)

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

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

```bash
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?

| Escolha auto | Escolha manual |
|-----------|-------------|
| Você ainda não sabe o que o site precisa | Você sabe exatamente qual engine o alvo requer |
| Você quer uma única chamada que simplesmente funcione | Você está otimizando o formato da request para um alvo conhecido |
| Não há problema em o auto reutilizar uma sessão aprendida | Você quer controle total sobre retry por chamada, timeout e escolha de proxy |
| Você aceita pagar por alguns segundos de sondagem na primeira chamada | A latência na primeira chamada importa mais do que a descoberta |

O modo auto nem sempre é a opção mais barata. Se você já sabe que um alvo funciona com Single e `unblocker` ativado, chamar Single diretamente pula a sequência de testes e custa 2 créditos. O modo auto no mesmo alvo custa o que a sequência de testes consumir.

## Quando Combinar Abordagens

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

1. **Descubra com auto**: passe uma regra `validate` e deixe a sequência identificar qual nível o site precisa.
2. **Repita com single**: pegue o `session.proxy`, `session.cookies` e `session.userAgent` retornados pelo auto e chame Single com eles para as próximas páginas no mesmo host.
3. **Recorra ao 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.

Esta abordagem progressiva mantém os custos baixos e as taxas de sucesso altas.

## Dicas de Desempenho

- Passe uma substring `validate.data.accept` em alvos protegidos. O auto reconhece as páginas de desafio comuns por conta própria, mas apenas sua regra pode capturar 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 você já sabe que funcionam e faça upgrade apenas 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 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` em um valor razoável: 10 a 15 segundos para a maioria das páginas, 30s+ para execuções a frio do auto contra sites protegidos.

## Próximos Passos

- [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch): Visão aprofundada sobre `/api/auto/`
- [Endpoints da API](https://foura.ai/docs/api/endpoints): Referência completa de parâmetros
- [Fazer Scraping de um Site Dinâmico](https://foura.ai/docs/how-to/scrape-dynamic-website): Guia passo a passo para requests com browser
- [Início Rápido](https://foura.ai/docs/getting-started/quick-start): Sua primeira request em 30 segundos
