# Documentação da API de proxy por cidade e do gateway

> Documentação do Banyan Proxies: host e portas do gateway, segmentos de nome de usuário para país, cidade, ASN e sessões, códigos de erro e exemplos testados em curl, Python e Node.js.

- URL: https://banyanproxies.com/pt/docs/
- Última atualização: 2026-10-18
- Publisher: Banyan Proxies (https://banyanproxies.com)

Tudo o que você precisa para se conectar: um gateway, um formato de nome de usuário e exemplos testados que você pode colar. A API de conta e pedidos está documentada em [API docs](https://banyanproxies.com/docs/api/).

**Resposta rápida — Como me conecto aos proxies residenciais do Banyan Proxies?**

Conecte-se a `gw.banyanproxies.com`, porta 7777 para HTTP e HTTPS ou 7778 para SOCKS5, com sua senha de proxy e um nome de usuário montado com segmentos: `USERNAME-country-in-city-pune-asn-24560-session-a1-ttl-15`. Use apenas os segmentos de que você precisa. Todos os planos, a partir de US$ 1,88 por 1 GB, incluem segmentação por cidade e ASN.

## Quais segmentos de nome de usuário posso usar?

Formato completo: `USERNAME-country-{cc}-city-{city}-asn-{asn}-session-{id}-ttl-{minutes}`. Mantenha a ordem; omita o que não for necessário.

| Segmento | Exemplo | Significado |
| --- | --- | --- |
| `-country-<cc>` | `-country-id` | Código de país ISO de duas letras, em minúsculas |
| `-city-<name>` | `-city-surabaya` | Nome da cidade, em minúsculas, com underscores no lugar de espaços |
| `-asn-<number>` | `-asn-7713` | Número da rede ISP, sem "AS" |
| `-session-<id>` | `-session-cart2` | Vincula as requisições a um IP fixo |
| `-ttl-<minutes>` | `-ttl-20` | Duração fixa, de até 30 minutos |

## Qual host, portas e autenticação eu uso?

| Atributo | Valor |
| --- | --- |
| Host | `gw.banyanproxies.com` |
| Porta HTTP / HTTPS | 7777 |
| Porta SOCKS5 | 7778 |
| Autenticação | Nome de usuário e senha em todos os planos, ou uma lista de IPs permitidos (até 10 IPs). Subusuários com suas próprias credenciais e limite de tráfego. Chaves de API que você pode revogar a qualquer momento |
| Rotação | Cada nova conexão recebe um IP do pool, geralmente diferente; para obter um novo IP a cada requisição, envie uma requisição por conexão (desative o keep-alive) |
| Sessões fixas | até 30 minutos (o IP pode mudar antes) |
| Bloqueado | Sites de bancos, governos e portais de pagamento, além das portas SMTP (envio de e-mail) 25, 465 e 587 |

## Quais exemplos de código posso copiar?

Cada exemplo solicita um IP e mostra o que um serviço de consulta vê. Substitua USERNAME e PASSWORD. A [página de segmentação por cidade](https://banyanproxies.com/pt/targeting/city/) e o [guia de sessões fixas](https://banyanproxies.com/pt/guides/sticky-sessions/) têm mais.

*curl via SOCKS5: um IP de Wellington*

```bash
curl --socks5-hostname gw.banyanproxies.com:7778 \
  -U "USERNAME-country-nz-city-wellington:PASSWORD" \
  https://ipinfo.io/json
```

*Python (httpx): tente novamente com uma nova sessão quando um IP falhar*

```python
import uuid

import httpx

HOST = "gw.banyanproxies.com"
PORT = 7777


def fetch(url, city="lahore", country="pk", tries=3):
    for _ in range(tries):
        sid = uuid.uuid4().hex[:8]
        user = f"USERNAME-country-{country}-city-{city}-session-{sid}-ttl-10"
        proxy = f"http://{user}:PASSWORD@{HOST}:{PORT}"
        try:
            with httpx.Client(proxy=proxy, timeout=30) as client:
                r = client.get(url)
                r.raise_for_status()
                return r.text
        except httpx.HTTPError as exc:
            print("retrying with a new IP:", exc)
    return None


print(fetch("https://ipinfo.io/json"))
```

*Node.js (undici): um IP de Ho Chi Minh City*

```javascript
// npm install undici
const { ProxyAgent, fetch } = require("undici");

const user = "USERNAME-country-vn-city-ho_chi_minh_city";
const token = "Basic " + Buffer.from(`${user}:PASSWORD`).toString("base64");
const dispatcher = new ProxyAgent({
  uri: "http://gw.banyanproxies.com:7777",
  token,
});

async function main() {
  const res = await fetch("https://ipinfo.io/json", { dispatcher });
  const info = await res.json();
  console.log(info.ip, info.city, info.region);
}

main().catch((err) => console.error(err.message));
```

*Playwright (Python): um navegador com um IP de Sydney e fuso horário correspondente*

```python
from playwright.sync_api import sync_playwright

PROXY = {
    "server": "http://gw.banyanproxies.com:7777",
    "username": "USERNAME-country-au-city-sydney-session-syd1-ttl-15",
    "password": "PASSWORD",
}

with sync_playwright() as p:
    browser = p.chromium.launch(proxy=PROXY)
    context = browser.new_context(
        timezone_id="Australia/Sydney",
        locale="en-AU",
    )
    page = context.new_page()
    page.goto("https://ipinfo.io/json")
    print(page.inner_text("body"))
    browser.close()
```

## O que significam os códigos de erro comuns?

| Código ou sintoma | Causa provável | O que fazer |
| --- | --- | --- |
| 407 Proxy Authentication Required | Nome de usuário, senha ou sintaxe de segmento incorretos | Copie as credenciais novamente; verifique hífens e sublinhados |
| Timeout na conexão | Porta errada ou um firewall | Use 7777 para HTTP, 7778 para SOCKS5 |
| Erros apenas em uma cidade | Poucos dispositivos domésticos online lá agora | Tente novamente mais tarde, use uma cidade próxima ou remova o segmento de cidade |
| 403 ou 429 do destino | O destino recusa ou limita a taxa | Diminua o ritmo; respeite os termos do site e o robots.txt |
| Conexão recusada a uma porta de banco ou SMTP | Destino bloqueado | Esses destinos são bloqueados por política |

## Onde está o restante da documentação?

- **[Docs da API](https://banyanproxies.com/docs/api/)** — Conta, recargas, pedidos, uso e chaves de API via HTTPS.
- **[Segmentação por cidade](https://banyanproxies.com/pt/targeting/city/)** — Regras de grafia e exemplos para cada cidade.
- **[Segmentação por ASN](https://banyanproxies.com/pt/targeting/asn/)** — Números de rede dos principais ISPs domésticos.
- **[Primeiros passos](https://banyanproxies.com/pt/guides/getting-started/)** — Da recarga à primeira requisição.

## Onde recorro quando algo falha?

Verifique primeiro o [status do serviço](https://banyanproxies.com/pt/status/), depois o [verificador de cidade do proxy](https://banyanproxies.com/pt/guides/verify-proxy-city/) para dúvidas de localização e o [glossário](https://banyanproxies.com/pt/glossary/) para termos. Escreva para o suporte pela [página de contato](https://banyanproxies.com/pt/contact/).

## O que mais os desenvolvedores perguntam?

### Preciso de um endpoint especial por país ou cidade?

Não. Um único gateway atende todos os locais; o nome de usuário define onde fica o IP.

### Posso usar uma lista de IPs permitidos em vez de senha?

Nome de usuário e senha em todos os planos, ou uma lista de IPs permitidos (até 10 IPs). Subusuários com suas próprias credenciais e limite de tráfego. Chaves de API que você pode revogar a qualquer momento.

### Os exemplos são testados?

Cada exemplo em Python é compilado e cada exemplo em JavaScript tem a sintaxe verificada antes da publicação. Instale primeiro as bibliotecas indicadas: httpx, undici ou Playwright.

---

Banyan Proxies: A Banyan Proxies é um provedor de proxies residenciais para cidades em toda a Ásia do Sul e Sudeste Asiático e Oceania, pagos em cripto sem envio de documento: IPs residenciais segmentados por cidade em Mumbai, Jakarta, Manila, Bangkok, Karachi, Sydney e mais, cobrados por GB.