> For the complete documentation index, see [llms.txt](https://helpdocs.ycloud.com/partner-center/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdocs.ycloud.com/partner-center/white-label-partner/he-zuo-huo-ban-ping-tai-guan-li-jie-kou/zhang-hu-guan-li-jie-kou.md).

# 账户管理接口

注意：

* 接口使用请求头 `X-API-Key` 鉴权，详见 [Authentication](https://docs.ycloud.com/reference/authentication)。
* 接口请求成功响应 HTTP 状态码 `2xx`，错误处理见 [Errors](https://docs.ycloud.com/reference/errors)。

### 创建账户

请求： POST <https://api.ycloud.com/v2/partner/managedAccounts>

请求体（数据类型 application/json）：

| 字段          | 描述                                                                                                                                |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| companyName | 【必需】账户公司名称，用户可见。最大长度 200。                                                                                                         |
| owner.email | 【必需】 用户邮箱地址。您必须为新建的账户分配一个拥有者。若该邮箱未注册，则会自动向其发送邀请邮件。若该邮箱已注册，则自动将其设置为新账户的拥有者。注意区分：账户是指一个工作空间，用户代表一个真实的人，一个账户可以由多个用户管理，一个用户也可以拥有多个账户。 |
| creditLimit | 【可选】授信额度，取值范围 0-1000000。该账户每月可消耗的金额，货币 USD。以东八区每月1日开始计算消耗额度。                                                                      |
| remark      | 【可选】账户备注，仅您可见。最大长度 1024。                                                                                                          |
| externalId  | 【可选】账户外部 ID，可用于与您的系统关联。最大长度 1024。                                                                                                 |

请求示例：

```sh
curl 'http://api.ycloud.com/v2/partner/managedAccounts' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-d '{
  "companyName": "COMPANY-NAME",
  "owner": {
    "email": "your@example.com"
  },
  "creditLimit": 100,
  "remark": "Remark!",
  "externalId": "EXTERNAL-ID"
}'
```

响应示例：

```json
{
  "id": "MANAGED-ACCOUNT-ID",
  "status": "pending",
  "companyName": "COMPANY-NAME",
  "owner": {
    "email": "your@example.com",
    "status": "pending"
  },
  "creditLimit": 100,
  "remark": "Remark!",
  "externalId": "EXTERNAL-ID",
  "createTime": "2024-07-29T09:50:00.000Z"
}
```

其中，账户状态 `status` 枚举值：

* `pending` - 待用户接受邀请成为该该账户拥有者
* `active` - 用户已接收邀请成为该账户拥有者
* `disabled` - 该账户已被禁用

注意，当请求字段 `owner.email` 指向一个已注册的用户时，该账户状态自动变为 `active` 。

用户状态 `owner.status` 枚举值：

* `pending` - 用户待注册
* `active` - 用户已注册

### 获取账户

功能描述：获取账户基本信息，以及拥有者信息、当月授信额度使用情况。

请求：GET <https://api.ycloud.com/v2/partner/managedAccounts/{accountId}>

请求示例：

```sh
curl 'http://api.ycloud.com/v2/partner/managedAccounts/MANAGED-ACCOUNT-ID' \
-H 'X-API-Key: YOUR_API_KEY'
```

响应示例：

```json
{
  "id": "MANAGED-ACCOUNT-ID",
  "status": "active",
  "companyName": "COMPANY-NAME",
  "owner": {
    "email": "your@example.com",
    "status": "active",
    "firstName": "FISRT-NAME",
    "lastName": "LAST-NAME"
  },
  "creditLimit": 100,
  "creditUsage": {
    "consumedBalance": 10,
    "frozenBalance": 20,
    "availableBalance": 70
  },
  "remark": "Remark!",
  "externalId": "EXTERNAL-ID",
  "createTime": "2024-07-29T09:50:00.000Z"
}
```

其中，`creditUsage.consumedBalance` 表示当月已计入账单的消费额度，`creditUsage.frozenBalance` 表示当月冻结额度（通常当 WhatsApp 消息已发送但未送达时会冻结一部分额度），`availableBalance` 表示当月实际可用额度，即：

`availableBalance = creditLimit - consumedBalance - frozenBalance`

### 更新账户

功能描述：更新账户基本信息、禁用或启用账户。

请求： PATCH <https://api.ycloud.com/v2/partner/managedAccounts/{accountId}>

请求体（数据类型 application/json）：

| 字段          | 描述                                                                                |
| ----------- | --------------------------------------------------------------------------------- |
| creditLimit | 【可选】授信额度，取值范围 0-1000000。该账户每月可消耗的金额，货币 USD。以东八区每月1日开始计算消耗额度。                      |
| remark      | 【可选】账户备注，仅您可见。最大长度 1024。                                                          |
| status      | 【可选】账户状态。枚举值： `disabled` - 将 `active` 状态的账户禁用。 `active` - 将 `disabled` 状态的账户重新启用。 |

请求示例：

```sh
curl -X PATCH 'http://api.ycloud.com/v2/partner/managedAccounts/MANAGED-ACCOUNT-ID
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-d '{
  "remark": "reMark",
  "creditLimit": 150,
  "status": "active"
}'
```

### 发送邀请邮件

功能描述：创建账户后会自动发送邀请邮件，若用户未收到，可调用此接口再次发送。

请求： POST <https://api.ycloud.com/v2/partner/managedAccounts/{accountId}/sendInvitation>

请求示例：

{% code title="" %}

```sh
curl -X POST 'http://api.ycloud.com/v2/partner/managedAccounts/MANAGED-ACCOUNT-ID/sendInvitation' \
-H 'X-API-Key: YOUR_API_KEY'
```

{% endcode %}

响应 HTTP 状态码 `200` 即成功。