# Node
> Realiza scraping, rastrea y extrae datos estructurados de sitios web con el SDK de Firecrawl para Node.js.
import InstallationNode from '/snippets/es/v2/installation/js.mdx'
import ScrapeAndCrawlExampleNode from '/snippets/es/v2/scrape-and-crawl/js.mdx'
import ScrapeNodeShort from '/snippets/es/v2/scrape/short/js.mdx'
import CrawlNodeShort from '/snippets/es/v2/crawl/short/js.mdx'
import CrawlSitemapOnlyNode from '/snippets/es/v2/crawl/sitemap-only/js.mdx'
import StartCrawlNodeShort from '/snippets/es/v2/start-crawl/short/js.mdx'
import CheckCrawlStatusNodeShort from '/snippets/es/v2/crawl-status/short/js.mdx'
import CancelCrawlNodeShort from '/snippets/es/v2/crawl-delete/short/js.mdx'
import MapNodeShort from '/snippets/es/v2/map/short/js.mdx'
import ExtractNodeShort from '/snippets/v2/extract/short/js.mdx'
import CrawlWebSocketNodeBase from '/snippets/es/v2/crawl-websocket/base/js.mdx'
import PersistentJS from '/snippets/es/v2/browser/persistent/js.mdx'
import AgentWithSchemaNode from '/snippets/es/v2/agent/with-schema/js.mdx'
import AgentStatusNode from '/snippets/es/v2/agent/status/js.mdx'
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:
## 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:
### Extracción de una URL
Extrae una sola URL y obtén datos estructurados de la página con el método `scrape`.
### 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
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.
### 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).
### 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.
### 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`.
### Cancelar un rastreo
Cancela un rastreo en curso con el método `cancelCrawl`. Pasa el ID de trabajo que devuelve `startCrawl`.
### 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.
{/* ### Extraer datos estructurados de sitios web
Para extraer datos estructurados de sitios web con manejo de errores, utiliza el método `extractUrl`. Recibe la URL inicial como parámetro y devuelve los datos extraídos como un diccionario.
*/}
### Ejecutar un agente
Asigna una tarea de investigación o extracción a un agente mediante el método `agent`. Proporciona un `prompt`, un `schema` opcional para definir la salida y `maxCredits` para limitar el gasto de la ejecución.
Las ejecuciones de agentes son asíncronas. Usa `startAgent` para obtener un ID de trabajo de inmediato y luego consulta su estado con `getAgentStatus`.
Cada ejecución también registra una traza de ejecución e instantáneas de salida, que puedes consultar con `getAgentTrace` y `getAgentSnapshot`. Consulta [Agent](/es/features/agent) para ver el esquema de eventos y la lista completa de parámetros.
### Rastreo de un sitio web con WebSockets
Obtén los resultados del rastreo en tiempo real con `watcher(jobId, options)`. Recibirás cada página a medida que se rastrea, en lugar de esperar a que termine todo el trabajo.
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
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
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
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
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
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
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
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
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:
### Conectar mediante CDP
Para obtener control completo de Playwright, conecta directamente usando la URL de CDP:
```js Node
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
// 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
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.