Partner API

Visão geral

A API de integração de parceiros do Firecrawl permite que sua plataforma crie e gerencie API keys do Firecrawl para seus usuários diretamente do seu próprio backend. Os usuários começam a usar o Firecrawl sem sair da sua plataforma.

Configure a Partner API por conta própria no painel do Firecrawl. Qualquer administrador ou membro de uma organização pode criar uma integração: dê um nome, escolha uma configuração, aceite o contrato correspondente e copie a chave de parceiro. A chave é exibida apenas uma vez. Depois, você pode gerar e revogar chaves em Settings. Não é necessário solicitação nem aprovação.

Existem duas configurações. Ambas provisionam contas da mesma forma pelos endpoints abaixo; a diferença está em quem paga pelo uso do usuário:

Partner API: cada conta provisionada mantém seu próprio plano e cobrança do Firecrawl. Os usuários começam no Free plan e fazem upgrade diretamente com o Firecrawl.
Gateway: as contas criadas pela sua integração são inscritas no Gateway, de modo que o uso elegível é cobrado da sua organização assim que os créditos do próprio usuário se esgotarem. As contas do Gateway são exclusivamente de API e não têm login próprio no painel.

Você escolhe a configuração ao criar a integração. Não é fácil mudar depois, então recomendamos avaliar as duas opções com atenção antes de aceitar o contrato. Consulte a página da Partner API para uma visão geral. Algumas ofertas de parceiro incluem créditos promocionais para usuários provisionados; nesses casos, Partner Credits descreve o que o usuário recebe.

URL base

https://integrations.firecrawl.dev

Autenticação

Todas as solicitações da API de integração de parceiros exigem um cabeçalho Authorization com sua chave de parceiro:

Authorization: Bearer <partner key>

As chaves de parceiro são diferentes das API keys padrão do Firecrawl. Você pode criá-las e revogá-las em Configurações > Partner API no painel do Firecrawl.

Requisitos de segurança

Somente no servidor: As chaves de parceiro devem ser usadas apenas em código executado no servidor. Nunca exponha uma chave de parceiro 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 ao usuário que aceite os Termos de Serviço do Firecrawl.

Endpoints

Criar usuário

Provisiona uma conta do Firecrawl para um dos seus usuários, identificado por e-mail, e retorna sua API key.

POST /partner/v1/accounts

Comportamento

Com o setup de Partner API:

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

Com o setup de Gateway:

Toda conta é criada exclusivamente para a sua integração. Uma requisição nunca é vinculada a uma conta Firecrawl já existente, mesmo que o email seja o mesmo. O email é armazenado como endereço de contato da conta e não é usado para localizar contas.
Chamadas repetidas para o mesmo email retornam a mesma conta e a mesma API key.

Se a sua integração incluir créditos promocionais, eles são aplicados uma única vez, no momento da criação da conta.

Requisição

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/accounts" \
  -H "Authorization: Bearer <partner 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. Com o setup Gateway, ele é armazenado como o endereço de contato da conta.

Resposta

200 OK

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

Com o setup do Gateway, a resposta também traz o status de inscrição:

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

Campo	Tipo	Descrição
`apiKey`	string	A API key do Firecrawl da equipe associada ao parceiro deste usuário
`alreadyExisted`	boolean	`true` se a sua integração já havia provisionado uma conta para este email. Isso não indica se o email existe em outro lugar no Firecrawl.
`gatewayStatus`	string	Apenas para integrações de gateway. `enrolled` na chamada que cria a conta, `already_enrolled` em chamadas repetidas para o mesmo email.

Erros

Status	Descrição
`400`	Requisição inválida — o `email` está ausente ou malformado
`401`	Não autorizado — a chave de parceiro está incorreta ou inválida
`500`	Erro interno do servidor — esses erros são monitorados pela Firecrawl

Validar chave de API

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

POST /partner/v1/api-keys/validate

Observações importantes

As chaves de API do Firecrawl não têm permissões nem data de expiração.
As chaves de API podem ser excluídas manualmente pelos usuários a qualquer momento.
As chaves de API excluídas não passam por exclusão lógica. 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 <partner key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'

Corpo

Campo	Tipo	Obrigatório	Descrição
`apiKey`	string	Sim	A chave de API 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 chave de API
`email`	string	O e-mail com o qual a conta foi provisionada. Para contas do Gateway, este é o endereço de contato que você informou.

Erros

Status	Descrição
`400`	Requisição inválida — a API key está malformada
`401`	Não autorizado — a chave de parceiro está incorreta ou inválida
`404`	API key não identificável — a chave não existe ou não foi criada por meio desta integração de parceiro
`500`	Erro interno do servidor — esses erros são monitorados pela Firecrawl

Rotacionar chave de API

Exclui uma chave de API do Firecrawl existente e cria uma nova para o mesmo usuário e 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 <partner key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'

Corpo

Campo	Tipo	Obrigatório	Descrição
`apiKey`	string	Sim	A chave de API que será excluída e substituída

Resposta

200 OK

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

Campo	Tipo	Descrição
`apiKey`	string	A chave de API recém-criada

Erros

Status	Descrição
`401`	Não autorizado - a chave de parceiro está incorreta ou inválida
`404`	Chave de API não identificada - a chave não existe ou não foi criada por meio desta integração de parceiro
`500`	Erro interno do servidor - esses erros são monitorados pela Firecrawl

Comece agora

Crie sua integração no painel do Firecrawl: faça login, escolha Partner API ou Gateway, aceite o contrato e copie sua chave de parceiro. A configuração não é fácil de alterar depois, então confirme sua escolha antes de aceitar o contrato. Em seguida, chame os endpoints acima a partir do seu servidor. Ficou com dúvidas sobre sua configuração? Escreva para help@firecrawl.com. Pensa 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

API de parceiro

Visão geral

URL base

Autenticação

Requisitos de segurança

Endpoints

Criar usuário

Comportamento

Requisição

Resposta

Erros

Validar chave de API

Observações importantes

Requisição

Resposta

Erros

Rotacionar chave de API

Requisição

Resposta

Erros

Comece agora

​Visão geral

​URL base

​Autenticação

​Requisitos de segurança

​Endpoints

​Criar usuário

​Comportamento

​Requisição

​Resposta

​Erros

​Validar chave de API

​Observações importantes

​Requisição

​Resposta

​Erros

​Rotacionar chave de API

​Requisição

​Resposta

​Erros

​Comece agora

Visão geral

URL base

Autenticação

Requisitos de segurança

Endpoints

Criar usuário

Comportamento

Requisição

Resposta

Erros

Validar chave de API

Observações importantes

Requisição

Resposta

Erros

Rotacionar chave de API

Requisição

Resposta

Erros

Comece agora