> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Node
> Realiza scraping, rastrea y extrae datos estructurados de sitios web con el SDK de Firecrawl para Node.
Haz scraping de páginas individuales, rastrea sitios completos y mapea URL desde tu aplicación Node.js. El SDK gestiona la paginación, los reintentos y la consulta asíncrona del estado de los trabajos para que puedas centrarte en trabajar con los datos devueltos.
## Instalación
Instala el SDK con npm:
```js Node theme={null}
// npm install firecrawl
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({
// No se necesita API key para comenzar — agrega una para obtener límites de tasa más altos:
// apiKey: "fc-YOUR-API-KEY",
});
```
## Uso
1. Obtén una clave de API en [firecrawl.dev](https://firecrawl.dev)
2. Define la clave de API como una variable de entorno llamada `FIRECRAWL_API_KEY` o pásala como parámetro a la clase `Firecrawl`.
**¿No tienes una clave de API?** Puedes crear `Firecrawl` sin una clave y usar `scrape`, `search` e `interact` en el plan Free sin clave (limitado por IP; consulta [Rate Limits](/es/rate-limits#keyless-no-api-key)). Todos los demás métodos requieren una clave.
Aquí tienes un ejemplo de cómo usar el SDK con manejo de errores:
```js Node theme={null}
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});
// Extraer datos de un sitio web
const scrapeResponse = await firecrawl.scrape('https://firecrawl.dev', {
formats: ['markdown', 'html'],
});
console.log(scrapeResponse)
// Rastrear un sitio web
const crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {
limit: 100,
scrapeOptions: {
formats: ['markdown', 'html'],
}
});
console.log(crawlResponse)
```
### Extracción de una URL
Extrae una sola URL y obtén datos estructurados de la página con el método `scrape`.
```js Node.js theme={null}
// Extraer un sitio web:
const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });
console.log(scrapeResult)
```
### Análisis de archivos subidos
Usa `parse` cuando quieras subir un archivo local (`html`, `pdf`, `docx`, `xlsx`, etc.) en lugar de hacer scraping mediante una URL.
`parse` no admite `changeTracking` ni opciones exclusivas del navegador, como `screenshot`, `branding`, `actions`, `waitFor`, `location` y `mobile`.
```js Node theme={null}
const parsed = await firecrawl.parse(
{
data: "Node Parse
",
filename: "upload.html",
contentType: "text/html",
},
{
formats: ["markdown"],
},
);
console.log(parsed.markdown);
```
### Rastreo de un sitio web
Rastrea un sitio web completo a partir de una sola URL con el método `crawl`. Puedes establecer un límite de páginas, restringir el rastreo a dominios específicos y seleccionar formatos de salida. Consulta [Pagination](#pagination) para la paginación automática y manual.
```js Node theme={null}
const job = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 5, pollInterval: 1, timeout: 120 });
console.log(job.status);
```
### Rastreo solo del sitemap
Usa `sitemap: "only"` para rastrear únicamente las URL del sitemap (la URL inicial siempre se incluye y se omite la detección de enlaces HTML).
```js Node theme={null}
const job = await firecrawl.crawl('https://docs.firecrawl.dev', {
sitemap: 'only',
limit: 25,
});
console.log(job.status, job.data.length);
```
### Iniciar un rastreo
Inicia un rastreo sin esperar a que termine usando `startCrawl`. El método devuelve un ID de trabajo que puedes consultar más tarde. Usa `crawl` en su lugar cuando quieras bloquear hasta que finalice. Consulta [Paginación](#pagination) para el comportamiento y los límites de paginación.
```js Node theme={null}
const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(id);
```
### Consultar el estado del rastreo
Verifica si un rastreo sigue en ejecución, se ha completado o ha fallado con el método `checkCrawlStatus`. Proporciona el ID de trabajo devuelto por `startCrawl`.
```js Node.js theme={null}
const estado = await firecrawl.getCrawlStatus("");
console.log(estado);
```
### Cancelar un rastreo
Cancela un rastreo en curso con el método `cancelCrawl`. Pasa el ID de trabajo que devuelve `startCrawl`.
```js Node theme={null}
const ok = await firecrawl.cancelCrawl("");
console.log("Cancelado:", ok);
```
### Mapear un sitio web
Descubre todas las URL de un sitio web con el método `map`. Pasa una URL inicial y obtén una lista de las páginas detectadas.
```js Node theme={null}
const res = await firecrawl.map('https://firecrawl.dev', { limit: 10 });
console.log(res.links);
```
### Rastreo de un sitio web con WebSockets
Obtén los resultados del rastreo en tiempo real con el método `crawlUrlAndWatch`. Recibirás cada página a medida que se rastrea, en lugar de esperar a que termine todo el trabajo.
```js Node theme={null}
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });
// Inicia un rastreo y luego míralo
const { id } = await firecrawl.startCrawl('https://mendable.ai', {
excludePaths: ['blog/*'],
limit: 5,
});
const watcher = firecrawl.watcher(id, { kind: 'crawl', pollInterval: 2, timeout: 120 });
watcher.on('document', (doc) => {
console.log('DOC', doc);
});
watcher.on('error', (err) => {
console.error('ERR', err?.error || err);
});
watcher.on('done', (state) => {
console.log('DONE', state.status);
});
// Comienza a mirar (WS con alternativa HTTP)
await watcher.start();
```
Los puntos de conexión de Firecrawl para crawl y batch devuelven una URL `next` cuando hay más datos disponibles. El SDK de Node realiza la paginación automáticamente por defecto y agrega todos los documentos; en ese caso, `next` será `null`. Puedes desactivar la paginación automática o establecer límites.
#### Rastreo
Usa el método auxiliar `crawl` para la forma más sencilla, o inicia un job y pagina manualmente.
* Consulta el flujo por defecto en [Rastrear un sitio web](#crawling-a-website).
* Inicia un trabajo y luego recupera una página a la vez con `autoPaginate: false`.
```js Nodo theme={null}
const crawlStart = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 5 });
const crawlJobId = crawlStart.id;
const crawlSingle = await firecrawl.getCrawlStatus(crawlJobId, { autoPaginate: false });
console.log('rastreo de una sola página:', crawlSingle.status, 'docs:', crawlSingle.data.length, 'siguiente:', crawlSingle.next);
```
* Mantén la paginación automática activada, pero deténla antes con `maxPages`, `maxResults` o `maxWaitTime`.
```js Node theme={null}
const crawlLimited = await firecrawl.getCrawlStatus(crawlJobId, {
autoPaginate: true,
maxPages: 2,
maxResults: 50,
maxWaitTime: 15,
});
console.log('rastreo limitado:', crawlLimited.status, 'docs:', crawlLimited.data.length, 'siguiente:', crawlLimited.next);
```
#### Scrape por lotes
Usa el método waiter `batchScrape`, o inicia un job y pagina manualmente.
* Consulta el flujo predeterminado en [Raspado por lotes](/es/features/batch-scrape).
* Inicia un job y luego recupera una página a la vez con `autoPaginate: false`.
```js Node theme={null}
const batchStart = await firecrawl.startBatchScrape([
'https://docs.firecrawl.dev',
'https://firecrawl.dev',
], { options: { formats: ['markdown'] } });
const batchJobId = batchStart.id;
const batchSingle = await firecrawl.getBatchScrapeStatus(batchJobId, { autoPaginate: false });
console.log('lote, una sola página:', batchSingle.status, 'docs:', batchSingle.data.length, 'siguiente:', batchSingle.next);
```
* Mantén la paginación automática activada, pero deténla antes con `maxPages`, `maxResults` o `maxWaitTime`.
```js Node theme={null}
const batchLimited = await firecrawl.getBatchScrapeStatus(batchJobId, {
autoPaginate: true,
maxPages: 2,
maxResults: 100,
maxWaitTime: 20,
});
console.log('lote limitado:', batchLimited.status, 'docs:', batchLimited.data.length, 'siguiente:', batchLimited.next);
```
## Browser
Inicia sesiones de navegador en la nube y ejecuta código de forma remota.
### Crear una sesión
```js Node theme={null}
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const session = await firecrawl.browser({ ttl: 600 });
console.log(session.id); // ID de sesión
console.log(session.cdpUrl); // wss://cdp-proxy.firecrawl.dev/cdp/...
console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...
```
### Ejecutar código
```js Node theme={null}
const result = await firecrawl.browserExecute(session.id, {
code: 'await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',
});
console.log(result.result); // "Hacker News"
```
Ejecuta JavaScript en lugar de Python:
```js Node theme={null}
const result = await firecrawl.browserExecute(session.id, {
code: 'await page.goto("https://example.com"); const t = await page.title(); console.log(t);',
language: "node",
});
```
Ejecuta Bash con agent-browser:
```js Node theme={null}
const result = await firecrawl.browserExecute(session.id, {
code: "agent-browser open https://example.com && agent-browser snapshot",
language: "bash",
});
```
### Perfiles
Guarda y reutiliza el estado del navegador (cookies, localStorage, etc.) entre distintas sesiones:
```js Node theme={null}
const session = await firecrawl.browser({
ttl: 600,
profile: {
name: "my-profile",
saveChanges: true,
},
});
```
### Conectar mediante CDP
Para obtener control completo de Playwright, conecta directamente usando la URL de CDP:
```js Node theme={null}
import { chromium } from "playwright";
const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await browser.close();
```
### Listar & cerrar sesiones
```js Node theme={null}
// Listar sesiones activas
const { sessions } = await firecrawl.listBrowsers({ status: "active" });
for (const s of sessions) {
console.log(s.id, s.status, s.createdAt);
}
// Cerrar una sesión
await firecrawl.deleteBrowser(session.id);
```
### Sesión interactiva vinculada al scraping
Usa un ID de trabajo de scraping para seguir interactuando con el contexto reproducido de la página de ese scraping:
* `interact(jobId, {...})` ejecuta código en la sesión del navegador vinculada al scraping.
* La primera llamada a `interact` inicializa automáticamente la sesión a partir del contexto del scraping.
* Las llamadas adicionales a `interact` con el mismo ID de trabajo reutilizan ese estado activo del navegador.
* `stopInteraction(jobId)` detiene la sesión interactiva cuando termines.
```js Node theme={null}
const doc = await firecrawl.scrape("https://example.com", {
actions: [{ type: "click", selector: "a[href='/pricing']" }],
});
const scrapeJobId = doc.metadata?.scrapeId;
if (!scrapeJobId) throw new Error("Missing scrape job id");
const run = await firecrawl.interact(scrapeJobId, {
code: "console.log(await page.url())",
language: "node",
timeout: 60,
});
console.log(run.stdout);
await firecrawl.stopInteraction(scrapeJobId);
```
## Manejo de errores
El SDK arroja excepciones descriptivas para cualquier error devuelto por la API de Firecrawl. Envuelve las llamadas en bloques `try/catch`, como se muestra en los ejemplos anteriores.
> ¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para obtener instrucciones de incorporación automatizada.