Integração de Proxy com Clientes REST API: Configuração do Postman, Insomnia, cURL e HTTPie

Ao desenvolver e testar APIs, muitas vezes é necessário enviar solicitações através de servidores proxy. Isso pode ser necessário para contornar restrições geográficas, testar o comportamento da API de diferentes regiões, garantir anonimato ou trabalhar com serviços que bloqueiam IPs de data centers. Neste guia, vamos discutir como configurar corretamente um proxy em clientes REST API populares e evitar erros comuns.

Vamos analisar quatro das ferramentas mais populares para trabalhar com APIs: Postman (interface gráfica para a maioria dos desenvolvedores), Insomnia (uma alternativa moderna com uma interface amigável), cURL (ferramenta clássica de linha de comando) e HTTPie (cliente CLI moderno com sintaxe legível). Para cada ferramenta, forneceremos exemplos de código e discutiremos as particularidades da configuração.

Quais tipos de proxy são adequados para trabalhar com APIs

Antes de configurar um proxy em clientes de API, é importante entender qual tipo de proxy é adequado para sua tarefa. Os clientes REST API suportam dois protocolos principais: HTTP/HTTPS e SOCKS5. A escolha depende das exigências específicas da API e do nível de segurança necessário.

Proxies HTTP/HTTPS operam no nível do protocolo HTTP e são ideais para a maioria das solicitações REST API. Eles entendem a estrutura do tráfego HTTP, podem armazenar em cache respostas e modificar cabeçalhos. Proxies HTTPS, além disso, criptografam a conexão entre o cliente e o servidor proxy, o que é importante ao transmitir dados sensíveis, como chaves de API ou tokens de autorização.

Proxies SOCKS5 operam em um nível mais baixo e transmitem qualquer tipo de tráfego sem modificação. Eles são mais lentos que os proxies HTTP, mas oferecem melhor anonimato e são adequados para casos em que a API utiliza protocolos não padrão ou quando é necessária total transparência na conexão. SOCKS5 também suporta tráfego UDP, embora isso raramente seja necessário para REST APIs.

Configuração de proxy no Postman: configurações globais e locais

O Postman é a ferramenta gráfica mais popular para trabalhar com REST APIs, utilizada por milhões de desenvolvedores. Ele suporta duas maneiras de configurar proxies: configurações globais (aplicadas a todas as solicitações) e configurações em nível de ambiente. Vamos analisar ambas as opções em detalhes.

Configuração global de proxy no Postman

As configurações globais de proxy estão no menu Configurações (ícone de engrenagem no canto superior direito). Este método é conveniente quando você deseja que todas as solicitações do Postman sempre passem pelo mesmo servidor proxy. Instruções passo a passo:

1. Abra o Postman e clique no ícone de engrenagem (Configurações) no canto superior direito
2. Vá para a aba "Proxy"
3. Ative a opção "Add a custom proxy configuration"
4. Escolha o tipo de proxy: HTTP, HTTPS ou SOCKS5
5. Insira o endereço do servidor proxy (por exemplo: proxy.example.com)
6. Especifique a porta (geralmente 8080 para HTTP, 1080 para SOCKS5)
7. Se o proxy exigir autenticação, ative "Proxy Auth" e insira login/senha
8. Clique em "Save" e feche a janela de configurações

Após isso, todas as solicitações do Postman passarão automaticamente pelo proxy especificado. Uma característica importante: o Postman também envia telemetria e verifica atualizações através do proxy, o que pode gerar tráfego adicional. Se você estiver usando um proxy com tráfego limitado, isso deve ser considerado.

Configuração de proxy através de variáveis de ambiente

Uma maneira mais flexível é usar variáveis de ambiente. Isso permite alternar rapidamente entre diferentes proxies para diferentes projetos ou APIs. Crie um novo ambiente e adicione as seguintes variáveis:

PROXY_HOST = proxy.example.com
PROXY_PORT = 8080
PROXY_USER = seu_usuario
PROXY_PASS = sua_senha

Em seguida, nas configurações globais de proxy, use essas variáveis em vez de valores específicos: {{PROXY_HOST}} e {{PROXY_PORT}}. Agora você pode criar vários ambientes (por exemplo, "Production Proxy", "Testing Proxy", "US Proxy") e alternar entre eles com um clique.

Uso do proxy do sistema

O Postman também pode usar as configurações de proxy do seu sistema operacional. Para isso, nas configurações de Proxy, selecione a opção "Use System Proxy". Isso é conveniente se você já configurou um proxy a nível de sistema (por exemplo, através das configurações do Windows ou macOS) e deseja que o Postman use as mesmas configurações que o navegador.

Configuração de proxy no Insomnia

O Insomnia é uma alternativa moderna ao Postman com uma interface limpa e código aberto. A configuração de proxy no Insomnia é um pouco diferente do Postman e requer a edição do arquivo de configuração ou o uso de variáveis de ambiente. Vamos discutir ambos os métodos.

Configuração através de variáveis de ambiente

A maneira mais simples de configurar um proxy no Insomnia é usar as variáveis de ambiente padrão HTTP_PROXY e HTTPS_PROXY. O Insomnia lê automaticamente essas variáveis do sistema. Defina-as antes de iniciar o Insomnia:

Linux/macOS:

export HTTP_PROXY="http://usuario:senha@proxy.example.com:8080"
export HTTPS_PROXY="http://usuario:senha@proxy.example.com:8080"
insomnia

Windows (PowerShell):

$env:HTTP_PROXY = "http://usuario:senha@proxy.example.com:8080"
$env:HTTPS_PROXY = "http://usuario:senha@proxy.example.com:8080"
insomnia

Observe o formato da URL: mesmo para proxies HTTPS, a esquema http:// é usada, e não https://. Este é um acordo padrão para variáveis de ambiente de proxy. Se o proxy não exigir autenticação, a URL será mais curta: http://proxy.example.com:8080.

Configuração de proxy SOCKS5

Para proxies SOCKS5, use a variável de ambiente ALL_PROXY:

export ALL_PROXY="socks5://usuario:senha@proxy.example.com:1080"

O Insomnia suporta SOCKS5, mas nem todas as versões lidam corretamente com a autenticação SOCKS5. Se você tiver problemas com SOCKS5 autenticado, tente usar um proxy HTTP ou atualize o Insomnia para a versão mais recente.

Configuração através do arquivo de configuração

Para uma configuração de proxy permanente, você pode editar o arquivo de configuração do Insomnia. A localização do arquivo depende do sistema operacional:

• Windows: %APPDATA%\Insomnia\config.json
• macOS: ~/Library/Application Support/Insomnia/config.json
• Linux: ~/.config/Insomnia/config.json

Abra o arquivo em um editor de texto e adicione a seção proxy:

{
  "proxy": {
    "http": "http://usuario:senha@proxy.example.com:8080",
    "https": "http://usuario:senha@proxy.example.com:8080"
  }
}

Após editar, reinicie o Insomnia. As configurações de proxy serão aplicadas a todas as solicitações automaticamente.

Uso de proxy no cURL: exemplos de comandos

O cURL é uma ferramenta clássica de linha de comando para trabalhar com HTTP, que está instalada em praticamente todos os sistemas Unix-like e Windows 10+. Ele suporta proxies através do parâmetro -x ou --proxy. Vamos analisar diferentes cenários de uso.

Uso básico de proxy HTTP

Um exemplo simples de uso de um proxy HTTP sem autenticação:

curl -x http://proxy.example.com:8080 https://api.example.com/users

O parâmetro -x indica o endereço e a porta do servidor proxy. O cURL determinará automaticamente que este é um proxy HTTP e configurará a conexão. Se você quiser especificar explicitamente o protocolo, use a URL completa:

curl --proxy http://proxy.example.com:8080 https://api.example.com/users

Proxy com autenticação

Se o proxy exigir autenticação com login e senha, adicione-os à URL do proxy ou use o parâmetro -U:

# Método 1: login e senha na URL
curl -x http://usuario:senha@proxy.example.com:8080 https://api.example.com/users

# Método 2: parâmetro -U (mais seguro, não é salvo no histórico de comandos)
curl -x http://proxy.example.com:8080 -U usuario:senha https://api.example.com/users

O segundo método é preferível, pois o login e a senha não aparecerão no histórico de comandos do shell. Para ainda mais segurança, você pode especificar apenas o login, e o cURL solicitará a senha interativamente:

curl -x http://proxy.example.com:8080 -U usuario https://api.example.com/users
# cURL solicitará a senha: Enter proxy password for user 'usuario':

Uso de proxy SOCKS5

Para proxies SOCKS5, especifique explicitamente o protocolo na URL:

# SOCKS5 sem autenticação
curl -x socks5://proxy.example.com:1080 https://api.example.com/users

# SOCKS5 com autenticação
curl -x socks5://usuario:senha@proxy.example.com:1080 https://api.example.com/users

# SOCKS5h (resolvendo DNS através do proxy)
curl -x socks5h://proxy.example.com:1080 https://api.example.com/users

A diferença entre socks5:// e socks5h://: no primeiro caso, a resolução DNS ocorre localmente (na sua máquina), enquanto no segundo, através do servidor proxy. Use socks5h:// se quiser ocultar completamente as consultas DNS do seu provedor.

Requisições POST através do proxy

O proxy funciona da mesma forma para todos os métodos HTTP. Exemplo de uma requisição POST com dados JSON através do proxy:

curl -x http://proxy.example.com:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com"}' \
  https://api.example.com/users

Para enviar arquivos, use o parâmetro -F:

curl -x http://proxy.example.com:8080 \
  -X POST \
  -F "file=@document.pdf" \
  -F "description=Important document" \
  https://api.example.com/upload

Uso de variáveis de ambiente

Em vez de especificar o proxy em cada comando, você pode usar variáveis de ambiente. O cURL lê automaticamente http_proxy, https_proxy e all_proxy:

# Definir variáveis de ambiente
export http_proxy="http://usuario:senha@proxy.example.com:8080"
export https_proxy="http://usuario:senha@proxy.example.com:8080"

# Agora todos os comandos cURL usam automaticamente o proxy
curl https://api.example.com/users

# Desativar o proxy para um comando específico
curl --noproxy "*" https://api.example.com/users

O parâmetro --noproxy permite excluir determinados domínios do proxy. Por exemplo, para não usar o proxy para localhost e domínios internos:

export no_proxy="localhost,127.0.0.1,.internal.company.com"

Configuração de proxy no HTTPie

O HTTPie é uma alternativa moderna ao cURL com sintaxe legível e saída colorida. É especialmente conveniente para trabalhar interativamente com APIs no terminal. O HTTPie suporta proxies através do parâmetro --proxy ou variáveis de ambiente.

Uso básico de proxy

A sintaxe do HTTPie para proxies é um pouco diferente do cURL. É necessário especificar o protocolo e a URL do proxy separadamente:

# Proxy HTTP
http --proxy=http:http://proxy.example.com:8080 \
     --proxy=https:http://proxy.example.com:8080 \
     GET https://api.example.com/users

# Forma abreviada (se o proxy for o mesmo para HTTP e HTTPS)
http --proxy=all:http://proxy.example.com:8080 GET https://api.example.com/users

Formato: --proxy=protocol:proxy_url. Para solicitações HTTPS, geralmente é usado um proxy HTTP (não HTTPS), este é o comportamento padrão.

Proxy com autenticação

Para autenticação, adicione login e senha à URL do proxy:

http --proxy=all:http://usuario:senha@proxy.example.com:8080 \
     GET https://api.example.com/users

O HTTPie também suporta o parâmetro --proxy-auth para especificar as credenciais de forma mais explícita, mas nas versões mais recentes esse parâmetro é considerado obsoleto, e é recomendado incluir a autenticação na URL.

Proxies SOCKS5 no HTTPie

O HTTPie suporta proxies SOCKS5 a partir da versão 2.0.0. Certifique-se de que você tem a versão mais recente instalada:

# Verificar versão do HTTPie
http --version

# Atualizar HTTPie via pip
pip install --upgrade httpie

# Usar proxy SOCKS5
http --proxy=all:socks5://proxy.example.com:1080 GET https://api.example.com/users

Para SOCKS5 com autenticação, será necessário instalar a biblioteca adicional pysocks:

pip install pysocks
http --proxy=all:socks5://usuario:senha@proxy.example.com:1080 \
     GET https://api.example.com/users

Requisições POST e envio de dados

O HTTPie tem uma sintaxe conveniente para requisições POST. Exemplo de envio de JSON através do proxy:

# POST com JSON (HTTPie determina automaticamente o Content-Type)
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/users \
     name="John Doe" \
     email="john@example.com" \
     age:=30

# Envio de arquivo
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/upload \
     file@document.pdf \
     description="Important document"

Observe a sintaxe: key=value para strings, key:=value para números e valores booleanos, key@file para arquivos.

Uso de variáveis de ambiente

Assim como o cURL, o HTTPie lê as variáveis de ambiente padrão http_proxy e https_proxy:

export http_proxy="http://usuario:senha@proxy.example.com:8080"
export https_proxy="http://usuario:senha@proxy.example.com:8080"

# Agora todos os comandos usam automaticamente o proxy
http GET https://api.example.com/users

Para desativar temporariamente o proxy, use o parâmetro --proxy= (valor vazio):

http --proxy= GET https://api.example.com/users

Autenticação de proxy: login e senha

A maioria dos serviços de proxy comerciais exige autenticação para proteção contra uso não autorizado. Existem dois métodos principais de autenticação: Autenticação Básica (login/senha) e Lista de IPs Permitidos (vinculação ao endereço IP). Vamos discutir as características de cada método e como configurá-los corretamente em clientes de API.

Autenticação Básica (login e senha)

A Autenticação Básica é o método mais comum. O servidor proxy exige login e senha a cada conexão. As credenciais são transmitidas no cabeçalho Proxy-Authorization no formato Base64. Todos os clientes de API modernos geram automaticamente esse cabeçalho se você especificar login e senha na URL do proxy.

Formato da URL com autenticação:

protocol://usuario:senha@proxy_host:proxy_port

Exemplos para diferentes protocolos:

# Proxy HTTP
http://usuario123:senha456@proxy.example.com:8080

# Proxy HTTPS (usa o mesmo formato)
http://usuario123:senha456@proxy.example.com:8080

# Proxy SOCKS5
socks5://usuario123:senha456@proxy.example.com:1080

Lista de IPs Permitidos (vinculação ao IP)

Alguns provedores de proxy oferecem autenticação por endereço IP. Nesse caso, você adiciona seu IP à lista de permitidos no painel de controle do proxy, e o servidor permite conexões apenas desse IP sem login e senha. Isso é mais conveniente e seguro, pois não é necessário transmitir credenciais em cada solicitação.

Ao usar a Lista de IPs Permitidos, o formato da URL do proxy é simplificado:

# Sem login e senha
http://proxy.example.com:8080

# Exemplo em cURL
curl -x http://proxy.example.com:8080 https://api.example.com/users

A desvantagem desse método é que se seu IP for dinâmico (muda ao reconectar à internet), você terá que atualizar a lista de permitidos a cada vez. Para servidores com IP estático, essa é a opção ideal.

Caracteres especiais na senha

Se a senha do proxy contiver caracteres especiais (@, :, /, ?), eles precisam ser codificados no formato de URL encoding (percent encoding). Por exemplo:

Exemplo de uso de uma senha com caracteres especiais:

# Senha original: P@ss:w0rd/123
# Senha codificada: P%40ss%3Aw0rd%2F123

curl -x http://usuario:P%40ss%3Aw0rd%2F123@proxy.example.com:8080 \
     https://api.example.com/users

Para codificação automática, você pode usar ferramentas online de codificação de URL ou um comando em Python:

python3 -c "import urllib.parse; print(urllib.parse.quote('P@ss:w0rd/123'))"
# Saída: P%40ss%3Aw0rd%2F123

Resolução de problemas comuns e erros

Ao trabalhar com proxies em clientes de API, frequentemente surgem erros comuns. Vamos discutir os problemas mais comuns e como resolvê-los.

Erro "407 Proxy Authentication Required"

Este erro significa que o servidor proxy requer autenticação, mas as credenciais não foram fornecidas ou estão incorretas. Soluções:

• Verifique a correção do login e senha no painel de controle do provedor de proxy
• Certifique-se de que os caracteres especiais na senha estão codificados (veja a seção acima)
• Verifique o formato da URL: http://usuario:senha@host:port
• Se você estiver usando a Lista de IPs Permitidos, verifique se seu IP atual está adicionado à lista

Exemplo de diagnóstico no cURL com saída detalhada:

curl -v -x http://usuario:senha@proxy.example.com:8080 https://api.example.com/users
# A flag -v (verbose) mostrará todos os cabeçalhos e o processo de autenticação

Erro "Connection timeout" ou "Failed to connect"

Este erro ocorre quando o cliente API não consegue estabelecer uma conexão com o servidor proxy. Possíveis causas:

• Endereço ou porta do servidor proxy incorretos — verifique as configurações com o provedor
• Servidor proxy indisponível ou sobrecarregado — tente outro servidor da lista
• Seu firewall está bloqueando conexões de saída na porta do proxy
• O provedor de proxy bloqueou seu IP por exceder limites

Para diagnóstico, tente conectar-se ao proxy diretamente através do telnet ou nc:

# Verificar a disponibilidade do proxy
telnet proxy.example.com 8080
# ou
nc -zv proxy.example.com 8080

# Se a conexão não for estabelecida, o problema está na rede ou o servidor proxy está indisponível

Erro "SSL certificate problem"

Ao usar proxies HTTPS, podem ocorrer problemas com a verificação de certificados SSL. Isso é especialmente relevante para proxies MITM (Man-in-the-Middle), que interceptam e descriptografam o tráfego HTTPS. Soluções:

• No cURL, use a flag -k ou --insecure para desativar a verificação do certificado (apenas para testes!)
• No Postman, desative "SSL certificate verification" em Configurações → Geral
• Instale o certificado raiz do proxy no sistema (para ambiente de produção)

# Desativar a verificação do certificado SSL
curl -k -x http://usuario:senha@proxy.example.com:8080 https://api.example.com/users