Pular para o conteúdo principal
Importante: Use a raspagem autenticada apenas em sistemas nos quais você tenha permissão explícita de ambas as partes (você e o proprietário da plataforma), como ferramentas internas, auto-hospedadas, ou recursos que você controla integralmente. Não use autenticação em plataformas a menos que tenha certeza de que ela está em conformidade com os Termos e Condições do site e obtenha permissão por escrito em caso de dúvida. O uso inadequado de cookies de sessão pode violar os termos de serviço ou leis; sempre confirme que você está autorizado a acessar conteúdo protegido dessa forma.

​
Visão geral

A abordagem recomendada para scraping autenticado é a autenticação baseada em cookies, em que você:
  1. Faz login manualmente no seu aplicativo
  2. Extrai o cookie de sessão pelo DevTools
  3. Usa o cookie com o Firecrawl para acessar páginas protegidas
Prazos de expiração de cookies:
  • Ferramentas internas: Geralmente de 7 a 30 dias ou mais
  • Outras ferramentas: Geralmente em horas ou minutos
Ferramentas internas costumam ter cookies com maior vida útil, tornando esse método ideal para tarefas recorrentes de scraping.

​
Configuração

1

Obter a chave de API

Obtenha sua chave de API do Firecrawl em firecrawl.dev/app
2

Instalar dependências

npm
npm install @mendable/firecrawl-js
Node.js < v20: Se você estiver usando a versão 19 ou anterior do Node.js, também será necessário instalar dotenv:
npm install dotenv
E importá-lo com import 'dotenv/config' no início do seu arquivo.
3

Configurar ambiente

Crie um arquivo .env:
.env
FIRECRAWL_API_KEY=your_firecrawl_api_key

​
Etapa 1: Extrair cookies pelo DevTools

Aplicativo de demonstração: Você pode praticar com nosso app de demonstração em https://firecrawl-auth.vercel.app
  • E-mail: test@example.com
  • Senha: password123
1

Fazer login no seu aplicativo

Acesse https://firecrawl-auth.vercel.app e faça login com as credenciais acima
2

Abrir o DevTools

Pressione F12 ou clique com o botão direito → “Inspecionar”
3

Ir até a guia Application

Clique na guia Application (Chrome) ou Storage (Firefox)
4

Encontrar e copiar o cookie

  1. Expanda Cookies na barra lateral
  2. Clique no seu domínio
  3. Encontre o cookie auth-token
  4. Dê um duplo clique no campo Value e copie
Visualização de cookies no DevTools
No app de demonstração, o cookie é semelhante a: 
auth-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJleGFtcGxlLXVzZXItaWQiLCJlbWFpbCI6InRlc3RAZXhhbXBsZS5jb20ifQ.example-signature-hash
Importante: Cookies são credenciais sensíveis. Nunca as compartilhe publicamente nem as versione em controle de código. Trate-os como senhas.

​
Etapa 2: Usar cookies com o Firecrawl

import FirecrawlApp from "@mendable/firecrawl-js";

const app = new FirecrawlApp({
  apiKey: process.env.FIRECRAWL_API_KEY
});

const result = await app.scrape("https://firecrawl-auth.vercel.app/dashboard", {
  formats: ["markdown", "screenshot"],
  headers: {
    Cookie: 'auth-token=COOKIE_GOES_HERE'
  },
  waitFor: 3000 // Aguarda 3 segundos para o carregamento da página
});

console.log("=== Markdown ===\n" + result.markdown + "\n\n=== URL da Captura de Tela ===\n" + result.screenshot);

​
Melhores práticas

Segurança de cookies

  • Armazene cookies em variáveis de ambiente
  • Nunca faça commit de cookies no Git
  • Faça rotação de cookies regularmente
  • Use .gitignore para arquivos .env

Expiração de cookies

  • Verifique os tempos de expiração no DevTools
  • Configure alertas antes da expiração
  • Extraia novamente os cookies quando expirarem
  • Considere usar autenticação baseada em formulário para cookies de curta duração

Limitação de taxa

  • Respeite os limites de taxa da aplicação
  • Adicione atrasos entre requisições
  • Monitore erros 429 (muitas solicitações)
  • Use backoff exponencial para novas tentativas

Tratamento de erros

  • Verifique erros 401/403 (cookies expirados)
  • Valide o conteúdo da resposta
  • Registre falhas de autenticação
  • Tenha métodos de autenticação de contingência

​
Solução de problemas

Possíveis causas:
  • O cookie expirou
  • O cookie foi copiado incorretamente
  • A aplicação requer cabeçalhos adicionais
  • A sessão foi invalidada no servidor
Soluções:
  • Extraia novamente os cookies no DevTools após um novo login
  • Verifique se você precisa de vários cookies (sessão + token CSRF)
  • Confirme se o domínio do cookie corresponde ao URL de destino
Para sessões de curta duração:
  • Use autenticação baseada em formulário
  • Automatize o login com ações
  • Configure um cron para renovar os cookies
  • Considere solicitar sessões mais longas ao administrador da sua ferramenta interna
Validade de cookies em ferramentas internas: Muitas ferramentas internas definem cookies com validade de 7 a 30 dias, o que os torna ideais para tarefas recorrentes de scraping. Verifique o campo Expires do seu cookie no DevTools para saber por quanto tempo ele é válido.