Como configurar proxy 4G no Postman e no cURL para testar APIs

Quando uma API responde de um jeito para quem acessa de fora do Brasil e de outro para o usuário local, a equipe precisa ver exatamente o que o usuário brasileiro recebe. Este guia mostra como configurar proxy no Postman e cURL usando o proxy móvel 4G dedicado da Proxy Brazil, com porta HTTP ou SOCKS5, usuário e senha. Ele também mostra como provar que a chamada saiu pelo proxy, como proteger credenciais e como diagnosticar os erros mais comuns.

Para testar uma API a partir do Brasil, o proxy 4G precisa estar no cliente da requisição

O proxy só altera a origem das chamadas feitas pelo cliente que você configurou. Se o cURL ou o Postman não estiver apontado para ele, a requisição sai pela sua rede normal. Para entender por que o IP pesa em testes de integração, leia por que o IP pesa em APIs. Aqui o foco é a prática.

O que você precisa ter antes de começar

Reúna estes dados, todos disponíveis no painel da Proxy Brazil:

• O host do proxy.
• A porta HTTP e a porta SOCKS5.
• O usuário e a senha.

O IP é de uma operadora móvel brasileira (Claro, TIM ou Vivo) e é dedicado ao seu uso. Não é possível escolher a cidade do IP, então o teste vale para o país e para a rede móvel, não para uma cidade específica.

Qual cliente usar: cURL para rapidez, Postman para coleções

O cURL é ideal para validar a conexão em segundos, inclusive com SOCKS5. O Postman é melhor para organizar coleções, variáveis e fluxos que a equipe repete. A sequência recomendada é configurar o cURL, confirmar o IP de saída e só então replicar no Postman.

No cURL, --proxy e --proxy-user resolvem o proxy HTTP com autenticação

Comando básico com porta HTTP

A opção --proxy (ou -x) recebe o host e a porta HTTP, e --proxy-user recebe usuário e senha separados por dois-pontos. Com placeholders, o comando fica assim:

curl -x 'http://SEU_HOST:PORTA_HTTP' --proxy-user 'USUARIO:SENHA' 'https://api.exemplo.com.br/v1/status'

Troque os placeholders pelos dados do painel e o endereço de exemplo pelo endpoint que você testa. Confira a sintaxe completa na documentação oficial do cURL, já que as opções evoluem entre versões.

Senha com caracteres especiais

É possível embutir as credenciais na URL do proxy, no formato usuario:senha@host. Nesse caso, caracteres especiais da senha precisam de codificação de URL (percent-encoding), senão o cURL interpreta o arroba ou os dois-pontos como separadores. Usar --proxy-user evita boa parte desse problema e deixa o comando mais limpo. Ainda assim, aspas simples ao redor do valor impedem que o shell interprete símbolos como cifrão ou exclamação.

Credenciais por variável de ambiente, sem expor no histórico

Digitar a senha direto no comando a deixa no histórico do terminal e em logs de CI. Prefira variáveis de ambiente. No bash, o comando read -s PROXY_PASS lê a senha sem exibi-la. Depois, use a variável entre aspas duplas:

curl -x 'http://SEU_HOST:PORTA_HTTP' --proxy-user "$PROXY_USER:$PROXY_PASS" 'https://api.exemplo.com.br/v1/status'

Em pipelines, injete os valores pelo cofre de segredos da ferramenta, nunca pelo repositório.

Para SOCKS5 no cURL, a diferença entre socks5 e socks5h define quem resolve o DNS

socks5 ou socks5h: o que muda no DNS

Segundo o post de Daniel Stenberg sobre a opção --socks5, o próprio cURL resolve o nome do host e passa o endereço ao proxy. Para o DNS ser resolvido pelo proxy, usa-se a variante socks5h. A mesma fonte informa que a opção --socks5 foi adicionada ao cURL na versão 7.18.0.

Em QA isso importa. Quando o DNS é resolvido na sua máquina, serviços que respondem por região podem devolver endereços diferentes dos que um usuário no Brasil receberia. Com socks5h, a resolução do nome fica a cargo do proxy.

Exemplo com porta SOCKS5 e usuário e senha

curl --proxy 'socks5h://USUARIO:SENHA@SEU_HOST:PORTA_SOCKS5' 'https://api.exemplo.com.br/v1/status'

Aqui as credenciais vão na URL, então valem os cuidados de codificação e de histórico vistos acima. Para escolher o protocolo em cada situação, veja HTTP ou SOCKS5: qual usar em cada situação. Neste guia, a escolha é só para o contexto de API.

No Postman, o proxy customizado das configurações vale para todas as requisições

Proxy do sistema versus proxy customizado

O proxy do sistema herda a configuração do sistema operacional. O proxy customizado é definido só dentro do Postman e vale para as requisições enviadas por ele, sem mexer no resto da máquina. Para testes de API com o IP móvel, o customizado é o mais previsível, porque o navegador e outros programas continuam saindo pela sua rede normal.

Preencher host, porta, usuário e senha

Abra as configurações do Postman, procure a aba de proxy e ative o proxy customizado. Informe o host e a porta HTTP, marque o uso de autenticação e preencha usuário e senha. Os nomes exatos dos menus variam entre versões, então confira a documentação oficial do Postman se algo estiver em outro lugar.

Neste guia, o Postman é configurado com a porta HTTP; confira na documentação oficial quais protocolos a sua versão aceita. Se a dúvida for sobre SOCKS5 ou sobre DNS, o cURL é um caminho direto para validar, porque a fonte citada acima trata justamente dessa diferença.

Guardar credenciais em variáveis, não em coleções compartilhadas

Coleções exportadas ou compartilhadas viajam com o que estiver nelas. Por isso:

• Não grave usuário e senha do proxy em corpo, cabeçalho ou script de requisição.
• Guarde valores sensíveis em variáveis com valor atual (local), deixando o valor inicial em branco, e confirme esse comportamento na documentação oficial.
• Se o campo de proxy aceitar variáveis na sua versão, use-as. Se não aceitar, lembre que a configuração fica no aplicativo, não na coleção.

Confirmar que a chamada saiu pelo proxy exige comparar IP, país e ASN com e sem proxy

Um 200 na resposta não prova nada, pois a requisição pode ter ido direto. A verificação segue quatro passos: consultar um endpoint que devolve o IP sem proxy, repetir com proxy, comparar os dados e registrar o resultado.

Comparar IP, país e ASN

Use um serviço de consulta de IP que devolva endereço, país e ASN (o endereço abaixo é um placeholder):

curl 'https://servico-de-ip.exemplo/json'

Depois repita com -x e --proxy-user. O IP deve mudar, o país deve ser Brasil e o ASN deve corresponder a uma operadora móvel brasileira. Veja o que é ASN e como conferir para interpretar esse campo.

Verbose do cURL e Console do Postman

No cURL, acrescente -v (verbose). A saída mostra a conexão com o proxy, o pedido de autenticação e a resposta. Se a conexão aparecer indo direto ao destino, o proxy não foi aplicado. No Postman, abra o Console (o nome do menu pode variar conforme a versão) para inspecionar a requisição enviada e a resposta recebida.

Checar o DNS ao usar SOCKS5

Se o teste depende de resolução por região e você usa a porta SOCKS5, rode a mesma chamada com socks5 e com socks5h e compare os resultados. Para outras formas de validação, consulte outros métodos para testar se o proxy está funcionando.

Comparar HTTP e SOCKS5 mostra qual porta usar em cada cliente

Tabela: porta HTTP x porta SOCKS5 em testes de API

A tabela resume onde cada opção funciona neste guia, como ela autentica e quando faz sentido escolhê-la. A comparação de DNS fica restrita a socks5 e socks5h, que é o que a fonte citada cobre.

Na prática, comece pela porta HTTP, que é a que você usa no Postman e também no cURL. Se o teste exigir SOCKS5, escolha de forma consciente entre socks5 e socks5h, já que a diferença entre as duas é justamente quem resolve o DNS. Em qualquer caso, confirme o resultado pelo fluxo de verificação da seção anterior.

Os erros mais comuns têm causa previsível: 407, timeout, certificado e senha mal codificada

Checklist de erros e correções

• 407 (Proxy Authentication Required): o proxy não recebeu credenciais ou recebeu credenciais incorretas. Confira usuário, senha e se --proxy-user está presente. No Postman, verifique se a autenticação está marcada.
• Timeout: geralmente porta ou protocolo errado, como usar a porta SOCKS5 com esquema http. Revise o par porta e protocolo e teste a rede.
• Erro de certificado: verifique se o problema é do destino ou do ambiente, e inspecione o -v. Não desative a validação como solução permanente.
• Senha com caractere especial: se a senha está na URL, codifique os caracteres. Se o 407 persistir, passe a usar --proxy-user.

Rotação de IP no meio de uma bateria de testes

O link de rotação no painel troca o IP na hora, e também é possível programar a rotação por tempo. Em uma bateria de testes, isso muda o IP de saída e pode alterar os resultados. Se a comparação precisa de origem estável, evite rotacionar até terminar. Em dúvidas de configuração, o suporte funciona 24/7 por WhatsApp, Telegram e email.

Exemplo prático: validar a resposta de uma API de preços e frete para o usuário brasileiro

Cenário e roteiro de teste

Uma agência com três clientes de e-commerce precisa conferir se a API de um deles devolve moeda, idioma e opções de frete corretos para o Brasil. A API é do próprio cliente, e a agência tem autorização para testá-la.

1. Rode a consulta de IP sem proxy e anote IP, país e ASN.
2. Rode a requisição da API de preços sem proxy e salve o corpo da resposta.
3. Configure o proxy 4G no cURL, repita a consulta de IP e confirme que o país é Brasil e o ASN é de operadora móvel brasileira.
4. Rode a mesma requisição da API pelo proxy e compare moeda, idioma e frete com a resposta anterior.
5. Repita o passo 4 no Postman, com o proxy customizado e as credenciais em variáveis locais.

Como registrar o resultado para a equipe

Salve as duas respostas em uma coleção do Postman, com o IP, o país e o ASN de cada execução em campos de descrição ou testes. O resultado esperado é uma resposta com dados coerentes com o mercado brasileiro, e qualquer diferença vira um item de correção para o time do cliente. Quem usa o teste grátis de 1 hora, com até 1 GB de tráfego, consegue validar esse fluxo antes de contratar um plano. Para ir além, veja testes de geolocalização para o usuário brasileiro.

O proxy resolve a origem da requisição, mas não substitui as regras de cada API

Quando faz sentido e quando não faz

Faz sentido para testar a versão brasileira de um serviço, comparar o comportamento por região e fazer QA de integrações próprias ou autorizadas. Não faz sentido quando a API exige outra forma de acesso, como chaves ou contrato específico, ou quando o teste não depende da origem da chamada.

O que o proxy não resolve

• Autenticação da API, limites de uso e termos de serviço.
• Erros de lógica do próprio código.
• Testes que dependam de uma cidade específica, já que não é possível escolher a cidade do IP.

Nenhum proxy autoriza o que uma API ou plataforma proíbe. Ele muda a origem da requisição, e as regras de uso de cada serviço continuam valendo.

Perguntas frequentes

Como usar proxy com usuário e senha no cURL?

Use --proxy (ou -x) com host e porta, e --proxy-user com usuário:senha. Prefira variáveis de ambiente para não deixar a senha no histórico.

Qual a diferença entre socks5 e socks5h no cURL?

Com socks5, o cURL resolve o DNS localmente e passa o endereço ao proxy. Com socks5h, o proxy resolve o nome do host.

Onde configuro o proxy customizado no Postman?

Nas configurações do aplicativo, na aba de proxy. Ative o proxy customizado e informe host, porta e autenticação. Os nomes dos menus podem variar conforme a versão.

Qual a diferença entre proxy do sistema e proxy customizado no Postman?

O proxy do sistema herda a configuração do sistema operacional. O customizado é definido apenas dentro do Postman.

Como saber se a requisição realmente saiu pelo proxy?

Compare IP, país e ASN com e sem proxy. No cURL, use o modo verbose. No Postman, consulte o Console.

O que significa o erro 407 ao usar proxy no cURL ou no Postman?

O proxy exige autenticação e não recebeu credenciais válidas. Confira usuário, senha, a opção --proxy-user no cURL e a caixa de autenticação no Postman.

Minha senha tem caracteres especiais. Como informar no cURL?

Use --proxy-user com a senha entre aspas simples. Se ela precisar ir na URL do proxy, aplique a codificação de URL aos caracteres especiais.

Como guardar usuário e senha do proxy sem expor em histórico ou coleções?

No terminal, use variáveis de ambiente ou um cofre de segredos. No Postman, use variáveis com valor atual local e mantenha as credenciais fora do corpo e dos scripts das requisições.

Devo usar a porta HTTP ou a SOCKS5 para testar APIs?

A porta HTTP é um bom ponto de partida no cURL e no Postman. Use a SOCKS5 no cURL quando o teste pedir esse protocolo e, nesse caso, escolha entre socks5 e socks5h conforme você queira que o DNS seja resolvido localmente ou pelo proxy. Para detalhes de comportamento do DNS com proxy HTTP, consulte a documentação oficial do cURL.

Posso escolher a cidade do IP para o teste?

Não. O IP é de uma operadora móvel brasileira (Claro, TIM ou Vivo), mas a cidade não pode ser escolhida.