星云企业微信开放平台 API
基于企业微信的自动化 API 接口平台，覆盖登录、联系人、消息、群聊、朋友圈、文件等能力，帮助你快速构建企业级应用与自动化服务。
多端设备支持
支持 Windows、iPad、Mac 等多种设备同时在线管理
多实例管理统一 REST API
所有接口统一 JSON 格式 HTTP POST 请求
简单易用实时 Webhook
事件实时推送，支持消息、状态、回调等多种事件类型
实时推送企业级稳定性
365 天持续稳定运行 99.9% 服务可用性保障
企业级保障快速开始
创建实例
注册账号并创建企业微信实例
获取 API Key
在控制台获取你的专属 API Key
调用接口
使用 API Key 调用第一个接口
配置 Webhook
接收事件推送与回调通知
正式上线
完成集成，开始使用星云 API
curl -X POST 'https://api.xingyapi.com/api/message/sendText' \ -H 'X-Nebula-Key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "instance_guid": "inst_xxxx", "conversationId": "会话ID（对方或群标识）", "content": "你好，欢迎了解星云。" }'
快速开始
跟随以下步骤，快速接入星云 API，发送第一条消息只需 5 分钟。
注册并登录控制台
在 open.xingyapi.com 注册账号，登录后进入开发者控制台。注册即自动开通体验版。
创建实例并扫码登录
在「实例与回调」点「一键登录」，用企业微信扫码上号，获得实例标识 instance_guid。
获取 API Key
在「API Key」页复制你的专属 Key（注册时已自动创建一个），请求时通过 X-Nebula-Key 头携带。
调用接口
用 API Key + instance_guid 调用业务接口，发送第一条消息。也可在控制台「在线测试」直接试。
接收回调（可选）
在「回调信息预览」实时查看实例收到的消息与事件；也可配置转发到你自己的服务器（见 Webhook 说明）。
基础信息准备
在开始之前，请确保你已经完成以下准备工作：
curl -X POST 'https://api.xingyapi.com/api/message/sendText' \ -H 'X-Nebula-Key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "instance_guid": "inst_xxxx", "conversationId": "会话ID（对方或群标识）", "content": "你好，欢迎使用星云 API！" }'
更新日志
记录星云 API 平台的每一次功能更新与优化，帮助您及时了解最新动态。
提供企业微信实例扫码托管、消息收发、通讯录、群聊、朋友圈、文件等语义化 API；支持在线测试、回调事件实时预览，以及体验版 / 企业 POC 权益体系。
https://api.xingyapi.com鉴权：X-Nebula-KeyWebhook 说明
实例登录后，它收到的企业微信消息与事件会被平台实时捕获。你有两种用法：① 在控制台「回调信息预览」直接查看，无需自建服务器；② 配置转发地址，平台把事件带签名 POST 到你的服务器。
工作原理
已登录实例收到消息 / 状态变更，上游推送到平台接收器
平台脱敏、解析后存入「回调信息预览」，并按需转发
控制台查看，或你的服务器收到 POST 后验签处理
方式一：控制台预览（零代码）
进入控制台「回调信息预览」，选择实例即可实时看到它收到的消息与事件（每 5 秒自动刷新），无需自建服务器。
方式二：转发到你的服务器
在「实例与回调」为实例配置回调地址，平台会把事件 POST 过去。
{"code":0} 确认接收。请求头与请求体
Content-Type: application/json X-Nebula-Timestamp: 1780000000 X-Nebula-Signature: HMAC-SHA256(secret, timestamp + "." + rawBody)
{
"instance_guid": "inst_xxxx",
"events": [
{
"fromUserId": "发送方ID",
"msgType": 2,
"content": [{ "type": 0, "content": "你好" }],
"timestamp": 1780000000
}
]
}
验证签名
用你的回调密钥（whsec_…，在「实例与回调」查看）按下式计算，与 X-Nebula-Signature 比对一致即为可信：
import hmac, hashlib sig = hmac.new(secret.encode(), (timestamp + ".").encode() + raw_body, hashlib.sha256).hexdigest() # sig == 请求头 X-Nebula-Signature ?
错误码
调用 API 时，如果返回的 code 不为 0，表示请求失败。你可以根据错误码定位问题并采取相应措施。
| 错误码 | 类型 | 描述 | 解决方案 |
|---|---|---|---|
| 0 | 成功 | 请求成功，业务数据在 data 字段 | 无 |
| 401 | 认证相关 | API Key 无效或缺失 | 请求头带 X-Nebula-Key: <你的Key>，值取自控制台「API Key」页 |
| 40001 | 请求参数 | 请求体必须为 JSON 对象 | Content-Type 用 application/json，body 为合法 JSON |
| 40301 | 接口限制 | 该接口需申请企业 POC 后开放（体验版仅开放 20 个基础接口） | 在控制台「企业 POC」提交申请，审核通过后全部接口开放 |
| 40302 | 接口限制 | 账号额度已满，无法再接入新实例 | 申请企业 POC 或联系客服扩容 |
| 50001 | 业务错误 | 接口调用失败，具体原因见 message（如「conversationId is required」） | 按 message 提示检查参数、实例是否在线 |
| 50000 | 服务器错误 | 上游服务调用失败（超时 / 网络异常 / 暂不可用） | 请稍后重试，持续失败请联系客服 |
| 50002 | 服务器错误 | 创建实例成功但未获取到实例标识 | 请重试，或联系客服 |
