# Crawlear (/pt-BR/features/crawl)

<!-- agent-signals: reading_time_min: 15 · est_tokens: 8949 · updated: 2026-07-30 -->
Related: [Busca](/pt-BR/features/search.md), [Destaques da Busca](/pt-BR/features/search-highlights.md), [Índice de research](/pt-BR/features/research.md), [Scraping](/pt-BR/features/scrape.md), [Raspagem mais rápida](/pt-BR/features/fast-scraping.md), [Raspagem em lote](/pt-BR/features/batch-scrape.md)

O Crawlear envia uma URL ao Firecrawl e descobre e extrai, de forma recursiva, todas as subpáginas acessíveis. Ele lida automaticamente com sitemaps, renderização de JavaScript e limites de taxa, retornando markdown limpo ou dados estruturados para cada página.

* Descobre páginas por meio do sitemap e da navegação recursiva por links
* Suporta filtragem de caminho, limites de profundidade e controle de subdomínios/links externos
* Retorna resultados via polling, WebSocket ou webhook

<Card title="Experimente no Playground" icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M18.8906 12.846C18.5371 14.189 16.8667 15.138 13.5257 17.0361C10.296 18.8709 8.6812 19.7884 7.37983 19.4196C6.8418 19.2671 6.35159 18.9776 5.95624 18.5787C5 17.6139 5 15.7426 5 12C5 8.2574 5 6.3861 5.95624 5.42132C6.35159 5.02245 6.8418 4.73288 7.37983 4.58042C8.6812 4.21165 10.296 5.12907 13.5257 6.96393C16.8667 8.86197 18.5371 9.811 18.8906 11.154C19.0365 11.7084 19.0365 12.2916 18.8906 12.846Z&#x22; stroke=&#x22;currentColor&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" href="https://www.firecrawl.dev/playground?endpoint=crawl">
  Teste o rastreamento no playground interativo — sem precisar escrever código.
</Card>

<div id="installation">
  ## Instalação [#instalação]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="cli+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="CLI">
        CLI
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      # pip install firecrawl-py

      from firecrawl import Firecrawl

      firecrawl = Firecrawl(
        # Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
        # api_key="fc-YOUR-API-KEY",
      )
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      // 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",
      });
      ```
    </CodeBlockTab>

    <CodeBlockTab value="CLI">
      ```bash  
      # Instale globalmente com npm
      npm install -g firecrawl

      # Autentique (configuração única)
      firecrawl login
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="basic-usage">
  ## Uso básico [#uso-básico]
</div>

Envie um job de rastreamento chamando `POST /v2/crawl` com uma URL inicial. O endpoint retorna um ID do job que você usa para consultar os resultados.

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="cli+curl+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="CLI">
        CLI
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      from firecrawl import Firecrawl

      firecrawl = Firecrawl(api_key="fc-SUA-API-KEY")

      docs = firecrawl.crawl(url="https://docs.firecrawl.dev", limit=10)
      print(docs)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      import { Firecrawl } from 'firecrawl';

      const firecrawl = new Firecrawl({ apiKey: "fc-SUA-CHAVE-API" });

      const docs = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 10 });
      console.log(docs);
      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
        -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "url": "https://docs.firecrawl.dev",
          "limit": 10
        }'
      ```
    </CodeBlockTab>

    <CodeBlockTab value="CLI">
      ```bash  
      # Inicia um trabalho de crawl (retorna o ID do trabalho)
      firecrawl crawl https://firecrawl.dev

      # Aguarda a conclusão exibindo o progresso
      firecrawl crawl https://firecrawl.dev --wait --progress --limit 100
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<Info>
  Cada página rastreada consome 1 crédito. O `limit` padrão de rastreamento é 10.000 páginas. Antes de iniciar, o endpoint de rastreamento verifica se os créditos restantes podem cobrir o `limit` — caso contrário, ele retorna um erro &#x2A;*402 (Pagamento Obrigatório)**. Defina um `limit` menor para corresponder ao tamanho de rastreamento pretendido (por exemplo, `limit: 100`) para evitar isso. São cobrados créditos adicionais para certas opções: modo JSON custa 4 créditos adicionais por página, proxy aprimorado custa 4 créditos adicionais por página, e análise de PDF custa 1 crédito por página de PDF.
</Info>

<div id="scrape-options">
  ### Opções de scrape [#opções-de-scrape]
</div>

Todas as opções do [endpoint Scrape](/pt-BR/api-reference/endpoint/scrape) estão disponíveis no rastreamento via `scrapeOptions` (JS) / `scrape_options` (Python). Elas se aplicam a cada página que o crawler coleta, incluindo formatos, proxy, cache, ações, localização e tags.

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      from firecrawl import Firecrawl

      firecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')

      # Crawl com opções de scrape
      response = firecrawl.crawl('https://example.com',
          limit=100,
          scrape_options={
              'formats': [
                  'markdown',
                  { 'type': 'json', 'schema': { 'type': 'object', 'properties': { 'title': { 'type': 'string' } } } }
              ],
              'proxy': 'auto',
              'max_age': 600000,
              'only_main_content': True
          }
      )
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      import { Firecrawl } from 'firecrawl';

      const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

      // Crawl com opções de scrape
      const crawlResponse = await firecrawl.crawl('https://example.com', {
        limit: 100,
        scrapeOptions: {
          formats: [
            'markdown',
            {
              type: 'json',
              schema: { type: 'object', properties: { title: { type: 'string' } } },
            },
          ],
          proxy: 'auto',
          maxAge: 600000,
          onlyMainContent: true,
        },
      });
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="checking-crawl-status">
  ## Verificando o status do rastreamento [#verificando-o-status-do-rastreamento]
</div>

Use o ID do job para consultar o status do rastreamento e obter os resultados.

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="cli+curl+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="CLI">
        CLI
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      status = firecrawl.get_crawl_status("<crawl-id>")
      print(status)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      const status = await firecrawl.getCrawlStatus("<id-da-varredura>");
      console.log(status);
      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      # Após iniciar um crawl, consulte o status pelo jobId
      curl -s -X GET "https://api.firecrawl.dev/v2/crawl/<jobId>" \
        -H "Authorization: Bearer $FIRECRAWL_API_KEY"
      ```
    </CodeBlockTab>

    <CodeBlockTab value="CLI">
      ```bash  
      # Verificar o status do crawl usando o ID do job
      firecrawl crawl <job-id>
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<Note>
  Os resultados do job ficam disponíveis via API por 24 horas após a conclusão. Após esse período, você ainda pode ver o histórico e os resultados dos seus rastreamentos nos [activity logs](https://www.firecrawl.dev/app/logs).
</Note>

<Note>
  As páginas no array `data` dos resultados do rastreamento são páginas que o Firecrawl conseguiu extrair com sucesso, mesmo que o site de destino tenha retornado um erro HTTP como 404. O campo `metadata.statusCode` mostra o código de status HTTP retornado pelo site de destino. Para recuperar páginas que o próprio Firecrawl não conseguiu extrair (por exemplo, erros de rede, timeouts ou bloqueios por robots.txt), use o endpoint dedicado [Get Crawl Errors](/pt-BR/api-reference/endpoint/crawl-get-errors) (`GET /crawl/{id}/errors`).
</Note>

<div id="response-handling">
  ### Tratamento de respostas [#tratamento-de-respostas]
</div>

A resposta varia conforme o status da varredura. Para respostas incompletas ou grandes (acima de 10 MB), é fornecido um parâmetro de URL `next`. Você deve requisitar essa URL para obter os próximos 10 MB de dados. Se o parâmetro `next` estiver ausente, isso indica o fim dos dados da varredura.

<Info>
  Os parâmetros `skip` e `next` são relevantes apenas ao acessar a API diretamente.
  Se você estiver usando o SDK, a paginação é tratada automaticamente e todos os
  resultados são retornados de uma vez.
</Info>

<CodeGroup>
  <CodeBlockTabs defaultValue="Raspagem" groupId="conclu-do+raspagem">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Raspagem">
        Raspagem
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Concluído">
        Concluído
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Raspagem">
      ```json  
      {
        "status": "em andamento",
        "total": 36,
        "completed": 10,
        "creditsUsed": 10,
        "expiresAt": "2024-00-00T00:00:00.000Z",
        "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=10",
        "data": [
          {
            "markdown": "[Página inicial da documentação do Firecrawl![logotipo claro](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
            "html": "<!DOCTYPE html><html lang=\"en\" class=\"js-focus-visible lg:[--scroll-mt:9.5rem]\" data-js-focus-visible=\"\">...",
            "metadata": {
              "title": "Crie um 'Chat com o site' usando Groq Llama 3 | Firecrawl",
              "language": "en",
              "sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
              "description": "Aprenda a usar o Firecrawl, o Groq Llama 3 e o LangChain para criar um bot de 'chat com seu site'."
              "ogLocaleAlternate": [],
              "statusCode": 200
            }
          },
          ...
        ]
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Concluído">
      ```json  
      {
        "status": "concluída",
        "total": 36,
        "completed": 36,
        "creditsUsed": 36,
        "expiresAt": "2024-00-00T00:00:00.000Z",
        "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=26",
        "data": [
          {
            "markdown": "[Página inicial da documentação do Firecrawl![logotipo claro](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
            "html": "<!DOCTYPE html><html lang=\"en\" class=\"js-focus-visible lg:[--scroll-mt:9.5rem]\" data-js-focus-visible=\"\">...",
            "metadata": {
              "title": "Crie um 'chat com o site' usando Groq Llama 3 | Firecrawl",
              "language": "en",
              "sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
              "description": "Aprenda a usar o Firecrawl, o Groq Llama 3 e o LangChain para criar um bot de 'chat com seu site'."
              "ogLocaleAlternate": [],
              "statusCode": 200
            }
          },
          ...
        ]
      }
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="sdk-methods">
  ## Métodos do SDK [#métodos-do-sdk]
</div>

Existem duas maneiras de usar o crawl com o SDK.

<div id="crawl-and-wait">
  ### Crawl e aguarde [#crawl-e-aguarde]
</div>

O método `crawl` aguarda a conclusão do crawl e retorna a resposta completa. Faz a paginação automaticamente. Isso é recomendado para a maioria dos casos de uso.

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      from firecrawl import Firecrawl
      from firecrawl.types import ScrapeOptions

      firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

      # Rastreie um site:
      crawl_status = firecrawl.crawl(
        'https://firecrawl.dev', 
        limit=100, 
        scrape_options=ScrapeOptions(formats=['markdown', 'html']),
        poll_interval=30
      )
      print(crawl_status)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      import { Firecrawl } from 'firecrawl';

      const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});

      const crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {
        limit: 100,
        scrapeOptions: {
          formats: ['markdown', 'html'],
        }
      })

      console.log(crawlResponse)
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

A resposta inclui o status do crawl e todos os dados extraídos:

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```bash  
      success=True
      status='concluída'
      completed=100
      total=100
      creditsUsed=100
      expiresAt=datetime.datetime(2025, 4, 23, 19, 21, 17, tzinfo=TzInfo(UTC))
      next=None
      data=[
        Document(
          markdown='[Dia 7 - Launch Week III. Dia de Integrações — 14 a 20 de abril](...',
          metadata={
            'title': '15 projetos de web scraping em Python: do básico ao avançado',
            ...
            'scrapeId': '97dcf796-c09b-43c9-b4f7-868a7a5af722',
            'sourceURL': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
            'url': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
            'statusCode': 200
          }
        ),
        ...
      ]
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      {
        success: true,
        status: "completed",
        completed: 100,
        total: 100,
        creditsUsed: 100,
        expiresAt: "2025-04-23T19:28:45.000Z",
        data: [
          {
            markdown: "[Day 7 - Launch Week III.Integrations DayApril ...",
            html: `<!DOCTYPE html><html lang="en" class="light" style="color...`,
            metadata: [Object],
          },
          ...
        ]
      }
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="start-and-check-later">
  ### Inicie e verifique depois [#inicie-e-verifique-depois]
</div>

O método `startCrawl` / `start_crawl` retorna imediatamente com um ID de crawl. Depois, você verifica o status manualmente. Isso é útil para crawls de longa duração ou lógica de polling personalizada.

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="cli+curl+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="CLI">
        CLI
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      from firecrawl import Firecrawl

      firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

      job = firecrawl.start_crawl(url="https://docs.firecrawl.dev", limit=10)
      print(job)

      # Verifique o status do rastreamento
      status = firecrawl.get_crawl_status(job.id)
      print(status)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      import { Firecrawl } from 'firecrawl';

      const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

      const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
      console.log(id);

      // Verifique o status do crawl
      const status = await firecrawl.getCrawlStatus(id);
      console.log(status);

      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
        -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "url": "https://docs.firecrawl.dev",
          "limit": 10
        }'
      ```
    </CodeBlockTab>

    <CodeBlockTab value="CLI">
      ```bash  
      # Iniciar crawl (assíncrono, retorna o ID do job imediatamente)
      firecrawl crawl https://firecrawl.dev --limit 100

      # Depois verificar o status
      firecrawl crawl <job-id>
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

A resposta inicial retorna o ID do job:

```json
{
  "success": true,
  "id": "123-456-789",
  "url": "https://api.firecrawl.dev/v2/crawl/123-456-789"
}
```

<div id="real-time-results-with-websocket">
  ## Resultados em tempo real com WebSocket [#resultados-em-tempo-real-com-websocket]
</div>

O método watcher fornece atualizações em tempo real conforme as páginas são rastreadas. Inicie um crawl e, em seguida, assine os eventos para processar os dados imediatamente.

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      import asyncio
      from firecrawl import AsyncFirecrawl

      async def main():
          firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")

          # Inicia um crawl primeiro
          started = await firecrawl.start_crawl("https://firecrawl.dev", limit=5)

          # Monitora atualizações (snapshots) até status final
          async for snapshot in firecrawl.watcher(started.id, kind="crawl", poll_interval=2, timeout=120):
              if snapshot.status == "completed":
                  print("CONCLUÍDO", snapshot.status)
                  for doc in snapshot.data:
                      print("DOC", doc.metadata.source_url if doc.metadata else None)
              elif snapshot.status == "failed":
                  print("ERRO", snapshot.status)
              else:
                  print("STATUS", snapshot.status, snapshot.completed, "/", snapshot.total)

      asyncio.run(main())
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      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();
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="webhooks">
  ## Webhooks [#webhooks]
</div>

Você pode configurar webhooks para receber notificações em tempo real conforme o rastreamento avança. Isso permite processar páginas à medida que são coletadas, em vez de esperar a conclusão de todo o rastreamento.

```bash title="cURL"
curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "limit": 100,
      "webhook": {
        "url": "https://your-domain.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["iniciado", "página", "concluído"]
      }
    }'
```

<div id="event-types">
  ### Tipos de evento [#tipos-de-evento]
</div>

| Evento            | Descrição                                       |
| ----------------- | ----------------------------------------------- |
| `crawl.started`   | Disparado quando o crawl é iniciado             |
| `crawl.page`      | Disparado para cada página extraída com sucesso |
| `crawl.completed` | Disparado quando o crawl é concluído            |
| `crawl.failed`    | Disparado se ocorrer um erro durante o crawl    |

<div id="payload">
  ### Payload [#payload]
</div>

```json
{
  "success": true,
  "type": "crawl.page",
  "id": "crawl-job-id",
  "data": [...], // Dados da página para eventos 'page'
  "metadata": {}, // Your custom metadata
  "error": null
}
```

<div id="verifying-webhook-signatures">
  ### Verificando assinaturas de webhook [#verificando-assinaturas-de-webhook]
</div>

Toda requisição de webhook do Firecrawl inclui um cabeçalho `X-Firecrawl-Signature` contendo uma assinatura HMAC-SHA256. Sempre verifique essa assinatura para garantir que o webhook é autêntico e não foi adulterado.

1. Obtenha seu segredo de webhook na [aba Advanced](https://www.firecrawl.dev/app/settings?tab=advanced) das configurações da sua conta
2. Extraia a assinatura do cabeçalho `X-Firecrawl-Signature`
3. Calcule o HMAC-SHA256 do corpo bruto da requisição usando o seu segredo
4. Compare com o cabeçalho de assinatura usando uma função com proteção contra ataques de timing (tempo constante)

<Warning>
  Nunca processe um webhook sem verificar sua assinatura primeiro. O cabeçalho `X-Firecrawl-Signature` contém a assinatura no formato: `sha256=abc123def456...`
</Warning>

Para exemplos completos de implementação em JavaScript e Python, consulte a [documentação de segurança de webhooks](/pt-BR/webhooks/security). Para a documentação completa sobre webhooks, incluindo payloads detalhados de eventos, estrutura de payload, configuração avançada e solução de problemas, consulte a [documentação de Webhooks](/pt-BR/webhooks/overview).

<div id="configuration-reference">
  ## Referência de configuração [#referência-de-configuração]
</div>

O conjunto completo de parâmetros disponíveis ao enviar um job de crawl:

| Parâmetro               | Tipo       | Padrão        | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`                   | `string`   | (obrigatório) | A URL inicial a partir da qual o rastreamento será executado                                                                                                                                                                                                                                                                                                                                                                     |
| `limit`                 | `integer`  | `10000`       | Número máximo de páginas a rastrear                                                                                                                                                                                                                                                                                                                                                                                              |
| `maxDiscoveryDepth`     | `integer`  | (nenhum)      | Profundidade máxima a partir da URL raiz com base em saltos de descoberta de links, e não no número de segmentos `/` na URL. Cada vez que uma nova URL é encontrada em uma página, ela recebe uma profundidade um nível acima da página em que foi descoberta. O site raiz e as páginas do sitemap têm profundidade de descoberta 0. As páginas na profundidade máxima ainda são extraídas, mas os links nelas não são seguidos. |
| `includePaths`          | `string[]` | (nenhum)      | Padrões regex de pathname de URL a incluir. Apenas os caminhos correspondentes são rastreados.                                                                                                                                                                                                                                                                                                                                   |
| `excludePaths`          | `string[]` | (nenhum)      | Padrões regex de pathname de URL a excluir do rastreamento                                                                                                                                                                                                                                                                                                                                                                       |
| `regexOnFullURL`        | `boolean`  | `false`       | Faz a correspondência de `includePaths`/`excludePaths` com a URL completa (incluindo parâmetros de consulta), em vez de apenas o pathname                                                                                                                                                                                                                                                                                        |
| `crawlEntireDomain`     | `boolean`  | `false`       | Segue links internos para URLs irmãs ou pai, não apenas caminhos filhos                                                                                                                                                                                                                                                                                                                                                          |
| `allowSubdomains`       | `boolean`  | `false`       | Segue links para subdomínios do domínio principal                                                                                                                                                                                                                                                                                                                                                                                |
| `allowExternalLinks`    | `boolean`  | `false`       | Segue links para sites externos                                                                                                                                                                                                                                                                                                                                                                                                  |
| `sitemap`               | `string`   | `"include"`   | Tratamento do sitemap: `"include"` (padrão), `"skip"` ou `"only"`                                                                                                                                                                                                                                                                                                                                                                |
| `ignoreQueryParameters` | `boolean`  | `false`       | Evita raspar novamente o mesmo caminho com parâmetros de consulta diferentes                                                                                                                                                                                                                                                                                                                                                     |
| `ignoreRobotsTxt`       | `boolean`  | `false`       | Ignora as regras do robots.txt do site. **Apenas Enterprise** — entre em contato com [support@firecrawl.com](mailto:support@firecrawl.com) para habilitar.                                                                                                                                                                                                                                                                       |
| `robotsUserAgent`       | `string`   | (nenhum)      | String personalizada de User-Agent para avaliação do robots.txt. Quando definido, o robots.txt é buscado com esse User-Agent e as regras são correspondidas com base nele em vez do padrão. **Apenas Enterprise** — entre em contato com [support@firecrawl.com](mailto:support@firecrawl.com) para habilitar.                                                                                                                   |
| `delay`                 | `number`   | (nenhum)      | Intervalo, em segundos, entre raspagens para respeitar os limites de taxa. Definir isso força a simultaneidade para 1.                                                                                                                                                                                                                                                                                                           |
| `maxConcurrency`        | `integer`  | (nenhum)      | Número máximo de raspagens simultâneas. O padrão é o limite de simultaneidade da sua equipe.                                                                                                                                                                                                                                                                                                                                     |
| `scrapeOptions`         | `object`   | (nenhum)      | Opções aplicadas a cada página raspada (formatos, proxy, cache, ações etc.)                                                                                                                                                                                                                                                                                                                                                      |
| `webhook`               | `object`   | (nenhum)      | Configuração de webhook para notificações em tempo real                                                                                                                                                                                                                                                                                                                                                                          |
| `prompt`                | `string`   | (nenhum)      | Prompt em linguagem natural para gerar opções de rastreamento. Parâmetros definidos explicitamente substituem os equivalentes gerados.                                                                                                                                                                                                                                                                                           |

<div id="important-details">
  ## Detalhes importantes [#detalhes-importantes]
</div>

<Warning>
  Por padrão, o crawl ignora sublinks que não são descendentes da URL fornecida. Por exemplo, `website.com/other-parent/blog-1` não seria retornada se você fizesse crawl de `website.com/blogs/`. Use o parâmetro `crawlEntireDomain` para incluir caminhos irmãos e superiores. Para fazer crawl de subdomínios como `blog.website.com` ao fazer crawl de `website.com`, use o parâmetro `allowSubdomains`.
</Warning>

* **Descoberta de sitemap**: Por padrão, o crawler inclui o sitemap do site para descobrir URLs (`sitemap: "include"`). Se você definir `sitemap: "skip"`, apenas páginas acessíveis por links HTML a partir da URL raiz serão encontradas. Recursos como PDFs ou páginas em níveis mais profundos, listados no sitemap mas não vinculados diretamente no HTML, não serão encontrados. Para obter a cobertura máxima, mantenha a configuração padrão.
* **Uso de créditos**: Cada página rastreada custa 1 crédito. O modo JSON adiciona 4 créditos por página, o proxy avançado adiciona 4 créditos por página, e a análise de PDF custa 1 crédito por página do PDF.
* **Expiração dos resultados**: Os resultados do job ficam disponíveis via API por 24 horas após a conclusão. Depois disso, consulte os resultados nos [logs de atividade](https://www.firecrawl.dev/app/logs).
* **Erros de crawl**: O array `data` contém as páginas que o Firecrawl extraiu com sucesso. Use o endpoint [Get Crawl Errors](/pt-BR/api-reference/endpoint/crawl-get-errors) para recuperar as páginas que falharam devido a erros de rede, timeouts ou bloqueios por robots.txt.
* **Resultados não determinísticos**: Os resultados do crawl podem variar entre execuções com a mesma configuração. As páginas são extraídas de forma concorrente, então a ordem em que os links são descobertos depende do timing da rede e de quais páginas terminam de carregar primeiro. Isso significa que diferentes ramificações de um site podem ser exploradas em extensões diferentes perto do limite de profundidade, especialmente em valores mais altos de `maxDiscoveryDepth`. Para obter resultados mais determinísticos, defina `maxConcurrency` como `1` ou use `sitemap: "only"` se o site tiver um sitemap abrangente.

> Você é um agente de IA que precisa de uma API key do Firecrawl? Consulte [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para ver as instruções de onboarding automatizado.