Firecrawl para plataformas

Visão geral

O Firecrawl for Platforms permite que sua plataforma crie e gerencie API keys do Firecrawl para seus usuários diretamente pelo seu próprio backend. Assim, os usuários começam a usar o Firecrawl sem sair da sua plataforma.

Você mesmo pode configurar o Firecrawl for Platforms no painel do Firecrawl. Qualquer administrador ou membro de uma organização pode criar uma integração: dê um nome a ela, escolha um tipo de integração, aceite o contrato correspondente e copie a chave da plataforma. A chave é exibida uma única vez. Depois, você pode gerar e revogar chaves em Configurações. Não é preciso fazer nenhuma solicitação nem aguardar aprovação.

Existem dois tipos de integração. Ambos provisionam contas da mesma forma, pelos endpoints abaixo e com a mesma chave da plataforma. A diferença está em quem paga pelo uso do usuário:

Standard: seus usuários pagam o Firecrawl. Cada conta provisionada mantém seu próprio plano e sua própria cobrança no Firecrawl, começa no plano Free e faz upgrade diretamente com o Firecrawl.
Gateway: sua organização custeia o uso dos seus usuários. As contas criadas pela sua integração são inscritas no Gateway, então o uso elegível delas passa a ser cobrado da sua organização quando os créditos do próprio usuário se esgotam. Consulte Gateway abaixo.

Você escolhe o tipo de integração ao criá-la. Como não é simples alterá-lo depois, recomendamos avaliar as duas opções com atenção antes de aceitar o contrato. Para uma visão geral, consulte a página do Firecrawl for Platforms. Algumas ofertas de parceiro incluem créditos promocionais para usuários provisionados. Nesses casos, a página Créditos de parceiro descreve o que o usuário recebe.

Gateway

Gateway é um tipo de integração, não uma API separada. A mesma chave da plataforma e os mesmos endpoints continuam valendo. O que muda em uma integração Gateway:

As contas são criadas exclusivamente para a sua integração e funcionam apenas via API, sem login próprio no painel. Uma requisição nunca é vinculada a uma conta existente do Firecrawl, mesmo quando o email corresponde ao de uma delas.
Os créditos do próprio usuário são usados primeiro. O uso elegível que ultrapassar esses créditos é cobrado da sua organização.
As respostas de POST /partner/v1/accounts incluem um campo gatewayStatus.
A integração aceita a versão Gateway do contrato no momento da criação.

URL base

https://integrations.firecrawl.dev

Autenticação

Todas as solicitações de API da Platforms exigem um header Authorization com a sua chave da plataforma:

Authorization: Bearer <platform key>

As chaves da plataforma são diferentes das API keys comuns do Firecrawl. Você pode criá-las e revogá-las em Configurações > Firecrawl for Platforms no painel do Firecrawl.

Requisitos de segurança

Somente no servidor: as chaves da plataforma devem ser usadas apenas em código executado no servidor. Nunca exponha uma chave da plataforma em código de frontend, JavaScript do lado do cliente ou aplicativos móveis.
Termos de Serviço: antes de chamar POST /partner/v1/accounts, sua plataforma deve solicitar que o usuário aceite os Termos de Serviço do Firecrawl.

Endpoints

Criar usuário

Provisiona uma conta do Firecrawl para um dos seus usuários, identificado pelo email, e retorna a API key correspondente.

POST /partner/v1/accounts

Comportamento

Com uma integração Standard:

Se o usuário ainda não tiver uma conta no Firecrawl, um novo usuário e uma nova equipe serão criados.
Se o usuário já tiver uma conta no Firecrawl, mas nenhuma equipe associada à sua integração, será criada uma nova equipe associada à sua integração.
Se o usuário já tiver uma conta no Firecrawl e uma equipe associada à sua integração, a equipe existente será retornada.

Com uma integração Gateway:

Cada conta é criada exclusivamente para a sua integração. Uma requisição nunca é vinculada a uma conta existente do Firecrawl, mesmo que o email corresponda a uma delas. O email é armazenado como endereço de contato da conta e não é usado para buscar contas.
Chamadas repetidas com o mesmo email retornam a mesma conta e a respectiva API key.

Se a sua integração incluir créditos promocionais, eles serão aplicados uma única vez, no momento em que a conta for criada.

Requisição

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/accounts" \
  -H "Authorization: Bearer <platform key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Corpo

Campo	Tipo	Obrigatório	Descrição
`email`	string	Sim	O endereço de e-mail do usuário. Em uma integração Gateway, ele é armazenado como o endereço de contato da conta.

Resposta

200 OK

{
  "apiKey": "fc-...",
  "alreadyExisted": false
}

Em uma integração Gateway, a resposta também inclui o status da inscrição:

{
  "apiKey": "fc-...",
  "alreadyExisted": false,
  "gatewayStatus": "enrolled"
}

Campo	Tipo	Descrição
`apiKey`	string	A API key do Firecrawl da equipe que sua integração provisionou para este usuário
`alreadyExisted`	boolean	`true` se sua integração já tiver provisionado uma conta para este email. Isso não indica se o email já existe em outra parte do Firecrawl.
`gatewayStatus`	string	Somente para integrações Gateway. `enrolled` na chamada que cria a conta e `already_enrolled` nas chamadas seguintes para o mesmo email.

Erros

Status	Descrição
`400`	Requisição inválida - o `email` está ausente ou em formato inválido
`401`	Não autorizado - a chave da plataforma está incorreta ou é inválida
`500`	Erro interno do servidor - esses erros são monitorados pelo Firecrawl

Validar API key

Valida uma API key do Firecrawl e retorna o nome da equipe associada e o endereço de e-mail do usuário. A API key só será considerada válida se tiver sido criada pela sua integração.

POST /partner/v1/api-keys/validate

Observações importantes

As API keys do Firecrawl não têm permissões nem data de expiração.
Os usuários podem excluir API keys manualmente a qualquer momento.
As API keys excluídas não passam por exclusão lógica (soft delete). O Firecrawl não consegue distinguir uma chave excluída de uma que nunca existiu.

Requisição

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/api-keys/validate" \
  -H "Authorization: Bearer <platform key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'

Corpo

Campo	Tipo	Obrigatório	Descrição
`apiKey`	string	Sim	A API key a ser validada

Resposta

200 OK

{
  "teamName": "Example Team",
  "email": "user@example.com"
}

Campo	Tipo	Descrição
`teamName`	string	O nome da equipe associada a esta API key
`email`	string	O email usado no provisionamento da conta. Em contas Gateway, é o endereço de contato que você informou.

Erros

Status	Descrição
`400`	Requisição inválida - a API key está mal formatada
`401`	Não autorizado - a chave da plataforma está incorreta ou é inválida
`404`	API key não identificável - a chave não existe ou não foi criada pela sua integração
`500`	Erro interno do servidor - esses erros são monitorados pelo Firecrawl

Rotacionar API key

Exclui uma API key existente do Firecrawl e cria uma nova para o mesmo usuário e a mesma equipe.

POST /partner/v1/api-keys/rotate

Requisição

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/api-keys/rotate" \
  -H "Authorization: Bearer <platform key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'

Corpo

Campo	Tipo	Obrigatório	Descrição
`apiKey`	string	Sim	A API key a ser excluída e substituída

Resposta

200 OK

{
  "apiKey": "fc-..."
}

Campo	Tipo	Descrição
`apiKey`	string	A nova API key criada

Erros

Status	Descrição
`401`	Não autorizado - a chave da plataforma está incorreta ou é inválida
`404`	API key não identificável - a chave não existe ou não foi criada pela sua integração
`500`	Erro interno do servidor - esses erros são monitorados pela Firecrawl

Primeiros passos

Crie sua integração no painel do Firecrawl: faça login, escolha Standard ou Gateway, aceite o contrato e copie sua chave da plataforma. Como não é fácil alterar o tipo de integração depois, confirme sua escolha antes de aceitar o contrato. Em seguida, chame os endpoints acima a partir do seu servidor. Tem dúvidas sobre a sua configuração? Escreva para help@firecrawl.com. Pensando em uma integração maior? Escreva para partnerships@firecrawl.dev.

Usando a API

Endpoints de busca

Endpoints /scrape

Endpoints para interagir / Browser Sandbox

Endpoints do Research Index

Endpoints do índice para desenvolvedores

Endpoints de mapeamento

Endpoints de análise

Endpoints de rastreamento

Endpoints de monitoramento

Endpoints de agente

Endpoints de feedback

Endpoints de depuração agêntica

Endpoints da conta

Payloads de webhook