htsy-skill/htsy/references/api-account.md

# 账号、用户、席位与角色

## 目录

- [登录与注册命令](#登录与注册命令)
- [账号管理](#账号管理)
- [用户管理](#用户管理)
- [席位管理](#席位管理)
- [角色管理](#角色管理)
- [订单与余额](#订单与余额)
- [通知与操作记录](#通知与操作记录)
- [常用示例](#常用示例)

## 登录与注册命令

优先使用 CLI 封装命令：

```bash
htsy-cli login --username USER --password PASS
htsy-cli account-login --phone PHONE --code CODE
htsy-cli send-code --phone PHONE --scene register
htsy-cli register --username PHONE --password PASS --sms-code CODE
```

验证码 `scene` 常用值：`register` 注册、`resetPwd` 重置密码、`login` 登录、`bind` 绑定手机号。

## 账号管理

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 账号信息 | `POST /api/account/info` | `{}` | `id`(int64)；`phone`(string)；`main`(bool，是否是主账号)；`cfg`(CfgItem，账号配置)；`clientType`(string，客户端类型)；`clientDownloadUrl`(string，客户端下载地址)；`isDistributor`(bool，是否是渠道商)；`agreeTerms`(bool，是否同意条款 false) |
| 登录 | `POST /api/account/login/in` | `phone`(string, 必填)；`password`(string, 可选，密码登录)；`code`(string, 可选，验证码登录) | `token`(string) |
| 设置账号配置 | `POST /api/account/cfg/set` | `singleDel`(bool, 必填，false 手动 true 自动)；`singleCronNum`(int64, 必填，定时单删的好友上限 默认全部删除)；`singleDelEvent`(bool, 必填，false 不执行， true执行)；`singleBlacklistDel`(bool, 必填，被客户加入黑名单 是否定时删除 false 手动， true 自动)；`singleBlacklistNum`(int64, 必填，定时删除被客户加入黑名单的客户上线 默认全部删除)；`singleBlacklistEvent`(bool, 必填，被客户加入黑名单时删除客户 false 不执行， true执行)；`botIds`(repeated int64, 可选，生效的微号id)；`botRangeType`(string, 可选，all 所有 specify 指定)；`isSendMsg`(bool, 可选，删除前是否发送消息)；`messageList`(repeated Message, 可选，消息列表)；`schedule`(Schedule, 可选，删除时间)；`frequency`(Frequency, 可选，频率设置)；`isSendFriendApply`(bool, 可选，删除前是否发送好友申请)；`verifyContent`(string, 可选，好友申请的文本)；`qwQueueCfg`(QueueCfg, 可选，企微队列配置)；`wxQueueCfg`(QueueCfg, 可选，企微队列配置)；`localBotSyncTagCfg`(LocalBotSyncTagCfg, 可选，本地微号同步标签配置) | 空对象或无业务数据 |
| 检查这个手机号是否属于海豚账号 | `POST /api/account/check/phone` | `phone`(string, 可选)；`num`(int64, 可选)；`botType`(int32, 可选)；`codeType`(int32, 可选) | `flag`(bool)；`accountId`(int64)；`darkToken`(string)；`price`(float) |
| 账号级白名单配置详情 | `POST /api/account/whiteList/info` | `{}` | `groupIds`(repeated int64，个微白名单群) |
| 账号级白名单配置更新 | `POST /api/account/whiteList/update` | `groupIds`(repeated int64, 必填，个微白名单群) | 空对象或无业务数据 |
| 资源包列表 | `POST /api/account/resource/list` | `{}` | `list`(repeated ResourcePackageInfoReply，资源包类型) |
| 分享注册链接 | `POST /api/account/shareRegisterLink` | `{}` | `link`(string) |
| 同意条款 | `POST /api/account/agreeTerms` | `agree`(bool, 可选) | 空对象或无业务数据 |
| 资源包充值 | `POST /api/account/resource/order/create` | `num`(int64, 必填，数量)；`pkgId`(int64, 必填，资源包id)；`payType`(int32, 必填，支付类型 1 余额 2 微信支付) | `qrCode`(string，微信支付的时候存在 二维码)；`orderId`(string，订单id)；`price`(double，实付价)；`originPrice`(double，原价)；`payType`(int32，支付类型 1 余额 2 微信支付)；`totalAmount`(double，到账总价)；`tables`(google.protobuf.Value，表格名字) |
| 资源包定价 | `POST /api/account/resource/prices` | `{}` | `riskList`(repeated ResourcePackagePrices，风控指数资源包)；`contentSecurity`(repeated ResourcePackagePrices，内容安全资源包) |
| 资源包对公购买 | `POST /api/account/resource/buy` | `num`(int64, 必填，数量)；`pkgId`(int64, 必填，资源包id)；`accountId`(int64, 必填，accountId)；`auth`(string, 必填) | 空对象或无业务数据 |


## 用户管理

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 用户信息 | `POST /api/account/user/info` | `{}` | `accountInfo`(AccountInfo，账号信息)；`nickname`(string，昵称)；`avatar`(string，头像)；`wxBotNum`(int64，个微机器人数量)；`username`(string，用户名)；`mainAccount`(bool，是否是主账号)；`bindGzh`(bool，是否绑定公众号)；`id`(int64，子账号id)；`qwBotNum`(int64，企微机器人数量)；`isSetPassword`(bool，是否设置了密码)；... |
| 创建子账号 | `POST /api/account/user/create` | `username`(string, 必填，用户名)；`password`(string, 必填，密码)；`nickname`(string, 可选，昵称)；`avatar`(string, 可选，头像)；`roleId`(int64, 可选，角色id) | 空对象或无业务数据 |
| 删除子账号 | `POST /api/account/user/delete` | `id`(int64, 必填，子账号id) | 空对象或无业务数据 |
| 用户账号登录 | `POST /api/account/user/login/in` | `username`(string, 必填，子账号用户名 xxx@主账号手机号)；`password`(string, 必填，密码) | `token`(string，token) |
| 用户账号登出 | `POST /api/account/user/login/logout` | `{}` | 空对象或无业务数据 |
| 子账号列表 | `POST /api/account/user/list` | `page`(int64, 必填，page)；`pageSize`(int64, 必填，pageSize)；`roleId`(int64, 可选，角色的ID) | `list`(repeated HttpUserInfo，组内群列表)；`page`(int64，page)；`pageSize`(int64，pageSize)；`total`(int64，total)；`last`(bool，last) |
| 修改密码 | `POST /api/account/user/password/modify` | `oldPassword`(string, 可选，旧密码)；`newPassword`(string, 可选)；`code`(string, 可选，验证码修改)；`phone`(string, 可选，获取验证码的手机号) | 空对象或无业务数据 |
| 获取登录二维码 | `POST /api/account/user/login/qrCode` | `{}` | `link`(string，二维码链接)；`code`(string，回调code) |
| 扫码回调 | `POST /api/account/user/login/scan/callback` | `code`(string, 必填，回调code) | `success`(bool，是否成功)；`list`(repeated AccountUser，多账号列表) |
| 选择需要登录的账号登录 | `POST /api/account/user/login/scan/loginIn` | `code`(string, 必填，回调code)；`id`(int64, 必填，userid) | `token`(string，token) |
| 查看账号列表 | `POST /api/account/user/accountUserList` | `{}` | `list`(repeated AccountUser，多账号列表) |
| 切换登录账号 | `POST /api/account/user/switchLogin` | `id`(int64, 必填，子账号id) | `token`(string，token) |
| 绑定公众号 | `POST /api/account/user/bind/gzh` | `{}` | `link`(string，二维码链接)；`code`(string，回调code) |
| 解绑公众号 | `POST /api/account/user/unBind/gzh` | `{}` | 空对象或无业务数据 |
| 修改昵称 | `POST /api/account/user/modify/nickname` | `nickname`(string, 必填，昵称)；`userId`(int64, 可选，子账号id) | 空对象或无业务数据 |
| 修改头像 | `POST /api/account/user/modify/avatar` | `avatar`(string, 必填，头像)；`userId`(int64, 可选，子账号id) | 空对象或无业务数据 |
| 修改子账号密码 | `POST /api/account/user/modify/userPassword` | `userId`(int64, 必填，子账号id)；`password`(string, 必填，密码) | 空对象或无业务数据 |
| 用户注册 | `POST /api/account/user/register` | `username`(string, 必填，用户名，也是手机号码)；`password`(string, 必填，密码)；`smsCode`(string, 必填，短信验证码)；`inviteToken`(string, 可选，注册码) | `token`(string，token) |
| 发送短信验证码 | `POST /api/account/user/phone/sendCode` | `phone`(string, 必填，手机号码)；`scene`(string, 必填，场景 注册 register 修改密码 resetPwd 登录 login 绑定手机号 bind) | 空对象或无业务数据 |
| 设置密码 | `POST /api/account/user/setPassword` | `password`(string, 必填，设置密码) | 空对象或无业务数据 |
| 关联手机号码 | `POST /api/account/bindPhone` | `phone`(string, 必填，手机号码)；`smsCode`(string, 必填，短信验证码) | 空对象或无业务数据 |
| 获取客服子账号 | `POST /api/account/customer/list` | `{}` | `list`(repeated HttpUserInfo，组内群列表) |


## 席位管理

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 席位管理-列表 | `POST /api/account/bot/list` | `page`(int64, 可选，分页page)；`pageSize`(int64, 可选，分页page size)；`statusList`(repeated int32, 可选，席位状态)；`botStatusList`(repeated int64, 可选，机器人状态)；`name`(string, 可选，名字 与授权码 互斥)；`botKey`(string, 可选，授权码)；`botType`(int32, 可选，席位类型 1个微 2企微)；`botId`(int64, 可选，机器人id)；`codeType`(int32, 可选，授权码类型 1 客户端 2 协议)；`userId`(int64, 可选，成员id)；`sort`(int32, 必填，0 默认排序 1 过期时间升序 2 过期时间降序)；`botFunctionType`(int32, 可选，1 全功能 2 发单版)；`tags`(repeated int64, 可选，按标签筛选)；`clientVersion`(string, 可选，客户端版本 4.1.12 和 4.1.16)；`clientPlatform`(int32, 可选，客户端平台类型 1 mac 2 pc 3 ipad) | `list`(repeated BotInfo，列表)；`page`(int64)；`pageSize`(int64)；`total`(int64)；`last`(bool) |
| 席位管理-临期列表(30天) | `POST /api/account/bot/expiryList` | `page`(int64, 可选，分页page)；`pageSize`(int64, 可选，分页page size)；`botType`(int32, 可选，席位类型 1个微 2企微)；`codeType`(int32, 可选，授权码类型 1 客户端 2 协议)；`sort`(int32, 必填，0 默认排序 1 过期时间升序 2 过期时间降序) | `list`(repeated BotInfo，列表)；`page`(int64)；`pageSize`(int64)；`total`(int64)；`last`(bool) |
| 席位管理-解绑 | `POST /api/account/bot/unbind` | `id`(int64, 可选) | 空对象或无业务数据 |
| 席位管理-获取席位的登录配置 | `POST /api/account/bot/loginConf/byBotKey` | `botKey`(string, 必填，席位码)；`type`(int32, 必填，获取配置的类型， 0 登录 1 升级) | `botKey`(string，席位码)；`botType`(int32，微号类型)；`codeType`(int32，席位类型)；`clientVersion`(string，客户端版本 4.1.12 和 4.1.16)；`clientPlatform`(int32，客户端平台类型 1 mac 2 pc 3 ipad)；`nickname`(string，微号昵称)；`avatar`(string，微号头像)；`loginConf`(repeated BotCodeLoginConf，登录配置)；`lasLoginType`(int64，上次登录方式 0 直接扫码 2 酷班app 3 其他登录方式) |
| 批量设置成员微号范围 | `POST /api/account/bot/setBotPermission` | `userId`(int64, 必填，子账号的id)；`wxBotList`(repeated int64, 可选，个微机器人列表 botid)；`qwBotList`(repeated int64, 可选，企微机器人列表 botid) | 空对象或无业务数据 |
| 批量设置成员席位范围 | `POST /api/account/bot/setBotKey` | `userId`(int64, 必填，子账号的id)；`keyIdList`(repeated int64, 可选，席位ids) | 空对象或无业务数据 |
| 席位管理-购买 | `POST /api/account/bot/buyBot/create` | `num`(int64, 必填，数量)；`botType`(int32, 必填，1 个微 2企微)；`codeType`(int32, 必填，1 本地 2 协议版)；`payType`(int32, 必填，支付类型 1 余额 2 微信支付)；`botFunctionType`(int32, 必填，1 全功能 2 发单 3 群发 4 接粉)；`payMode`(string, 必填，年付 year 月付 month)；`expireNum`(int64, 必填，1 一年/一个月 2.....) | `qrCode`(string，微信支付的时候存在 二维码)；`orderId`(string，订单id)；`price`(double，实付价)；`originPrice`(double，原价)；`payType`(int32，支付类型 1 余额 2 微信支付)；`totalAmount`(double，到账总价)；`tables`(google.protobuf.Value，表格名字) |
| 席位管理-续费 | `POST /api/account/bot/renew/create` | `ids`(repeated int64, 必填，席位的ids)；`payType`(int32, 必填，支付类型 1 余额 2 微信支付)；`payMode`(string, 必填，年付 year 月付 month)；`expireNum`(int64, 必填，1 一年/一个月 2.....) | `qrCode`(string，微信支付的时候存在 二维码)；`orderId`(string，订单id)；`price`(double，实付价)；`originPrice`(double，原价)；`payType`(int32，支付类型 1 余额 2 微信支付)；`totalAmount`(double，到账总价)；`tables`(google.protobuf.Value，表格名字) |
| 席位管理-删除 | `POST /api/account/bot/del` | `ids`(repeated int64, 必填，席位的ids) | 空对象或无业务数据 |
| 席位管理-席位功能类型变更 | `POST /api/account/bot/botFunctionType/change` | `botKeyIds`(repeated int64, 必填，需要降级的席位码Id)；`payType`(int32, 必填，支付类型 1 余额 2 微信支付)；`botFuncType`(int32, 必填，类型：1 全功能 2 发单) | `qrCode`(string，微信支付的时候存在 二维码)；`orderId`(string，订单id)；`price`(double，实付价)；`originPrice`(double，原价)；`payType`(int32，支付类型 1 余额 2 微信支付)；`totalAmount`(double，到账总价)；`tables`(google.protobuf.Value，表格名字) |
| 登录h5链接获取 | `POST /api/account/bot/h5Link/get` | `botKeyId`(int64, 必填，席位码id) | `link`(string，分享给号主登录的h5链接) |
| 登录h5链接获取登录信息 | `POST /api/account/bot/h5Link/info` | `botKey`(string, 必填，席位码)；`botType`(int32, 必填，微号类型)；`token`(string, 必填，授权token) | `nickname`(string，昵称)；`avatar`(string，头像)；`botType`(int32，微号类型)；`clientVersion`(string，客户端版本 4.1.12 和 4.1.16)；`clientPlatform`(int32，客户端平台类型 1 mac 2 pc 3 ipad) |
| 席位标签-创建标签 | `POST /api/account/bot/tag/create` | `tagName`(string, 可选) | `id`(int64) |
| 席位标签-创建信息更新 | `POST /api/account/bot/tag/update` | `id`(int64, 可选)；`tagName`(string, 可选)；`num`(int64, 可选，席位数量) | 空对象或无业务数据 |
| 席位标签-删除标签 | `POST /api/account/bot/tag/del` | `id`(int64, 可选) | 空对象或无业务数据 |
| 席位标签-标签列表 | `POST /api/account/bot/tag/list` | `page`(int64, 可选，分页page)；`pageSize`(int64, 可选，分页page size) | `list`(repeated AccountBotTagItem，列表)；`page`(int64)；`pageSize`(int64)；`total`(int64)；`last`(bool) |
| 席位标签-给席位添加标签或者删除标签 | `POST /api/account/bot/tag/addTagOrDelTag` | `accountBotTagId`(int64, 可选)；`accountBotId`(int64, 可选)；`isDel`(bool, 可选) | 空对象或无业务数据 |


## 角色管理

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 角色列表 | `POST /api/account/role/list` | `{}` | `list`(repeated RoleItem，角色列表) |
| 成员设置角色 | `POST /api/account/role/user/set` | `userIds`(repeated int64, 必填，成员的id)；`roleId`(int64, 必填，角色id) | 空对象或无业务数据 |
| 创建自定义角色 | `POST /api/account/role/add` | `name`(string, 必填，角色名字)；`permissionList`(repeated int64, 必填，权限列表)；`specialPermissionList`(repeated SpecialPermissionData, 必填，高级权限列表) | 空对象或无业务数据 |
| 修改自定义角色 | `POST /api/account/role/update` | `id`(int64, 必填，角色id)；`name`(string, 必填，角色名字)；`permissionList`(repeated int64, 必填，权限列表)；`specialPermissionList`(repeated SpecialPermissionData, 必填，高级权限列表) | 空对象或无业务数据 |
| 删除自定义角色 | `POST /api/account/role/del` | `id`(int64, 必填，角色id) | 空对象或无业务数据 |
| 全部权限列表 | `POST /api/account/role/all_permission` | `{}` | `list`(repeated PermissionItem，权限列表)；`specialList`(repeated SpecialPermissionItem，特殊权限列表) |
| 角色的权限列表 | `POST /api/account/role/permission/list` | `roleId`(int64, 必填，角色id) | `list`(repeated PermissionItem，权限列表)；`specialList`(repeated SpecialPermissionItem，特殊权限列表) |
| 角色包含的成员 | `POST /api/account/role/user/list` | `roleId`(int64, 必填，角色id) | `list`(repeated RoleUserItem，角色成员) |


## 订单与余额

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 手机端订单详情 | `POST /api/account/order/detail` | `orderId`(string, 必填，订单id) | `name`(string，名字)；`price`(double，实付价)；`originPrice`(double，原价)；`orderId`(string，订单号)；`status`(string，待支付 wait 支付成功 success 支付失败 fail) |
| 用余额完成订单 | `POST /api/account/order/complete/byBalance` | `orderId`(string, 必填，订单id) | 空对象或无业务数据 |
| 用订单创建微信支付订单 | `POST /api/account/order/complete/byWxPay` | `orderId`(string, 必填，订单id)；`openid`(string, 必填，openid) | `payInfo`(google.protobuf.Value，微信支付信息) |
| 账号金额明细 | `POST /api/account/order/record/list` | `page`(int64, 可选)；`pageSize`(int64, 可选)；`payType`(string, 可选，支付类型：余额：balance 微信：wx)；`incomeOrExpense`(int64, 可选，0:全部 1 收入 2 支出) | `list`(repeated RecordItem)；`total`(int64)；`last`(bool)；`page`(int64)；`pageSize`(int64) |
| 各个产品的价格 | `POST /api/account/product/prices` | `{}` | `list`(repeated Product，全功能 1 个微协议 2 个微客户端 3 企微协议 4 企微客户端 发单 5 企微协议 6企微客户端) |
| 充值余额 | `POST /api/account/recharge/balance` | `accountId`(int64, 可选)；`auth`(string, 可选)；`money`(double, 可选) | 空对象或无业务数据 |
| 代理商-转账 | `POST /api/account/transfer/balance` | `phone`(string, 可选)；`money`(double, 可选) | 空对象或无业务数据 |
| 使用微信支付充值余额 | `POST /api/account/recharge/wxPay` | `money`(double, 可选) | `qrCode`(string，微信支付的时候存在 二维码)；`orderId`(string，订单id)；`price`(double，实付价)；`originPrice`(double，原价)；`payType`(int32，支付类型 1 余额 2 微信支付)；`totalAmount`(double，到账总价)；`tables`(google.protobuf.Value，表格名字) |


## 通知与操作记录

| 目标 | 接口 | 请求字段 | 常用返回字段 |
| --- | --- | --- | --- |
| 用户操作记录 | `POST /api/account/operationRecord/list` | `page`(int64, 可选，分页page)；`pageSize`(int64, 可选，分页pagesize)；`userIds`(repeated int64, 可选，操作人)；`startTime`(int64, 可选，操作人)；`endTime`(int64, 可选，操作人)；`ip`(string, 可选，ip搜索)；`module`(string, 可选，操作模块)；`action`(string, 可选，操作动作) | `list`(repeated RecordItem，日志列表)；`page`(int64，分页page)；`pageSize`(int64，分页pagesize)；`total`(int64，总数)；`last`(bool，是否最后) |
| 模块列表 | `POST /api/account/operationRecord/modules` | `{}` | `list`(repeated ModuleItem，模块列表) |
| 操作动作列表 | `POST /api/account/operationRecord/actions` | `module`(string, 必填，模块) | `list`(repeated ActionItem，动作列表) |


## 常用示例

```bash
htsy-cli call /api/account/info -d '{}'
htsy-cli call /api/account/user/list -d '{"page":1,"pageSize":20}'
htsy-cli call /api/account/bot/list -d '{"page":1,"pageSize":20,"botType":1}'
htsy-cli call /api/account/role/list -d '{}'
```