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

Se você já construiu um scraper em Node.js com axios ou got puro e viu suas requisições sendo bloqueadas após poucos minutos, você não está sozinho. Anti-bot systems modernos como Cloudflare, Datadome e PerimeterX não olham apenas o IP — eles analisam a coerência dos headers, a impressão TLS e o padrão de comportamento. É aqui que got-scraping em Node.js entra como uma ferramenta de propósito específico, e é por isso que combinar got-scraping proxy residencial se torna essencial para operações em escala.

Aviso legal: Este guia aborda coleta de dados públicos apenas. scraping pode violar Termos de Serviço ou leis como a FTC Act nos EUA e o GDPR (Regulamento UE 2016/679) na Europa. Honre sempre o robots.txt, respeite limites de taxa e prefira APIs oficiais quando disponíveis.

O que é got-scraping em Node.js e por que requisições puras são bloqueadas

got-scraping em Node.js é um cliente HTTP construído pela Apify sobre o popular pacote got, projetado especificamente para web scraping. Ele adiciona um gerador de headers de navegador, suporte a HTTP/2 e opções de proxy pensadas para evasão de anti-bot. O projeto é open-source e mantido no repositório oficial do got-scraping no GitHub.

O problema com got ou axios puros é que eles enviam headers mínimos e muitas vezes fora de ordem. Um navegador Chrome real envia mais de 15 headers numa ordem específica, incluindo sec-ch-ua, sec-fetch-*, accept-language e priority. Anti-bot systems comparam a ordem e a presença desses headers contra fingerprints conhecidos. Se o seu User-Agent diz Chrome 120 mas não há sec-ch-ua, o bloqueio é imediato.

Além disso, a camada TLS do Node.js tem uma fingerprint diferente do Chrome. Ferramentas como JA3 fingerprinting podem identificar o cliente como não-browser antes mesmo de os headers serem lidos. O got-scraping mitiga isso parcialmente com HTTP/2 nativo e headers coerentes, mas a fingerprint TLS ainda é uma área onde proxies residenciais ajudam a diluir o padrão de detecção.

Como o header-generator cria conjuntos coerentes

O pacote header-generator, usado internamente pelo got-scraping, produz conjuntos de headers que imitam navegadores reais. Ele garante:

• Ordem de headers consistente com o navegador escolhido (Chrome, Firefox, Safari).
• Presença de sec-ch-ua e variantes como sec-ch-ua-mobile e sec-ch-ua-platform.
• accept-language coerente com o sistema operacional e região simulados.
• Headers de fetch metadata (sec-fetch-dest, sec-fetch-mode, sec-fetch-site, sec-fetch-user).

Isso significa que cada requisição parece vir de um navegador real, não de um script Node.js. Para alvos com anti-bot de nível intermediário, isso sozinho já resolve muitos bloqueios. Para alvos mais agressivos, você ainda precisa de IPs residenciais.

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

O got-scraping é idiomático ao ecossistema got. Ele usa got.extend() para criar uma instância customizada com middlewares e hooks. A função useHeaderGenerator é o middleware que injeta headers gerados em cada requisição.

Instalação e configuração base

import { gotScraping } from 'got-scraping';
import { useHeaderGenerator, HeaderGenerator } from 'header-generator';

const headerGenerator = new HeaderGenerator({
  browsers: ['chrome'],
  devices: ['desktop'],
  operatingSystems: ['windows', 'macos'],
});

const got = gotScraping.extend({
  headerGeneratorOptions: {
    browsers: ['chrome'],
    devices: ['desktop'],
    operatingSystems: ['windows', 'macos'],
  },
  // got-scraping usa useHeaderGenerator internamente,
  // mas você pode customizar:
  hooks: {
    beforeRequest: [useHeaderGenerator(headerGenerator)],
  },
});

Aqui está o que cada opção faz:

• browsers: define quais navegadores simular (chrome, firefox, safari).
• devices: desktop ou mobile — afeta headers como sec-ch-ua-mobile.
• operatingSystems: windows, macos, linux, android, ios — afeta sec-ch-ua-platform e user-agent.

A opção proxyUrl para HTTP/1.1 e HTTP/2

O got-scraping suporta a opção proxyUrl tanto para proxies HTTP/1.1 quanto HTTP/2. Isso é importante porque alguns provedores de proxy oferecem gateways HTTP/2 que são mais difíceis de detectar. A opção aceita o formato padrão de URL com autenticação:

const response = await got('https://example.com', {
  proxyUrl: 'http://user-country-US:pass@gate.proxyhat.com:8080',
});

Para SOCKS5, basta usar o esquema socks5:// na porta 1080:

const response = await got('https://example.com', {
  proxyUrl: 'socks5://user-country-DE:pass@gate.proxyhat.com:1080',
});

Roteando através de proxies residenciais em gate.proxyhat.com

Quando os headers e o suporte HTTP/2 já fazem suas requisições parecerem legítimas, o próximo vetor de detecção é o IP. IPs de datacenter são trivialmente identificados — serviços como MaxMind GeoIP e IP2Location classificam ASN por tipo (ISP residencial vs datacenter vs hosting). Se o alvo vê um IP da AWS ou DigitalOcean com headers de Chrome desktop, a inconsistência é óbvia.

Proxies residenciais usam IPs atribuídos a ISPs reais — casas, dispositivos móveis, conexões de fibra doméstica. Para o alvo, a requisição parece vir de um usuário comum. Isso é o complemento perfeito para o nodejs scraping proxy com got-scraping: headers coerentes + IP residencial = requisição que passa por anti-bot de nível avançado.

Com o ProxyHat, você controla geolocalização e sessão diretamente no nome de usuário:

• user-country-US — IP residencial nos EUA.
• user-country-DE-city-berlin — IP residencial em Berlim.
• user-session-abc123 — sessão fixa (sticky IP) para manter cookies entre requisições.

Para casos onde HTTP não é suficiente, o SOCKS5 na porta 1080 oferece uma camada de transporte diferente, útil quando o alvo bloqueia conexões HTTP proxy conhecidas. Veja todas as localizações disponíveis na página de locations do ProxyHat.

Exemplo runnable: rotação de IPs residenciais com retry hooks

Aqui está um exemplo completo que rotaciona IPs residenciais por requisição, usa sessões fixas quando necessário e implementa retry com backoff exponencial. O got scraping header generator cuida dos headers automaticamente.

import { gotScraping } from 'got-scraping';
import pLimit from 'p-limit';

// ProxyHat SDK — gera nomes de usuário por requisição
function proxyUsername(opts = {}) {
  const parts = [];
  if (opts.country) parts.push(`country-${opts.country}`);
  if (opts.city) parts.push(`city-${opts.city.toLowerCase()}`);
  if (opts.session) parts.push(`session-${opts.session}`);
  return `user-${parts.join('-')}`;
}

function proxyUrl(opts = {}) {
  const user = proxyUsername(opts);
  return `http://${user}:PASSWORD@gate.proxyhat.com:8080`;
}

// Instância got-scraping com headers de Chrome desktop
const got = gotScraping.extend({
  headerGeneratorOptions: {
    browsers: ['chrome'],
    devices: ['desktop'],
    operatingSystems: ['windows', 'macos'],
  },
  retry: {
    limit: 3,
    statusCodes: [403, 429, 500, 502, 503],
    backoffLimit: 5000,
  },
  hooks: {
    beforeRequest: [
      (options) => {
        // Rotaciona sessão a cada requisição
        const session = Math.random().toString(36).slice(2, 10);
        options.proxyUrl = proxyUrl({
          country: 'US',
          session,
        });
      },
    ],
    afterResponse: [
      (response, retryWithMergedOptions) => {
        if (response.statusCode === 403) {
          console.log('403 recebido — rotacionando IP e tentando novamente');
          const newSession = Math.random().toString(36).slice(2, 10);
          return retryWithMergedOptions({
            proxyUrl: proxyUrl({ country: 'US', session: newSession }),
          });
        }
        return response;
      },
    ],
  },
});

// Coleta com concorrência limitada
const limit = pLimit(10);

async function scrapeUrl(url) {
  const response = await got(url, {
    timeout: { request: 15000 },
    responseType: 'json',
  });
  return response.body;
}

// Executa 100 URLs com no máximo 10 concorrentes
const urls = Array.from({ length: 100 }, (_, i) =>
  `https://httpbin.org/json?page=${i}`
);

const results = await Promise.all(
  urls.map((url) => limit(() => scrapeUrl(url)))
);

console.log(`Coletados ${results.length} resultados`);

Este exemplo demonstra três padrões críticos:

• Rotação por requisição: cada requisição recebe uma sessão única, garantindo um IP diferente.
• Retry com rotação: o hook afterResponse detecta 403 e tenta novamente com um novo IP.
• Concorrência limitada: p-limit com 10 conexões simultâneas evita sobrecarregar tanto seu servidor quanto o alvo.

Padrões de produção: hooks, cookies e Crawlee

Retry e afterResponse hooks

O sistema de hooks do got é o ponto de extensão idiomático para lógica de retry customizada. Além do beforeRequest e afterResponse mostrados acima, você pode usar:

• beforeRetry: executado antes de cada tentativa de retry — útil para trocar proxy.
• beforeRedirect: executado antes de seguir redirects — útil para validar a URL de destino.
• init: executado quando a requisição é criada — útil para logging.

hooks: {
  beforeRetry: [
    (error, retryOptions) => {
      console.log(`Retry para ${retryOptions.url} — erro: ${error.code}`);
      // Troca a sessão do proxy no retry
      retryOptions.proxyUrl = proxyUrl({
        country: 'US',
        session: Math.random().toString(36).slice(2, 10),
      });
    },
  ],
},

Cookie jars para sessões persistentes

Alguns sites exigem sessões persistentes — você precisa manter cookies entre requisições. O got suporta tough-cookie nativamente:

import { CookieJar } from 'tough-cookie';

const cookieJar = new CookieJar();

const got = gotScraping.extend({
  headerGeneratorOptions: {
    browsers: ['chrome'],
    devices: ['desktop'],
    operatingSystems: ['windows'],
  },
  cookieJar,
  hooks: {
    beforeRequest: [
      (options) => {
        // Sessão fixa para manter cookies válidos
        options.proxyUrl = proxyUrl({
          country: 'US',
          session: 'checkout-flow-001',
        });
      },
    ],
  },
});

// Primeira requisição estabelece cookies
await got('https://example.com/login');

// Segunda requisição reusa cookies e mesmo IP
await got('https://example.com/dashboard');

Integração com Crawlee CheerioCrawler

Para operações maiores, o Crawlee é o framework de scraping da Apify que usa got-scraping internamente. O CheerioCrawler é ideal para páginas estáticas — ele faz a requisição com got-scraping e parseia o HTML com Cheerio:

import { CheerioCrawler } from 'crawlee';

const crawler = new CheerioCrawler({
  requestHandler: async ({ $, request }) => {
    const title = $('title').text();
    const links = $('a[href]').map((_, el) => $(el).attr('href')).get();
    console.log(`${request.url}: ${title} (${links.length} links)`);
  },
  // got-scraping options passadas para cada requisição
  useHeaderGenerator: true,
  headerGeneratorOptions: {
    browsers: ['chrome'],
    devices: ['desktop'],
    operatingSystems: ['windows', 'macos'],
  },
  proxyConfiguration: {
    proxyUrls: [
      'http://user-country-US:PASSWORD@gate.proxyhat.com:8080',
    ],
  },
  maxConcurrency: 10,
  maxRequestRetries: 3,
});

await crawler.run(['https://example.com']);

O Crawlee gerencia fila de URLs, deduplicação, retry e armazenamento automaticamente. Para scraping de SERP em escala, veja nosso guia de SERP tracking com proxies.

Quando um navegador headless é inevitável

got-scraping resolve a maioria dos casos de páginas estáticas e APIs internas. Mas alguns sites exigem execução de JavaScript, resolução de CAPTCHAs ou interação com DOM. Nesses casos, você precisa de um navegador headless como Playwright ou Puppeteer.

Sinais de que você precisa ir além do got-scraping:

• A página carrega conteúdo via XHR/fetch após o load — o HTML inicial está vazio.
• Há um challenge de JavaScript que precisa ser executado (Cloudflare JS challenge, Datadome).
• CAPTCHAs aparecem mesmo com headers e IPs residenciais corretos.

Para esses cenários, o Crawlee oferece PlaywrightCrawler que combina navegador headless com proxies residenciais. A documentação do ProxyHat tem exemplos de configuração para Playwright.

Ética: dados públicos, robots.txt e limites

Antes de qualquer scraping, verifique três coisas:

1. robots.txt: respeite as diretivas Disallow. Ferramentas como robots-parser podem automatizar isso.
2. Termos de Serviço: alguns sites proíbem scraping explicitamente. Violar ToS pode ter consequências legais sob leis como a Computer Fraud and Abuse Act (CFAA).
3. API oficial: se existe uma API, use-a. É mais estável, legalmente mais segura e frequentemente mais rápida.

Para dados pessoais, o GDPR exige base legal para processamento. Dados públicos não são isentos — o processamento deve ter uma base legal legítima.

Comparação: got-scraping vs axios vs Crawlee

Key Takeaways

• got-scraping em Node.js resolve o problema de headers incoerentes que causa bloqueios em got e axios puros.
• O got scraping header generator produz conjuntos completos de headers de Chrome/Firefox/Safari com ordem correta, sec-ch-ua e accept-language.
• Headers coerentes sem IP residencial ainda são detectáveis — got-scraping proxy residencial em gate.proxyhat.com:8080 completa a camuflagem.
• Use got.extend() com headerGeneratorOptions e hooks de beforeRequest para rotação idiomática de proxies.
• Para escala, combine got-scraping com p-limit (concorrência limitada), tough-cookie (sessões) e Crawlee (fila e deduplicação).
• Respeite robots.txt, ToS e leis como CFAA e GDPR. Prefira APIs oficiais quando disponíveis.

Pronto para começar? Veja os planos do ProxyHat e configure seu primeiro nodejs scraping proxy em minutos. Para mais casos de uso, visite nosso guia de web scraping com proxies.