> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agencyhandy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AgencyHandy API：身份验证与入门指南

> 生成 API 密钥、查找您的公司 ID，并通过本快速设置指南开始基于 AgencyHandy REST API 构建集成。

AgencyHandy API 允许您从任何外部系统或脚本自动化潜在客户创建、客户管理、订单更新等操作。每个请求都通过您从工作区设置中生成的 API 密钥进行身份验证。本指南将引导您获取凭据并完成第一次 API 调用。

<Note>
  您必须是 AgencyHandy 工作区的**超级管理员**或**管理员**才能生成 API 密钥。
</Note>

## 基础 URL

所有 API 请求均发送至：

```
https://api.agencyhandy.com
```

在 API 文档中的所有示例请求中，请将 `{{URL}}` 替换为此基础 URL。

## 第一步：生成 API 密钥

<Steps>
  <Step title="打开工作区配置">
    前往您的工作区设置：

    ```
    {{workspaceUrl}}/workspace-config?tab=api-key
    ```

    这将打开工作区配置中的 **API 密钥** 选项卡。
  </Step>

  <Step title="生成并复制您的 API 密钥">
    点击 **生成**（若已有密钥则点击 **重新生成**）。复制 API 密钥并安全存储 — 请将其视为密码。离开页面后，AgencyHandy 将不再显示该密钥。
  </Step>
</Steps>

<Warning>
  重新生成 API 密钥会立即使之前的密钥失效。任何使用旧密钥的现有集成将停止工作，直到您用新密钥更新它们。
</Warning>

## 第二步：获取您的公司 ID

大多数 API 端点需要一个 `companyid` 标头来标识请求目标工作区。使用以下端点获取您的公司 ID。

### 端点

```
GET {{URL}}/accounts/companies
```

### 标头

| 标头          | 值         |
| ----------- | --------- |
| `x-api-key` | 您的 API 密钥 |

### 示例请求

```bash cURL theme={null}
curl --request GET "https://api.agencyhandy.com/accounts/companies" \
  --header "x-api-key: <YOUR_API_KEY>"
```

### 示例响应

```json theme={null}
{
  "message": "Companies associated with API token.",
  "companies": [
    {
      "_id": "6525994184e9ddd79853450e",
      "name": "onethread123",
      "logo": "",
      "extraSmallLogo": "",
      "largeLogo": ""
    }
  ]
}
```

<Steps>
  <Step title="找到您的公司 ID">
    在响应中，找到 `companies` 数组内的 `_id` 字段。这就是您的**公司 ID**。

    ```javascript theme={null}
    const companyId = response.companies[0]._id;
    // e.g. "6525994184e9ddd79853450e"
    ```
  </Step>

  <Step title="存储公司 ID">
    保存公司 ID 以便在所有后续 API 请求中使用。您需要将其作为 `companyid` 标头传递：

    | 标头          | 值         |
    | ----------- | --------- |
    | `x-api-key` | 您的 API 密钥 |
    | `companyid` | 您的公司 ID   |
  </Step>
</Steps>

## 身份验证摘要

每个经过身份验证的 API 请求至少需要：

```
x-api-key: <YOUR_API_KEY>
companyid: <YOUR_COMPANY_ID>
```

获得 API 密钥和公司 ID 后，您就可以使用 AgencyHandy API 的其余功能了。请继续查看以下端点指南。