SOO 开放平台 API 对接文档

// C# (.NET 6+) 最小示例：签名 + 卡密登录 + 心跳（无第三方依赖）
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

var appKey  = "你的app_key";
var secret  = "你的api_secret";
var card    = "你的卡密号";
var machine = "本机机器码";
var http    = new HttpClient();

Dictionary<string, string> Sign(Dictionary<string, string> p)
{
    p["app_key"]   = appKey;
    p["timestamp"] = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
    p["nonce"]     = Guid.NewGuid().ToString("N");
    var canon = string.Join("&",
        p.Where(x => x.Key != "sign" && x.Value != "")
         .OrderBy(x => x.Key).Select(x => $"{x.Key}={x.Value}"));
    using (var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
        p["sign"] = Convert.ToHexString(h.ComputeHash(Encoding.UTF8.GetBytes(canon))).ToLower();
    return p;
}

async Task<string> Post(string path, Dictionary<string, string> p)
{
    var body = new StringContent(JsonSerializer.Serialize(Sign(p)),
        Encoding.UTF8, "application/json");
    var resp = await http.PostAsync("https://sooyz.com" + path, body);
    return await resp.Content.ReadAsStringAsync();
}

async Task<(string token, int hbSec)> CardLogin()
{
    var r = await Post("/api/open/card/login",
        new Dictionary<string, string> { { "card", card }, { "machine", machine } });
    var data = JsonSerializer.Deserialize<JsonElement>(r);
    if (data.GetProperty("code").GetInt32() != 0) throw new Exception(r);
    var d = data.GetProperty("data");
    Console.WriteLine("登录成功 " + r);
    // 心跳间隔（秒）以服务端下发 heartbeat_sec 为准，缺省 60
    var hb = d.TryGetProperty("heartbeat_sec", out var h) ? h.GetInt32() : 60;
    return (d.GetProperty("token").GetString(), hb);
}

// 1. 卡密登录（首次自动绑定机器码）
var (token, hbSec) = await CardLogin();

// 2. 心跳保活（间隔=heartbeat_sec；返回 4015 需重登）
while (true)
{
    await Task.Delay(hbSec * 1000);
    var hr = await Post("/api/open/heartbeat",
        new Dictionary<string, string> { { "token", token }, { "machine", machine } });
    Console.WriteLine("心跳 " + hr);
    if (hr.Contains("\"4015\"")) { Console.WriteLine("会话失效，重新登录"); (token, hbSec) = await CardLogin(); }
}

// Java 11+ 最小示例：签名 + 卡密登录 + 心跳（JDK 自带 java.net.http，无第三方依赖）
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.*;

public class SooApi {
    static String appKey  = "你的app_key";
    static String secret  = "你的api_secret";
    static String card    = "你的卡密号";
    static String machine = "本机机器码";
    static HttpClient http = HttpClient.newHttpClient();

    static Map<String,String> sign(Map<String,String> p) {
        p.put("app_key", appKey);
        p.put("timestamp", String.valueOf(System.currentTimeMillis()/1000));
        p.put("nonce", UUID.randomUUID().toString().replace("-",""));
        List<String> keys = new ArrayList<>(p.keySet());
        Collections.sort(keys);
        StringBuilder canon = new StringBuilder();
        boolean first = true;
        for (String k : keys) {
            if (k.equals("sign") || p.get(k).isEmpty()) continue;
            if (!first) canon.append("&");
            first = false;
            canon.append(k).append("=").append(p.get(k));
        }
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
            byte[] h = mac.doFinal(canon.toString().getBytes(StandardCharsets.UTF_8));
            StringBuilder sb = new StringBuilder();
            for (byte b : h) sb.append(String.format("%02x", b));
            p.put("sign", sb.toString());
        } catch (Exception e) { throw new RuntimeException(e); }
        return p;
    }

    static String toJson(Map<String,String> p) {
        StringBuilder sb = new StringBuilder("{");
        boolean first = true;
        for (Map.Entry<String,String> e : p.entrySet()) {
            if (!first) sb.append(",");
            first = false;
            sb.append("\"").append(e.getKey()).append("\"")
              .append(":").append("\"").append(e.getValue()).append("\"");
        }
        return sb.append("}").toString();
    }

    static String post(String path, Map<String,String> p) throws Exception {
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://sooyz.com" + path))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(toJson(sign(p))))
            .build();
        return http.send(req, HttpResponse.BodyHandlers.ofString()).body();
    }

    static int hbSec = 60;  // 心跳间隔（秒）：登录时从 data.heartbeat_sec 读取，缺省 60

    static String cardLogin() throws Exception {
        Map<String,String> p = new HashMap<>();
        p.put("card", card); p.put("machine", machine);
        String r = post("/api/open/card/login", p);
        if (!r.contains("\"code\":0") && !r.contains("\"code\": 0")) throw new RuntimeException(r);
        System.out.println("登录成功 " + r);
        // 解析 data.heartbeat_sec（缺省 60）
        String[] hs = r.split("\"heartbeat_sec\":");
        if (hs.length > 1) hbSec = Integer.parseInt(hs[1].split(",")[0].trim());
        return r.split("\"token\":\"")[1].split("\"")[0];
    }

    public static void main(String[] args) throws Exception {
        // 1. 卡密登录（首次自动绑定机器码）
        String token = cardLogin();
        // 2. 心跳保活（间隔=heartbeat_sec；返回 4015 需重登）
        while (true) {
            Thread.sleep(hbSec * 1000L);
            Map<String,String> h = new HashMap<>();
            h.put("token", token); h.put("machine", machine);
            String hr = post("/api/open/heartbeat", h);
            System.out.println("心跳 " + hr);
            if (hr.contains("4015")) { System.out.println("会话失效，重新登录"); token = cardLogin(); }
        }
    }
}

// Go 最小示例：签名 + 卡密登录 + 心跳（标准库，无第三方依赖）
package main

import (
    "bytes"
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "net/http"
    "sort"
    "strconv"
    "strings"
    "time"
)

var (
    base    = "https://sooyz.com"
    appKey  = "你的app_key"
    secret  = "你的api_secret"
    card    = "你的卡密号"
    machine = "本机机器码"
)

func signParams(p map[string]string) map[string]string {
    p["app_key"] = appKey
    p["timestamp"] = strconv.FormatInt(time.Now().Unix(), 10)
    p["nonce"] = fmt.Sprintf("%d", time.Now().UnixNano())
    keys := make([]string, 0, len(p))
    for k := range p { keys = append(keys, k) }
    sort.Strings(keys)
    var parts []string
    for _, k := range keys {
        if k == "sign" || p[k] == "" { continue }
        parts = append(parts, k+"="+p[k])
    }
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(strings.Join(parts, "&")))
    p["sign"] = hex.EncodeToString(mac.Sum(nil))
    return p
}

func post(path string, p map[string]string) (map[string]interface{}, error) {
    body, _ := json.Marshal(signParams(p))
    resp, err := http.Post(base+path, "application/json", bytes.NewReader(body))
    if err != nil { return nil, err }
    defer resp.Body.Close()
    var out map[string]interface{}
    err = json.NewDecoder(resp.Body).Decode(&out)
    return out, err
}

func cardLogin() (string, int, error) {
    r, err := post("/api/open/card/login", map[string]string{"card": card, "machine": machine})
    if err != nil { return "", 60, err }
    if code, _ := r["code"].(float64); code != 0 { return "", 60, fmt.Errorf("%v", r) }
    data := r["data"].(map[string]interface{})
    token := data["token"].(string)
    hb := 60 // 心跳间隔（秒）：以服务端下发 heartbeat_sec 为准，缺省 60
    if v, ok := data["heartbeat_sec"].(float64); ok && v > 0 { hb = int(v) }
    fmt.Println("登录成功", data)
    return token, hb, nil
}

func main() {
    // 1. 卡密登录（首次自动绑定机器码）
    token, hbSec, err := cardLogin()
    if err != nil { fmt.Println(err); return }
    // 2. 心跳保活（间隔=heartbeat_sec；返回 4015 需重登）
    for {
        time.Sleep(time.Duration(hbSec) * time.Second)
        hr, err := post("/api/open/heartbeat", map[string]string{"token": token, "machine": machine})
        if err != nil { fmt.Println("心跳错误", err); continue }
        fmt.Println("心跳", hr)
        if code, _ := hr["code"].(float64); code == 4015 {
            fmt.Println("会话失效，重新登录")
            token, hbSec, _ = cardLogin()
        }
    }
}

<?php // PHP 最小示例：签名 + 卡密登录 + 心跳（标准库，无第三方依赖，CLI 运行）
<?php
$base   = 'https://sooyz.com';
$appKey = '你的app_key';
$secret = '你的api_secret';
$card   = '你的卡密号';
$machine = '本机机器码';

function sign_params($params) {
    global $appKey, $secret;
    $params['app_key']   = $appKey;
    $params['timestamp'] = (string)time();
    $params['nonce']     = bin2hex(random_bytes(8));
    ksort($params);                                          // 字典序
    $canon = '';
    foreach ($params as $k => $v) {
        if ($k === 'sign' || $v === '') continue;
        $canon .= $k . '=' . $v . '&';
    }
    $params['sign'] = hash_hmac('sha256', rtrim($canon, '&'), $secret);
    return $params;
}

function post($path, $params) {
    global $base;
    $params = sign_params($params);
    $ctx = stream_context_create(['http' => [
        'method'  => 'POST',
        'header'  => 'Content-Type: application/json',
        'content' => json_encode($params),
    ]]);
    return json_decode(file_get_contents($base . $path, false, $ctx), true);
}

function card_login() {
    global $card, $machine;
    $r = post('/api/open/card/login', ['card' => $card, 'machine' => $machine]);
    if ($r['code'] !== 0) { fwrite(STDERR, json_encode($r) . PHP_EOL); exit(1); }
    $d = $r['data'];
    echo "登录成功 " . json_encode($d) . PHP_EOL;
    // 心跳间隔（秒）：以服务端下发 heartbeat_sec 为准，缺省 60
    $hb = isset($d['heartbeat_sec']) && $d['heartbeat_sec'] > 0 ? (int)$d['heartbeat_sec'] : 60;
    return ['token' => $d['token'], 'hb' => $hb];
}

// 1. 卡密登录（首次自动绑定机器码）
$login = card_login(); $token = $login['token']; $hbSec = $login['hb'];

// 2. 心跳保活（间隔=heartbeat_sec；返回 4015 需重登）
while (true) {
    sleep($hbSec);
    $hr = post('/api/open/heartbeat', ['token' => $token, 'machine' => $machine]);
    echo "心跳 " . json_encode($hr) . PHP_EOL;
    if ($hr['code'] === 4015) { echo "会话失效，重新登录" . PHP_EOL; $login = card_login(); $token = $login['token']; $hbSec = $login['hb']; }
}

'================================================'
'  易语言 · 签名 + 卡密登录 + 心跳（精易模块 / 或直接 Winhttp）'
'================================================'
.版本 2
.程序集 窗口程序集_启动窗口

.子程序 取签名, 文本型
.参数 参数字典, 文本型   ' 已按字典序排好的 k=v&k=v
.参数 密钥, 文本型
.局部变量 结果, 字节集
结果 ＝ 校验_取HMAC_SHA256 (到字节集 (参数字典), 到字节集 (密钥))
返回 (取数据摘要 (结果))   ' 十六进制小写

.子程序 卡密登录, 文本型
.局部变量 时间戳, 文本型
.局部变量 随机串, 文本型
.局部变量 签名, 文本型
.局部变量 请求体, 文本型
.局部变量 返回文本, 文本型
.局部变量 结果对象, 对象
.局部变量 token, 文本型
时间戳 ＝ 到文本 (取现行时间戳 ())
随机串 ＝ 文本_取随机字符 (16)
' 参数需按 key 字典序拼接：app_key,card,machine,nonce,timestamp
签名 ＝ 取签名 (
    “app_key=” ＋ “你的app_key” ＋ “&card=” ＋ “你的卡密号”
    ＋ “&machine=” ＋ “本机机器码” ＋ “&nonce=” ＋ 随机串
    ＋ “&timestamp=” ＋ 时间戳,
    “你的api_secret”)
请求体 ＝ “{” ＋ “” ＋ “\”app_key\”:” ＋ “\”你的app_key\”” ＋ “,\”card\”:” ＋ “\”你的卡密号\”” ＋ “,\”machine\”:” ＋ “\”本机机器码\”” ＋ “,\”nonce\”:” ＋ “\”” ＋ 随机串 ＋ “\”” ＋ “,\”timestamp\”:” ＋ “\”” ＋ 时间戳 ＋ “\”” ＋ “,\”sign\”:” ＋ “\”” ＋ 签名 ＋ “\”” ＋ “}”
' 返回文本 ＝ 网页_访问_对象 (“https://sooyz.com/api/open/card/login”, 1, 请求体, , , “application/json”)
' 用 编码_Utf8到Ansi / json 解析 返回文本，取 data.token 存入全局变量 token
' 同时取 data.heartbeat_sec 存入全局变量 心跳间隔（缺省 60，5~600）
' 若 code≠0 提示错误（4010 卡密不存在 / 4011 已封禁 / 4012 机器码不匹配）
返回 (token)

.子程序 心跳保活
.局部变量 时间戳, 文本型
.局部变量 随机串, 文本型
.局部变量 签名, 文本型
.局部变量 请求体, 文本型
.局部变量 返回文本, 文本型
' 每 心跳间隔 秒调用一次（间隔=登录返回的 data.heartbeat_sec，缺省 60）；参数：token,machine + 公共参数，字典序拼接后签名
时间戳 ＝ 到文本 (取现行时间戳 ())
随机串 ＝ 文本_取随机字符 (16)
签名 ＝ 取签名 (
    “app_key=” ＋ “你的app_key” ＋ “&machine=” ＋ “本机机器码”
    ＋ “&nonce=” ＋ 随机串 ＋ “&timestamp=” ＋ 时间戳
    ＋ “&token=” ＋ 全局token,
    “你的api_secret”)
请求体 ＝ “{” ＋ “\”app_key\”:” ＋ “\”你的app_key\”” ＋ “,\”machine\”:” ＋ “\”本机机器码\”” ＋ “,\”nonce\”:” ＋ “\”” ＋ 随机串 ＋ “\”” ＋ “,\”timestamp\”:” ＋ “\”” ＋ 时间戳 ＋ “\”” ＋ “,\”token\”:” ＋ “\”” ＋ 全局token ＋ “\”” ＋ “,\”sign\”:” ＋ “\”” ＋ 签名 ＋ “\”” ＋ “}”
' 返回文本 ＝ 网页_访问_对象 (“https://sooyz.com/api/open/heartbeat”, 1, 请求体, , , “application/json”)
' 解析返回 code：0=正常；4015=会话失效需重新 卡密登录()

'================================================'
'  火山PC · 签名 + 卡密登录 + 心跳'
'================================================'
' 关键步骤（火山视窗，需引用「火山模块」或手写 HMAC）：'
' 1. 组装参数：app_key、card、machine、nonce、timestamp（心跳再加 token）'
' 2. 按键名首字母排序后拼 "k=v&k=v"（字典序，排除空值与 sign）'
' 3. 用 api_secret 做 HMAC-SHA256，转十六进制小写 = sign'
' 4. 把全部参数转 JSON 文本，POST https://sooyz.com/api/open/card/login'
' 5. 解析返回 JSON，code==0 取 data.token 保存（4012=机器码不匹配需解绑）；并保存 data.heartbeat_sec 为心跳间隔（缺省 60，5~600）'
' 6. 每 心跳间隔 秒 POST /api/open/heartbeat（间隔=登录返回 heartbeat_sec，缺省 60）；code==4015 重新登录'

' 火山视窗代码示意（伪码，方法名以你引用的模块为准）：'
' 时间戳 ＝ 取Unix时间戳 ()'
' 随机串 ＝ 文本_生成随机字符串 (16)'
' 待签名文本 ＝ "app_key=" ＋ 你的app_key ＋ "&card=" ＋ 你的卡密号'
' 待签名文本 ＝ 待签名文本 ＋ "&machine=" ＋ 本机机器码'
' 待签名文本 ＝ 待签名文本 ＋ "&nonce=" ＋ 随机串 ＋ "&timestamp=" ＋ 时间戳'
' 签名 ＝ HMAC_SHA256_十六进制 (待签名文本, 你的api_secret)'
' 发送POST请求(地址="https://sooyz.com/api/open/card/login", 数据=JSON化参数, 内容类型="application/json")'
' 返回 JSON 解析 code==0 后取 data.token 保存到全局变量'
' 心跳：每 心跳间隔 秒 发送POST请求(地址="https://sooyz.com/api/open/heartbeat", 数据=JSON化(token,machine), 内容类型="application/json")  （间隔=登录返回 data.heartbeat_sec，缺省 60）'
' 若 code==4015 → 重新执行登录流程

'================================================'
'  按键精灵（QUI / 脚本）· 签名 + 卡密登录 + 心跳'
'================================================'
' 需调用系统 COM 或使用第三方脚本插件实现 HMAC-SHA256；'
' 若脚本环境无 HMAC 库，可在本地程序内算好 sign 后由脚本调用（推荐）。'

' 按键精灵 9 / 2014 脚本示意：'
Dim appKey, secret, card, machine, ts, nonce, canon, sign, resp, token
appKey = "你的app_key" : secret = "你的api_secret"
card = "你的卡密号" : machine = "本机机器码"

' —— 卡密登录 ——'
ts = CStr(Round(GetSysTime()/1000))      ' Unix 秒级时间戳
nonce = GetTime() & Int(Rnd*100000)      ' 随机串
' 字典序拼接（app_key < card < machine < nonce < timestamp）
canon = "app_key=" & appKey & "&card=" & card & "&machine=" & machine
canon = canon & "&nonce=" & nonce & "&timestamp=" & ts
' sign = HMAC_SHA256(secret, canon) —— 用插件/COM 计算后填充
sign = 调用插件计算HMAC(canon, secret)
' 组装 JSON 并 POST https://sooyz.com/api/open/card/login，解析 code==0 取 data.token
' 并记录 data.heartbeat_sec 为心跳间隔（缺省 60，5~600）
' token = 解析返回JSON(data.token)

' —— 心跳保活：每 心跳间隔 秒执行一次（登录返回 heartbeat_sec，缺省 60） ——'
ts = CStr(Round(GetSysTime()/1000)) : nonce = GetTime() & Int(Rnd*100000)
canon = "app_key=" & appKey & "&machine=" & machine & "&nonce=" & nonce
canon = canon & "&timestamp=" & ts & "&token=" & token
sign = 调用插件计算HMAC(canon, secret)
' 组装 JSON POST https://sooyz.com/api/open/heartbeat'
' 返回 code==4015 → 回到上方重新执行卡密登录
' （计时可用 Plugin.Window 或延时循环控制，一轮 = 心跳间隔秒数，从登录返回 heartbeat_sec 读取）