> ## 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 for Platforms

> API 参考：供平台为其用户创建和管理 Firecrawl API 密钥

<h2 id="overview">
  概述
</h2>

借助 Firecrawl for Platforms，你的平台可以直接在自己的后端为用户创建和管理 Firecrawl API 密钥。用户无需离开你的平台即可开始使用 Firecrawl。

<Note>
  你可以在 [Firecrawl Dashboard](https://www.firecrawl.dev/app/partner-api) 中自行设置 Firecrawl for Platforms。组织中的任何管理员或成员都可以创建集成：为其命名、选择集成类型、接受该类型对应的协议，然后复制平台密钥。该密钥仅显示一次。之后你可以在 Settings 中生成和撤销密钥。无需提交申请，也无需等待审批。
</Note>

集成分为两种类型。两者开通账户的方式相同，都是使用同一个平台密钥调用下方的接口；区别在于由谁为用户的使用量付费：

* **Standard**：由你的用户向 Firecrawl 付费。每个开通的账户各自保留 Firecrawl 方案和计费，初始为 Free 套餐，并直接在 Firecrawl 升级。
* **Gateway**：由你的组织为用户买单。通过你的集成创建的账户会加入 Gateway，用户自己的额度用完后，其符合条件的使用量将计入你的组织账单。请参见下方的 [Gateway](#gateway)。

集成类型需在创建集成时选定，之后不易更改，因此建议在接受协议前仔细比较这两种类型。概览请参见 [Firecrawl for Platforms 页面](https://www.firecrawl.dev/firecrawl-for-platforms)。

部分合作伙伴优惠会为开通的用户提供促销额度；如有，请参见 [Partner Credits](/zh/partner-credits) 了解用户可获得的具体内容。

<h3 id="gateway">
  Gateway
</h3>

Gateway 是一种集成类型，而非独立的 API，使用的平台密钥和接口均保持不变。Gateway 集成的不同之处如下：

* 账户专为你的集成创建，仅支持 API 访问，不提供独立的 Dashboard 登录。即使邮箱与某个现有 Firecrawl 账户相同，请求也不会关联到该账户。
* 优先消耗用户自己的额度。超出部分中符合条件的用量将计入你的组织账单。
* `POST /partner/v1/accounts` 的响应中包含 `gatewayStatus` 字段。
* 集成在创建时即接受 Gateway 版本的协议。

<h2 id="base-url">
  基础 URL
</h2>

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

<h2 id="authentication">
  身份验证
</h2>

所有 Platforms API 请求都需要在 `Authorization` 请求头中携带你的平台密钥：

```bash theme={null}
Authorization: Bearer <platform key>
```

平台密钥与普通的 Firecrawl API 密钥不同。你可以在 [Firecrawl Dashboard](https://www.firecrawl.dev/app/partner-api) 的 Settings > Firecrawl for Platforms 中创建和撤销平台密钥。

<h2 id="security-requirements">
  安全要求
</h2>

* **仅限服务器端**：平台密钥只能在服务器端代码中使用。切勿在前端代码、客户端 JavaScript 或移动应用中暴露平台密钥。
* **服务条款**：在调用 `POST /partner/v1/accounts` 之前，您的平台必须提示用户接受 Firecrawl 的[服务条款](https://www.firecrawl.dev/terms-of-service)。

***

<h2 id="endpoints">
  接口
</h2>

<h3 id="create-user">
  创建用户
</h3>

为你的某个用户 (以电子邮件地址标识) 开通 Firecrawl 账户，并返回该账户的 API 密钥。

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

<h4 id="behavior">
  行为
</h4>

对于 **Standard** 集成：

* 如果用户尚无 Firecrawl 账户，将创建新用户和新团队。
* 如果用户已有 Firecrawl 账户，但尚无与你的集成关联的团队，将创建一个与你的集成关联的新团队。
* 如果用户已有 Firecrawl 账户，且已有与你的集成关联的团队，则返回现有团队。

对于 **Gateway** 集成：

* 所有账户均专为你的集成创建。请求绝不会关联到已有的 Firecrawl 账户，即使电子邮件地址与某个现有账户相同也是如此。电子邮件地址仅作为账户的联系地址存储，不会用于查找账户。
* 使用同一电子邮件地址重复调用时，将返回同一个账户及其 API 密钥。

如果你的集成包含促销额度，这些额度仅在首次创建账户时发放一次。

<h4 id="request">
  请求
</h4>

```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"}'
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
| - | - | - | - |
| `email` | string | 是 | 用户的电子邮件地址。对于 Gateway 集成，该地址会存储为账户的联系地址。 |

<h4 id="response">
  响应
</h4>

**`200 OK`**

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

对于 Gateway 集成，响应中还会包含注册状态：

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

| 字段 | 类型 | 描述 |
| - | - | - |
| `apiKey` | string | 你的集成为该用户开通的团队对应的 Firecrawl API 密钥 |
| `alreadyExisted` | boolean | 若你的集成此前已为该邮箱开通过账户，则为 `true`。该字段并不反映该邮箱是否已存在于 Firecrawl 的其他位置。 |
| `gatewayStatus` | string | 仅适用于 Gateway 集成。创建账户的那次调用返回 `enrolled`，之后针对同一邮箱的重复调用返回 `already_enrolled`。 |

<h4 id="errors">
  错误
</h4>

| 状态 | 描述 |
| - | - |
| `400` | 请求错误 - `email` 缺失或格式不正确 |
| `401` | 未授权 - 平台密钥错误或无效 |
| `500` | 内部服务器错误 - Firecrawl 会监控此类错误 |

***

<h3 id="validate-api-key">
  验证 API 密钥
</h3>

验证 Firecrawl API 密钥，并返回其关联的团队名称和用户电子邮件地址。仅当 API 密钥是通过您的集成创建时，才会返回有效结果。

```
POST /partner/v1/api-keys/validate
```

<h4 id="important-notes">
  重要说明
</h4>

* Firecrawl API 密钥不设权限，也没有过期时间。
* 用户可以随时手动删除 API 密钥。
* 删除 API 密钥并非软删除。Firecrawl 无法区分已删除的密钥与从未存在过的密钥。

<h4 id="request-2">
  请求
</h4>

```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-..."}'
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
| - | - | - | - |
| `apiKey` | string | 是 | 待验证的 API 密钥 |

<h4 id="response-2">
  响应
</h4>

**`200 OK`**

```json theme={null}
{
  "teamName": "Example Team",
  "email": "user@example.com"
}
```

| 字段 | 类型 | 描述 |
| - | - | - |
| `teamName` | string | 与此 API 密钥关联的团队名称 |
| `email` | string | 开通该账户时使用的邮箱。对于 Gateway 账户，该值为您提供的联系邮箱。 |

<h4 id="errors-2">
  错误
</h4>

| 状态 | 描述 |
| - | - |
| `400` | 请求错误 - API 密钥格式不正确 |
| `401` | 未授权 - 平台密钥不正确或无效 |
| `404` | 无法识别 API 密钥 - 该密钥不存在，或并非通过您的集成创建 |
| `500` | 内部服务器错误 - Firecrawl 会监控此类错误 |

***

<h3 id="rotate-api-key">
  轮换 API 密钥
</h3>

删除现有的 Firecrawl API 密钥，并为同一用户和团队创建新的密钥。

```
POST /partner/v1/api-keys/rotate
```

<h4 id="request-3">
  请求
</h4>

```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-..."}'
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
| - | - | - | - |
| `apiKey` | string | 是 | 要删除并替换的 API 密钥 |

<h4 id="response-3">
  响应
</h4>

**`200 OK`**

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

| 字段 | 类型 | 描述 |
| - | - | - |
| `apiKey` | string | 新创建的 API 密钥 |

<h4 id="errors-3">
  错误
</h4>

| 状态 | 描述 |
| - | - |
| `401` | 未授权 - 平台密钥不正确或无效 |
| `404` | 无法识别 API 密钥 - 该密钥不存在，或并非通过你的集成创建 |
| `500` | 内部服务器错误 - Firecrawl 会监控此类错误 |

***

<h2 id="get-started">
  快速开始
</h2>

在 [Firecrawl Dashboard](https://www.firecrawl.dev/app/partner-api) 中创建您的集成：登录后选择 Standard 或 Gateway，接受协议，然后复制您的平台密钥。集成类型创建后不便更改，请在接受协议前确认您的选择。随后，从您的服务器调用上述接口即可。对配置方式有疑问？请发送邮件至 [help@firecrawl.com](mailto:help@firecrawl.com)。如有更大规模的集成计划，请发送邮件至 [partnerships@firecrawl.dev](mailto:partnerships@firecrawl.dev)。