Como funciona · para leigos

Os sites julgam você pelo IP. Esta é a central que escolhe qual IP o seu agente veste.

Todo aparelho na internet tem um endereço. Busca, lojas, anúncios e sites de notícia usam esse endereço para decidir o que você vê — moeda, idioma, posições, até se a página carrega. Um agente de IA num datacenter tem um endereço: o desse datacenter. Sem uma saída localizada, todo fetch parece ter saído do mesmo prédio.

Você pede um país ou uma cidade. O IP Router escolhe uma saída lá, manda a requisição por esse IP e devolve a página. O mesmo cérebro para um agente JSON e um navegador de verdade.

Testar uma requisição Ir para os casos de uso

A ideia

Quatro fatos, depois você usa o resto.

O site nunca vê o seu notebook

Ele vê o IP de saída. Troque a saída e a página muda — preços, SERP, localizador de lojas, paywall, tudo.

País não é idioma

cc-JP põe você num IP do Japão. lang-ja diz ao site que você lê japonês. Em geral você quer os dois.

Sticky quer dizer “a mesma pessoa”

Duas portas, um kernel

Agentes fazem POST de JSON em /api/v1/fetch. Navegadores e curl falam CONNECT em :7777. Os dois chamam selectRoute.

Palavras

Os doze termos que o console usa.

IP / saída: O endereço que o site vê. Não o seu notebook, não o host do agente — o último salto que saiu do IP Router.
cc (país): Código de país ISO. GB é o Reino Unido, DE é a Alemanha, JP é o Japão. Isso escolhe o mercado.
cidade: Mais fino que o país. Londres contra Manchester, Nova York contra Austin. Espaços viram sublinhado no username: city-new_york.
idioma: Cabeçalho Accept-Language. A pergunta do site: “que idioma você lê?”. Independente do IP.
sessid (sticky): Um nome que você reutiliza para cada salto de um trabalho usar a mesma saída. O TTL padrão é 10 minutos; sesstime substitui.
tipo: Que tipo de rede a saída é: residential, datacenter, mobile ou ISP. Os sites tratam cada um de um jeito.
pool: Uma lista de nós que você adicionou, cada um com um país e talvez uma cidade. O roteador casa o direcionamento com um nó.
backconnect: Um gateway de fornecedor. O IP Router acrescenta -cc-US-city-austin-sessid-job1 ao username desse fornecedor.
direct: Esta máquina. Serve para aprender. O site ainda vê o IP do seu host, então as páginas com geo não mudam.
IP farm: Celulares Android que você monta em rack numa cidade. Os agentes saem por essa última milha, cobrados por conexão ativa — não por GB.
Fetch API: POST /api/v1/fetch com JSON. Para agentes e LLMs que não falam HTTP CONNECT.
Gateway :7777: Um proxy HTTP. curl -x, Playwright, navegadores. O direcionamento fica no username, no estilo Oxylabs.

Duas portas

O mesmo direcionamento. Clientes diferentes.

Escolha a porta que combina com o jeito que o seu cliente fala. O direcionamento é o mesmo nos dois casos.

Fetch API — a porta do agente

Use quando o seu cliente envia JSON: uma ferramenta de LLM, um script, um nó do n8n, o playground.

POST /api/v1/fetch com uma chave Bearer. Coloque país, cidade, idioma e sessão no corpo. A resposta inclui a página, o geo da saída e route.reason, para você ver por que aquele salto foi escolhido.

Ela busca uma URL e devolve o corpo. Não clica, não preenche formulário e não guarda os cookies de um navegador de verdade. Para um checkout num navegador de verdade, use o gateway.

Gateway HTTP — a porta do navegador

Use quando o cliente já fala proxy HTTP: curl -x, Playwright, Chrome, um scraper que espera CONNECT.

Aponte o proxy para host:7777. O username é iprouter-{keyId}-cc-GB-city-london-sessid-job1. A senha é a chave de API. Os mesmos tokens de direcionamento do corpo do fetch, só que no username.

O CONNECT não reescreve cabeçalhos HTTPS. Se você precisa de Accept-Language num site TLS, o navegador (ou a Fetch API) tem que enviar. lang- no username é uma dica para o roteamento e para HTTP, não uma injeção mágica em HTTPS.

Se você é	Use
Agente JSON / ferramenta de LLM	Fetch API
Playground / testar uma URL	Fetch API
curl, Playwright, um navegador de verdade	Gateway :7777
Entrar e depois varrer a mesma sessão	Qualquer porta, mais um sessid

Saídas

Por onde a requisição realmente sai.

Uma saída é o ponto em que a requisição sai para a internet, do ponto de vista do site. Você precisa de pelo menos uma que não seja “esta máquina” antes de as páginas com geo mudarem.

Direct — esta máquina

Já vem com o nó. As requisições dão certo na hora, então o playground funciona. route.reason vai dizer “direct” ou “direct fallback (no geo node)”. O site ainda vê o IP do seu host.

Pool — IPs que você adicionou

Console → Pool de proxies. Cada nó tem um país, uma cidade opcional e um type. Peça Londres; um nó de pool em Londres vence. Peça GB sem cidade; qualquer nó GB vence.

Backconnect — um gateway de fornecedor

Você adiciona um gateway. O IP Router injeta o direcionamento no username (-cc-DE-city-berlin-sessid-s1). Use quando você compra banda de um fornecedor em vez de listar cada IP.

IP farm — celulares numa cidade

Monte celulares Android em rack, marque o site com um país e uma cidade, e defina quantas conexões estão no ar. Os agentes saem por essa última milha. Cobrado por conexão ao mês. Um teste de 14 dias cobre o primeiro celular.

Quando você nomeia um país, o roteador tenta nesta ordem: city pool match → country pool match → backconnect geo injection → direct fallback. Nenhum proxy ativo é um 422, não uma falha silenciosa.

Pool de proxies IP farm Árvore de roteamento

Primeira tentativa

Cinco minutos. Você ainda não precisa de uma saída paga.

Faça isso uma vez para o resto do guia não ficar abstrato. Cinco minutos. Você ainda não precisa de uma saída paga.

01
Abra o console
Página → Abrir o console. Localmente não há cadastro. Você cai na Visão geral.
02
Envie a URL de echo
O playground já vem preenchido com o echo local. Escolha um país (US serve). Deixe a sessão como agent-demo. Envie. Você sempre recebe um 200 do echo — isso prova a porta, não o geo.
03
Leia três campos
ok deve ser true. route.reason diz qual saída foi escolhida. geo.exit é o IP que o mundo de fora veria — vazio, ou a sua máquina, no direct.
04
Saia do IP da máquina
Adicione um nó de pool ou de backconnect em Pool de proxies, ou um IP farm numa cidade que importe para você. Envie de novo. reason não deve mais dizer “direct fallback”.
05
Copie uma chave e escolha uma porta
Chaves de API para a Fetch API. Endpoints monta o username do gateway. Agentes tem o schema da ferramenta de LLM. O mesmo direcionamento, três interfaces.

Casos de uso

Como funciona em cada trabalho.

Os mesmos controles de sempre: país, cidade, idioma, sticky, type. O trabalho só muda quais você gira e por qual porta você entra. Escolha uma linha.

cidade / país

Ver a busca como alguém nessa cidade vê

O Google (o Bing e o Maps) não mostra uma internet só. Mostra a internet de onde você está. Posições, pack local, anúncios, até a grafia que acharam que você quis dizer — tudo isso depende do IP de saída e do cabeçalho de idioma. Se o seu agente busca a partir de um datacenter nos EUA, você está julgando uma página de resultados dos EUA, mesmo quando a pergunta é “como isso aparece em Manchester”.

Sem o IP Router

Você recebe a SERP do país do host. Uma consulta de Londres a partir de uma VM da Virgínia continua uma página da Virgínia, com uma consulta no formato de Londres.

Com ele

cc-GB + city-london + lang-en_GB. O salto sai por uma saída do Reino Unido, o Accept-Language é inglês britânico, e a página é a que um visitante de Londres veria.

Como funciona

01Nomeie o mercado: país GB, cidade London, idioma en-GB. A cidade importa aqui — Manchester e London têm packs locais diferentes.
02Use a Fetch API se quiser HTML/JSON de volta para o agente ler. Use o gateway se um navegador headless estiver conduzindo a SERP.
03Envie um sessid estável se for paginar ou clicar adiante. Uma sessão nova no meio da rolagem parece um visitante novo.
04Leia route.reason. Você quer city pool match (ou backconnect geo injection). direct fallback quer dizer que você ainda está no host.
05Compare duas execuções: a mesma consulta, US contra GB. O pack local e os anúncios devem mudar de lugar. Se não mudarem, você ainda não está numa saída com geo.

Porta

Qualquer porta. Fetch quando o agente envia JSON; gateway quando o cliente fala CONNECT.

cc-GBcity-londonlang-en_GB

Fetch API

{
  "url": "https://www.google.com/search?q=best+coffee+near+me",
  "geo": { "country": "GB", "city": "London", "language": "en-GB" },
  "session": "serp-london"
}

Gateway :7777

curl -x http://iprouter-key_dev-cc-GB-city-london-lang-en_GB-sessid-serp-london:ipr_live_dev_key@127.0.0.1:7777 https://www.google.com/search?q=best+coffee+near+me

Você sabe que funcionou quando

route.reason é um acerto de geo, geo.exit não é o seu host, e o pack local cita estabelecimentos de Londres — não os que ficam ao lado do seu servidor.

Erros comuns

Só o país. GB sem cidade muitas vezes te deixa numa página nacional, sem o pack local que você queria.
Sem lang. Um IP do Reino Unido com en-US ainda puxa a grafia americana e resultados US no meio.

Testar no playground Schemas de agente

route.reason

A frase que diz se o geo aconteceu de verdade.

city pool match: Você pediu uma cidade e um nó de pool nessa cidade estava ativo. O melhor acerto de geo.
country pool match: Sem nó de cidade (ou você não pediu uma cidade), mas um nó de pool nesse país estava ativo.
backconnect geo injection: Nenhum nó de pool nesse país. Um gateway de backconnect está ligado, então o direcionamento foi escrito no username dele.
direct fallback (no geo node): Nada nesse país. A requisição saiu mesmo assim — por esta máquina. As páginas com geo não mudam. Adicione um nó ou um farm.
sticky session: Você reutilizou um sessid e a saída antiga ainda está ativa. O mesmo IP da última vez. TTL renovado.
backconnect rotate / pool rotate / direct: Você não nomeou um país. O roteador escolheu qualquer saída correspondente e, se você enviou uma sessão, fez hash da escolha para ela ficar no lugar.

Erros

Os que parecem bugs do produto.

País sem idioma

Um IP japonês com Accept-Language em inglês muitas vezes ainda serve inglês. Defina lang (ou language no corpo do fetch) além de cc.

sessid novo a cada requisição

Se a string da sessão muda, você é uma pessoa nova. Os logins caem. Reutilize o mesmo sessid no trabalho inteiro.

Confiar no direct fallback

Um 200 do echo nesta máquina não prova o geo. Leia route.reason. Se disser direct fallback, o site ainda viu o seu host.

Datacenter contra residencial

Algumas origens fazem fingerprint do ASN. Se a página for um muro de captcha ou uma tela em branco de “datacenter detectado”, defina type-residential ou use um IP farm.

HTTPS + gateway + lang

O gateway não consegue injetar Accept-Language num túnel HTTPS CONNECT. Envie o cabeçalho pelo cliente, ou use a Fetch API.

Pool vazio

Se todo nó estiver desligado, você recebe 422 “No enabled proxies in the pool.” Ative o nó direct ou adicione um que esteja ligado.