📘 SUP API 对接文档

最后更新：2026-05-14  |  版本：v1  |  基础地址：https://www.niceym.com/wp-json/sup-api/v1

🔐 认证方式

所有接口均采用 HMAC-SHA256 签名认证，需要在请求头中携带以下参数：

请求头	说明	示例
X-SUP-API-Key	用户的 API Key	sk_xxxxxxxxxxxx
X-SUP-Timestamp	当前 Unix 时间戳（秒），允许误差 ±5 分钟	1715643600
X-SUP-Signature	HMAC-SHA256 签名	a3f2b8c1d4e5...

签名计算方式

代码示例

// PHP 示例
$api_key    = 'sk_xxxxxxxxxxxx';
$api_secret = 'ss_yyyyyyyyyyyy';
$timestamp  = time();
$signature  = hash_hmac('sha256', (string)$timestamp, $api_secret);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.niceym.com/wp-json/sup-api/v1/resources?per_page=5');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-SUP-API-Key: ' . $api_key,
    'X-SUP-Timestamp: ' . $timestamp,
    'X-SUP-Signature: ' . $signature,
));
$response = curl_exec($ch);
$result = json_decode($response, true);

// Python 示例
import hmac, hashlib, time, requests

api_key = 'sk_xxxxxxxxxxxx'
api_secret = 'ss_yyyyyyyyyyyy'
timestamp = str(int(time.time()))
signature = hmac.new(api_secret.encode(), timestamp.encode(), hashlib.sha256).hexdigest()

headers = {
    'X-SUP-API-Key': api_key,
    'X-SUP-Timestamp': timestamp,
    'X-SUP-Signature': signature,
}
resp = requests.get('https://www.niceym.com/wp-json/sup-api/v1/resources?per_page=5', headers=headers)
data = resp.json()

📂 1. 获取分类列表

返回当前用户有权访问的分类列表。

请求

项目	值
方法	GET
路径	/categories
完整地址	https://www.niceym.com/wp-json/sup-api/v1/categories

返回示例

{
    "success": true,
    "data": [
        {
            "id": 5,
            "name": "WordPress主题",
            "slug": "wordpress-themes",
            "count": 128
        },
        {
            "id": 8,
            "name": "WordPress插件",
            "slug": "wordpress-plugins",
            "count": 96
        }
    ]
}

📋 2. 获取资源列表

分页返回用户有权访问的资源列表。

请求

项目	值
方法	GET
路径	/resources
完整地址	https://www.niceym.com/wp-json/sup-api/v1/resources

查询参数

参数	类型	默认值	说明
per_page	int	20	每页数量，最大 100
page	int	1	页码
flatten	string	-	传 true 或 1 返回扁平化字段格式，推荐使用

返回示例

{
    "success": true,
    "data": [
        {
            "id": 123,
            "title": "Flavor WordPress主题",
            "excerpt": "一款功能强大的虚拟资源下载主题...",
            "thumbnail": "https://example.com/wp-content/uploads/2026/05/flavor.jpg",
            "date": "2026-05-10 14:30:00",
            "url": "https://example.com/flavor-theme.html",
            "categories": [
                { "id": 5, "name": "WordPress主题", "slug": "wordpress-themes" }
            ],
            "is_product": true,
            "price": "29.9",
            "views": 1520
        }
    ],
    "total": 328,
    "pages": 17,
    "current_page": 1,
    "per_page": 20
}

📄 3. 获取资源详情

获取单个资源的完整信息。

请求

项目	值
方法	GET
路径	/resource/{id}
完整地址	https://www.niceym.com/wp-json/sup-api/v1/resource/123

路径参数

参数	类型	说明
id	int	资源文章ID

查询参数

参数	类型	说明
format	string	传 sup 返回SUP标准格式（主题无关，推荐）
flatten	string	传 true 或 1 返回扁平化字段格式

SUP标准格式返回示例（format=sup）

{
    "success": true,
    "data": {
        "id": 123,
        "title": "Flavor WordPress主题",
        "content": "<p>完整HTML内容...</p>",
        "excerpt": "摘要文本...",
        "thumbnail": "https://example.com/uploads/flavor.jpg",
        "date": "2026-05-10 14:30:00",
        "modified": "2026-05-12 09:00:00",
        "categories": [
            { "id": 5, "name": "WordPress主题", "slug": "wordpress-themes" }
        ],
        "tags": [
            { "id": 12, "name": "虚拟资源", "slug": "virtual-resource" }
        ],
        "sup_is_product": true,
        "sup_product_type": "virtual",
        "sup_price": 29.9,
        "sup_downloads": [
            { "title": "蓝奏云", "url": "", "password": "ab12" }
        ],
        "sup_info": [
            { "title": "版本", "desc": "3.2.1" },
            { "title": "授权", "desc": "永久授权" }
        ],
        "sup_demo_url": "https://demo.example.com",
        "sup_views": 1520,
        "sup_sales": 230
    }
}

⬇️ 4. 获取下载地址

获取资源的真实下载地址，需用户具有该分类的访问权限。

请求

项目	值
方法	GET
路径	/get-down-url
完整地址	https://www.niceym.com/wp-json/sup-api/v1/get-down-url?post_id=123

查询参数

参数	类型	必填	说明
post_id	int	是	资源文章ID

请求头（额外）

请求头	说明
X-SUP-SITE-URL	您的SUP站点域名（用于白名单校验）

返回示例

{
    "success": true,
    "down_info": [
        {
            "title": "版本信息",
            "desc": "v3.2.1 永久授权"
        }
    ],
    "ceo_shop_virtual_info": [
        {
            "name": "标准版",
            "price": "29.9",
            "down": [
                {
                    "name": "蓝奏云下载",
                    "url": "https://xxx.lanzou.com/xxxxx",
                    "hide": "ab12"
                }
            ]
        }
    ]
}

❌ 错误码说明

HTTP状态码	错误代码	说明
400	missing_params	缺少必要的认证参数（API Key / Timestamp / Signature）
400	invalid_timestamp	时间戳无效或已过期（误差超过5分钟）
400	missing_param	缺少必要的请求参数
401	invalid_api_key	API Key 无效
401	invalid_signature	签名验证失败
403	account_disabled	API权限已被禁用
403	vip_expired	VIP已过期（严格模式）
403	url_not_set	未设置SUP站点URL
403	url_not_allowed	请求来源不在白名单内
403	no_permission	无权访问该资源
404	resource_not_found	资源不存在
429	rate_limit_exceeded	请求频率超限

🧪 在线测试工具