Guia completo de got-scraping em Node.js com proxies residenciais

Aviso legal: Este guia cobre técnicas de coleta de dados públicos. A raspagem de dados pode violar Termos de Serviço, o CFAA nos EUA, o GDPR na UE, e legislações locais. Consulte sempre um advogado antes de operar em escala. Honre robots.txt, rate limits e prefira APIs oficiais quando disponíveis.

Se você já construiu um scraper em Node.js usando got ou axios puros, provavelmente já enfrentou o ciclo: funciona localmente, funciona por algumas horas em produção, e de repente tudo retorna HTTP 403 ou um desafio CAPTCHA. A causa raramente é o proxy isoladamente — é a combinação de headers inconsistentes, falta de suporte a HTTP/2 e TLS fingerprint que não corresponde ao que o servidor espera de um navegador real. É exatamente aqui que got-scraping em Node.js se torna relevante: ele envolve o got com geração automática de headers de navegador e suporte nativo a HTTP/2, fechando a lacuna entre uma requisição HTTP crua e o tráfego orgânico que um site espera receber.

O que é got-scraping em Node.js e por que requests crus falham

got-scraping é um cliente HTTP para Node.js mantido pela Apify, construído sobre o popular got. Ele foi projetado especificamente para raspagem de dados, adicionando três camadas críticas que o got puro não oferece por padrão:

• Geração automática de headers de navegador — cada requisição recebe um conjunto coerente de headers (User-Agent, sec-ch-ua, accept-language, accept-encoding, e a ordem correta deles).
• Suporte a HTTP/2 — muitos sites modernos negociam HTTP/2, e o fingerprint do protocolo importa para sistemas anti-bot.
• Opções de proxy otimizadas — suporte a proxyUrl para HTTP/1.1 e HTTP/2, com gerenciamento de conexões que evita vazamentos de IP.

O problema com requests crus é que bibliotecas como got e axios enviam headers minimalistas por padrão. Um got('https://example.com') típico envia algo como user-agent: got (https://github.com/sindresorhus/got) e accept: application/json. Para qualquer sistema anti-bot moderno — Cloudflare, Datadome, PerimeterX, Akamai Bot Manager — isso é uma bandeira vermelha imediata. Browsers reais enviam dezenas de headers em uma ordem específica, incluindo client hints como sec-ch-ua, sec-ch-ua-mobile e sec-ch-ua-platform.

O header-generator, biblioteca que o got-scraping usa internamente, produz conjuntos de headers que correspondem a navegadores reais (Chrome, Firefox, Edge, Safari) em dispositivos específicos (desktop, mobile) e sistemas operacionais reais (Windows, macOS, Linux, Android, iOS). A coerência é o ponto-chave: não basta ter um User-Agent do Chrome se os sec-ch-ua headers não correspondem, ou se a ordem dos headers diverge do que o Chrome realmente envia.

Como o got scraping header generator cria conjuntos coerentes

O header-generator não apenas sorteia um User-Agent aleatório. Ele constrói um conjunto completo de headers que são internamente consistentes. Por exemplo, se ele gera headers para Chrome 120 no Windows, o sec-ch-ua conterá "Not_A Brand";v="8", "Chromium";v="120", "Google Chrome";v="120", o sec-ch-ua-platform será "Windows", e o accept-language seguirá um padrão realista como en-US,en;q=0.9.

A ordem dos headers também importa. Sistemas anti-bot como o Cloudflare verificam a ordem dos headers porque navegadores diferentes os enviam em sequências distintas. O header-generator respeita essas ordens, fazendo com que a requisição se pareça visualmente com tráfego de navegador genuíno no nível do cabeçalho HTTP.

É importante entender que headers coerentes são necessários, mas não suficientes. O TLS fingerprint (JA3/JA4) da conexão ainda é determinado pela biblioteca TLS do Node.js, que difere do fingerprint de um navegador real. Para sites com anti-bot avançado que inspeciona JA3, um navegador headless via Playwright ou Puppeteer pode ser necessário. Mas para a maioria dos sites com proteção moderada, headers coerentes + HTTP/2 + proxies residenciais já resolvem o problema.

Superfície idiomática — got.extend, useHeaderGenerator e proxyUrl

O got-scraping expõe uma API que segue o padrão idiomático do got: você usa got.extend() para criar instâncias configuradas com middleware e opções reutilizáveis. As três extensões principais são:

useHeaderGenerator

Esta opção ativa a geração automática de headers. Quando habilitada, cada requisição recebe um novo conjunto de headers de navegador coerente, a menos que você fixe uma sessão. Você pode passar headerGeneratorOptions para controlar quais perfis de navegador são gerados:

const { got } = require('got-scraping');

const client = got.extend({
  useHeaderGenerator: true,
  headerGeneratorOptions: {
    browsers: [
      { name: 'chrome', minVersion: 118, maxVersion: 122 }
    ],
    devices: ['desktop'],
    operatingSystems: ['windows', 'macos']
  }
});

(async () => {
  const res = await client.get('https://httpbin.org/headers');
  console.log(JSON.parse(res.body).headers);
})();

Restringir os navegadores a uma faixa específica (por exemplo, Chrome 118-122) é uma boa prática em produção. Se você permite todos os navegadores, pode acabar com um conjunto Safari em uma requisição e Chrome na seguinte, o que é inconsistente se o servidor rastreia sessões por IP.

proxyUrl

A opção proxyUrl aceita uma URL de proxy no formato padrão. Para proxies HTTP, o got-scraping usa o proxy para a conexão TCP e o handshake TLS acontece através do túnel CONNECT. Para proxies SOCKS5, o got-scraping delega para o agente SOCKS apropriado:

// Proxy HTTP via ProxyHat
const httpProxy = 'http://user-country-US:pass@gate.proxyhat.com:8080';

// Proxy SOCKS5 via ProxyHat
const socksProxy = 'socks5://user-country-US:pass@gate.proxyhat.com:1080';

const client = got.extend({
  useHeaderGenerator: true,
  proxyUrl: httpProxy,
  headerGeneratorOptions: {
    browsers: [{ name: 'chrome', minVersion: 118, maxVersion: 122 }],
    devices: ['desktop'],
    operatingSystems: ['windows']
  }
});

Note que o proxyUrl pode ser sobrescrito por requisição, permitindo rotação de proxies sem recriar a instância do cliente. Isso é fundamental para integrar com um pool de proxies residenciais.

Rotas residenciais via ProxyHat em gate.proxyhat.com

Quando os headers e o protocolo já parecem legítimos, o próximo vetor de detecção é o IP. Proxies datacenter usam ranges de ASN registrados como hosting (AWS, DigitalOcean, Hetzner), que muitos sistemas anti-bot classificam como tráfego automatizado por padrão. Proxies residenciais, por outro lado, usam IPs atribuídos a ISPs reais — o mesmo tipo de IP que um usuário doméstico teria.

Com o ProxyHat, você rota através de proxies residenciais em gate.proxyhat.com:8080 (HTTP) ou gate.proxyhat.com:1080 (SOCKS5). O país e a sessão são controlados via o nome de usuário, sem necessidade de endpoints separados:

• user-country-US — IP residencial nos Estados Unidos
• user-country-DE-city-berlin — IP residencial em Berlim, Alemanha
• user-session-abc123 — sessão sticky que mantém o mesmo IP entre requisições
• user-country-US-session-abc123 — país fixo com sessão persistente

Esses flags podem ser combinados para controle granular. Para a maioria dos casos de raspagem, você quer rotação automática (sem flag de sessão) para distribuir requisições entre muitos IPs, ou sessões sticky quando precisa manter estado (login, carrinho, paginação com tokens). Veja as documentações do ProxyHat para detalhes completos de configuração.

Por que residencial importa quando os headers já estão coerentes? Porque um servidor anti-bot pode aceitar a requisição no nível HTTP (headers corretos, HTTP/2) e ainda assim rejeitar no nível de IP. Se o IP pertence a um range de datacenter conhecido, o servidor pode servir um desafio CAPTCHA ou um 403 silencioso, mesmo com headers perfeitos. A combinação de headers coerentes + IP residencial é o que maximiza a taxa de sucesso. Consulte nossa página de localizações para ver a cobertura geográfica disponível.

Exemplo prático: rotação de proxies residenciais com retry hooks

O exemplo a seguir mostra uma integração completa: got-scraping com header-generator, proxies residenciais rotativos do ProxyHat, hooks de retry com backoff exponencial, e geração de nomes de usuário por requisição para garantir rotação de IP:

const { got } = require('got-scraping');
const crypto = require('crypto');

// Credenciais base do ProxyHat
const PROXYHAT_USER = 'user';
const PROXYHAT_PASS = 'pass';
const PROXYHAT_GATE = 'gate.proxyhat.com:8080';

// Função que gera um nome de usuário único por requisição
// para forçar rotação de IP residencial
function buildProxyUrl(country = 'US') {
  const session = crypto.randomBytes(6).toString('hex');
  const username = `${PROXYHAT_USER}-country-${country}-session-${session}`;
  return `http://${username}:${PROXYHAT_PASS}@${PROXYHAT_GATE}`;
}

// Cliente got-scraping com header-generator e retry hook
const client = got.extend({
  useHeaderGenerator: true,
  headerGeneratorOptions: {
    browsers: [{ name: 'chrome', minVersion: 118, maxVersion: 122 }],
    devices: ['desktop'],
    operatingSystems: ['windows', 'macos']
  },
  retry: {
    limit: 3,
    statusCodes: [403, 429, 500, 502, 503],
    backoffLimit: 5000
  },
  hooks: {
    beforeRequest: [
      (options) => {
        // Rotaciona o proxy a cada requisição
        options.proxyUrl = buildProxyUrl('US');
      }
    ],
    afterResponse: [
      (response, retryWithMergedOptions) => {
        // Detecta respostas que indicam bloqueio mesmo com 200
        const body = response.body;
        if (typeof body === 'string' && body.includes('cf-challenge')) {
          throw new got.HTTPError(response);
        }
        return response;
      }
    ]
  }
});

(async () => {
  const targets = [
    'https://example.com/page/1',
    'https://example.com/page/2',
    'https://example.com/page/3'
  ];

  for (const url of targets) {
    try {
      const res = await client.get(url);
      console.log(`[${res.statusCode}] ${url} — ${res.body.length} bytes`);
    } catch (err) {
      console.error(`[ERRO] ${url} — ${err.message}`);
    }
  }
})();

O hook beforeRequest é o ponto idiomático para injetar a rotação de proxy. Cada requisição recebe um session aleatório, o que faz o ProxyHat atribuir um IP residencial diferente. O hook afterResponse verifica respostas que tecnicamente retornam 200 mas contêm desafios anti-bot no corpo — um padrão comum do Cloudflare.

Para SOCKS5, basta trocar a função buildProxyUrl:

function buildSocksProxyUrl(country = 'US') {
  const session = crypto.randomBytes(6).toString('hex');
  const username = `${PROXYHAT_USER}-country-${country}-session-${session}`;
  return `socks5://${username}:${PROXYHAT_PASS}@gate.proxyhat.com:1080`;
}

SOCKS5 é útil quando o site alvo bloqueia conexões que passam por proxies HTTP conhecidos, ou quando você precisa de um túnel mais opaco que não expõe headers Via ou X-Forwarded-For.

Padrões de produção — hooks, concorrência e cookies

Em produção, três preocupações dominam: concorrência controlada, persistência de cookies e integração com frameworks de crawling.

Concorrência limitada com p-limit

Disparar centenas de requisições simultâneas contra um único domínio é a forma mais rápida de ser bloqueado. Use p-limit para bound de concorrência:

const pLimit = require('p-limit');

const limit = pLimit(10); // Máx 10 requisições concorrentes

const targets = Array.from({ length: 500 }, (_, i) =>
  `https://example.com/page/${i + 1}`
);

(async () => {
  const results = await Promise.all(
    targets.map(url =>
      limit(() =>
        client.get(url)
          .then(res => ({ url, status: res.statusCode, ok: true }))
          .catch(err => ({ url, status: 0, ok: false, error: err.message }))
      )
    )
  );

  const success = results.filter(r => r.ok).length;
  console.log(`Sucesso: ${success}/${results.length}`);
})();

Um limite de 10 requisições concorrentes por domínio é um ponto de partida razoável. Sites com anti-bot agressivo podem exigir 5 ou menos. Sempre monitore a taxa de sucesso e ajuste — se você vê 20% de falhas, reduza a concorrência ou adicione delays entre requisições.

Cookie jars para sessões autenticadas

Quando você precisa manter uma sessão (login, paginação stateful), use tough-cookie com o cookieJar do got. Combine com o flag de sessão do ProxyHat para manter o mesmo IP durante toda a sessão:

const { CookieJar } = require('tough-cookie');

const sessionJar = new CookieJar();
const sessionId = crypto.randomBytes(8).toString('hex');

const sessionClient = got.extend({
  useHeaderGenerator: true,
  cookieJar: sessionJar,
  proxyUrl: `http://${PROXYHAT_USER}-country-US-session-${sessionId}:${PROXYHAT_PASS}@gate.proxyhat.com:8080`,
  headerGeneratorOptions: {
    browsers: [{ name: 'chrome', minVersion: 118, maxVersion: 122 }],
    devices: ['desktop'],
    operatingSystems: ['windows']
  }
});

(async () => {
  // Login mantém cookies + mesmo IP residencial
  await sessionClient.post('https://example.com/login', {
    json: { username: 'user', password: 'pass' }
  });

  // Requisições subsequentes usam os mesmos cookies e IP
  for (let page = 1; page <= 10; page++) {
    const res = await sessionClient.get(`https://example.com/dashboard?page=${page}`);
    console.log(`Página ${page}: ${res.statusCode}`);
  }
})();

O cookie jar garante que os cookies de sessão do servidor sejam preservados entre requisições, enquanto o flag session-${sessionId} no ProxyHat garante que o IP residencial permaneça o mesmo. Sem o flag de sessão, o ProxyHat rotacionaria o IP a cada requisição, o que faria o servidor invalidar a sessão por mudança de IP.

Integração com Crawlee e CheerioCrawler

O got-scraping é a base HTTP do Crawlee, o framework de crawling da Apify. Quando seu projeto cresce além de scripts isolados, migrar para o CheerioCrawler do Crawlee traz gerenciamento de fila, deduplicação de URLs, armazenamento de resultados e rotação automática de proxies. O CheerioCrawler usa got-scraping internamente, então toda a configuração de header-generator e proxyUrl é herdada:

const { CheerioCrawler } = require('crawlee');

const crawler = new CheerioCrawler({
  requestHandler: async ({ $, request }) => {
    const title = $('title').text();
    console.log(`[${request.url}] ${title}`);
  },
  proxyConfiguration: {
    newUrlFunction: () =>
      `http://${PROXYHAT_USER}-country-US-session-${crypto.randomBytes(6).toString('hex')}:${PROXYHAT_PASS}@gate.proxyhat.com:8080`
  },
  maxConcurrency: 10,
  maxRequestRetries: 3
});

(async () => {
  await crawler.run(['https://example.com/page/1', 'https://example.com/page/2']);
})();

A migração de scripts got-scraping para Crawlee é incremental: a API de proxy e headers é a mesma, mas você ganha fila persistente, retries automáticos e armazenamento estruturado de dados.

Quando um navegador headless é inevitável

Apesar de toda a engenharia de headers e proxies, existem sites onde o got-scraping não é suficiente. Os sinais de que você precisa de um navegador headless (Playwright, Puppeteer) incluem:

• Desafios JavaScript interativos — o site renderiza um desafio que executa JavaScript ofuscado e espera uma resposta computada.
• Renderização client-side — o conteúdo que você precisa é gerado por JavaScript após o load da página, e não está no HTML inicial.
• Detecção de TLS fingerprint (JA3/JA4) — o Node.js usa OpenSSL, que produz um fingerprint TLS diferente do Chrome (que usa BoringSSL). Sistemas avançados como Cloudflare Bot Management podem detectar essa divergência.
• Canvas/WebGL fingerprinting — o site coleta fingerprints de canvas e WebGL que não existem em um cliente HTTP puro.

Nesses casos, use Playwright ou Puppeteer com os mesmos proxies residenciais do ProxyHat. O IP residencial continua sendo crítico — um navegador headless com IP datacenter ainda será detectado por sistemas baseados em reputação de ASN. Para padrões de escala com headless, considere containerização (Docker + Playwright) e um fleet de browsers com rotação de contexto a cada N requisições para evitar acúmulo de estado.

Ética, legalidade e boas práticas

Antes de qualquer implementação técnica, considere o quadro ético e legal:

• Dados públicos apenas. Não raspe conteúdo protegido por login sem autorização, dados pessoais sensíveis, ou conteúdo que você não tem direito de acessar.
• CFAA e GDPR. Nos EUA, o Computer Fraud and Abuse Act pode criminalizar acesso não autorizado a sistemas computacionais. Na UE, o GDPR regula o processamento de dados pessoais — raspagem de dados pessoais de residentes da UE sem base legal é uma violação.
• Honre robots.txt. Verifique /robots.txt antes de raspar. Mesmo que não seja legalmente vinculante em todas as jurisdições, é uma convenção respeitada pela comunidade e pode ser usada como evidência de boa-fé.
• Rate limits. Se o site publica rate limits (em robots.txt, headers Retry-After, ou documentação API), respeite-os. Disparar 1000 requisições/segundo contra um site pequeno pode ser considerado DoS.
• Prefira APIs oficiais. Muitos sites oferecem APIs com documentação, rate limits razoáveis e dados estruturados. Se a API existe e atende às suas necessidades, use-a em vez de raspar HTML.

Para casos de uso de web scraping e SERP tracking, o ProxyHat oferece proxies residenciais com cobertura global. Consulte nossa página de preços para planos adequados ao seu volume.

Pontos-chave

Headers coerentes são a base. O got-scraping com header-generator produz conjuntos de headers de navegador que são internamente consistentes — User-Agent, sec-ch-ua, accept-language e ordem de headers — reduzindo bloqueios no nível HTTP.

IP residencial é o multiplicador. Headers coerentes sem IP residencial ainda falham em sites com verificação de ASN. A combinação de headers coerentes + HTTP/2 + IP residencial maximiza a taxa de sucesso, que pode chegar a 99% em sites com proteção moderada.

Rotação via nome de usuário. O ProxyHat controla país, cidade e sessão via flags no nome de usuário, sem endpoints separados. Use session-* aleatório para rotação e session-fix para sessões sticky.

Concorrência limitada. Use p-limit ou o maxConcurrency do Crawlee para evitar rajadas que disparam rate limits. Comece com 10 concorrentes e ajuste baseado na taxa de sucesso.

Saiba quando migrar para headless. Se o site usa JA3 fingerprinting, desafios JS interativos ou renderização client-side, o got-scraping não é suficiente — use Playwright com os mesmos proxies residenciais.

FAQ

O que é got-scraping em Node.js?

got-scraping é um cliente HTTP para Node.js baseado no got, desenvolvido pela Apify. Ele estende o got com geração automática de cabeçalhos de navegador coerentes, suporte a HTTP/2 e opções de proxy otimizadas para raspagem de dados, reduzindo a chance de bloqueios em sites com proteção anti-bot. É a biblioteca HTTP padrão usada pelo framework Crawlee.

Por que o got-scraping em Node.js importa para usuários de proxy?

Mesmo com proxies residenciais, headers incoerentes ou TLS fingerprint divergente do navegador podem levar a bloqueios. O got-scraping resolve isso gerando conjuntos de headers realistas (sec-ch-ua, accept-language, ordem correta) e suportando HTTP/2, tornando cada requisição mais próxima do tráfego orgânico de navegador. Sem essa camada, o proxy residencial é desperdiçado por detecção no nível HTTP.

Qual tipo de proxy funciona melhor com got-scraping em Node.js?

Proxies residenciais são a melhor escolha porque oferecem IPs de ISPs reais, que combinam com headers de navegador coerentes gerados pelo got-scraping. Proxies datacenter podem funcionar em sites menos protegidos, mas residenciais e móveis têm taxas de sucesso significativamente maiores em plataformas com anti-bot agressivo como Cloudflare e Datadome. SOCKS5 via porta 1080 é útil quando proxies HTTP são detectados.

Como evitar bloqueios ao implementar got-scraping em Node.js?

Combine headers coerentes do header-generator com proxies residenciais rotativos do ProxyHat, respeite rate limits com p-limit, use sessões sticky quando precisar manter estado, implemente retry com backoff exponencial via hooks do got, e monitore a taxa de sucesso continuamente. Evite padrões de requisição previsíveis (intervalos exatos, ordem sequencial) e sempre verifique robots.txt antes de raspar um site.