For AI agents: the complete documentation index is available at https://docs.clickmax.io/llms.txt, the full documentation bundle is available at https://docs.clickmax.io/llms-full.txt, and this page is available as Markdown at https://docs.clickmax.io/reference/api/firecrawl.md.
  • Português
  • Como usar o Firecrawl pela API da Clickmax

    A API da Clickmax faz chamadas ao Firecrawl para buscar na web e ler páginas, com a mesma chave de API da Clickmax que você já usa nas outras chamadas. Você não precisa ter conta no Firecrawl: sem chave própria conectada, a Clickmax faz a chamada pela conta dela. Se preferir usar a sua conta Firecrawl, conecte a chave dela ao workspace, e as chamadas passam a gastar os créditos da sua conta Firecrawl.

    Antes de começar, você precisa de:

    • uma chave de API do workspace da Clickmax (veja Autenticação na API da Clickmax);
    • só para usar a sua conta Firecrawl: uma chave de API do Firecrawl (fc-...), criada no painel do Firecrawl, e permissão para gerenciar integrações no workspace.

    A conexão com o Firecrawl existe só pela API. Ela não aparece na tela de Integrações.

    Os exemplos usam o SDK TypeScript. Pela API HTTP, os caminhos são os mesmos, sob /api/v0/firecrawl/.

    Usar a sua conta Firecrawl (opcional)

    import { Clickmax } from '@clickmax/public-sdk'
    
    const clickmax = new Clickmax(process.env.CLICKMAX_API_KEY!)
    
    const [ok, error, status] = await clickmax.firecrawl.connect({
      apiKey: process.env.FIRECRAWL_API_KEY!,
    })

    A Clickmax confere a chave com o Firecrawl antes de guardar, sem gastar créditos. Uma chave recusada não é guardada. Conectar de novo troca a chave anterior. Cada workspace tem uma chave Firecrawl.

    • clickmax.firecrawl.status() mostra se há uma chave conectada. O campo billing diz qual conta as chamadas usam: own_key (a sua conta Firecrawl) ou clickmax_credits (a conta da Clickmax).
    • clickmax.firecrawl.disconnect() remove a chave. As chamadas seguintes voltam a usar a conta da Clickmax.

    Buscar na web

    const [ok, error, result] = await clickmax.firecrawl.search({
      query: 'clínicas de estética em Belo Horizonte -site:instagram.com -site:facebook.com',
      limit: 20,
      country: 'BR',
    })
    
    for (const item of result?.data.web ?? []) {
      console.log(item.url, item.title, item.description)
    }

    A consulta aceita operadores como site:, -site: e frases entre aspas. Sem scrapeOptions, cada resultado traz só url, title e description. Para receber também o conteúdo de cada página, envie scrapeOptions: { formats: ['markdown'], onlyMainContent: true }. Isso deixa a busca mais lenta e mais cara.

    Ler uma página

    const [ok, error, page] = await clickmax.firecrawl.scrape({
      url: 'https://exemplo.com.br',
      formats: ['markdown', 'links'],
      onlyMainContent: false,
      timeout: 30_000,
    })
    
    if (ok && (page.data.metadata?.statusCode ?? 200) < 400) {
      console.log(page.data.markdown, page.data.links)
    }
    • formats aceita markdown e links. O padrão é ["markdown"].
    • onlyMainContent: false mantém cabeçalho e rodapé, onde costumam ficar telefone e WhatsApp.
    • Uma página que respondeu com erro ainda volta com sucesso. Confira data.metadata.statusCode: 400 ou mais indica página de erro.
    • maxAge, storeInCache, blockAds, removeBase64Images e location (country, languages) seguem o comportamento do Firecrawl.

    Consultar o saldo da sua conta Firecrawl

    const [ok, error, usage] = await clickmax.firecrawl.creditUsage()
    console.log(usage?.data.remainingCredits)

    A consulta não gasta créditos e serve também para conferir se a chave conectada ainda funciona. Ela só funciona com a sua chave conectada: sem ela, volta o erro firecrawl_not_connected, e as buscas e leituras continuam funcionando pela conta da Clickmax.

    Tempo limite

    timeout vai de 1000 a 60000 milissegundos, e o padrão é 30000. O Firecrawl para de tentar ao atingir esse tempo. Mantenha o timeout do cliente da Clickmax (padrão de 60000) acima do timeout da chamada, para receber a resposta do Firecrawl em vez de um erro de tempo do SDK.

    Erros do Firecrawl

    Leia o code do erro para decidir o que fazer.

    codeStatusO que significaO que fazer
    firecrawl_not_connected412creditUsage foi chamado sem chave Firecrawl conectadaConecte a sua chave com firecrawl.connect, ou não consulte o saldo
    firecrawl_key_invalid412O Firecrawl recusou a sua chave conectadaConecte uma chave válida, ou desconecte para usar a conta da Clickmax
    firecrawl_forbidden403O Firecrawl negou a chamada, por exemplo por restrição de IP ou de endpoint na chave, ou URL bloqueadaAjuste as restrições da chave no Firecrawl ou troque a URL; a mensagem traz o motivo
    firecrawl_insufficient_credits402A sua conta Firecrawl está sem créditosRecarregue a conta no Firecrawl
    firecrawl_rate_limited429O Firecrawl limitou as chamadas da sua chaveEspere o tempo de retryAfter e tente de novo. Quando o Firecrawl não informa o tempo, retryAfter vem com 10 segundos
    firecrawl_timeout504O Firecrawl não respondeu a tempoTente de novo ou aumente o timeout
    firecrawl_invalid_request400O Firecrawl recusou os parâmetrosCorrija a chamada; a mensagem traz o motivo
    firecrawl_unavailable502 ou 503O Firecrawl falhou, ou a conta da Clickmax no Firecrawl está indisponível no momentoTente de novo mais tarde, respeitando retryAfter quando vier, ou conecte a sua chave

    A Clickmax não repete chamadas ao Firecrawl por conta própria. Os limites de chamadas da API da Clickmax continuam valendo.