一、API 概述

SafeW 开放平台提供基于 HTTPS 的 RESTful API，所有请求和响应均使用 JSON 格式编码。API 基础地址为 https://api.safewe.org/v1/。所有 API 调用必须包含 Authorization 请求头承载 Bot Token 或用户访问令牌。API 采用基于 HMAC-SHA256 的请求签名机制，有效防止重放攻击和请求篡改。

二、Bot 机器人 API

SafeW Bot API 允许开发者创建在 SafeW 平台内运行的自动化机器人账号。Bot 可以接收和发送消息、管理群组、处理指令命令。

  • 消息收发：Bot 可发送文本、图片、文件、Markdown 格式消息和交互式按钮键盘。
  • 命令系统：支持注册自定义斜杠命令（如 /subscribe、/status），用户在与 Bot 的对话中直接调用。
  • 群组管理：Bot 可受邀加入群组，监听群内消息并根据预设规则自动响应或执行管理操作。
  • 权限控制：每个 Bot 拥有独立的最小权限范围，仅能访问其被授权执行的操作。

三、Mini App 平台

SafeW Mini App 是运行在 SafeW 客户端内的轻量级 Web 应用。开发者使用标准的 HTML、CSS 和 JavaScript 技术栈构建 Mini App，SafeW 客户端提供原生桥接 API：

  • SafeW.WebApp.initData：经过 Ed25519 签名的初始化数据，服务端可验证数据来源的真实性。
  • SecureStorage API：提供加密的键值对存储，最多支持 10 个加密存储项。数据在客户端加密后存储，仅创建该数据的 Mini App 可读取。
  • 生物识别认证：Mini App 可调用客户端的指纹或面部识别能力进行用户身份二次验证。
  • 主题适配：Mini App 可获取用户当前的 SafeW 主题配色，自动适配亮色/暗色模式。

四、Webhook 事件订阅

开发者可为 Bot 配置 Webhook URL，当指定事件发生时，SafeW 服务器将向该 URL 发送 HTTP POST 请求携带事件数据。支持的事件类型包括：消息接收、消息已读回执、群组成员变更和支付状态回调。

Webhook 数据使用 Bot Token 进行 HMAC-SHA256 签名，开发者应在处理请求前验证签名以确保数据来源的可信性。SafeW 对未成功投递的 Webhook 进行指数退避重试（最多 5 次），确保事件不丢失。

五、安全最佳实践

  • 将所有 API 请求置于服务端代码中执行，切勿在客户端（Mini App 前端）代码中暴露 Bot Token。
  • 始终在服务端对 Mini App 的 initData 原始字符串进行 Ed25519 签名验证，不信任 initDataUnsafe 中的数据。
  • 对 Webhook 接收端点实施速率限制，防范恶意请求洪泛。
  • 定期轮换 Bot Token，建议每 90 天更新一次。

完整的 API 参考文档（含请求/响应 Schema、错误码对照表和代码示例）请通过 SafeW 开发者门户获取。