SDK .NET | Firecrawl

Instalação

O SDK oficial do .NET é mantido no monorepo do Firecrawl em apps/dot-net-sdk. Para instalar o SDK .NET do Firecrawl, adicione o pacote NuGet:

CLI do .NET
Gerenciador de Pacotes
PackageReference

dotnet add package firecrawl-sdk

Install-Package firecrawl-sdk

<PackageReference Include="firecrawl-sdk" Version="1.0.0" />

Requer .NET 8.0 ou superior.

Uso

Obtenha uma chave de API em firecrawl.dev
Defina a chave de API como uma variável de ambiente chamada FIRECRAWL_API_KEY ou passe-a para o construtor FirecrawlClient

Aqui está um exemplo rápido usando a API atual do SDK:

using Firecrawl;
using Firecrawl.Models;

var client = new FirecrawlClient("fc-your-api-key");

// Faz scraping de uma única página
var doc = await client.ScrapeAsync("https://firecrawl.dev",
    new ScrapeOptions { Formats = new List<object> { "markdown" } });

// Rastreia um site
var job = await client.CrawlAsync("https://firecrawl.dev",
    new CrawlOptions { Limit = 5 });

Console.WriteLine(doc.Markdown);
Console.WriteLine($"Crawled pages: {job.Data?.Count ?? 0}");

Fazer scraping de uma URL

Para fazer scraping de uma única URL, use o método ScrapeAsync.

using Firecrawl.Models;

var doc = await client.ScrapeAsync("https://firecrawl.dev",
    new ScrapeOptions
    {
        Formats = new List<object> { "markdown", "html" },
        OnlyMainContent = true,
        WaitFor = 5000
    });

Console.WriteLine(doc.Markdown);
Console.WriteLine(doc.Metadata?["title"]);

Extração JSON

Extraia JSON estruturado com JsonFormat pelo endpoint /scrape:

using Firecrawl.Models;

var jsonFmt = new JsonFormat
{
    Prompt = "Extract the product name and price",
    Schema = new Dictionary<string, object>
    {
        ["type"] = "object",
        ["properties"] = new Dictionary<string, object>
        {
            ["name"] = new Dictionary<string, object> { ["type"] = "string" },
            ["price"] = new Dictionary<string, object> { ["type"] = "number" }
        }
    }
};

var doc = await client.ScrapeAsync("https://example.com/product",
    new ScrapeOptions
    {
        Formats = new List<object> { jsonFmt }
    });

Console.WriteLine(doc.Json);

Rastreamento de um site

Para rastrear um site e aguardar a conclusão, use CrawlAsync. Esse método faz as consultas e a paginação automaticamente.

using Firecrawl.Models;

var job = await client.CrawlAsync("https://firecrawl.dev",
    new CrawlOptions
    {
        Limit = 50,
        MaxDiscoveryDepth = 3,
        ScrapeOptions = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

Console.WriteLine($"Status: {job.Status}");
Console.WriteLine($"Progress: {job.Completed}/{job.Total}");

if (job.Data != null)
{
    foreach (var page in job.Data)
    {
        Console.WriteLine(page.Metadata?["sourceURL"]);
    }
}

Iniciar um rastreamento

Inicie um job sem aguardar usando StartCrawlAsync.

using Firecrawl.Models;

var start = await client.StartCrawlAsync("https://firecrawl.dev",
    new CrawlOptions { Limit = 100 });

Console.WriteLine($"Job ID: {start.Id}");

Verificando o status do rastreamento

Verifique o andamento do rastreamento com GetCrawlStatusAsync.

var status = await client.GetCrawlStatusAsync(start.Id!);
Console.WriteLine($"Status: {status.Status}");
Console.WriteLine($"Progress: {status.Completed}/{status.Total}");

Cancelando um rastreamento

Cancele um rastreamento em andamento com CancelCrawlAsync.

var result = await client.CancelCrawlAsync(start.Id!);
Console.WriteLine(result);

Mapear um site

Descubra links em um site com MapAsync.

using Firecrawl.Models;

var data = await client.MapAsync("https://firecrawl.dev",
    new MapOptions
    {
        Limit = 100,
        Search = "blog"
    });

if (data.Links != null)
{
    foreach (var link in data.Links)
    {
        Console.WriteLine(link);
    }
}

Pesquisando na Web

Pesquise na Web com configurações de busca opcionais usando SearchAsync.

using Firecrawl.Models;

var results = await client.SearchAsync("firecrawl web scraping",
    new SearchOptions
    {
        Limit = 10,
        Location = "US"
    });

if (results.Web != null)
{
    foreach (var hit in results.Web)
    {
        Console.WriteLine($"{hit.Title} - {hit.Url}");
    }
}

Scraping em lote

Faça scraping de várias URLs em paralelo usando BatchScrapeAsync. Esse método gerencia as consultas e a paginação automaticamente.

using Firecrawl.Models;

var urls = new List<string>
{
    "https://firecrawl.dev",
    "https://firecrawl.dev/blog"
};

var job = await client.BatchScrapeAsync(urls,
    new BatchScrapeOptions
    {
        Options = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

if (job.Data != null)
{
    foreach (var doc in job.Data)
    {
        Console.WriteLine(doc.Markdown);
    }
}

Extração em lote com chave de idempotência

Para garantir que solicitações duplicadas não sejam processadas, forneça uma IdempotencyKey:

var job = await client.BatchScrapeAsync(urls,
    new BatchScrapeOptions
    {
        IdempotencyKey = "my-unique-key",
        Options = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

Uso & métricas

Confira a concorrência e os créditos restantes:

using Firecrawl.Models;

var concurrency = await client.GetConcurrencyAsync();
Console.WriteLine($"Concurrency: {concurrency.Current}/{concurrency.MaxConcurrency}");

var credits = await client.GetCreditUsageAsync();
Console.WriteLine($"Remaining credits: {credits.RemainingCredits}");

Suporte a async

Todos os métodos no SDK .NET são assíncronos por padrão e retornam Task<T>. Eles oferecem suporte a CancellationToken para cancelamento cooperativo.

using Firecrawl.Models;

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));

var doc = await client.ScrapeAsync("https://example.com",
    new ScrapeOptions
    {
        Formats = new List<object> { "markdown" }
    },
    cancellationToken: cts.Token);

Console.WriteLine(doc.Markdown);

Configuração

O construtor FirecrawlClient oferece suporte às seguintes opções:

Option	Type	Default	Description
`apiKey`	`string?`	variável de ambiente `FIRECRAWL_API_KEY`	Sua chave de API do Firecrawl
`apiUrl`	`string?`	`https://api.firecrawl.dev` (ou `FIRECRAWL_API_URL`)	URL base da API
`timeout`	`TimeSpan?`	5 minutos	Tempo limite da solicitação HTTP
`maxRetries`	`int`	`3`	Tentativas automáticas para falhas transitórias
`backoffFactor`	`double`	`0.5`	Fator de backoff exponencial em segundos
`httpClient`	`HttpClient?`	Criado a partir de `timeout`	Instância pré-configurada de HttpClient

using Firecrawl;

var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    apiUrl: "https://api.firecrawl.dev",
    timeout: TimeSpan.FromMinutes(5),
    maxRetries: 3,
    backoffFactor: 0.5);

Cliente HTTP personalizado

Você pode passar um HttpClient pré-configurado para controlar o pool de conexões, proxies, handlers de mensagem e qualquer outro recurso do HttpClient. Quando fornecido, a configuração de tempo limite é ignorada em favor da configuração do próprio cliente.

using Firecrawl;

var handler = new HttpClientHandler
{
    Proxy = new WebProxy("http://proxy.example.com:8080"),
    UseProxy = true
};

var httpClient = new HttpClient(handler)
{
    Timeout = TimeSpan.FromSeconds(60)
};

var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    httpClient: httpClient);

Configuração de variáveis de ambiente

O SDK obtém a configuração a partir de variáveis de ambiente quando os parâmetros do construtor são omitidos:

// Usa as variáveis de ambiente FIRECRAWL_API_KEY e FIRECRAWL_API_URL
var client = new FirecrawlClient();

Tratamento de erros

O SDK lança exceções específicas em Firecrawl.Exceptions.

using Firecrawl.Exceptions;
using Firecrawl.Models;

try
{
    var doc = await client.ScrapeAsync("https://example.com");
}
catch (AuthenticationException ex)
{
    Console.Error.WriteLine($"Auth failed: {ex.Message}");
}
catch (RateLimitException ex)
{
    Console.Error.WriteLine($"Rate limited: {ex.Message}");
}
catch (JobTimeoutException ex)
{
    Console.Error.WriteLine($"Job {ex.JobId} timed out after {ex.TimeoutSeconds}s");
}
catch (FirecrawlException ex)
{
    Console.Error.WriteLine($"Error {ex.StatusCode}: {ex.Message}");
}

Hierarquia de exceções:

Exceção	Código HTTP	Quando
`AuthenticationException`	401	Chave de API inválida ou ausente
`RateLimitException`	429	Muitas solicitações
`JobTimeoutException`	—	Job assíncrono (rastreamento/extração em lote) não foi concluído a tempo
`FirecrawlException`	varia	Exceção base para todos os outros erros da API

Falhas transitórias (408, 409, 502 e outros erros 5xx) são repetidas automaticamente com backoff exponencial antes de uma exceção ser lançada.

Você é um agente de IA que precisa de uma chave de API do Firecrawl? Consulte firecrawl.dev/agent-onboarding/SKILL.md para instruções automatizadas de onboarding.

​Instalação

​Uso

​Fazer scraping de uma URL

​Extração JSON

​Rastreamento de um site

​Iniciar um rastreamento

​Verificando o status do rastreamento

​Cancelando um rastreamento

​Mapear um site

​Pesquisando na Web

​Scraping em lote

​Extração em lote com chave de idempotência

​Uso & métricas

​Suporte a async

​Configuração

​Cliente HTTP personalizado

​Configuração de variáveis de ambiente

​Tratamento de erros

Instalação

Uso

Fazer scraping de uma URL

Extração JSON

Rastreamento de um site

Iniciar um rastreamento

Verificando o status do rastreamento

Cancelando um rastreamento

Mapear um site

Pesquisando na Web

Scraping em lote

Extração em lote com chave de idempotência

Uso & métricas

Suporte a async

Configuração

Cliente HTTP personalizado

Configuração de variáveis de ambiente

Tratamento de erros