SDK de Firecrawl para .NET

Instalación

El SDK oficial de Firecrawl para .NET se mantiene en el monorepo de Firecrawl, en apps/dot-net-sdk. Para instalar el SDK de Firecrawl para .NET, agrega el paquete NuGet:

.NET CLI
Administrador de paquetes
PackageReference

dotnet add package firecrawl-sdk

Install-Package firecrawl-sdk

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

Requiere .NET 8.0 o posterior.

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

Cliente HTTP personalizado

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.

General

Oficial

.NET

Instalación

Uso

Hacer scraping de una URL

Extracción JSON

Rastreo de un sitio web

Iniciar un rastreo

Consultar el estado del rastreo

Cancelar un rastreo

Mapeo de un sitio web

Búsqueda en la Web

Scraping por lotes

Extracción por lotes con clave de idempotencia

Uso y métricas

Compatibilidad con async

Configuración

Cliente HTTP personalizado

Configuración de variables de entorno

Manejo de errores

​Instalación

​Uso

​Hacer scraping de una URL

​Extracción JSON

​Rastreo de un sitio web

​Iniciar un rastreo

​Consultar el estado del rastreo

​Cancelar un rastreo

​Mapeo de un sitio web

​Búsqueda en la Web

​Scraping por lotes

​Extracción por lotes con clave de idempotencia

​Uso y métricas

​Compatibilidad con async

​Configuración

​Cliente HTTP personalizado

​Configuración de variables de entorno

​Manejo de errores

Instalación

Uso

Hacer scraping de una URL

Extracción JSON

Rastreo de un sitio web

Iniciar un rastreo

Consultar el estado del rastreo

Cancelar un rastreo

Mapeo de un sitio web

Búsqueda en la Web

Scraping por lotes

Extracción por lotes con clave de idempotencia

Uso y métricas

Compatibilidad con async

Configuración

Cliente HTTP personalizado

Configuración de variables de entorno

Manejo de errores