> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby

> El SDK de Ruby de Firecrawl es un wrapper de la API de Firecrawl que te permite convertir sitios web en Markdown fácilmente.

<div id="installation">
  ## Instalación
</div>

El SDK oficial de Ruby se mantiene en el monorepo de Firecrawl, en [apps/ruby-sdk](https://github.com/firecrawl/firecrawl/tree/main/apps/ruby-sdk).

Para instalar el SDK de Ruby de Firecrawl, añádelo a tu proyecto:

<Tabs>
  <Tab title="Bundler">
    Añádelo a tu `Gemfile`:

    ```ruby theme={null}
    gem "firecrawl-sdk", "~> 1.0"
    ```

    Luego, ejecuta:

    ```bash theme={null}
    bundle install
    ```
  </Tab>

  <Tab title="Gem install">
    ```bash theme={null}
    gem install firecrawl-sdk
    ```
  </Tab>
</Tabs>

<Note>Requiere Ruby 3.0 o una versión posterior.</Note>

<div id="usage">
  ## Uso
</div>

1. Obtén una clave de API de [firecrawl.dev](https://firecrawl.dev)
2. Configura la clave de API como una variable de entorno llamada `FIRECRAWL_API_KEY`, o pásala directamente con `Firecrawl::Client.new(api_key: ...)`

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

```ruby theme={null}
require "firecrawl"

client = Firecrawl::Client.from_env

doc = client.scrape(
  "https://firecrawl.dev",
  Firecrawl::Models::ScrapeOptions.new(formats: ["markdown"])
)

job = client.crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(limit: 5)
)

puts doc.markdown
puts "Crawled pages: #{job.data&.size || 0}"
```

<div id="scraping-a-url">
  ### Hacer scraping de una URL
</div>

Para hacer scraping de una sola URL, usa el método `scrape`.

```ruby theme={null}
doc = client.scrape(
  "https://firecrawl.dev",
  Firecrawl::Models::ScrapeOptions.new(
    formats: ["markdown", "html"],
    only_main_content: true,
    wait_for: 5000
  )
)

puts doc.markdown
puts doc.metadata["title"]
```

<div id="json-extraction">
  #### Extracción JSON
</div>

Extrae JSON estructurado a través del endpoint `scrape` incluyendo el formato `json` junto con un prompt y un schema:

```ruby theme={null}
doc = client.scrape(
  "https://example.com/product",
  Firecrawl::Models::ScrapeOptions.new(
    formats: [
      {
        "type" => "json",
        "prompt" => "Extract the product name and price",
        "schema" => {
          "type" => "object",
          "properties" => {
            "name" => { "type" => "string" },
            "price" => { "type" => "number" }
          }
        }
      }
    ]
  )
)

puts doc.json
```

<div id="crawling-a-website">
  ### Rastreo de un sitio web
</div>

Para rastrear un sitio web y esperar a que finalice, usa `crawl`. Realiza sondeos automáticamente hasta que el trabajo termine.

```ruby theme={null}
job = client.crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(
    limit: 50,
    max_discovery_depth: 3,
    scrape_options: Firecrawl::Models::ScrapeOptions.new(
      formats: ["markdown"]
    )
  )
)

puts "Status: #{job.status}"
puts "Progress: #{job.completed}/#{job.total}"

job.data&.each do |page|
  puts page.metadata["sourceURL"]
end
```

<div id="start-a-crawl">
  ### Iniciar un rastreo
</div>

Inicia un trabajo sin esperar con `start_crawl`.

```ruby theme={null}
response = client.start_crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(limit: 100)
)

puts "Job ID: #{response.id}"
```

<div id="checking-crawl-status">
  ### Consultar el estado del rastreo
</div>

Consulta el progreso del rastreo con `get_crawl_status`.

```ruby theme={null}
status = client.get_crawl_status(response.id)
puts "Status: #{status.status}"
puts "Progress: #{status.completed}/#{status.total}"
```

<div id="cancelling-a-crawl">
  ### Cancelar un rastreo
</div>

Cancela un rastreo en curso con `cancel_crawl`.

```ruby theme={null}
result = client.cancel_crawl(response.id)
puts result
```

<div id="mapping-a-website">
  ### Mapeo de un sitio web
</div>

Descubre enlaces en un sitio web utilizando `map`.

```ruby theme={null}
data = client.map(
  "https://firecrawl.dev",
  Firecrawl::Models::MapOptions.new(
    limit: 100,
    search: "blog"
  )
)

data.links&.each do |link|
  puts "#{link["url"]} - #{link["title"]}"
end
```

<div id="searching-the-web">
  ### Buscar en la Web
</div>

Busca con opciones de configuración opcionales utilizando `search`.

```ruby theme={null}
results = client.search(
  "firecrawl web scraping",
  Firecrawl::Models::SearchOptions.new(limit: 10)
)

results.web&.each do |result|
  puts "#{result["title"]} - #{result["url"]}"
end
```

<div id="batch-scraping">
  ### Scraping por lotes
</div>

Realiza scraping de varias URL en paralelo con `batch_scrape`.

```ruby theme={null}
job = client.batch_scrape(
  ["https://firecrawl.dev", "https://firecrawl.dev/blog"],
  Firecrawl::Models::BatchScrapeOptions.new(
    options: Firecrawl::Models::ScrapeOptions.new(
      formats: ["markdown"]
    )
  )
)

job.data&.each do |doc|
  puts doc.markdown
end
```

<div id="agent">
  ### Agente
</div>

Ejecuta un agente con IA mediante `agent`.

```ruby theme={null}
result = client.agent(
  Firecrawl::Models::AgentOptions.new(
    prompt: "Find the pricing plans for Firecrawl and compare them"
  )
)

puts result.data
```

Con un esquema JSON para salida estructurada:

```ruby theme={null}
result = client.agent(
  Firecrawl::Models::AgentOptions.new(
    prompt: "Extract pricing plan details",
    urls: ["https://firecrawl.dev"],
    schema: {
      "type" => "object",
      "properties" => {
        "plans" => {
          "type" => "array",
          "items" => {
            "type" => "object",
            "properties" => {
              "name" => { "type" => "string" },
              "price" => { "type" => "string" }
            }
          }
        }
      }
    }
  )
)

puts result.data
```

<div id="usage-metrics">
  ### Uso & métricas
</div>

Consulta la concurrencia y los créditos restantes:

```ruby theme={null}
concurrency = client.get_concurrency
puts "Concurrency: #{concurrency.concurrency}/#{concurrency.max_concurrency}"

credits = client.get_credit_usage
puts "Remaining credits: #{credits.remaining_credits}"
```

<div id="browser">
  ## Browser
</div>

El SDK de Ruby incluye utilidades para el sandbox del navegador.

<div id="scrape-bound-interactive-session">
  ### Sesión interactiva vinculada al scraping
</div>

Usa un ID de trabajo de scraping para ejecutar código adicional de browser en el mismo contexto reproducido:

* `interact(...)` ejecuta código en la sesión de browser vinculada al scraping (y la inicializa la primera vez que se usa).
* `stop_interactive_browser(...)` detiene explícitamente la sesión interactiva cuando terminas.

```ruby theme={null}
scrape_job_id = "550e8400-e29b-41d4-a716-446655440000"

run = client.interact(
  scrape_job_id,
  "console.log(page.url());",
  language: "node",
  timeout: 60
)

puts run["stdout"]

deleted = client.stop_interactive_browser(scrape_job_id)
puts "Deleted: #{deleted["success"]}"
```

<div id="configuration">
  ## Configuración
</div>

`Firecrawl::Client.new` admite las siguientes opciones:

| Opción           | Tipo      | Predeterminado                                      | Descripción                                       |
| ---------------- | --------- | --------------------------------------------------- | ------------------------------------------------- |
| `api_key`        | `String`  | variable de entorno `FIRECRAWL_API_KEY`             | Tu clave de la API de Firecrawl                   |
| `api_url`        | `String`  | `https://api.firecrawl.dev` (o `FIRECRAWL_API_URL`) | URL base de la API                                |
| `timeout`        | `Integer` | `300`                                               | Tiempo de espera de la solicitud HTTP en segundos |
| `max_retries`    | `Integer` | `3`                                                 | Reintentos automáticos ante fallos transitorios   |
| `backoff_factor` | `Float`   | `0.5`                                               | Factor de backoff exponencial en segundos         |

```ruby theme={null}
client = Firecrawl::Client.new(
  api_key: "fc-your-api-key",
  api_url: "https://api.firecrawl.dev",
  timeout: 300,
  max_retries: 3,
  backoff_factor: 0.5
)
```

<div id="error-handling">
  ## Manejo de errores
</div>

El SDK lanza excepciones dentro del módulo `Firecrawl`.

```ruby theme={null}
begin
  doc = client.scrape("https://example.com")
rescue Firecrawl::AuthenticationError => e
  puts "Auth failed: #{e.message}"
rescue Firecrawl::RateLimitError => e
  puts "Rate limited: #{e.message}"
rescue Firecrawl::JobTimeoutError => e
  puts "Job #{e.job_id} timed out after #{e.timeout_seconds}s"
rescue Firecrawl::FirecrawlError => e
  puts "Error (#{e.status_code}): #{e.message}"
end
```

> ¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para ver las instrucciones de incorporación automática.