星云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！"
  }'

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": "YOUR_INSTANCE_GUID",
    "conversationId": "会话ID（对方或群标识）",
    "content": "你好，欢迎使用星云 API！"
  }'

import requests

resp = requests.post(
    "https://api.xingyapi.com/api/message/sendText",
    headers={"X-Nebula-Key": "YOUR_API_KEY"},
    json={
        "instance_guid": "YOUR_INSTANCE_GUID",
        "conversationId": "会话ID",
        "content": "你好，欢迎使用星云 API！",
    },
)
print(resp.json())

const resp = await fetch("https://api.xingyapi.com/api/message/sendText", {
  method: "POST",
  headers: {
    "X-Nebula-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    instance_guid: "YOUR_INSTANCE_GUID",
    conversationId: "会话ID",
    content: "你好，欢迎使用星云 API！",
  }),
});
console.log(await resp.json());

{
  "ok": true,
  "code": 0,
  "message": "success",
  "request_id": "nb_xxxxxxxx",
  "data": {}
}

{
  "ok": false,
  "code": 401,
  "message": "API Key 无效或缺失",
  "request_id": "nb_xxxxxxxx",
  "data": null
}

{
  "ok": true,
  "code": 0,
  "message": "success",
  "request_id": "nb_xxxxxxxx",
  "data": {
    "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA…（PNG 图片 Base64，约 50–60KB，此处省略）",
    "uuid": "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6",
    "refreshInterval": 600
  }
}

{
  "ok": true,
  "code": 0,
  "message": "success",
  "request_id": "nb_xxxxxxxx",
  "data": {
    "status": 0,
    "uuid": "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6"
  }
}

{
  "ok": true,
  "code": 0,
  "message": "success",
  "request_id": "nb_xxxxxxxx",
  "data": {
    "status": 2,
    "uuid": "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6",
    "nickName": "示例用户",
    "avatarUrl": "https://example.com/avatar.png",
    "corpId": 1970320000000001,
    "corpUserId": 1688850000000001,
    "corpLogoUrl": "https://example.com/logo.png",
    "confirmedFlag": true
  }
}

{
  "ok": false,
  "code": 50001,
  "message": "-12007|get expired data empty",
  "request_id": "nb_xxxxxxxx",
  "data": null
}

{
  "ok": false,
  "code": 50001,
  "message": "no account is currently logged in on this device",
  "request_id": "nb_xxxxxxxx",
  "data": null
}

{
  "ok": true,
  "code": 0,
  "message": "success",
  "request_id": "nb_xxxxxxxx",
  "data": {
    "uin": 1688850000000001,
    "name": "示例用户",
    "corpId": 1970320000000001,
    "gender": 1,
    "iconUrl": "https://example.com/avatar.png",
    "position": ""
  }
}

# 01 创建设备（只需一次）：保存返回的 data.instance_guid
curl -X POST 'https://api.xingyapi.com/api/device/create' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"type":"iPad","name":"客服设备01","version":0,"proxy":""}'
# → {"ok":true,"code":0,"message":"success","request_id":"nb_xxxxxxxx","data":{"instance_guid":"inst_xxxxxxxx"}}

# 02 获取个人信息（检查是否已登录）：新设备返回 no account（正常）；uin 非 0 → 已在线，跳到 08
curl -X POST 'https://api.xingyapi.com/api/personal/getInfo' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"instance_guid":"inst_xxxxxxxx"}'

# 03 获取二维码：展示 data.imageBase64，记下 data.uuid（不用代理 proxy 传 ""）
curl -X POST 'https://api.xingyapi.com/api/login/getQr' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"instance_guid":"inst_xxxxxxxx","proxy":""}'

# 04 检测二维码：每 2–3 秒一次；status=10 → 05；status=2 → 07；-12007 → 回到 03 重新取码
#    直连推送：每次都带同一个 callbackUrl；使用控制台转发：去掉 callbackUrl 字段
curl -X POST 'https://api.xingyapi.com/api/login/checkQr' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"instance_guid":"inst_xxxxxxxx","uuid":"A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6","proxy":"","pushHistory":false,"callbackUrl":"https://example.com/wecom/callback"}'

# 05（仅 status=10 时）提交手机企业微信上显示的验证码
curl -X POST 'https://api.xingyapi.com/api/login/submitQrCode' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"instance_guid":"inst_xxxxxxxx","uuid":"A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6","code":"123456","proxy":""}'

# 06（提交验证码后）再检测二维码：每 2–3 秒一次，直到 data.status=2（必须，否则登录未完成）
curl -X POST 'https://api.xingyapi.com/api/login/checkQr' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"instance_guid":"inst_xxxxxxxx","uuid":"A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6","proxy":"","pushHistory":false}'

# 07 获取个人信息（确认登录成功）：code=0 且 data.uin 非 0（未就绪时每 0.5–1 秒再查，最多约 10 秒）
curl -X POST 'https://api.xingyapi.com/api/personal/getInfo' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"instance_guid":"inst_xxxxxxxx"}'

# 08（直连推送时）更新回调地址：消息直接推到你的地址；用控制台回调转发则跳过；体验版不可用
curl -X POST 'https://api.xingyapi.com/api/long/updateCallbackURL' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"instance_guid":"inst_xxxxxxxx","callbackUrl":"https://example.com/wecom/callback"}'

# 开始业务调用，例如发送文本消息（把 YOUR_CONVERSATION_ID 换成对方或群的会话 ID，可从收到的回调消息里获取）
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_xxxxxxxx","conversationId":"YOUR_CONVERSATION_ID","content":"你好"}'

# 退出：先退出账号，再关闭长链（设备上已无账号时返回 no account …，可视为已退出）
curl -X POST 'https://api.xingyapi.com/api/login/logout' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"instance_guid":"inst_xxxxxxxx"}'
curl -X POST 'https://api.xingyapi.com/api/long/stop' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"instance_guid":"inst_xxxxxxxx"}'

import time
import requests

BASE = "https://api.xingyapi.com"
HEADERS = {"X-Nebula-Key": "YOUR_API_KEY"}
INSTANCE = "inst_xxxxxxxx"   # 第 01 步 device/create 返回的 instance_guid
PROXY = ""                   # 不用代理传 ""；用代理时第 03 / 04 / 05 步必须相同
CALLBACK = ""                # 直连推送地址；使用控制台转发时保持为空


def call(path, body):
    # 以响应体里的 code 判断结果（失败时 HTTP 状态码可能不是 200）
    return requests.post(BASE + path, json=body, headers=HEADERS, timeout=30).json()


def is_online(res):
    # code=0 且 uin 非 0 才算真正在线；uin 可能是数字也可能是字符串
    data = res.get("data") or {}
    return res.get("code") == 0 and str(data.get("uin") or 0) != "0"


def show_qr(image_base64):
    # 换成你自己的展示逻辑，例如网页里 <img src="data:image/png;base64,...">
    print("请用企业微信扫码，二维码图片长度：", len(image_base64))


def get_qr():
    res = call("/api/login/getQr", {"instance_guid": INSTANCE, "proxy": PROXY})
    if res.get("code") != 0:
        raise RuntimeError("取码失败：" + str(res.get("message")))
    show_qr(res["data"]["imageBase64"])
    return res["data"]["uuid"]


def wait_ready(timeout=10):
    # 第 07 步：获取个人信息，确认登录成功
    deadline = time.time() + timeout
    while time.time() < deadline:
        res = call("/api/personal/getInfo", {"instance_guid": INSTANCE})
        if is_online(res):
            return res["data"]
        time.sleep(1)
    return None


def login(max_refresh=3):
    # 第 02 步：已登录就直接返回，避免重复取码
    res = call("/api/personal/getInfo", {"instance_guid": INSTANCE})
    if is_online(res):
        return res["data"]

    uuid = get_qr()                      # 第 03 步
    refreshed = 0
    busy = 0                             # 连续 50000 的次数
    while True:                          # 第 04 步：每 2.5 秒轮询一次
        time.sleep(2.5)
        body = {"instance_guid": INSTANCE, "uuid": uuid, "proxy": PROXY, "pushHistory": False}
        if CALLBACK:
            body["callbackUrl"] = CALLBACK
        res = call("/api/login/checkQr", body)

        if res.get("code") != 0:
            msg = str(res.get("message") or "")
            if "-12007" in msg and refreshed < max_refresh:
                refreshed += 1           # 二维码过期 / uuid 无效 → 重新取码
                uuid = get_qr()
                continue
            if res.get("code") == 50000 and busy < 20:
                busy += 1
                continue                 # 服务暂时不可用：下一轮再查（连续多次失败则放弃）
            raise RuntimeError("登录失败：" + msg)

        busy = 0
        status = res["data"]["status"]
        if status in (0, 1):
            continue                     # 未扫码 / 等待手机确认
        if status == 10:                 # 第 05 步：提交验证码
            code = input("请输入手机企业微信上显示的验证码：")
            r = call("/api/login/submitQrCode",
                     {"instance_guid": INSTANCE, "uuid": uuid, "code": code, "proxy": PROXY})
            if r.get("code") != 0:
                print("验证码提交失败：", r.get("message"))
            continue                     # 第 06 步：提交后回到这里继续检测，直到 status=2
        if status == 2:
            break                        # 认证成功：立即停止轮询
        if status == 4:
            raise RuntimeError("用户在手机上取消了登录")
        raise RuntimeError("登录未完成，status=%s" % status)   # 其他状态按失败处理

    info = wait_ready()                  # 第 07 步
    if not info:
        raise RuntimeError("会话暂未就绪，请稍后再调用 getInfo 确认")
    return info


if __name__ == "__main__":
    me = login()
    print("登录成功，账号 uin：", me["uin"])

Content-Type: application/json
X-Nebula-Timestamp: 1780000000
X-Nebula-Signature: HMAC-SHA256(secret, timestamp + "." + rawBody)

{
  "instance_guid": "inst_xxxx",
  "events": [
    {
      "id": 1013420,
      "messageType": 0,
      "contentType": 0,
      "fromUserId": 7881300000000002,
      "sendTime": 1789093735,
      "content": [{ "type": 0, "text": "您好" }]
    }
  ]
}

import hmac, hashlib
sig = hmac.new(secret.encode(),
      (timestamp + ".").encode() + raw_body,
      hashlib.sha256).hexdigest()
# sig == 请求头 X-Nebula-Signature ?

Content-Type: application/json
X-Nebula-Timestamp: 1789200000
X-Nebula-Signature: <HMAC-SHA256(secret, timestamp + "." + rawBody)>
User-Agent: Nebula-Webhook/1.0

{
  "instance_guid": "inst_xxxxxxxx",
  "events": [
    {
      "id": 1013420,
      "messageType": 0,
      "contentType": 0,
      "roomId": 0,
      "fromUserId": 7881300000000002,
      "toUserId": 1688850000000001,
      "sendTime": 1789093735,
      "content": [{ "type": 0, "text": "您好" }]
    }
  ]
}

import hmac, hashlib
sig = hmac.new(secret.encode(),
      (timestamp + ".").encode() + raw_body,
      hashlib.sha256).hexdigest()
# sig == 请求头 X-Nebula-Signature ?（raw_body 用原始字节，勿重序列化）

{
  "id": 1013420,
  "messageType": 0,
  "contentType": 0,
  "roomId": 0,
  "fromUserId": 7881300000000002,
  "toUserId": 1688850000000001,
  "senderName": "",
  "summary": "您好",
  "sendTime": 1789093735,
  "syncKey": 12014383,
  "flag": 16777216,
  "appInfo": "<appInfo>",
  "extraData": "",
  "devInfo": 0,
  "content": [{ "type": 0, "text": "您好" }]
}

{ "id": 1000554, "messageType": 1, "contentType": 0, "roomId": 10000000000002,
  "fromUserId": 1688850000000011, "sendTime": 1789106713,
  "content": [{ "type": 0, "text": "就仅仅" }] }

{ "id": 1013724, "messageType": 1, "contentType": 14, "roomId": 10000000000002,
  "content": { "id": "<下载凭证>", "md5": "<md5>", "aesKey": "<aesKey>",
    "size": 1209017, "width": 1080, "height": 1920, "thumbMd5": "<md5>" } }

{ "id": 1013637, "messageType": 0, "contentType": 16, "summary": "[语音]",
  "content": { "id": "<下载凭证>", "md5": "<md5>", "aesKey": "<aesKey>", "size": 2608, "voiceTime": 2 } }

{ "id": 1013739, "messageType": 0, "contentType": 23,
  "content": { "id": "<下载凭证>", "md5": "<md5>", "aesKey": "<aesKey>",
    "size": 2533630, "width": 1920, "height": 1080, "duration": 2 } }

{ "id": 1013745, "messageType": 0, "contentType": 15,
  "content": { "id": "<下载凭证>", "md5": "<md5>", "aesKey": "<aesKey>", "name": "示例文件.jpg", "size": 1863186 } }

{ "id": 1013589, "messageType": 3, "contentType": 2357, "roomId": 10030, "fromUserId": 10030,
  "summary": "示例客户@微信申请添加你为联系人",
  "content": { "uin": 7881300000000002, "corpId": 1970320000000001,
    "source": "微信", "corpName": "示例网络科技", "customerName": "示例客户" } }