> ## 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.

# Elixir

> O SDK Elixir do Firecrawl é um cliente gerado automaticamente para a API v2 do Firecrawl, desenvolvido com Req e NimbleOptions.

Faça scraping de páginas individuais, rastreie sites inteiros e mapeie URLs na sua aplicação Elixir. O SDK valida todos os parâmetros em tempo de execução com NimbleOptions e usa Req para HTTP, para que você receba mensagens de erro claras para erros de digitação e opções inválidas antes que qualquer requisição seja feita.

Toda função tem uma variante com bang (`!`) que gera uma exceção em caso de erro, em vez de retornar tuplas `{:error, ...}`.

<div id="installation">
  ## Instalação
</div>

Adicione `firecrawl` à sua lista de dependências no `mix.exs` e configure sua chave de API:

```elixir Elixir theme={null}
# Adicione ao mix.exs
{:firecrawl, "~> 1.0"}

# Em seguida, configure sua API key em config.exs
config :firecrawl, api_key: "fc-YOUR-API-KEY"
```

Ou passe a chave de API em cada requisição:

```elixir Elixir theme={null}
Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR-API-KEY")
```

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

1. Obtenha uma chave de API em [firecrawl.dev](https://firecrawl.dev)
2. Defina a chave de API na configuração do seu aplicativo ou passe-a como opção para qualquer função.

```elixir Elixir theme={null}
# Fazer scraping de um site:
{:ok, scrape_result} = Firecrawl.scrape_and_extract_from_url(
  url: "https://firecrawl.dev",
  formats: ["markdown", "html"]
)
IO.inspect(scrape_result.body)

# Rastrear um site:
{:ok, crawl_result} = Firecrawl.crawl_urls(
  url: "https://firecrawl.dev",
  limit: 100,
  scrape_options: [
    formats: ["markdown", "html"]
  ]
)
IO.inspect(crawl_result.body)
```

<div id="scraping-a-url">
  ### Fazendo scraping de uma URL
</div>

Faça o scraping de uma única URL com `scrape_and_extract_from_url`. Ela retorna o conteúdo da página como dados estruturados, incluindo markdown, metadados e quaisquer outros formatos que você solicitar.

```elixir Elixir theme={null}
# Fazer scraping de um site:
{:ok, result} = Firecrawl.scrape_and_extract_from_url(url: "https://firecrawl.dev", formats: ["markdown", "html"])
IO.inspect(result.body)
```

<div id="crawl-a-website">
  ### Rastrear um site
</div>

Para rastrear um site, use `crawl_urls`. Ele aceita a URL inicial e parâmetros opcionais, como limite de páginas, domínios permitidos e formato de resultado.

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.crawl_urls(url: "https://docs.firecrawl.dev", limit: 5)
IO.inspect(result.body)
```

<div id="start-a-crawl">
  ### Iniciar um rastreamento
</div>

Inicie um job de rastreamento e receba o ID do job sem bloqueio:

```elixir Elixir theme={null}
{:ok, job} = Firecrawl.crawl_urls(url: "https://docs.firecrawl.dev", limit: 10)
crawl_id = job.body["id"]
IO.puts(crawl_id)
```

<div id="checking-crawl-status">
  ### Verificando o status do rastreamento
</div>

Consulte o status de um job de rastreamento com `get_crawl_status`:

```elixir Elixir theme={null}
{:ok, status} = Firecrawl.get_crawl_status("<crawl-id>")
IO.inspect(status.body)
```

<div id="cancelling-a-crawl">
  ### Cancelar um rastreamento
</div>

Cancele um job de rastreamento com `cancel_crawl`:

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.cancel_crawl("<crawl-id>")
IO.puts("Cancelled: #{inspect(result.body)}")
```

<div id="map-a-website">
  ### Mapeie um site
</div>

Use `map_urls` para gerar uma lista de URLs a partir de um site:

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.map_urls(url: "https://firecrawl.dev", limit: 10)
IO.inspect(result.body)
```

<div id="search">
  ### Busca
</div>

Faça uma busca na web e, opcionalmente, faça scraping dos resultados:

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.search_and_scrape(query: "firecrawl web scraping", limit: 5)
IO.inspect(result.body["data"]["web"])
```

<div id="batch-scrape">
  ### Extração em lote
</div>

Realize o scraping de várias URLs em um único job em lote:

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.scrape_and_extract_from_urls(
  urls: ["https://firecrawl.dev", "https://docs.firecrawl.dev"],
  formats: ["markdown"]
)
IO.inspect(result.body)
```

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

Inicie uma tarefa de extração de dados com agente:

```elixir Elixir theme={null}
{:ok, job} = Firecrawl.start_agent(
  prompt: "Extract all product names and prices",
  urls: ["https://example.com/products"]
)
job_id = job.body["id"]

# Consultar status
{:ok, status} = Firecrawl.get_agent_status(job_id)
IO.inspect(status.body)
```

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

Inicie sessões de navegador na nuvem e execute código remotamente.

<div id="create-a-session">
  ### Criar uma sessão
</div>

```elixir Elixir theme={null}
{:ok, session} = Firecrawl.create_browser_session(ttl: 600)
session_id = session.body["id"]
cdp_url = session.body["cdpUrl"]
live_view_url = session.body["liveViewUrl"]
```

<div id="execute-code">
  ### Executar código
</div>

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.execute_browser_code(session_id,
  code: ~s(await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)),
  language: "python"
)
IO.inspect(result.body)
```

<div id="profiles">
  ### Perfis
</div>

Salve e reutilize o estado do navegador (cookies, localStorage etc.) entre sessões:

```elixir Elixir theme={null}
{:ok, session} = Firecrawl.create_browser_session(
  ttl: 600,
  profile: [
    name: "my-profile",
    save_changes: true
  ]
)
```

<div id="list-close-sessions">
  ### Listar & encerrar sessões
</div>

```elixir Elixir theme={null}
# Listar sessões ativas
{:ok, sessions} = Firecrawl.list_browser_sessions(status: "active")
IO.inspect(sessions.body)

# Encerrar uma sessão
{:ok, _} = Firecrawl.delete_browser_session(session_id)
```

<div id="self-hosted-instances">
  ## Instâncias auto-hospedadas
</div>

Para usar uma instância auto-hospedada do Firecrawl, passe a opção `base_url`:

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.scrape_and_extract_from_url(
  [url: "https://example.com"],
  base_url: "https://your-instance.com/v2"
)
```

<div id="error-handling">
  ## Tratamento de erros
</div>

Funções sem bang retornam `{:ok, response}` ou `{:error, exception}`. As variantes com bang levantam uma exceção em caso de erro. O NimbleOptions valida todos os parâmetros antes de a requisição ser enviada, detectando imediatamente erros de digitação, campos obrigatórios ausentes e erros de tipo.

```elixir Elixir theme={null}
case Firecrawl.scrape_and_extract_from_url(url: "https://example.com") do
  {:ok, response} -> IO.inspect(response.body)
  {:error, error} -> IO.puts("Error: #{Exception.message(error)}")
end

# Ou utilize a variante com bang para lançar um erro:
response = Firecrawl.scrape_and_extract_from_url!(url: "https://example.com")
IO.inspect(response.body)
```

<div id="all-available-functions">
  ## Todas as funções disponíveis
</div>

| Função                         | Descrição                                 |
| ------------------------------ | ----------------------------------------- |
| `scrape_and_extract_from_url`  | Faz scraping de uma única URL             |
| `scrape_and_extract_from_urls` | Faz extração em lote de várias URLs       |
| `crawl_urls`                   | Faz o rastreamento de um site             |
| `get_crawl_status`             | Verifica o status do job de rastreamento  |
| `get_crawl_errors`             | Obtém os erros do job de rastreamento     |
| `get_active_crawls`            | Lista os rastreamentos ativos             |
| `cancel_crawl`                 | Cancela um job de rastreamento            |
| `map_urls`                     | Mapeia URLs em um site                    |
| `search_and_scrape`            | Busca e faz scraping dos resultados       |
| `start_agent`                  | Inicia uma tarefa de extração com agente  |
| `get_agent_status`             | Verifica o status do job do agente        |
| `cancel_agent`                 | Cancela um job do agente                  |
| `create_browser_session`       | Cria uma sessão de navegador              |
| `execute_browser_code`         | Executa código em uma sessão de navegador |
| `list_browser_sessions`        | Lista as sessões de navegador             |
| `delete_browser_session`       | Exclui uma sessão de navegador            |
| `get_batch_scrape_status`      | Verifica o status da extração em lote     |
| `get_batch_scrape_errors`      | Obtém os erros da extração em lote        |
| `cancel_batch_scrape`          | Cancela uma extração em lote              |
| `get_credit_usage`             | Obtém os créditos restantes               |

Todas as funções acima têm uma variante com bang (`!`) (por exemplo, `scrape_and_extract_from_url!`) que gera uma exceção em vez de retornar tuplas de erro.

Para ver a documentação completa da API, consulte [hexdocs.pm/firecrawl](https://hexdocs.pm/firecrawl).