Saltar al contenido principal

​
Instalación

El SDK oficial de Firecrawl para .NET se mantiene en el monorepo de Firecrawl, en apps/.net-sdk. Para instalar el SDK de Firecrawl para .NET, agrega el paquete NuGet:
bash dotnet add package firecrawl-sdk
Requiere .NET 8.0 o posterior.

​
Uso

  1. Obtén una clave de API de firecrawl.dev
  2. 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ónTipoPredeterminadoDescripción
apiKeystring?Variable de entorno FIRECRAWL_API_KEYTu clave de la API de Firecrawl
apiUrlstring?https://api.firecrawl.dev (o FIRECRAWL_API_URL)URL base de la API
timeoutTimeSpan?5 minutosTiempo de espera de la solicitud HTTP
maxRetriesint3Reintentos automáticos ante fallos transitorios
backoffFactordouble0.5Factor de retroceso exponencial en segundos
httpClientHttpClient?Se crea a partir de timeoutInstancia 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:
ExceptionHTTP CodeWhen
AuthenticationException401Clave de API no válida o ausente
RateLimitException429Demasiadas solicitudes
JobTimeoutException—El trabajo asíncrono (crawl/extracción por lotes) no se completó a tiempo
FirecrawlExceptionvaríaExcepció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.