XuqmGroup-Web/docs-site/docs/server/api.md

Server API 参考

XuqmGroup 的服务端能力分成两类：

• IM 服务：账号、消息、群组、好友、会话、黑名单、管理端、回调
• Push 服务：设备注册、离线推送、诊断、管理端

Base URL：https://dev.xuqinmin.com

所有接口都通过 Nginx 反代，无需关心内部端口。

---

认证

IM 服务

• POST /api/im/auth/login 返回 im_jwt
• 客户端登录使用 userId + userSig
• userSig 由服务端或 IM 管理页生成，服务端 SDK 可本地生成和校验
• GET /api/im/platform-events/token 由 IM 服务返回平台事件账号 platform 的登录 token，用于租户平台实时刷新
• 服务端管理类调用使用具备管理员权限的 IM 账号登录后获得的 im_jwt
• 服务端如果不想先走 SDK，也可以直接调用 /api/im/admin/users/{userId}/usersig 生成 userSig，再用 /api/im/auth/login?userSig=... 换取 im_jwt
• 只有被标记为管理员的 IM 注册账号，才允许用于服务端 SDK / 管理端 REST API
• IM 管理页里的 UserSig 生成 / 校验工具也只对管理员账号开放

Push / Update / Tenant 相关服务

• 业务侧调用通常使用 appKey
• 管理端接口需要租户或运营平台的 JWT
• 内部接口统一使用 X-Internal-Token

---

IM 服务

账号与登录

方法	路径	说明
POST	/api/im/auth/login	IM 登录，返回 JWT Token；支持 userSig
POST	/api/im/admin/users/{userId}/usersig	生成 UserSig
POST	/api/im/admin/users/{userId}/usersig/verify	校验 UserSig
GET	/api/im/accounts/{userId}	获取账号资料
PUT	/api/im/accounts/{userId}	更新账号资料
GET	/api/im/accounts/search	搜索账号
POST	/api/im/accounts/import	导入单个账号
POST	/api/im/accounts/import/batch	批量导入账号
DELETE	/api/im/accounts/{userId}	删除账号
GET	/api/im/accounts/{userId}/exists	检查账号是否存在

消息

方法	路径	说明
POST	/api/im/messages/send	发送消息
POST	/api/im/messages/{id}/revoke	撤回消息
PUT	/api/im/messages/{id}	编辑消息
GET	/api/im/messages/history/{toId}	单聊历史
GET	/api/im/messages/group-history/{groupId}	群聊历史
GET	/api/im/messages/search	按关键字搜索消息
GET	/api/im/messages/offline/count	离线消息数
POST	/api/im/messages/offline	同步离线消息

会话

方法	路径	说明
GET	/api/im/conversations	会话列表
PUT	/api/im/conversations/{targetId}/pinned	置顶会话
PUT	/api/im/conversations/{targetId}/muted	免打扰
PUT	/api/im/conversations/{targetId}/read	标记已读
PUT	/api/im/conversations/{targetId}/draft	设置草稿
PUT	/api/im/conversations/{targetId}/hidden	隐藏会话
PUT	/api/im/conversations/{targetId}/group	设置会话分组
GET	/api/im/conversation-groups	会话分组列表
GET	/api/im/conversation-groups/{groupName}	指定分组内容
DELETE	/api/im/conversations/{targetId}	删除会话

好友与黑名单

方法	路径	说明
GET	/api/im/friends	好友列表
POST	/api/im/friends	添加好友
POST	/api/im/friends/batch	批量添加好友
DELETE	/api/im/friends/{friendId}	删除好友
DELETE	/api/im/friends	删除全部好友
POST	/api/im/friends/batch/remove	批量删除好友
PUT	/api/im/friends/{friendId}/group	设置好友分组
GET	/api/im/friends/groups	好友分组列表
GET	/api/im/friends/groups/{groupName}	指定分组好友
POST	/api/im/friends/check	校验好友关系
GET	/api/im/blacklist	黑名单列表
POST	/api/im/blacklist	添加黑名单
DELETE	/api/im/blacklist	删除黑名单
GET	/api/im/blacklist/check	校验黑名单关系

群组

方法	路径	说明
GET	/api/im/groups	群列表
POST	/api/im/groups	创建群组
GET	/api/im/groups/public	公开群列表
GET	/api/im/groups/search	搜索群
GET	/api/im/groups/{groupId}	群详情
GET	/api/im/groups/{groupId}/members	群成员
GET	/api/im/groups/{groupId}/members/search	搜索群成员
PUT	/api/im/groups/{groupId}	更新群信息
POST	/api/im/groups/{groupId}/members	添加群成员
POST	/api/im/groups/{groupId}/members/batch	批量添加群成员
DELETE	/api/im/groups/{groupId}/members/{targetUserId}	删除群成员
POST	/api/im/groups/{groupId}/members/batch/remove	批量删除群成员
POST	/api/im/groups/{groupId}/roles	设置群角色
POST	/api/im/groups/{groupId}/owner	转让群主
PUT	/api/im/groups/{groupId}/attributes	更新群属性
POST	/api/im/groups/{groupId}/attributes/delete	删除群属性
POST	/api/im/groups/{groupId}/mute	群成员禁言
DELETE	/api/im/groups/{groupId}	解散群
POST	/api/im/groups/{groupId}/join-requests	发送加群申请
GET	/api/im/groups/{groupId}/join-requests	查询加群申请
POST	/api/im/groups/{groupId}/join-requests/{requestId}/accept	接受加群申请
POST	/api/im/groups/{groupId}/join-requests/{requestId}/reject	拒绝加群申请
POST	/api/im/groups/{groupId}/join-requests/batch/accept	批量接受加群申请
POST	/api/im/groups/{groupId}/join-requests/batch/reject	批量拒绝加群申请

管理端

方法	路径	说明
GET	/api/im/admin/users/state	查询用户在线状态
POST	/api/im/admin/users/kick	踢下线用户
POST	/api/im/admin/messages/batch-send	批量发消息
POST	/api/im/admin/messages/read	管理端标记已读
POST	/api/im/admin/messages/import	导入消息
GET	/api/im/admin/groups/{groupId}/owner	查询群主
PUT	/api/im/admin/groups/{groupId}/owner	管理端转让群主
PUT	/api/im/admin/groups/{groupId}/attributes	管理端更新群属性
POST	/api/im/admin/groups/{groupId}/attributes/delete	管理端删除群属性
GET	/api/im/admin/groups/{groupId}/read-receipts	群已读统计
GET	/api/im/admin/webhooks	Webhook 列表
POST	/api/im/admin/webhooks	创建 Webhook
PUT	/api/im/admin/webhooks/{id}	更新 Webhook
DELETE	/api/im/admin/webhooks/{id}	删除 Webhook
GET	/api/im/admin/webhook-deliveries	Webhook 投递记录
GET	/api/im/admin/webhook-alerts	Webhook 告警
POST	/api/im/admin/webhook-alerts/{id}/acknowledge	告警确认
GET	/api/im/admin/webhooks/{id}/health	Webhook 健康状态
GET	/api/im/admin/keyword-filters	敏感词列表
POST	/api/im/admin/keyword-filters	新增敏感词
PUT	/api/im/admin/keyword-filters/{id}	更新敏感词
DELETE	/api/im/admin/keyword-filters/{id}	删除敏感词
GET	/api/im/admin/global-mute	全局禁言状态
PUT	/api/im/admin/global-mute	更新全局禁言
GET	/api/im/admin/operation-logs	IM 操作日志

内部接口

方法	路径	说明
POST	/api/im/internal/presence/resolve-token	解析 IM Token
GET	/api/im/internal/presence/users/{userId}	查询用户在线状态

---

Push 服务

公开接口

方法	路径	说明
POST	/api/push/register	设备注册推送 token
DELETE	/api/push/unregister	设备取消注册
POST	/api/push/send	发送推送
POST	/api/push/receive-push	推送回执/接收

管理端

方法	路径	说明
GET	/api/push/admin/user-status	查询用户推送状态
GET	/api/push/admin/device-logs	设备日志
POST	/api/push/admin/test-offline	离线推送测试

Push 服务不使用 UserSig；公开接口面向业务服务，管理端接口继续使用平台登录态或服务端管理态。 Push SDK 与 REST API 的公开调用面向业务系统，管理员诊断能力通过平台 JWT 或服务端管理态访问。

内部接口

方法	路径	说明
POST	/api/push/internal/notify	内部通知转发
GET	/api/push/internal/diagnostics/search	按 token 查询诊断
GET	/api/push/internal/device-logs	内部设备日志
POST	/api/push/internal/test-offline	内部离线测试

---

数据模型约定

应用标识

• 所有业务侧判断应用身份使用 appKey
• appId 仅保留在第三方厂商账号字段里，不作为应用身份

常见响应

{
  "code": 200,
  "status": "0",
  "data": { },
  "message": "success"
}

错误码

HTTP 状态	code	含义
400	400	参数错误
401	401	鉴权失败
403	403	无权限
404	404	资源不存在
500	500	服务端内部错误

---

集成建议

• 服务端业务代码统一使用 Java / Go / Python Server SDK 调用上述 REST 接口
• 客户端统一使用 appKey 作为应用上下文
• 实时刷新场景建议使用 IM SDK 订阅服务端事件
• Push、IM 的后台能力可以独立接入，也可以组合使用