> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-locadex-parallel-t9n-main-ydzk9zxoc20klj1uk5u1gd5b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner API

> Referência da API para parceiros do Firecrawl criarem e gerenciarem API keys para seus usuários

<div id="overview">
  ## Visão geral
</div>

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.

<Note>
  Configure a Partner API por conta própria 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, 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.
</Note>

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](https://www.firecrawl.dev/partner-program) para uma visão geral.

Algumas ofertas de parceiro incluem créditos promocionais para usuários provisionados; nesses casos, [Partner Credits](/pt-BR/partner-credits) descreve o que o usuário recebe.

<div id="base-url">
  ## URL base
</div>

```
https://integrations.firecrawl.dev
```

<div id="authentication">
  ## Autenticação
</div>

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

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

<div id="security-requirements">
  ## Requisitos de segurança
</div>

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

***

<div id="endpoints">
  ## Endpoints
</div>

<div id="create-user">
  ### Criar usuário
</div>

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

```
POST /partner/v1/accounts
```

<div id="behavior">
  #### Comportamento
</div>

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.

<div id="request">
  #### Requisição
</div>

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

<div id="response">
  #### Resposta
</div>

**`200 OK`**

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

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

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

<div id="errors">
  #### Erros
</div>

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

***

<div id="validate-api-key">
  ### Validar chave de API
</div>

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
```

<div id="important-notes">
  #### Observações importantes
</div>

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

<div id="request-2">
  #### Requisição
</div>

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

<div id="response-2">
  #### Resposta
</div>

**`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 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. |

<div id="errors-2">
  #### Erros
</div>

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

***

<div id="rotate-api-key">
  ### Rotacionar chave de API
</div>

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
```

<div id="request-3">
  #### Requisição
</div>

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

<div id="response-3">
  #### Resposta
</div>

**`200 OK`**

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

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

<div id="errors-3">
  #### Erros
</div>

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

***

<div id="get-started">
  ## Comece agora
</div>

Crie sua integração no [painel do Firecrawl](https://www.firecrawl.dev/app/partner-api): 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](mailto:help@firecrawl.com). Pensa em uma integração maior? Escreva para [partnerships@firecrawl.dev](mailto:partnerships@firecrawl.dev).