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

# 合作伙伴 API

> 供 Firecrawl 合作伙伴为其用户创建和管理 API 密钥的 API 参考

<div id="overview">
  ## 概述
</div>

Firecrawl 合作伙伴集成 API 让你的平台可以直接在自己的后端为用户创建和管理 Firecrawl API 密钥。用户无需离开你的平台即可开始使用 Firecrawl。

<Note>
  你可以在 [Firecrawl dashboard](https://www.firecrawl.dev/app/partner-api) 中自行配置合作伙伴 API。组织中的任何管理员或成员都可以创建集成：命名、选择一种配置方式、接受该方式对应的协议，然后复制合作伙伴密钥。该密钥仅显示一次。之后你可以在 Settings 中签发和吊销密钥。无需申请或审批。
</Note>

共有两种配置方式。两者开通账户的流程相同，都通过下方的接口完成；区别在于由谁为用户的使用量付费：

* **Partner API**：每个开通的账户各自保留自己的 Firecrawl 方案和计费。用户从 Free 套餐起步，直接向 Firecrawl 升级。
* **Gateway**：由你的集成创建的账户会被纳入 Gateway，因此在用户自身的额度用尽后，其符合条件的使用量将计费到你的组织。Gateway 账户仅支持 API 调用，没有自己的 dashboard 登录入口。

配置方式在创建集成时选定，之后不易更改，因此我们建议在接受协议前仔细比较两种选项。请参见[合作伙伴 API 页面](https://www.firecrawl.dev/partner-program)了解概况。

部分合作伙伴优惠会为开通的用户赠送促销额度；如有此类优惠，[合作伙伴额度](/zh/partner-credits)会说明用户具体能获得什么。

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

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

<div id="authentication">
  ## 身份验证
</div>

所有 合作伙伴集成 API 请求都必须在 `Authorization` 标头中附带您的合作伙伴密钥：

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

合作伙伴密钥与标准 Firecrawl API 密钥不同。您可以在 [Firecrawl dashboard](https://www.firecrawl.dev/app/partner-api) 的 Settings > Partner API 中创建和吊销合作伙伴密钥。

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

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

***

<div id="endpoints">
  ## 接口
</div>

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

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

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

<div id="behavior">
  #### 行为说明
</div>

采用 **合作伙伴 API** 配置方式时：

* 如果用户还没有 Firecrawl 账户，则会创建新用户和新团队。
* 如果用户已有 Firecrawl 账户，但没有与你的集成关联的团队，则会创建一个新的合作伙伴关联团队。
* 如果用户已有 Firecrawl 账户，且已有与你的集成关联的团队，则返回该已有团队。

采用 **Gateway** 配置方式时：

* 每个账户都只为你的集成创建。即使邮箱地址相同，请求也绝不会关联到已有的 Firecrawl 账户。该邮箱仅作为账户的联系地址存储，不用于查找账户。
* 对同一邮箱重复调用会返回同一个账户及其 API 密钥。

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

<div id="request">
  #### 请求
</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"}'
```

**请求体**

| 字段      | 类型     | 必填 | 描述                                     |
| ------- | ------ | -- | -------------------------------------- |
| `email` | string | 是  | 用户邮箱地址。在 Gateway 配置方式下，它会被存储为该账户的联系地址。 |

<div id="response">
  #### 响应
</div>

**`200 OK`**

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

在 Gateway 配置方式下，响应中还会包含注册 status：

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

| 字段               | 类型      | 描述                                                                     |
| ---------------- | ------- | ---------------------------------------------------------------------- |
| `apiKey`         | string  | 该用户所属合作伙伴关联团队的 Firecrawl API 密钥                                        |
| `alreadyExisted` | boolean | 如果你的 集成 已为该邮箱开通过账户，则为 `true`。它并不说明该邮箱是否存在于 Firecrawl 的其他地方。            |
| `gatewayStatus`  | string  | 仅适用于Gateway 集成。创建账户的那次调用返回 `enrolled`，对同一邮箱的重复调用返回 `already_enrolled`。 |

<div id="errors">
  #### 错误
</div>

| 状态    | 描述                            |
| ----- | ----------------------------- |
| `400` | 请求错误 - `email` 缺失或格式不正确       |
| `401` | 未授权 - 合作伙伴密钥不正确或无效            |
| `500` | 内部服务器错误 - 这些错误会由 Firecrawl 监控 |

***

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

验证 Firecrawl API 密钥，并返回关联的团队名称和用户邮箱地址。只有通过此合作伙伴集成创建的 API 密钥才会被视为有效。

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

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

* Firecrawl API 密钥不设权限，也不会过期。
* 用户可以随时手动删除 API 密钥。
* 已删除的 API 密钥不会进行软删除。Firecrawl 无法区分某个密钥是已被删除，还是从未存在过。

<div id="request-2">
  #### 请求
</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-..."}'
```

**请求体**

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

<div id="response-2">
  #### 响应
</div>

**`200 OK`**

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

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

<div id="errors-2">
  #### 错误
</div>

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

***

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

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

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

<div id="request-3">
  #### 请求
</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-..."}'
```

**请求体**

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

<div id="response-3">
  #### 响应
</div>

**`200 OK`**

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

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

<div id="errors-3">
  #### 错误
</div>

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

***

<div id="get-started">
  ## 开始使用
</div>

在 [Firecrawl Dashboard](https://www.firecrawl.dev/app/partner-api) 中创建你的集成：登录后选择 Partner API 或 Gateway，接受协议，然后复制你的合作伙伴密钥。该配置方式在完成后不易更改，请在接受协议前确认你的选择。之后即可从你的服务器调用上述接口。对配置方式有疑问？欢迎联系 [help@firecrawl.com](mailto:help@firecrawl.com)。想做更大规模的集成？欢迎联系 [partnerships@firecrawl.dev](mailto:partnerships@firecrawl.dev)。