通用约定

统一入口	`https://你的域名/api/{接口名称}`
请求方式	大部分为POST，特殊标注GET除外；`application/x-www-form-urlencoded`
返回格式	JSON (UTF-8)

通用返回结构：

{
    "code": 0,
    "msg": "操作成功",
    "data": {}
}

A类鉴权：app_id + sign (MD5签名降序排序)
B类鉴权：api_token (安全KEY AES加密) + admin_user + admin_pass
C类鉴权：username + password

签名算法（A类API）— MD5（降序排序）

签名步骤 (重要：按key降序 krsort)
1. 收集所有参数（排除sign），过滤空值；
2. 按参数名 降序 (krsort) 排列；
3. 拼接为 key=value&key2=value2...；
4. 末尾追加 &app_key={appKey}；
5. 计算MD5 32位小写。

PHP 示例

<?php
function buildSign($params, $appKey) {
    krsort($params);
    $str = '';
    foreach ($params as $k => $v) {
        if ($k === 'sign' || $v === '') continue;
        $str .= $k . '=' . $v . '&';
    }
    $str .= 'app_key=' . $appKey;
    return md5($str);
}
?>

安全令牌 · Admin API (AES-128-CBC)

准备：后台「系统设置 → 安全KEY」设置 secret_key。
生成 api_token：AES-128-CBC 加密 secret_key，IV随机，结果 Base64(iv+密文)

PHP 示例

function makeApiToken($plainKey) {
    $key = substr(hash('sha256', 'ylcloud_secret_key_v1', true), 0, 16);
    $iv = openssl_random_pseudo_bytes(16);
    $encrypted = openssl_encrypt($plainKey, 'aes-128-cbc', $key, OPENSSL_RAW_DATA, $iv);
    return base64_encode($iv . $encrypted);
}
$api_token = makeApiToken('你的安全KEY');

错误码参考

分类	错误场景	说明
A类	签名验证失败	msg:"签名验证失败"
A类	应用不存在/禁用	msg:"应用不存在" / "应用已被禁用"
A类	套餐过期/次数不足	msg:"套餐已过期，请续费" / "调用次数不足"
B类	安全令牌无效	msg:"安全令牌无效"
B类	管理员密码错误	msg:"管理员密码错误"
C类	账号不存在/密码错误	msg:"账号不存在" / "密码错误"

人脸识别异步说明

/api/face 支持两种模式：发起扫脸( name+idcard ) 和轮询结果( biz_token )。

// 发起响应
{ "code":0, "data":{ "status":"scan_pending", "biz_token":"xxx", "scan_url":"https://..." } }
// 查询结果
{ "code":0, "data":{ "status":"success", "result":"通过" } }