> ## 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
> Faça scraping, rastreamento e extração de dados estruturados em sites usando o Firecrawl Node SDK.
Faça scraping de páginas individuais, rastreie sites inteiros e mapeie URLs no seu aplicativo Node.js. O SDK gerencia a paginação, as novas tentativas e a consulta assíncrona de jobs para que você possa se concentrar nos dados retornados.
## Instalação
Instale o SDK com npm:
```js Node theme={null}
// npm install firecrawl
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({
// Nenhuma API key necessária para começar — adicione uma para limites de taxa maiores:
// apiKey: "fc-YOUR-API-KEY",
});
```
## Uso
1. Obtenha uma chave de API em [firecrawl.dev](https://firecrawl.dev)
2. Defina a chave de API como uma variável de ambiente chamada `FIRECRAWL_API_KEY` ou passe-a como parâmetro para a classe `Firecrawl`.
**Sem chave de API?** Você pode instanciar `Firecrawl` sem uma chave e usar `scrape`, `search` e `interact` no plano gratuito sem chave (com limite de taxa por IP — veja [Limites de taxa](/pt-BR/rate-limits#keyless-no-api-key)). Todos os outros métodos exigem uma chave.
Veja um exemplo de como usar o SDK com tratamento de erros:
```js Node theme={null}
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});
// Fazer scraping de um site
const scrapeResponse = await firecrawl.scrape('https://firecrawl.dev', {
formats: ['markdown', 'html'],
});
console.log(scrapeResponse)
// Fazer crawling de um site
const crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {
limit: 100,
scrapeOptions: {
formats: ['markdown', 'html'],
}
});
console.log(crawlResponse)
```
### Scraping de uma URL
Use o método `scrape` para extrair os dados de uma única URL e receber os dados estruturados da página.
```js Node theme={null}
// Fazer scraping de um site:
const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });
console.log(scrapeResult)
```
### Análise de arquivos enviados
Use `parse` quando quiser enviar um arquivo local (`html`, `pdf`, `docx`, `xlsx`, etc.) em vez de fazer scraping a partir de uma URL.
`parse` não oferece suporte a `changeTracking` nem a opções exclusivas do navegador, como `screenshot`, `branding`, `actions`, `waitFor`, `location` e `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);
```
### Rastreando um site
Rastreie um site inteiro a partir de uma única URL com o método `crawl`. Você pode definir um limite de páginas, restringir o rastreamento a domínios específicos e escolher formatos de resultado. Consulte [Paginação](#pagination) para paginação automática e manual.
```js Node theme={null}
const job = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 5, pollInterval: 1, timeout: 120 });
console.log(job.status);
```
### Rastreamento Somente do Sitemap
Use `sitemap: "only"` para rastrear apenas URLs do sitemap (a URL inicial sempre é incluída e a descoberta de links em HTML é ignorada).
```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 um rastreamento
Inicie um rastreamento sem aguardar a conclusão usando `startCrawl`. O método retorna um ID do job que você pode consultar depois. Use `crawl` em vez disso quando quiser bloquear até a conclusão. Veja [Paginação](#pagination) para comportamento e limites de paginação.
```js Node theme={null}
const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(id);
```
### Verificando o status do rastreamento
Verifique se um rastreamento ainda está em execução, foi concluído ou falhou usando o método `checkCrawlStatus`. Passe o ID do job retornado por `startCrawl`.
```js Node theme={null}
const status = await firecrawl.getCrawlStatus("");
console.log(status);
```
### Cancelando um rastreamento
Cancele um rastreamento em andamento usando o método `cancelCrawl`. Informe o ID do job retornado por `startCrawl`.
```js Node.js theme={null}
const ok = await firecrawl.cancelCrawl("");
console.log("Cancelado:", ok);
```
### Mapeando um site
Descubra todas as URLs de um site com o método `map`. Informe uma URL inicial e receba uma lista das páginas encontradas.
```js Node.js theme={null}
const res = await firecrawl.map('https://firecrawl.dev', { limit: 10 });
console.log(res.links);
```
### Rastreamento de um site com WebSockets
Receba os resultados do rastreamento em tempo real com o método `crawlUrlAndWatch`. Você recebe cada página conforme ela é rastreada, em vez de aguardar a conclusão de todo o job.
```js Node theme={null}
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });
// Inicie um crawl e depois acompanhe
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);
});
// Comece a acompanhar (WS com fallback em HTTP)
await watcher.start();
```
Os endpoints do Firecrawl para crawl e batch retornam uma URL `next` quando há mais dados disponíveis. O SDK de Node faz paginação automática por padrão e agrega todos os documentos; nesse caso, `next` será `null`. Você pode desativar a paginação automática ou definir limites.
#### Rastreamento
Use o método waiter `crawl` para a experiência mais simples, ou inicie um job e faça a paginação manualmente.
* Veja o fluxo padrão em [Rastrear um site](#crawling-a-website).
* Inicie um job e, em seguida, recupere uma página por vez com `autoPaginate: false`.
```js Node 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('rastreamento de página única:', crawlSingle.status, 'docs:', crawlSingle.data.length, 'próximo:', crawlSingle.next);
```
* Mantenha a paginação automática ativada, mas interrompa antecipadamente com `maxPages`, `maxResults` ou `maxWaitTime`.
```js Node theme={null}
const crawlLimited = await firecrawl.getCrawlStatus(crawlJobId, {
autoPaginate: true,
maxPages: 2,
maxResults: 50,
maxWaitTime: 15,
});
console.log('crawl limitado:', crawlLimited.status, 'docs:', crawlLimited.data.length, 'próximo:', crawlLimited.next);
```
#### Coleta em lote
Use o método waiter `batchScrape` ou inicie uma tarefa e pagine manualmente.
* Veja o fluxo padrão em [Raspagem em lote](/pt-BR/features/batch-scrape).
* Inicie um job e, em seguida, recupere uma página por vez com `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('página única do lote:', batchSingle.status, 'docs:', batchSingle.data.length, 'próximo:', batchSingle.next);
```
* Mantenha a paginação automática ligada, mas interrompa antes com `maxPages`, `maxResults` ou `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, 'próximo:', batchLimited.next);
```
## Browser
Inicie sessões de navegador na nuvem e execute código remotamente.
### Criar sessão
```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 da sessão
console.log(session.cdpUrl); // wss://cdp-proxy.firecrawl.dev/cdp/...
console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...
```
### Executar 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"
```
Use JavaScript em vez 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",
});
```
Execute o bash usando 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",
});
```
### Perfis
Salve e reutilize o estado do navegador (cookies, localStorage etc.) entre sessões:
```js Node theme={null}
const session = await firecrawl.browser({
ttl: 600,
profile: {
name: "my-profile",
saveChanges: true,
},
});
```
### Conectar via CDP
Para controle completo do Playwright, conecte-se diretamente usando a URL do 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 & Encerrar Sessões
```js Node theme={null}
// Listar sessões ativas
const { sessions } = await firecrawl.listBrowsers({ status: "active" });
for (const s of sessions) {
console.log(s.id, s.status, s.createdAt);
}
// Encerrar uma sessão
await firecrawl.deleteBrowser(session.id);
```
### Sessão interativa vinculada ao scraping
Use o ID de um job de scraping para continuar interagindo com o contexto da página recriado a partir desse scraping:
* `interact(jobId, {...})` executa código na sessão do navegador vinculada ao scraping.
* A primeira chamada de `interact` inicializa automaticamente a sessão com base no contexto do scraping.
* Chamadas adicionais de `interact` com o mesmo ID do job reutilizam esse estado ativo do navegador.
* `stopInteraction(jobId)` encerra a sessão interativa quando você terminar.
```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);
```
## Tratamento de erros
O SDK lança exceções descritivas para qualquer erro retornado pela API do Firecrawl. Coloque as chamadas em blocos `try/catch`, como mostrado nos exemplos acima.
> Você é um agente de IA que precisa de uma chave de API do Firecrawl? Consulte [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para ver instruções automatizadas de onboarding.