账户管理接口

管理您站点的账户。

注意：

接口使用请求头 X-API-Key 鉴权，详见 Authentication。
接口请求成功响应 HTTP 状态码 2xx，错误处理见 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。

请求示例：

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": "[email protected]"
  },
  "creditLimit": 100,
  "remark": "Remark!",
  "externalId": "EXTERNAL-ID"
}'

响应示例：

{
  "id": "MANAGED-ACCOUNT-ID",
  "status": "pending",
  "companyName": "COMPANY-NAME",
  "owner": {
    "email": "[email protected]",
    "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}

请求示例：

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

响应示例：

{
  "id": "MANAGED-ACCOUNT-ID",
  "status": "active",
  "companyName": "COMPANY-NAME",
  "owner": {
    "email": "[email protected]",
    "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 状态的账户重新启用。

请求示例：

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

请求示例：

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

响应 HTTP 状态码 200 即成功。

Last updated 11 months ago