open-im-server-deploy/docs/client-api.md

# OpenIM 客户端接口文档

本文档用于前端开发人员对接 OpenIM 服务器 API 接口。

## 目录

- [基础说明](#基础说明)
- [认证接口](#认证接口)
- [用户接口](#用户接口)
- [好友接口](#好友接口)
- [群组接口](#群组接口)
- [消息接口](#消息接口)
- [会话接口](#会话接口)
- [第三方服务接口](#第三方服务接口)
- [红包接口](#红包接口)
- [会议接口](#会议接口)
- [钱包接口](#钱包接口)
- [错误码说明](#错误码说明)

---

## 基础说明

### 请求格式

- **请求方法**: 所有接口均使用 `POST` 方法（除特殊说明外）
- **Content-Type**: `application/json`
- **请求头**: 需要在请求头中携带 `token` 进行身份验证（除白名单接口外）

```http
POST /api/user/get_users_info
Content-Type: application/json
token: your_token_here
```

### 响应格式

所有接口统一返回以下格式：

```json
{
  "errCode": 0,        // 错误码，0表示成功
  "errMsg": "",        // 错误消息
  "errDlt": "",        // 错误详情
  "data": {}           // 响应数据，具体结构见各接口说明
}
```

### 认证说明

- 大部分接口需要在请求头中携带 `token`
- 白名单接口（无需token）：
  - `/auth/get_admin_token` - 获取管理员token
  - `/auth/parse_token` - 解析token

### 基础URL

根据部署环境配置，例如：
- 开发环境: `http://localhost:10002`
- 生产环境: `https://your-domain.com`

---

## 认证接口

### 1. 获取用户Token

**接口地址**: `POST /auth/get_user_token`

**接口描述**: 用户登录时获取token

**请求参数**:
```json
{
  "secret": "string",           // 密钥（必填）
  "userID": "string",           // 用户ID（必填）
  "platform": 1                 // 平台ID（必填）：1-iOS, 2-Android, 3-Windows, 4-OSX, 5-Web, 6-小程序
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expireTimeSeconds": 604800
  }
}
```

### 2. 解析Token

**接口地址**: `POST /auth/parse_token`

**接口描述**: 解析token，验证token有效性（白名单接口，无需token）

**请求参数**:
```json
{
  "token": "string"  // token字符串（必填）
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "userID": "string",
    "platform": 1,
    "expireTimeSeconds": 604800
  }
}
```

### 3. 强制登出

**接口地址**: `POST /auth/force_logout`

**接口描述**: 强制用户登出，使token失效

**请求参数**:
```json
{
  "userID": "string",    // 用户ID（必填）
  "platform": 1          // 平台ID（必填）
}
```

---

## 用户接口

### 1. 用户注册

**接口地址**: `POST /user/user_register`

**请求参数**:
```json
{
  "secret": "string",      // 密钥（必填）
  "users": [               // 用户列表（必填）
    {
      "userID": "string",  // 用户ID（必填）
      "nickname": "string", // 昵称（必填）
      "faceURL": "string",  // 头像URL（选填）
      "ex": "string"        // 扩展字段（选填）
    }
  ]
}
```

### 2. 更新用户信息

**接口地址**: `POST /user/update_user_info_ex`

**请求参数**:
```json
{
  "userID": "string",      // 用户ID（必填）
  "nickname": "string",    // 昵称（选填）
  "faceURL": "string",     // 头像URL（选填）
  "ex": "string"           // 扩展字段（选填）
}
```

### 3. 获取用户信息

**接口地址**: `POST /user/get_users_info`

**请求参数**:
```json
{
  "userIDs": ["user1", "user2"]  // 用户ID列表（必填）
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "users": [
      {
        "userID": "string",
        "nickname": "string",
        "faceURL": "string",
        "ex": "string",
        "createTime": 1234567890000
      }
    ]
  }
}
```

### 4. 获取用户在线状态

**接口地址**: `POST /user/get_users_online_status`

**请求参数**:
```json
{
  "userIDs": ["user1", "user2"]  // 用户ID列表（必填）
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "successResult": [
      {
        "userID": "string",
        "status": "online",  // online/offline
        "platformIDs": [1, 2]
      }
    ],
    "failedResult": [
      {
        "userID": "string",
        "errMsg": "string"
      }
    ]
  }
}
```

### 5. 订阅用户状态

**接口地址**: `POST /user/subscribe_users_status`

**请求参数**:
```json
{
  "userIDs": ["user1", "user2"]  // 要订阅的用户ID列表（必填）
}
```

### 6. 获取订阅的用户状态

**接口地址**: `POST /user/get_subscribe_users_status`

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "statusList": [
      {
        "userID": "string",
        "status": "online",
        "platformIDs": [1, 2]
      }
    ]
  }
}
```

### 7. 设置全局消息接收选项

**接口地址**: `POST /user/set_global_msg_recv_opt`

**请求参数**:
```json
{
  "globalRecvMsgOpt": 0  // 0-接收并通知，1-接收但不通知，2-不接收
}
```

---

## 好友接口

### 1. 申请添加好友

**接口地址**: `POST /friend/add_friend`

**请求参数**:
```json
{
  "toUserID": "string",      // 目标用户ID（必填）
  "reqMsg": "string",        // 申请消息（选填）
  "ex": "string"             // 扩展字段（选填）
}
```

### 2. 处理好友申请

**接口地址**: `POST /friend/add_friend_response`

**请求参数**:
```json
{
  "fromUserID": "string",    // 申请者用户ID（必填）
  "handleResult": 1,         // 处理结果（必填）：0-拒绝，1-同意
  "handleMsg": "string"       // 处理消息（选填）
}
```

### 3. 删除好友

**接口地址**: `POST /friend/delete_friend`

**请求参数**:
```json
{
  "friendUserID": "string"   // 好友用户ID（必填）
}
```

### 4. 获取好友列表

**接口地址**: `POST /friend/get_friend_list`

**请求参数**:
```json
{
  "pagination": {            // 分页参数（选填）
    "pageNumber": 1,
    "showNumber": 20
  }
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "friendsInfo": [
      {
        "ownerUserID": "string",
        "remark": "string",
        "createTime": 1234567890000,
        "friendUser": {
          "userID": "string",
          "nickname": "string",
          "faceURL": "string"
        }
      }
    ],
    "total": 100
  }
}
```

### 5. 获取指定好友信息

**接口地址**: `POST /friend/get_designated_friends`

**请求参数**:
```json
{
  "friendUserIDs": ["user1", "user2"]  // 好友用户ID列表（必填）
}
```

### 6. 设置好友备注

**接口地址**: `POST /friend/set_friend_remark`

**请求参数**:
```json
{
  "toUserID": "string",      // 好友用户ID（必填）
  "remark": "string"          // 备注（必填）
}
```

### 7. 获取好友申请列表

**接口地址**: `POST /friend/get_friend_apply_list`

**请求参数**:
```json
{
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}
```

### 8. 获取自己的申请列表

**接口地址**: `POST /friend/get_self_friend_apply_list`

**请求参数**: 同上

### 9. 添加黑名单

**接口地址**: `POST /friend/add_black`

**请求参数**:
```json
{
  "toUserID": "string"  // 目标用户ID（必填）
}
```

### 10. 获取黑名单列表

**接口地址**: `POST /friend/get_black_list`

**请求参数**:
```json
{
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}
```

### 11. 移除黑名单

**接口地址**: `POST /friend/remove_black`

**请求参数**:
```json
{
  "toUserID": "string"  // 目标用户ID（必填）
}
```

### 12. 检查是否为好友

**接口地址**: `POST /friend/is_friend`

**请求参数**:
```json
{
  "toUserIDs": ["user1", "user2"]  // 用户ID列表（必填）
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "results": [
      {
        "userID": "string",
        "isFriend": true
      }
    ]
  }
}
```

---

## 群组接口

### 1. 创建群组

**接口地址**: `POST /group/create_group`

**请求参数**:
```json
{
  "groupInfo": {
    "groupName": "string",        // 群名称（必填）
    "introduction": "string",     // 群介绍（选填）
    "faceURL": "string",          // 群头像（选填）
    "ex": "string"                // 扩展字段（选填）
  },
  "memberUserIDs": ["user1", "user2"]  // 初始成员列表（选填）
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "groupInfo": {
      "groupID": "string",
      "groupName": "string",
      "introduction": "string",
      "faceURL": "string",
      "ownerUserID": "string",
      "createTime": 1234567890000,
      "memberCount": 1
    }
  }
}
```

### 2. 设置群信息

**接口地址**: `POST /group/set_group_info`

**请求参数**:
```json
{
  "groupID": "string",           // 群ID（必填）
  "groupName": "string",         // 群名称（选填）
  "introduction": "string",      // 群介绍（选填）
  "faceURL": "string",           // 群头像（选填）
  "ex": "string"                 // 扩展字段（选填）
}
```

### 3. 加入群组

**接口地址**: `POST /group/join_group`

**请求参数**:
```json
{
  "groupID": "string",      // 群ID（必填）
  "reqMessage": "string",   // 申请消息（选填）
  "ex": "string"            // 扩展字段（选填）
}
```

### 4. 退出群组

**接口地址**: `POST /group/quit_group`

**请求参数**:
```json
{
  "groupID": "string"  // 群ID（必填）
}
```

### 5. 处理群组申请

**接口地址**: `POST /group/group_application_response`

**请求参数**:
```json
{
  "groupID": "string",        // 群ID（必填）
  "fromUserID": "string",     // 申请者用户ID（必填）
  "handleResult": 1,          // 处理结果（必填）：0-拒绝，1-同意
  "handledMsg": "string"      // 处理消息（选填）
}
```

### 6. 转让群主

**接口地址**: `POST /group/transfer_group`

**请求参数**:
```json
{
  "groupID": "string",      // 群ID（必填）
  "newOwnerUserID": "string"  // 新群主用户ID（必填）
}
```

### 7. 获取群组信息

**接口地址**: `POST /group/get_groups_info`

**请求参数**:
```json
{
  "groupIDs": ["group1", "group2"]  // 群ID列表（必填）
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "groups": [
      {
        "groupID": "string",
        "groupName": "string",
        "introduction": "string",
        "faceURL": "string",
        "ownerUserID": "string",
        "createTime": 1234567890000,
        "memberCount": 10
      }
    ]
  }
}
```

### 8. 获取已加入的群组列表

**接口地址**: `POST /group/get_joined_group_list`

**请求参数**:
```json
{
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}
```

### 9. 获取群成员列表

**接口地址**: `POST /group/get_group_member_list`

**请求参数**:
```json
{
  "groupID": "string",      // 群ID（必填）
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "members": [
      {
        "groupID": "string",
        "userID": "string",
        "roleLevel": 1,      // 1-群主，2-管理员，3-普通成员
        "joinTime": 1234567890000,
        "nickname": "string",
        "faceURL": "string"
      }
    ],
    "total": 100
  }
}
```

### 10. 邀请用户加入群组

**接口地址**: `POST /group/invite_user_to_group`

**请求参数**:
```json
{
  "groupID": "string",              // 群ID（必填）
  "invitedUserIDs": ["user1", "user2"],  // 被邀请用户ID列表（必填）
  "reason": "string"                 // 邀请理由（选填）
}
```

### 11. 踢出群成员

**接口地址**: `POST /group/kick_group`

**请求参数**:
```json
{
  "groupID": "string",           // 群ID（必填）
  "kickedUserIDs": ["user1"]     // 被踢出用户ID列表（必填）
}
```

### 12. 解散群组

**接口地址**: `POST /group/dismiss_group`

**请求参数**:
```json
{
  "groupID": "string"  // 群ID（必填）
}
```

### 13. 设置群成员信息

**接口地址**: `POST /group/set_group_member_info`

**请求参数**:
```json
{
  "groupID": "string",      // 群ID（必填）
  "userID": "string",       // 用户ID（必填）
  "nickname": "string",     // 群内昵称（选填）
  "faceURL": "string",     // 头像（选填）
  "roleLevel": 2,          // 角色等级（选填）：1-群主，2-管理员，3-普通成员
  "ex": "string"           // 扩展字段（选填）
}
```

### 14. 禁言群成员

**接口地址**: `POST /group/mute_group_member`

**请求参数**:
```json
{
  "groupID": "string",      // 群ID（必填）
  "userID": "string",       // 用户ID（必填）
  "mutedSeconds": 3600      // 禁言时长（秒，必填）
}
```

### 15. 取消禁言群成员

**接口地址**: `POST /group/cancel_mute_group_member`

**请求参数**:
```json
{
  "groupID": "string",  // 群ID（必填）
  "userID": "string"    // 用户ID（必填）
}
```

### 16. 禁言群组

**接口地址**: `POST /group/mute_group`

**请求参数**:
```json
{
  "groupID": "string"  // 群ID（必填）
}
```

### 17. 取消禁言群组

**接口地址**: `POST /group/cancel_mute_group`

**请求参数**:
```json
{
  "groupID": "string"  // 群ID（必填）
}
```

---

## 消息接口

### 1. 发送消息

**接口地址**: `POST /msg/send_msg`

**请求参数**:
```json
{
  "sendID": "string",        // 发送者ID（必填）
  "groupID": "string",       // 群ID（选填，单聊不填，群聊必填）
  "recvID": "string",        // 接收者ID（选填，单聊必填，群聊不填）
  "senderNickname": "string", // 发送者昵称（选填）
  "senderFaceURL": "string",  // 发送者头像（选填）
  "contentType": 101,        // 消息类型（必填）：101-文本，102-图片，103-语音，104-视频等
  "content": "string",       // 消息内容（必填）
  "options": {               // 消息选项（选填）
    "isHistory": true,       // 是否存储历史
    "isPersistent": true,    // 是否持久化
    "isSenderSync": true     // 是否同步给发送者
  },
  "clientMsgID": "string",   // 客户端消息ID（必填）
  "offlinePushInfo": {       // 离线推送信息（选填）
    "title": "string",
    "desc": "string"
  }
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "serverMsgID": "string",
    "clientMsgID": "string",
    "sendTime": 1234567890000
  }
}
```

### 2. 发送简单消息

**接口地址**: `POST /msg/send_simple_msg`

**请求参数**: 同上，但参数更简化

### 3. 批量发送消息

**接口地址**: `POST /msg/batch_send_msg`

**请求参数**:
```json
{
  "sendID": "string",
  "groupID": "string",
  "recvIDs": ["user1", "user2"],  // 接收者ID列表
  "contentType": 101,
  "content": "string",
  "clientMsgID": "string"
}
```

### 4. 获取最新序列号

**接口地址**: `POST /msg/newest_seq`

**请求参数**:
```json
{
  "userID": "string"  // 用户ID（必填）
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "seq": 1000  // 最新序列号
  }
}
```

### 5. 根据序列号拉取消息

**接口地址**: `POST /msg/pull_msg_by_seq`

**请求参数**:
```json
{
  "userID": "string",           // 用户ID（必填）
  "seqRanges": [                // 序列号范围列表（必填）
    {
      "start": 1,
      "end": 100
    }
  ]
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "msgs": [
      {
        "serverMsgID": "string",
        "clientMsgID": "string",
        "sendID": "string",
        "recvID": "string",
        "groupID": "string",
        "contentType": 101,
        "content": "string",
        "sendTime": 1234567890000
      }
    ]
  }
}
```

### 6. 搜索消息

**接口地址**: `POST /msg/search_msg`

**请求参数**:
```json
{
  "sendID": "string",        // 发送者ID（选填）
  "recvID": "string",        // 接收者ID（选填）
  "groupID": "string",       // 群ID（选填）
  "contentType": 101,        // 消息类型（选填）
  "keyword": "string",        // 关键词（选填）
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}
```

### 7. 撤回消息

**接口地址**: `POST /msg/revoke_msg`

**请求参数**:
```json
{
  "conversationID": "string",  // 会话ID（必填）
  "seq": 100,                  // 消息序列号（必填）
  "userID": "string"           // 用户ID（必填）
}
```

### 8. 标记消息已读

**接口地址**: `POST /msg/mark_msgs_as_read`

**请求参数**:
```json
{
  "conversationID": "string",  // 会话ID（必填）
  "seqs": [100, 101, 102],    // 消息序列号列表（必填）
  "userID": "string"          // 用户ID（必填）
}
```

### 9. 标记会话已读

**接口地址**: `POST /msg/mark_conversation_as_read`

**请求参数**:
```json
{
  "conversationID": "string",  // 会话ID（必填）
  "hasReadSeq": 100,           // 已读序列号（必填）
  "userID": "string"           // 用户ID（必填）
}
```

### 10. 获取会话已读序列号

**接口地址**: `POST /msg/get_conversations_has_read_and_max_seq`

**请求参数**:
```json
{
  "userID": "string",                    // 用户ID（必填）
  "conversationIDs": ["conv1", "conv2"]  // 会话ID列表（必填）
}
```

### 11. 删除消息

**接口地址**: `POST /msg/delete_msgs`

**请求参数**:
```json
{
  "userID": "string",           // 用户ID（必填）
  "conversationID": "string",   // 会话ID（必填）
  "seqs": [100, 101, 102]      // 消息序列号列表（必填）
}
```

### 12. 清空会话消息

**接口地址**: `POST /msg/clear_conversation_msg`

**请求参数**:
```json
{
  "userID": "string",          // 用户ID（必填）
  "conversationID": "string"   // 会话ID（必填）
}
```

### 13. 获取服务器时间

**接口地址**: `POST /msg/get_server_time`

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "serverTime": 1234567890000  // 服务器时间戳（毫秒）
  }
}
```

---

## 会话接口

### 1. 获取所有会话

**接口地址**: `POST /conversation/get_all_conversations`

**请求参数**:
```json
{
  "ownerUserID": "string"  // 用户ID（必填）
}
```

**响应参数**:
```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "conversations": [
      {
        "ownerUserID": "string",
        "conversationID": "string",
        "conversationType": 1,  // 1-单聊，2-群聊
        "userID": "string",      // 单聊时使用
        "groupID": "string",     // 群聊时使用
        "recvMsgOpt": 0,         // 接收消息选项：0-接收并通知，1-接收但不通知，2-不接收
        "unreadCount": 0,        // 未读消息数
        "draftText": "string",   // 草稿
        "draftTextTime": 0,      // 草稿时间
        "isPinned": false,       // 是否置顶
        "isPrivateChat": false,  // 是否私聊
        "burnDuration": 0,       // 阅后即焚时长（秒）
        "groupAtType": 0,        // 群@类型
        "maxSeq": 0,             // 最大序列号
        "hasReadSeq": 0,         // 已读序列号
        "updateUnreadCountTime": 0
      }
    ]
  }
}
```

### 2. 获取排序后的会话列表

**接口地址**: `POST /conversation/get_sorted_conversation_list`

**请求参数**:
```json
{
  "ownerUserID": "string",  // 用户ID（必填）
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}
```

### 3. 获取指定会话

**接口地址**: `POST /conversation/get_conversation`

**请求参数**:
```json
{
  "ownerUserID": "string",     // 用户ID（必填）
  "conversationID": "string"   // 会话ID（必填）
}
```

### 4. 批量获取会话

**接口地址**: `POST /conversation/get_conversations`

**请求参数**:
```json
{
  "ownerUserID": "string",                    // 用户ID（必填）
  "conversationIDs": ["conv1", "conv2"]      // 会话ID列表（必填）
}
```

### 5. 设置会话

**接口地址**: `POST /conversation/set_conversations`

**请求参数**:
```json
{
  "conversations": [
    {
      "conversationID": "string",
      "recvMsgOpt": 0,
      "isPinned": false,
      "isPrivateChat": false,
      "groupAtType": 0,
      "draftText": "string",
      "draftTextTime": 0,
      "burnDuration": 0
    }
  ]
}
```

### 6. 获取增量会话

**接口地址**: `POST /conversation/get_incremental_conversations`

**请求参数**:
```json
{
  "ownerUserID": "string",     // 用户ID（必填）
  "seq": 100                   // 起始序列号（必填）
}
```

### 7. 获取置顶会话ID列表

**接口地址**: `POST /conversation/get_pinned_conversation_ids`

**请求参数**:
```json
{
  "ownerUserID": "string"  // 用户ID（必填）
}
```

### 8. 删除会话

**接口地址**: `POST /conversation/delete_conversations`

**请求参数**:
```json
{
  "ownerUserID": "string",                    // 用户ID（必填）
  "conversationIDs": ["conv1", "conv2"]     // 会话ID列表（必填）
}
```

---

## 第三方服务接口

### 1. 更新FCM Token

**接口地址**: `POST /third/fcm_update_token`

**请求参数**:
```json
{
  "platform": 1,        // 平台ID（必填）
  "fcmToken": "string", // FCM Token（必填）
  "userID": "string"    // 用户ID（必填）
}
```

### 2. 设置应用角标

**接口地址**: `POST /third/set_app_badge`

**请求参数**:
```json
{
  "userID": "string",    // 用户ID（必填）
  "unreadCount": 10     // 未读数（必填）
}
```

### 3. 上传日志

**接口地址**: `POST /third/logs/upload`

**请求参数**: 文件上传（multipart/form-data）

### 4. 对象存储 - 初始化分片上传

**接口地址**: `POST /object/initiate_multipart_upload`

**请求参数**:
```json
{
  "name": "string",      // 对象名称（必填）
  "contentType": "string"  // 内容类型（选填）
}
```

### 5. 对象存储 - 完成分片上传

**接口地址**: `POST /object/complete_multipart_upload`

**请求参数**:
```json
{
  "name": "string",      // 对象名称（必填）
  "uploadID": "string", // 上传ID（必填）
  "parts": [            // 分片列表（必填）
    {
      "partNumber": 1,
      "etag": "string"
    }
  ]
}
```

### 6. 对象存储 - 获取访问URL

**接口地址**: `POST /object/access_url`

**请求参数**:
```json
{
  "name": "string",     // 对象名称（必填）
  "expires": 3600       // 过期时间（秒，选填）
}
```

---

## 红包接口

详细文档请参考：[红包接口文档](./redpacket-api.md)

### 主要接口

1. **发送红包**: `POST /redpacket/send_redpacket`
2. **领取红包**: `POST /redpacket/receive`
3. **查询红包详情**: `POST /redpacket/get_detail`

---

## 会议接口

详细文档请参考：[会议接口文档](./meeting-api.md)

### 用户端接口

1. **获取会议信息**: `POST /meeting/get_meeting`
2. **获取会议列表**: `POST /meeting/get_meetings_public`

---

## 钱包接口

### 1. 获取钱包列表（管理接口）

**接口地址**: `POST /wallet/get_wallets`

**请求参数**:
```json
{
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}
```

### 2. 批量更新余额（管理接口）

**接口地址**: `POST /wallet/batch_update_balance`

**请求参数**:
```json
{
  "updates": [
    {
      "userID": "string",
      "amount": 10000,      // 金额（分）
      "changeType": 1       // 变更类型：1-增加，2-减少
    }
  ]
}
```

---

## 错误码说明

### 通用错误码

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 500 | 服务器内部错误 |
| 1001 | 参数错误 |
| 1002 | 权限不足 |
| 1003 | 重复键错误 |
| 1004 | 记录不存在 |

### 用户相关错误码

| 错误码 | 说明 |
|--------|------|
| 1101 | 用户ID不存在或未注册 |
| 1102 | 用户已注册 |

### 群组相关错误码

| 错误码 | 说明 |
|--------|------|
| 1201 | 群ID不存在 |
| 1202 | 群ID已存在 |
| 1203 | 尚未加入群组 |
| 1204 | 群组已解散 |
| 1205 | 群组类型不支持 |
| 1206 | 群组申请已处理 |

### 好友相关错误码

| 错误码 | 说明 |
|--------|------|
| 1301 | 不能添加自己为好友 |
| 1302 | 被对方拉黑 |
| 1303 | 不是对方的好友 |
| 1304 | 已经是好友关系 |

### 消息相关错误码

| 错误码 | 说明 |
|--------|------|
| 1401 | 消息已读功能禁用 |
| 1402 | 群成员被禁言 |
| 1403 | 群组被禁言 |
| 1404 | 消息已撤回 |
| 1405 | 消息包含链接（不允许） |
| 1406 | 图片包含二维码（不允许） |

### Token相关错误码

| 错误码 | 说明 |
|--------|------|
| 1501 | Token已过期 |
| 1502 | Token无效 |
| 1503 | Token格式错误 |
| 1504 | Token尚未生效 |
| 1505 | Token未知错误 |
| 1506 | Token被踢出 |
| 1507 | Token不存在 |

### 红包相关错误码

| 错误码 | 说明 |
|--------|------|
| 1801 | 红包已被领完 |
| 1802 | 红包已过期 |
| 1803 | 用户已领取过该红包 |

---

## 注意事项

### 1. 认证

- 除白名单接口外，所有接口都需要在请求头中携带 `token`
- Token通过 `/auth/get_user_token` 接口获取
- Token过期后需要重新获取

### 2. 请求格式

- 所有接口使用 `POST` 方法（除特殊说明外）
- Content-Type: `application/json`
- 请求体为JSON格式

### 3. 响应格式

- 所有接口统一返回格式：`{errCode, errMsg, errDlt, data}`
- `errCode` 为 0 表示成功，非0表示失败
- 失败时查看 `errMsg` 和 `errDlt` 获取错误详情

### 4. 分页参数

- 分页参数统一格式：
  ```json
  {
    "pagination": {
      "pageNumber": 1,    // 页码，从1开始
      "showNumber": 20    // 每页数量
    }
  }
  ```

### 5. 时间戳

- 所有时间戳均为毫秒级Unix时间戳
- 例如：`1234567890000` 表示 2009-02-13 23:31:30

### 6. 平台ID

- 1: iOS
- 2: Android
- 3: Windows
- 4: OSX
- 5: Web
- 6: 小程序

### 7. 消息类型

- 101: 文本消息
- 102: 图片消息
- 103: 语音消息
- 104: 视频消息
- 105: 文件消息
- 106: @消息
- 107: 位置消息
- 108: 自定义消息
- 109: 引用消息
- 110: 自定义消息（红包等）

### 8. 会话类型

- 1: 单聊
- 2: 群聊

### 9. 群成员角色

- 1: 群主
- 2: 管理员
- 3: 普通成员

### 10. 接收消息选项

- 0: 接收并通知
- 1: 接收但不通知
- 2: 不接收

---

## 接口汇总表

| 模块 | 接口数量 | 主要功能 |
|------|---------|---------|
| 认证 | 3 | 获取token、解析token、强制登出 |
| 用户 | 19 | 注册、更新信息、查询、在线状态等 |
| 好友 | 16 | 添加、删除、查询、黑名单等 |
| 群组 | 17 | 创建、加入、退出、管理成员等 |
| 消息 | 13 | 发送、接收、搜索、撤回等 |
| 会话 | 8 | 获取、设置、删除会话等 |
| 第三方服务 | 6+ | 文件上传、对象存储等 |
| 红包 | 3 | 发送、领取、查询 |
| 会议 | 2 | 查询会议信息 |
| 钱包 | 2 | 查询钱包、更新余额 |

---

## 相关文档

- [红包接口详细文档](./redpacket-api.md)
- [会议接口详细文档](./meeting-api.md)
- [错误码标准](./contrib/error-code.md)
- [API标准](./contrib/api.md)

---

**最后更新时间**: 2025-01-23