Saltar al contenido principal
Importante: Usa el scraping autenticado solo en sistemas donde tengas permiso explícito de ambas partes (tú y el propietario de la plataforma), como herramientas internas, autohospedadas o recursos que controlas por completo. No utilices autenticación en plataformas a menos que estés seguro de que cumple con los Términos y Condiciones del sitio, y obtén permiso por escrito en caso de duda. El uso indebido de cookies de sesión puede violar los Términos de Servicio o la ley; confirma siempre que estás autorizado a acceder a contenido protegido de esta manera.

​
Descripción general

El enfoque recomendado para el scraping autenticado es la autenticación basada en cookies, donde:
  1. Inicias sesión manualmente en tu aplicación
  2. Extraes la cookie de sesión desde DevTools
  3. Usas la cookie con Firecrawl para acceder a páginas protegidas
Tiempos de expiración de las cookies:
  • Herramientas internas: A menudo 7-30 días o más
  • Otras herramientas: A menudo horas o minutos
Las herramientas internas suelen tener una mayor duración de las cookies, lo que hace que este método sea ideal para tareas de scraping recurrentes.

​
Configuración

1

Obtener la clave de API

Obtén tu clave de API de Firecrawl en firecrawl.dev/app
2

Instalar dependencias

npm
npm install @mendable/firecrawl-js
Node.js < v20: Si usas Node.js versión 19 o anterior, también necesitarás instalar dotenv:
npm install dotenv
e importarlo con import 'dotenv/config' al inicio de tu archivo.
3

Configurar el entorno

Crea un archivo .env:
.env
FIRECRAWL_API_KEY=your_firecrawl_api_key

​
Paso 1: Extraer cookies con DevTools

Aplicación de demostración: Puedes practicar con nuestra app de demo en https://firecrawl-auth.vercel.app
  • Correo electrónico: test@example.com
  • Contraseña: password123
1

Inicia sesión en tu aplicación

Ve a https://firecrawl-auth.vercel.app e inicia sesión con las credenciales anteriores
2

Abre DevTools

Presiona F12 o haz clic derecho → “Inspect”
3

Ve a la pestaña Application

Haz clic en la pestaña Application (Chrome) o Storage (Firefox)
4

Busca y copia la cookie

  1. Despliega Cookies en la barra lateral
  2. Haz clic en tu dominio
  3. Busca la cookie auth-token
  4. Haz doble clic en Value y cópialo
Vista de cookies en DevTools
Para la app de demo, la cookie se ve así: 
auth-token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJleGFtcGxlLXVzZXItaWQiLCJlbWFpbCI6InRlc3RAZXhhbXBsZS5jb20ifQ.example-signature-hash
Importante: Las cookies son credenciales sensibles. Nunca las compartas públicamente ni las subas al control de versiones. Trátalas como contraseñas.

​
Paso 2: Usa cookies con 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 // Espera 3 segundos a que cargue la página
});

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

​
Mejores prácticas

Seguridad de cookies

  • Almacena las cookies en variables de entorno
  • Nunca subas/confirmes cookies al repositorio
  • Rota las cookies con regularidad
  • Usa .gitignore para los archivos .env

Vencimiento de cookies

  • Revisa las fechas de vencimiento en DevTools
  • Configura alertas antes del vencimiento
  • Vuelve a extraer las cookies cuando venzan
  • Considera usar autenticación basada en formularios para cookies de corta duración

Limitación de tasa

  • Respeta los límites de tasa de la aplicación
  • Agrega demoras entre solicitudes
  • Supervisa errores 429 (Too Many Requests)
  • Usa reintentos con backoff exponencial

Manejo de errores

  • Revisa errores 401/403 (cookies vencidas)
  • Valida el contenido de la respuesta
  • Registra fallos de autenticación
  • Ten métodos de autenticación alternativos

​
Solución de problemas

Posibles causas:
  • La cookie ha caducado
  • La cookie se copió de forma incorrecta
  • La aplicación requiere encabezados adicionales
  • La sesión se invalidó en el servidor
Soluciones:
  • Vuelve a extraer las cookies desde DevTools después de un inicio de sesión nuevo
  • Verifica si necesitas varias cookies (sesión + token CSRF)
  • Comprueba que el dominio de la cookie coincida con la URL de destino
Para sesiones de corta duración:
  • Usa autenticación basada en formularios
  • Automatiza el inicio de sesión con acciones
  • Configura un cron para renovar las cookies
  • Considera solicitar sesiones más largas al administrador de tu herramienta interna
Vigencia de las cookies para herramientas internas: Muchas herramientas internas establecen cookies con vencimientos de 7 a 30 días, lo que las hace ideales para tareas de scraping recurrentes. Revisa el campo Expires de tu cookie en DevTools para ver cuánto tiempo sigue siendo válida.