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

# Firecrawl para plataformas

> Referência da API para plataformas que criam e gerenciam API keys do Firecrawl para seus usuários

## 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, seus usuários podem pesquisar, fazer scraping e interagir com a web por meio do Firecrawl, a API de contexto para agentes de IA, sem sair da sua plataforma.

> [!NOTE]
>
> Você mesmo pode configurar o Firecrawl for Platforms no [painel do Firecrawl](https://www.firecrawl.dev/app/partner-api). 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](#credits-for-provisioned-accounts) 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](#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](https://www.firecrawl.dev/firecrawl-for-platforms).

Algumas ofertas de parceiro incluem créditos promocionais para usuários provisionados. Nesses casos, a página [Créditos de parceiro](https://docs.firecrawl.dev/pt-BR/partner-credits.md) 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](#credits-for-provisioned-accounts) 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:

```bash theme={null}
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](https://www.firecrawl.dev/app/partner-api).

## 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](https://www.firecrawl.dev/terms-of-service) 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](mailto: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](mailto: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](mailto: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

```bash cURL theme={null}
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`**

```json theme={null}
{
  "apiKey": "fc-...",
  "alreadyExisted": false
}
```

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

```json theme={null}
{
  "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](#limits) |
| `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

```bash cURL theme={null}
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`**

```json theme={null}
{
  "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

```bash cURL theme={null}
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`**

```json theme={null}
{
  "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](https://www.firecrawl.dev/app/partner-api): 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](mailto:help@firecrawl.com). Pensando em uma integração maior? Escreva para [partnerships@firecrawl.dev](mailto: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. Todos os parceiros são analisados e aprovados pela nossa equipe.

[Inscreva-se no Partner Program](https://www.firecrawl.dev/firecrawl-for-platforms/partner-program?source=docs)

Você escreve sobre o Firecrawl ou publica links para ele? Nesse caso, o [programa de afiliados](https://www.firecrawl.dev/affiliates) é a melhor opção.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.