Developer API · v1

API 预充值部署
企业级安全对接

四重防线保护预充值余额：IP 白名单、防重放、HMAC 签名、漏桶限流。按次扣费，自动为客户部署正版授权。

登录开通 API 查看 PHP 示例

单次部署 ¥5.00

时间戳容差 30s

限流策略 60/min

安全防御架构

请求进入控制器前，经中间件逐层审查

IP 白名单

仅允许个人中心配置的服务器出口 IP，非法来源直接 403

时间戳 + Nonce

误差 ≤ 30 秒；同一 Nonce 不可重复使用

HMAC-SHA256

请求体参数防篡改，签名不匹配返回 401

漏桶限流

每 api_id 每分钟最多 60 次，防 CC 与爆破

接入准备

按顺序完成以下四步，即可开始调用

开通 API 凭证

登录个人中心 → API 开发者，获取 X-API-ID 与 api_secret

配置 IP 白名单

填写业务服务器固定出口公网 IP，多个用英文逗号分隔

预充值余额

每次部署扣 ¥5.00，余额不足返回 402 并暂停网关校验

反向代理

生产环境经 Nginx / CDN 时，确保传递 X-Forwarded-For 以匹配白名单

部署授权接口

为客户域名 + IP 自动创建授权并扣费

POST https://sq.zaobj.com/gateway/developer/deploy

请求头必填

Header	说明
`X-API-ID`	开发者 API ID
`X-API-SIGN`	HMAC-SHA256 签名
`X-API-TIMESTAMP`	Unix 秒级时间戳
`X-API-NONCE`	随机唯一串，建议 `bin2hex(random_bytes(8))`
`Content-Type`	`application/json`

签名规则

Formula

X-API-SIGN = HMAC_SHA256(raw_json_body + X-API-NONCE + X-API-TIMESTAMP, api_secret)

⚠ raw_json_body 为原始 JSON 字符串，Body 中勿包含 timestamp 字段

请求体

JSON

{
  "auth_domain": "client-site.com",
  "auth_ip": "8.8.8.8",
  "product_id": 1,
  "valid_days": 365,
  "label": "客户A商城"
}

成功响应

200 OK

{
  "code": 200,
  "msg": "License Deployed Successfully",
  "data": {
    "license_key": "SQ-XXXX-XXXX",
    "fee_charged": 5.00,
    "balance_after": 95.00
  }
}

错误码

按 HTTP 状态码与 status 字段排查问题

HTTP	status	说明
400	`MISSING_SECURITY_HEADERS`	缺少安全请求头
401	`INVALID_API_ID` / `INVALID_SIGNATURE`	凭证或签名错误
402	`INSUFFICIENT_BALANCE`	预充值余额不足
403	`REQUEST_EXPIRED` / `REPLAY_ATTACK`	时间戳过期或重放攻击
403	`IP_WHITELIST_EMPTY` / `UNAUTHORIZED_SOURCE_IP`	白名单未配置或 IP 非法
429	—	超过每分钟 60 次限流

PHP 调用示例

复制到业务服务器即可测试（需先配置白名单 IP）

PHP · cURL

$apiUrl = "https://sq.zaobj.com/gateway/developer/deploy";
$apiId = "YOUR_API_ID";
$apiSecret = "YOUR_API_SECRET";

$bodyData = json_encode([
    'product_id' => 1,
    'auth_domain' => 'client-site.com',
    'auth_ip' => '8.8.8.8',
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

$timestamp = (string) time();
$nonce = bin2hex(random_bytes(8));
$signature = hash_hmac('sha256', $bodyData . $nonce . $timestamp, $apiSecret);

$ch = curl_init($apiUrl);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $bodyData,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        "X-API-ID: {$apiId}",
        "X-API-SIGN: {$signature}",
        "X-API-TIMESTAMP: {$timestamp}",
        "X-API-NONCE: {$nonce}",
    ],
]);
$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));

封装 SDK：sdk/php/DeveloperApiClient.php

其他接口

辅助查询，部署接口需完整安全头

GET https://sq.zaobj.com/gateway/developer/deploy 接口说明（无需鉴权）

GET https://sq.zaobj.com/gateway/developer/products 可购套餐列表

POST https://sq.zaobj.com/gateway/developer/balance 查询余额（需安全头）