快速开始

01 / 创建并登录实例

1. 打开 控制台，登录账号并选择你有权限访问的租户。
2. 在实例列表创建实例，然后进入实例详情页发起扫码登录。
3. 按页面提示完成验证，确认实例已登录并运行。记录实例 ID，后续调用使用它定位账号。

02 / 创建接口密钥

由租户 owner 或 admin 在控制台「接口密钥」页面创建 AccessToken，选择名称和有效期。完整密钥只在创建时显示一次，请及时保存。

Authorization: Bearer <access_token>

控制台登录 Token 与开放接口 AccessToken 分开使用。开放密钥绑定租户，可访问该租户下的实例。实例 ID 必须属于该租户；不要把密钥放入公开网页或提交到代码仓库。

轮换密钥时，先创建新密钥并更新调用方，再撤销旧密钥。过期或撤销的密钥将无法发起新请求。

03 / 发起第一次调用

将下面的服务地址、实例 ID 和密钥替换为你的实际配置。这个示例向文件传输助手发送一条文本消息。

BASE_URL=http://localhost:8058
INSTANCE_ID=1
TOKEN=替换为你的接口密钥

curl "$BASE_URL/api/open/v1/instances/$INSTANCE_ID/msg/send_txt" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to_wxid":"filehelper","content":"Hello, 小微云!","type":1}'

在 接口参考 中查阅完整的参数和响应定义，再使用你的开发工具或服务端代码发起调用。

实例与会话

停止实例会暂停运行，保留可恢复的会话；恢复实例会尝试使用已有会话。退出登录会清除可用会话，重新使用前需要扫码登录。需要更换登录时，在控制台使用重新登录操作。

开放接口中的 login/auto_heart_beat、login/close_auto_heart_beat 和 login/log_out 分别对应恢复、停止与退出操作。这些操作需要当前实例 version 与至少 8 个字符的 request_id。处理中返回 HTTP 202，通过同一实例下的 GET /operations/{requestID} 查询最终状态。

响应与错误处理

业务接口使用 code、message、data 统一包装。外层 code 为 OK 表示平台成功处理了请求；协议调用还需要检查 data.success、data.code 和具体协议结果。

{
  "code": "OK",
  "message": "...",
  "data": { "success": true, "code": 0, "data": {} }
}
// 结构示意；data 以实际接口返回为准。

完整响应格式、通用错误码及处理建议见响应规范。

消息发送超时或返回结果不明时，不要盲目重发，应先核对实际结果。协议发送并不提供可靠发送队列或自动重试承诺。