# Porta do Proxy

> URL: https://foura.ai/pt/docs/api/proxy-port
> Updated: 2026-10-15
> Index: https://foura.ai/llms.txt

Envie seu próprio tráfego pelas saídas da FourA a partir de qualquer cliente que aceite uma URL de proxy: um navegador, uma ferramenta de download, um scraper que você já executa. A porta de proxy abre um túnel para o destino especificado e copia bytes em ambas as direções, transmitindo o que a API JSON não suporta: streams, downloads grandes e sessões inteiras de navegador.

## Conectando

| Configuração | Valor |
|---------|-------|
| Host | `proxy.foura.ai` |
| Port | `34004` |
| Protocol | HTTP CONNECT com autenticação Basic |
| Target ports | `443` e `80` |

As credenciais são obtidas no dashboard. Crie um usuário de proxy em **Proxy** na barra lateral para gerar um username e senha. Eles são separados da sua chave de API de propósito: o handshake do proxy trafega em texto não criptografado a cada conexão, e um usuário de proxy pode ser rotacionado sem afetar sua integração com a API. Consulte [Proxy Users](https://foura.ai/docs/dashboard/proxy).

```bash
curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 https://example.com
```

```python
import requests

proxy = "http://USERNAME:PASSWORD@proxy.foura.ai:34004"
r = requests.get("https://example.com", proxies={"https": proxy, "http": proxy})
print(r.status_code)
```

A porta aceita apenas CONNECT. Um destino `https://` é encapsulado por qualquer cliente. Um destino `http://` comum funciona quando seu cliente também o encapsula (curl: `--proxytunnel`); um cliente que, em vez disso, encaminha a requisição comum para o proxy recebe `405 Method Not Allowed`.

## Opções são passadas no Username

Tudo após a credencial é uma lista de pares `-key-value`, em qualquer ordem:

```
USERNAME-network-premium-country-de-session-a1
```

Os valores são palavras em minúsculas. Um traço dentro de um valor inicia uma nova opção, portanto `-city-new-york` é interpretado como duas opções e é recusado. Uma chave desconhecida também é recusada, nunca descartada: um `-contry-de` digitado incorretamente retorna como um 400 que lista as chaves suportadas, em vez de ser atendido a partir do país incorreto.

| Opção | Valores | O que faz |
|--------|--------|-----------|
| `network` | `shared` (padrão, alias `pool`), `premium` (alias `residential`) | De qual rede o endereço se origina. Shared são as saídas próprias da FourA, incluídas no seu plano. Premium são endereços residenciais, extraídos do tráfego premium que o seu plano inclui mais o que você comprar. |
| `fallback` | `premium` (alias `residential`), `off` | Apenas rede compartilhada. Usa uma saída premium quando a rede compartilhada não puder transportar a request. Desativado a menos que solicitado, e só é acionado quando o seu plano inclui tráfego premium e há cota disponível. |
| `country` | ISO 3166-1 alpha-2, repetível | O país de saída que o destino visualiza. Repita para um escopo de múltiplos países: `-country-de-country-fr`. |
| `session` | 1 a 32 letras, dígitos ou sublinhados | Conexões compartilhando um nome compartilham um endereço (sticky). Omita para um novo endereço por conexão (rotating). |
| `state` | uma palavra | Região. Apenas premium. |
| `city` | uma palavra | Cidade. Apenas premium. |
| `asn` | um número | Rede, pelo número de AS. Apenas premium. |
| `os` | `windows`, `android`, `ios`, `mac` | O tipo de dispositivo ao qual o endereço pertence. Apenas premium. |
| `lifetime` | `3` a `1440` | Minutos que um endereço premium sticky é mantido. Apenas premium. |

Todas as opções, exceto `network`, `fallback` e `session`, aceitam `any`, que limpa um valor salvo no usuário proxy para esta única conexão.

Três combinações são recusadas com um 400 em vez de serem atendidas parcialmente:

- `state`, `city`, `asn`, `os` ou `lifetime` na rede compartilhada. A rede compartilhada é selecionada por país e nada mais específico; adicione `-network-premium` para direcionar a uma cidade.
- `-fallback-premium` junto com `-network-premium`. Um fallback não tem função na rede para a qual ele faz o fallback.
- Segmentação mais precisa com um fallback ativo. Um fallback pode ou não ser acionado, logo uma cidade que ele só poderia atender às vezes é recusada.

### Sessões

Na rede compartilhada, uma sessão nomeada mantém a mesma saída pelo tempo em que você continuar usando-a, em uma janela deslizante de dez minutos. Se essa saída parar de funcionar, a sessão migra para outra em vez de falhar. Um navegador controlado através da porta deve sempre conter um nome de sessão: o carregamento de uma página abre dezenas de conexões e, sem uma sessão, cada uma sai de um endereço diferente.

Na rede premium, uma sessão nomeada retém seu endereço por `lifetime` minutos, ou pelo padrão da rede quando você não define um.

### Padrões salvos

A segmentação salva em um proxy user no painel se aplica a cada conexão feita com ele, permitindo que o username continue curto. Qualquer valor inserido no username prevalece para essa conexão específica, e `any` redefine para o valor salvo. Um padrão premium salvo consome saldo apenas quando o seu plano permite; caso contrário, a conexão é atendida pela rede compartilhada e o túnel ainda é aberto.

### CONNECT headers

Um cliente que pode adicionar headers à request CONNECT pode enviar as mesmas opções como headers. Um header tem prioridade sobre a mesma opção definida no username.

| Header | Same as |
|--------|---------|
| `X-Foura-Network` | `-network-` |
| `X-Foura-Fallback` | `-fallback-` (`premium` or `off`) |
| `X-Foura-Country` | `-country-`, comma-separated for several |
| `X-Foura-Session` | `-session-` |
| `X-Foura-State` | `-state-` |
| `X-Foura-City` | `-city-` |
| `X-Foura-Asn` | `-asn-` |
| `X-Foura-Lifetime` | `-lifetime-` |

```bash
curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 \
  --proxy-header "X-Foura-Country: de" \
  https://example.com
```

## Responses

Um túnel que se abre responde `200 Connection established`. Toda recusa feita após a verificação das suas credenciais contém um header `X-Foura-Error` com o motivo em uma linha, portanto leia esse header antes de qualquer outra coisa.

| Status | Quando |
|--------|------|
| 400 Bad Request | Uma request malformada ou uma opção que a FourA não pode atender. `X-Foura-Error` especifica a opção e os valores suportados. |
| 403 Forbidden | A porta de destino não é atendida, o destino não é um host da internet pública, a porta não está inclusa no seu plano ou você definiu `-network-premium` e seu plano não tem tráfego premium restante ou não inclui a rede premium. |
| 405 Method Not Allowed | Uma request comum em vez de CONNECT. |
| 407 Proxy Authentication Required | Credenciais ausentes ou incorretas. A resposta nunca diz qual parte estava errada. |
| 408 Request Timeout | O client conectou e não enviou nada por 15 segundos. |
| 431 Request Header Fields Too Large | Os headers da request CONNECT ultrapassaram 16 KB. |
| 429 Too Many Requests | Um dos limites do seu plano: túneis abertos simultaneamente, aberturas de túnel por minuto ou o tráfego padrão para este período de faturamento. Também ocorre quando a própria porta atinge sua capacidade ou taxa de abertura. `X-Foura-Error` informa qual deles. |
| 502 Bad Gateway | Nenhuma saída funcional foi encontrada para esse destino dentro do limite de tempo de seleção, ou o próprio resolver da FourA não conseguiu consultar o host. Os dois casos geram mensagens diferentes em `X-Foura-Error`. |
| 503 Service Unavailable | A porta do proxy está desativada. |

## Limits

- Túneis abertos simultaneamente e aberturas de túnel por minuto dependem do seu plano e são contabilizados por conta, e não por usuário de proxy: emitir uma segunda credencial não concede uma franquia adicional. Seus números estão em [Usage & Limits](https://foura.ai/docs/dashboard/quota).
- Encontrar uma saída leva até 45 segundos antes de a porta desistir com um erro 502. Uma sessão que já possui uma saída normalmente se conecta em bem menos de um segundo.
- Um túnel sem tráfego de bytes em nenhuma das direções é encerrado após dois minutos de inatividade.
- Quando a porta é atualizada, os túneis já abertos têm pouco menos de três minutos para finalizar e depois são encerrados, enquanto novas conexões continuam abrindo. Downloads longos ou transmissões contínuas devem se reconectar quando o túnel fechar.
- Um usuário de proxy que você desativar ou excluir no dashboard para de se autenticar dentro de um minuto.

## Metering

Os bytes que passam pela porta contam para a largura de banda na sua página [Usage & Limits](https://foura.ai/docs/dashboard/quota), e os bytes por uma saída premium também contam para o seu tráfego premium: são os mesmos bytes, reportados duas vezes, nunca somados. Quando um túnel abre, o tráfego de saídas premium que a porta tentou mas não utilizou também conta como tráfego premium. Tentativas não utilizadas na rede compartilhada não são contabilizadas, e nada é contabilizado quando nenhum túnel abre.

O tráfego padrão que a porta pode usar é o do seu plano. Em um plano vendido por créditos, a porta tem seus próprios gigabytes incluídos, e a página Billing vende pacotes adicionais; em um plano vendido por tráfego, ela consome do mesmo pool da API. Quando esse limite acaba, novas conexões são recusadas até que o período seja reiniciado ou você adicione mais, e os e-mails de uso informam quando isso ocorre.

Assim que a franquia premium se esgota, as três formas de acesso a essa rede recebem respostas distintas, propositalmente. Uma conexão que especifica `-network-premium` é recusada com um 403 informando o motivo, pois um cliente que solicitou gastar créditos e foi atendido silenciosamente por outra rota continuaria fazendo requisições e tentando conciliar um consumo premium que nunca aparece. Um fallback não é acionado, e um padrão premium salvo no proxy user sofre downgrade para a rede compartilhada, que ainda abre o túnel: nenhuma dessas opções escolheu gastar créditos nesta conexão específica.

## Related

- [Proxy Users](https://foura.ai/docs/dashboard/proxy): Crie proxy users e monte uma connection string no dashboard
- [Proxy Request](https://foura.ai/docs/api/endpoints#proxy-request): A alternativa via JSON API, com retentativas e validação integradas
- [Reuse a Proxy Across Requests](https://foura.ai/docs/how-to/reuse-a-proxy): Mantendo uma única saída na JSON API
- [Usage & Limits](https://foura.ai/docs/dashboard/quota): Largura de banda e tráfego premium em relação ao seu plano