Configuração de proxy no Postman passo a passo

Você geralmente abre o Postman para testar uma API, e a requisição sai direto do seu computador. Em alguns casos, porém, a requisição precisa vir de outro endereço IP: a API responde de forma diferente a requisições de um país específico, a rede da empresa só permite acessar a internet por um proxy ou você está testando a restrição por IP de uma integração. O Postman oferece duas formas de lidar com isso: usar a configuração de proxy do sistema operacional ou definir um proxy específico para o Postman.

Neste artigo, explicamos onde o Postman guarda as configurações de proxy, como definir um proxy próprio passo a passo, como adicionar usuário e senha e como verificar se o proxy está realmente funcionando. Depois, vemos a lista de bypass, os erros de conexão mais comuns e o uso de proxy com o Newman na linha de comando.

Como o Postman usa um proxy?#

O Postman envia as requisições de API que você faz de dentro do aplicativo de desktop. Se essas requisições passam por um proxy é decidido pelas configurações da aba Settings > Proxy. Segundo a documentação de proxy do Postman, há duas opções para enviar requisições por um proxy:

• Proxy do sistema (Use the system proxy): o Postman usa a configuração de proxy do sistema operacional e as variáveis de ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY. É prático se todos os aplicativos do computador já passam pelo mesmo proxy.
• Proxy próprio (Use custom proxy configuration): você define um proxy para o Postman independentemente do sistema operacional. É a opção certa se só os testes de API devem passar pelo proxy, deixando o navegador e os outros aplicativos intactos.

Segundo a documentação, se as duas opções estiverem ligadas, o Postman usa o proxy próprio. Para evitar confusão, recomendamos deixar desligada a opção que você não usa.

A interface do Postman pode mudar entre versões. Os nomes de menus e campos deste artigo seguem a documentação atual do Postman; em outra versão, você pode ver pequenas diferenças.

Como definir um proxy próprio?#

1. Abra o aplicativo de desktop do Postman, clique no ícone de engrenagem no canto superior direito e vá em Settings.
2. Na janela que abrir, mude para a aba Proxy.
3. Na seção de envio de requisições, ative Use custom proxy configuration.
4. Em Use proxy for, escolha para qual tráfego o proxy será usado. Quase todas as APIs são HTTPS, então garanta que HTTPS esteja selecionado; marcar as duas caixas é a escolha mais segura.
5. Em Proxy server, escolha primeiro o protocolo. Para APIs web, HTTP geralmente basta. Se usar um proxy SOCKS5, prefira SOCKS5H para que a resolução de nomes de domínio aconteça do lado do proxy.
6. Na mesma linha, informe o endereço e a porta do servidor proxy, por exemplo pr.proxynet.io e 8000.
7. Se o proxy exigir usuário e senha, siga os passos da próxima seção.
8. As configurações são salvas automaticamente. Feche a janela e envie uma requisição para testar.

A documentação do Postman observa que só requisições HTTP e HTTPS podem ser enviadas por um proxy SOCKS. Para outros tipos de requisição, como WebSocket ou gRPC, é preciso testar o comportamento do proxy separadamente.

Como adicionar autenticação?#

Há duas formas de se conectar a um proxy: com usuário e senha, ou adicionando o endereço IP do seu computador a uma lista de permitidos no painel. Comparamos os dois métodos e a segurança de cada um em Autenticação de proxy: user:pass ou whitelist de IP.

Com usuário e senha:

1. Na aba Proxy, ative Proxy auth.
2. Digite as credenciais do seu painel nos campos Username e Password.
3. Digite a senha nesses campos como ela é, sem codificação. Codificações como %40, necessárias para senhas escritas dentro de um endereço, não são necessárias aqui; o Postman pega as credenciais de campos separados e monta o cabeçalho Proxy-Authorization sozinho.

Com whitelist de IP:

1. Com o proxy desligado, descubra o endereço IP público do seu computador. Enviar uma requisição GET para https://api.ipify.org no Postman basta.
2. Adicione esse endereço à lista de IPs permitidos no painel do cliente.
3. Deixe Proxy auth desligado no Postman.

Se o IP da sua conexão doméstica mudar, a whitelist deixa de funcionar depois de um tempo; nesse caso, mudar para usuário e senha dá menos trabalho.

Como verificar se o proxy está funcionando?#

Depois de salvar as configurações, envie uma requisição a um endereço que retorna o seu IP para ver se a requisição realmente passa pelo proxy.

1. Abra uma nova aba de requisição e deixe o método como GET.
2. Digite https://httpbin.org/ip na barra de endereço e clique em Send.
3. Veja o valor origin no corpo da resposta.

{
  "origin": "203.0.113.25"
}

Esse deve ser o IP de saída do proxy. Se aparecer o seu próprio endereço IP, a requisição não está passando pelo proxy; confira se o botão do proxy próprio está ligado e se HTTPS está selecionado em Use proxy for.

Para ver os detalhes de uma requisição, abra o Postman Console (botão Console na barra inferior). O console mostra os cabeçalhos enviados, o tempo de resposta e o texto completo de qualquer erro de conexão. É o primeiro lugar para olhar ao depurar.

Você pode fazer a mesma verificação pela linha de comando. Se uma requisição não funciona no Postman, testar o mesmo proxy com cURL mostra rapidamente se o problema está nas configurações do Postman ou no proxy:

curl -x "http://user:pass@pr.proxynet.io:8000" https://httpbin.org/ip

Se o cURL funciona e o Postman não, o problema está nas configurações do Postman. Se o cURL também falha, confira as credenciais do proxy ou a sua rede. As opções de proxy do cURL estão em Como usar proxy com cURL.

Para que serve a lista de bypass?#

O campo Proxy bypass recebe uma lista, separada por vírgulas, de endereços que não devem passar pelo proxy. Ele é mais necessário nestas situações:

• Servidor de desenvolvimento local. Quando você testa a sua API rodando em localhost:3000, enviar a requisição ao proxy não faz sentido; o proxy não consegue chegar a um endereço da sua rede local.
• Serviços internos. Serviços internos do bloco 10.0.0.0 ou com nomes .local.
• Servidores de autenticação. Se o serviço de onde você obtém um token não tem restrição por IP e só a requisição principal da API precisa passar pelo proxy.

Valor de exemplo:

localhost,127.0.0.1,*.company.local,10.0.0.5

Endereços locais que você esquece de adicionar à lista de bypass dão timeout enquanto o proxy está ligado ou terminam em uma página de erro devolvida pelo proxy.

Testar respostas de API por localização#

Um dos motivos mais comuns para usar proxy no Postman é ver como uma API responde a requisições de países diferentes. Um serviço de preços pode mudar a moeda, uma API de conteúdo o idioma e o catálogo, e um serviço de pagamentos os métodos aceitos conforme o país de origem da requisição.

Uma rotina prática para esses testes:

1. Prepare dados de proxy separados para cada país.
2. No Postman, crie um Environment para cada país e guarde como variáveis a moeda, o idioma e outros valores esperados.
3. Mude a configuração de proxy para o ponto de saída do país testado.
4. Escreva na aba Tests da requisição uma verificação que compare o valor esperado.

pm.test("A moeda corresponde ao país", () => {
  const body = pm.response.json();
  pm.expect(body.currency).to.eql(pm.environment.get("expectedCurrency"));
});

A configuração de proxy do Postman vale para o aplicativo inteiro, não por environment. Ao trocar de país, você também precisa mudar o endereço do proxy na tela Settings. Se você testa muitos países com frequência, automatizar com o Newman, como mostrado abaixo, é mais prático. A configuração de testes de localização está na nossa página de solução de localização, e os cenários gerais de teste de aplicativos, na nossa página de solução de testes de aplicativos.

Se cada teste precisa de um IP de saída diferente, dá para usar um Proxies rotativos, que entrega um IP novo a cada conexão sem mudar o endereço. Se o IP precisa se manter durante todo o teste, escolha um endereço fixo.

Erros comuns e soluções#

Uma observação sobre verificação SSL. Uma solução muito sugerida na internet é desligar SSL certificate verification na tela Settings. Um forward proxy normal transporta o tráfego HTTPS por um túnel CONNECT e não mexe em certificados, então com um proxy padrão você não deveria ter erro de certificado. Se tiver, algo no meio está descriptografando o tráfego. Adicionar o certificado desse sistema, em vez de desligar a verificação, evita que você deixe passar um problema real de segurança.

O significado geral dos códigos de status HTTP e a lógica de novas tentativas estão em Códigos de status HTTP no web scraping.

Usar proxy na linha de comando com o Newman#

O Newman, usado para rodar coleções do Postman em pipelines de CI ou tarefas agendadas, não lê as configurações de proxy do aplicativo de desktop. O README do Newman diz que ele usa as variáveis de ambiente padrão de proxy: HTTP_PROXY, HTTPS_PROXY e NO_PROXY.

No Linux e no macOS:

export HTTPS_PROXY="http://user:pass@pr.proxynet.io:8000"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1"

newman run collection.json -e environment-de.json

No Windows PowerShell:

$env:HTTPS_PROXY = "http://user:pass@pr.proxynet.io:8000"
$env:HTTP_PROXY = $env:HTTPS_PROXY
$env:NO_PROXY = "localhost,127.0.0.1"

newman run collection.json -e environment-de.json

Como o endereço na variável de ambiente é uma URL, caracteres como @, : ou / na senha precisam ser codificados: @ vira %40.

Um script que testa países diferentes em sequência pode rodar a mesma coleção trocando a cada vez a variável de ambiente e o arquivo de environment do Postman:

#!/usr/bin/env bash
set -euo pipefail

for country in de fr tr; do
  export HTTPS_PROXY="http://user-${country}:pass@pr.proxynet.io:8000"
  newman run collection.json -e "environment-${country}.json" --reporters cli,junit \
    --reporter-junit-export "result-${country}.xml"
done

O formato user-${country} é só um exemplo; se o país é escolhido pelo usuário, por outra porta ou pelo painel depende do provedor. O formato certo está no painel do cliente. Se você usa a ferramenta de linha de comando mais nova do Postman, o Postman CLI, consulte a documentação dela para as configurações de proxy.

Casos de uso#

• Uma equipe que testa o comportamento de uma API por localização: roda a mesma coleção com pontos de saída em países diferentes. Para APIs web, um Proxies HTTPS basta.
• Um desenvolvedor que valida uma integração restrita por IP: se o outro lado só aceita requisições de um IP fixo específico, ele passa o Postman por um proxy com esse IP e testa a integração antes de ir para produção.
• Um usuário em rede corporativa: se a empresa só permite acessar a internet por proxy, a opção de proxy do sistema basta; com inspeção TLS, adiciona-se o certificado da empresa.
• Uma equipe de QA que examina o comportamento de limites de taxa: verifica como uma API responde a requisições seguidas do mesmo IP e se retorna corretamente o cabeçalho Retry-After.

Guia de decisão#

Perguntas frequentes#

O aplicativo web do Postman tem configuração de proxy?#

Segundo a documentação do Postman, o proxy padrão do próprio Postman não pode ser configurado no aplicativo web; para enviar requisições, usam-se as opções de proxy do sistema ou proxy próprio. O aplicativo de desktop é mais prático para ver e controlar todas as configurações em uma única tela.

Dá para definir um proxy só para uma coleção?#

No aplicativo de desktop, a configuração de proxy vale para o aplicativo inteiro; não é definida por coleção nem por environment. Se coleções diferentes precisam de proxies diferentes, passar ao Newman uma variável de ambiente diferente a cada execução é o jeito mais limpo.

O proxy afeta a sincronização do Postman enquanto está ligado?#

O Postman mantém configurações separadas para o próprio tráfego, que sincroniza com a sua conta, e para as requisições de API que você envia. A configuração descrita neste artigo é para as requisições que você envia.

A minha senha tem caracteres especiais. Coloco dentro do endereço?#

No aplicativo de desktop do Postman, digite a senha no campo Password sem codificar. No Newman, a senha vai dentro da URL na variável de ambiente, então @, : e / precisam ser codificados.

Por que as minhas requisições ficaram mais lentas com proxy?#

Cada requisição tem um salto a mais, e a diferença fica perceptível quando o ponto de saída do proxy está longe da API testada. O indicador de tempo de resposta do Postman e o console mostram se o tempo vai para a conexão ou para a resposta do servidor.

Escolho SOCKS5 ou HTTP?#

Se você só envia requisições de API HTTP e HTTPS pelo Postman, um proxy HTTP basta e é o que dá menos problema. Se você só tem um proxy SOCKS5, use a opção SOCKS5H. A diferença entre os dois protocolos está em SOCKS ou HTTP proxy.

Em resumo#

No Postman, o proxy é configurado na aba Settings > Proxy, usando a configuração do sistema operacional ou uma configuração própria do Postman. Para um proxy próprio, informe servidor, porta e protocolo; se houver autenticação, digite a senha sem codificação no campo dela. Confirme a configuração com uma requisição para https://httpbin.org/ip, adicione os endereços locais à lista de bypass e use a variável de ambiente HTTPS_PROXY no Newman em pipelines de CI. Para entender como os proxies funcionam em geral, veja O que é um servidor proxy e como ele funciona?; para planos adequados aos seus testes de API, conheça os nossos serviços de proxy.