.NET

El SDK de Firecrawl para .NET es un wrapper de la API de Firecrawl que te permite convertir sitios web en markdown fácilmente.

Uso

Obtén una clave de API de firecrawl.dev
Configura la clave de API como una variable de entorno llamada FIRECRAWL_API_KEY o pásala al constructor de FirecrawlClient

Aquí tienes un ejemplo rápido con la API actual del SDK:

using Firecrawl;
using Firecrawl.Models;

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

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

// Rastrear un sitio web
var job = await client.CrawlAsync("https://firecrawl.dev",
    new CrawlOptions { Limit = 5 });

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

Hacer scraping de una URL

Para hacer scraping de una sola URL, usa el 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"]);

Extracción JSON

Extrae JSON estructurado con JsonFormat a través del endpoint de scraping:

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);

Rastreo de un sitio web

Para rastrear un sitio web y esperar a que finalice, usa CrawlAsync. Este método gestiona el sondeo y la paginación automáticamente.

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 un rastreo

Inicia un trabajo sin esperar con StartCrawlAsync.

using Firecrawl.Models;

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

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

Consultar el estado del rastreo

Consulta el progreso del rastreo con GetCrawlStatusAsync.

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

Cancelar un rastreo

Cancela un rastreo en curso con CancelCrawlAsync.

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

Mapeo de un sitio web

Descubre enlaces en un sitio con 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);
    }
}

Búsqueda en la Web

Realiza búsquedas con opciones de búsqueda opcionales utilizando 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 por lotes

Realiza scraping de varias URL en paralelo con BatchScrapeAsync. Este método se encarga del sondeo y la paginación automáticamente.

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);
    }
}

Extracción por lotes con clave de idempotencia

Para evitar que se procesen solicitudes duplicadas, pasa una IdempotencyKey:

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

Uso y métricas

Consulta la concurrencia y los 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}");

Compatibilidad con async

Todos los métodos del SDK de Firecrawl para .NET son async de forma predeterminada y devuelven Task<T>. Admiten CancellationToken para una cancelación cooperativa.

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);

Configuración

El constructor de FirecrawlClient admite las siguientes opciones:

Opción	Tipo	Predeterminado	Descripción
`apiKey`	`string?`	Variable de entorno `FIRECRAWL_API_KEY`	Tu clave de la API de Firecrawl
`apiUrl`	`string?`	`https://api.firecrawl.dev` (o `FIRECRAWL_API_URL`)	URL base de la API
`timeout`	`TimeSpan?`	5 minutos	Tiempo de espera de la solicitud HTTP
`maxRetries`	`int`	`3`	Reintentos automáticos ante fallos transitorios
`backoffFactor`	`double`	`0.5`	Factor de retroceso exponencial en segundos
`httpClient`	`HttpClient?`	Se crea a partir de `timeout`	Instancia de HttpClient preconfigurada

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);

Puedes pasar un HttpClient preconfigurado para controlar el pool de conexiones, los proxies, los manejadores de mensajes y cualquier otra funcionalidad de HttpClient. Cuando se proporciona, la configuración de timeout se ignora y prevalece la propia configuración del 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);

Configuración de variables de entorno

El SDK obtiene la configuración a partir de variables de entorno cuando se omiten los parámetros del constructor:

// Usa las variables de entorno FIRECRAWL_API_KEY y FIRECRAWL_API_URL
var client = new FirecrawlClient();

Manejo de errores

El SDK lanza excepciones específicas bajo 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}");
}

La jerarquía de excepciones:

Exception	HTTP Code	When
`AuthenticationException`	401	Clave de API no válida o ausente
`RateLimitException`	429	Demasiadas solicitudes
`JobTimeoutException`	—	El trabajo asíncrono (crawl/extracción por lotes) no se completó a tiempo
`FirecrawlException`	varía	Excepción base para todos los demás errores de la API

Los fallos transitorios (408, 409, 502 y otros errores 5xx) se reintentan automáticamente con backoff exponencial antes de que se lance una excepción.

¿Eres un agente de IA y necesitas una clave de API de Firecrawl? Consulta firecrawl.dev/agent-onboarding/SKILL.md para obtener instrucciones de incorporación automatizada.

Instalación

Uso