# 账户管理接口

注意：

* 接口使用请求头 `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` 即成功。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET 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?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.