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 acordo 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 e faz upgrade diretamente com o Firecrawl. Consulte Créditos para contas provisionadas para saber com o que uma nova conta começa.
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. 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 acordo. 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.
O uso elegível é cobrado da sua organização. Veja Créditos para contas provisionadas para saber quando os créditos do próprio usuário são usados primeiro.
As respostas de POST /partner/v1/accounts incluem um campo gatewayStatus.
A integração aceita a versão Gateway do acordo 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.

Créditos para contas provisionadas

As contas criadas pela sua integração não incluem créditos gratuitos, a menos que o Firecrawl tenha verificado sua plataforma ou que você tenha um acordo assinado com o Firecrawl. Até lá:

Uma conta Standard começa sem créditos incluídos. O usuário pode adicionar um método de pagamento ou escolher um plano no painel do Firecrawl a qualquer momento.
Uma conta Gateway cobra todos os créditos da sua organização.

Depois que sua plataforma for verificada, as contas novas e existentes passam a incluir os créditos mensais do plano gratuito. Nas contas Gateway, esses créditos são consumidos antes de qualquer cobrança à sua organização. A verificação é feita manualmente pela equipe do Firecrawl. Quando sua integração estiver em produção, ou se você estiver construindo uma aplicação para produção, escreva para partnerships@firecrawl.dev informando o ID da sua integração.

Limites

A criação de contas é limitada por integração, tanto na quantidade de contas que uma integração pode criar quanto na velocidade de criação. Os limites aumentam à medida que o relacionamento da sua organização com o Firecrawl evolui e nunca afetam as contas que você já criou. Uma chamada repetida para um usuário que você já provisionou retorna a conta existente e não é contabilizada no limite de contas. O endereço de e-mail informado para uma conta Standard precisa ser um endereço no qual seu usuário consiga receber mensagens. Se você atingir um limite ou estiver planejando uma integração em produção, escreva para partnerships@firecrawl.dev informando o ID da sua integração e o volume esperado. Se o Firecrawl suspender sua integração, escreva para help@firecrawl.com.

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
`403`	Recusada - o `error.code` no corpo da resposta informa o motivo: `partner_account_cap_reached` (a integração atingiu o limite de contas), `partner_provisioning_email_rejected` (o endereço não pode ser usado em uma conta Firecrawl) ou `partner_integration_suspended`. Veja Limites
`429`	Requisições em excesso - `rate_limit_exceeded`; reduza o ritmo e tente novamente
`502`	O Firecrawl não conseguiu acessar o provider de cobrança ao configurar a conta - tente fazer a request novamente
`503`	O Firecrawl não conseguiu verificar o limite de requisições - tente novamente em instantes
`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.

Partner Program

Plataformas que provisionam contas do Firecrawl para seus usuários podem se inscrever no Firecrawl Partner Program. Parceiros aprovados recebem participação na receita sobre o uso pago dos usuários que indicarem, ações de co-marketing e uma listagem em nosso diretório de parceiros, acesso antecipado a novos endpoints, um canal direto com nossa equipe para suporte técnico e limites mais altos para seus usuários. A participação no programa é feita mediante inscrição, e respondemos em até uma semana. Em contrapartida, os parceiros exibem “Powered by Firecrawl” em seu produto, com link para firecrawl.dev usando a tag ?ref=<partner>. A participação na receita vale apenas para novos clientes pagantes que você indicar após a aprovação da sua inscrição, nunca de forma retroativa. Ela cobre o primeiro ano de cada cliente em planos de autoatendimento; os planos Scale e Enterprise não estão incluídos. Todos os parceiros são analisados e aprovados pela nossa equipe. Inscreva-se no Partner Program Você escreve sobre o Firecrawl ou publica links para ele? Nesse caso, o programa de afiliados é a melhor opção.

​Visão geral

​Gateway

​URL base

​Autenticação

​Requisitos de segurança

​Créditos para contas provisionadas

​Limites

​Endpoints

​Criar usuário

​Comportamento

​Requisição

​Resposta

​Erros

​Validar API key

​Observações importantes

​Requisição

​Resposta

​Erros

​Rotacionar API key

​Requisição

​Resposta

​Erros

​Primeiros passos

​Partner Program

Visão geral

Gateway

URL base

Autenticação

Requisitos de segurança

Créditos para contas provisionadas

Limites

Endpoints

Criar usuário

Comportamento

Requisição

Resposta

Erros

Validar API key

Observações importantes

Requisição

Resposta

Erros

Rotacionar API key

Requisição

Resposta

Erros

Primeiros passos

Partner Program