XuqmGroup-Web/docs-site/docs/server/python-sdk.md

# Python Server SDK

XuqmGroup 服务端 Python SDK，封装了：

- IM 账号、UserSig 生成与登录、消息、群组、好友、会话、黑名单
- 管理端 Webhook、操作日志
- Push 注册与推送

---

## 安装

```bash
pip install xuqmgroup-server-sdk-python
```

---

## 初始化

```python
from xuqm_im_server_sdk import XuqmImServerSdk

sdk = XuqmImServerSdk(
    base_url="https://dev.xuqinmin.com",
    app_key="your_app_key",
    app_secret="your_app_secret",
)
```

> 服务端 SDK 需要 `app_secret` 用于 HMAC 签名，`app_secret` 绝不下发到客户端。

---

## UserSig

```python
user_sig = sdk.generate_user_sig("user_001")
valid = sdk.verify_user_sig("user_001", user_sig)
login = sdk.login_with_user_sig("user_001", user_sig)
```

管理员账号可用于服务端 SDK / 管理端 REST API。

---

## 能力分类

| 分类 | 主要方法 |
|------|----------|
| 登录 | `generate_user_sig`, `verify_user_sig`, `login`, `login_with_user_sig` |
| 账号 | `import_account`, `import_accounts`, `delete_account`, `get_profile`, `update_profile`, `search_accounts`, `check_account` |
| 消息 | `send_message`, `revoke_message`, `edit_message`, `fetch_history`, `fetch_group_history`, `search_messages` |
| 会话 | `list_conversations`, `set_conversation_pinned`, `set_conversation_muted`, `mark_read`, `set_draft`, `set_conversation_hidden`, `set_conversation_group`, `delete_conversation` |
| 好友 | `list_friends`, `add_friend`, `add_friends`, `remove_friend`, `remove_friends`, `remove_all_friends`, `set_friend_group`, `list_friend_groups`, `list_friends_by_group`, `check_friends` |
| 黑名单 | `list_blacklist`, `add_blacklist`, `remove_blacklist`, `check_blacklist` |
| 群组 | `list_groups`, `list_public_groups`, `search_groups`, `get_group`, `list_group_members`, `search_group_members`, `create_group`, `update_group`, `add_group_member`, `add_group_members`, `remove_group_member`, `remove_group_members`, `set_group_role`, `transfer_group_owner`, `leave_group`, `update_group_attributes`, `remove_group_attributes`, `mute_group_member`, `dismiss_group`, `send_group_join_request`, `list_group_join_requests`, `accept_group_join_request`, `reject_group_join_request`, `accept_group_join_requests`, `reject_group_join_requests` |
| 管理端 | `query_user_state`, `kick_users`, `batch_send_message`, `admin_set_msg_read`, `import_messages`, `admin_transfer_group_owner`, `admin_update_group_attributes`, `admin_remove_group_attributes`, `admin_group_read_receipts` |
| Webhook | `list_webhooks`, `create_webhook`, `update_webhook`, `delete_webhook`, `verify_callback_signature`, `parse_callback_envelope` |
| Push | `register_push_token`, `send_push`, `push_user_status`, `push_device_logs`, `test_offline_push` |

---

## 发送消息

```python
msg = sdk.send_message(
    to_id="user_002",
    chat_type="SINGLE",
    msg_type="TEXT",
    content="Hello from Python SDK!",
)
print(f"消息已发送: {msg['id']}")
```

### 发送群消息

```python
msg = sdk.send_message(
    to_id="group_xxx",
    chat_type="GROUP",
    msg_type="TEXT",
    content="大家好",
)
```

### 撤回消息

```python
sdk.revoke_message("message_id")
```

---

## 群管理

```python
group = sdk.create_group(
    name="项目讨论",
    member_ids=["user_001", "user_002"],
)

sdk.add_group_member("group_xxx", "user_003")
sdk.remove_group_member("group_xxx", "user_003")

groups = sdk.list_groups()
members = sdk.list_group_members("group_xxx")
```

---

## Push 推送

```python
sdk.send_push(
    user_id="user_001",
    title="新消息",
    body="你有一条未读消息",
    payload={"chatId": "user_002"},
)
```

---

## 错误处理

SDK 在请求失败时会抛出 `XuqmAPIError` 异常：

```python
from xuqm_im_server_sdk import XuqmAPIError

try:
    msg = sdk.send_message(to_id="user_002", chat_type="SINGLE", msg_type="TEXT", content="Hello")
except XuqmAPIError as e:
    print(f"API 错误: status={e.status}, code={e.code}, message={e.message}")
```

[→ Server API 文档](/server/api)