概述

欢迎使用 猎鹰API 对接接口。本文档面向第三方开发者，提供完整的接口说明、参数定义和示例代码，帮助您快速完成系统集成。

系统支持同步和异步两种下单模式，可根据业务场景灵活选择。

基础地址

https://lieyingtg.com/openapi/v1

所有接口路径均基于此基础地址。请求方式统一为 POST，参数通过 JSON Body 传递。

鉴权签名

每个请求必须携带以下 4 个 HTTP Header：

签名算法

1. 将请求 Body 中的参数按 key 字母升序排列
2. 使用 http_build_query 拼接为查询字符串
3. 拼接 &timestamp=xxx&nonce=xxx
4. 使用 app_secret 作为密钥，计算 HMAC-SHA256

签名示例（PHP）

$appKey    = 'ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$appSecret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$timestamp = (string) time();
$nonce     = bin2hex(random_bytes(8)); // 16位随机串

// 请求参数
$params = [
    'product_id' => 1,
    'quantity'   => 5,
    'mode'       => 'sync',
];

// 1. 按 key 升序
ksort($params);

// 2. 构建查询字符串
$paramString = http_build_query($params);

// 3. 拼接 timestamp 和 nonce
$signString = $paramString . '&timestamp=' . $timestamp . '&nonce=' . $nonce;

// 4. HMAC-SHA256 签名
$sign = hash_hmac('sha256', $signString, $appSecret);

// 发送请求
$ch = curl_init('https://lieyingtg.com/openapi/v1/order/create');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($params),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Api-Key: ' . $appKey,
        'X-Api-Sign: ' . $sign,
        'X-Api-Timestamp: ' . $timestamp,
        'X-Api-Nonce: ' . $nonce,
    ],
]);
$response = curl_exec($ch);

签名示例（Python）

import hashlib, hmac, time, random, string, requests, urllib.parse

app_key = 'ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
app_secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
timestamp = str(int(time.time()))
nonce = ''.join(random.choices(string.ascii_letters + string.digits, k=16))

params = {
    'product_id': 1,
    'quantity': 5,
    'mode': 'sync',
}

# 1. 按 key 升序
sorted_params = dict(sorted(params.items()))

# 2. 构建查询字符串
param_string = urllib.parse.urlencode(sorted_params)

# 3. 拼接 timestamp 和 nonce
sign_string = f"{param_string}&timestamp={timestamp}&nonce={nonce}"

# 4. HMAC-SHA256 签名
sign = hmac.new(app_secret.encode(), sign_string.encode(), hashlib.sha256).hexdigest()

headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': app_key,
    'X-Api-Sign': sign,
    'X-Api-Timestamp': timestamp,
    'X-Api-Nonce': nonce,
}
resp = requests.post('https://lieyingtg.com/openapi/v1/order/create', json=params, headers=headers)

响应格式

所有接口统一返回 JSON，HTTP 状态码始终为 200，通过 code 字段判断业务结果：

{
    "code": 0,           // 0 = 成功，非0 = 错误码
    "message": "success", // 结果描述
    "data": { ... },      // 业务数据（成功时返回）
    "request_id": "req_aB3xK9mNpQ2r" // 请求追踪ID
}

安全配置

IP 白名单（可选）

您可以为 API Key 设置 IP 白名单，限制只有指定 IP 才能调用接口。

回调地址（可选）

异步模式下单时，如果配置了回调地址，订单完成/失败后系统会主动 POST 通知到您的服务器，无需反复轮询。

错误码

获取分类列表

{
    "code": 0,
    "message": "success",
    "data": [
        {
            "category_id": 1,
            "name": "美国账号",
            "name_en": "US Accounts",
            "product_count": 12
        },
        {
            "category_id": 2,
            "name": "英国账号",
            "name_en": "UK Accounts",
            "product_count": 8
        }
    ],
    "request_id": "req_xK9mN3pQ2rBv"
}

获取商品列表

{
    "code": 0,
    "data": {
        "list": [
            {
                "product_id": 1,
                "name": "美国账号 - 直登",
                "price": "2.50",
                "stock": 156,
                "category_id": 1
            }
        ],
        "total": 12,
        "page": 1,
        "page_size": 20
    }
}

商品详情

{
    "code": 0,
    "data": {
        "product_id": 1,
        "name": "美国账号 - 直登",
        "price": "2.50",
        "stock": 156,
        "category_id": 1,
        "category_name": "美国账号",
        "min_purchase": 1,
        "max_purchase": 156
    }
}

搜索商品

{
    "code": 0,
    "data": {
        "list": [
            {
                "product_id": 3,
                "name": "美国账号 - 协议直登",
                "price": "3.00",
                "stock": 89,
                "category_id": 1
            }
        ],
        "total": 1,
        "page": 1,
        "page_size": 20
    }
}

创建订单

{
    "code": 0,
    "data": {
        "order_no": "API20260703142530AB12CD",
        "mode": "sync",
        "product_name": "美国账号 - 直登",
        "quantity": 5,
        "unit_price": "2.50",
        "total_amount": "12.50",
        "status": "completed",
        "balance_after": "187.50"
    }
}

{
    "code": 0,
    "data": {
        "order_no": "API20260703142530AB12CD",
        "mode": "async",
        "product_name": "美国账号 - 直登",
        "quantity": 200,
        "unit_price": "2.50",
        "total_amount": "500.00",
        "status": "processing",
        "message": "订单已提交，正在处理中。请通过 /order/query 查询结果",
        "balance_after": "0.00"
    }
}

查询订单

{
    "code": 0,
    "data": {
        "order_no": "API20260703142530AB12CD",
        "status": "completed",      // processing | completed | failed
        "quantity": 200,
        "total_amount": "500.00",
        "has_download": true,
        "created_at": "2026-07-03 14:25:30"
    }
}

下载文件

订单列表

{
    "code": 0,
    "data": {
        "list": [
            {
                "order_no": "API20260703142530AB12CD",
                "status": "completed",
                "quantity": 5,
                "total_amount": "12.50",
                "created_at": "2026-07-03 14:25:30"
            }
        ],
        "total": 42,
        "page": 1,
        "page_size": 20
    }
}

查询余额

{
    "code": 0,
    "data": {
        "balance": "187.50",
        "total_recharge": "500.00",
        "total_consume": "312.50",
        "account": "user@example.com"
    }
}

异步下单说明

当 mode=async 时，系统会立即返回订单号，后台队列异步处理发货。适用于大批量采购场景。

同步 vs 异步对比

异步订单处理流程

轮询建议

• 轮询间隔建议 3~5 秒，不要过于频繁
• 当 status 变为 completed 或 failed 时停止轮询
• 如果配置了回调地址，系统会主动推送结果，无需轮询

回调通知

异步模式下，如果您配置了回调地址（callback_url），订单处理完成后系统会主动 POST 通知到您的服务器。设置方式参见上方「安全配置」章节。

回调数据格式

{
    "event": "order.completed",   // order.completed 或 order.failed
    "order_no": "API20260703142530AB12CD",
    "status": "completed",        // completed 或 failed
    "message": "success",
    "quantity": 200,
    "total_amount": "500.00",
    "timestamp": 1751529930,
    "sign": "a1b2c3d4e5f6..."      // HMAC-SHA256 签名
}

验证回调签名

回调数据中包含 sign 字段，用于验证通知来源的真实性。验证步骤：

1. 从回调数据中取出 sign 字段
2. 将剩余字段按 key 升序排列，拼接为查询字符串
3. 使用您的 app_secret 计算 HMAC-SHA256
4. 比对计算结果与 sign 是否一致

// PHP 验签示例
$data = $_POST;
$receivedSign = $data['sign'];
unset($data['sign']);

ksort($data);
$signString = http_build_query($data);
$expectedSign = hash_hmac('sha256', $signString, $appSecret);

if (hash_equals($expectedSign, $receivedSign)) {
    // 签名验证通过，可信任此回调
    // 请返回 HTTP 200 表示已收到
} else {
    // 签名无效，忽略此回调
}