logo logo
user登录
首页 我的订单 个人中心

API 接口文档

本系统提供标准 RESTful API，支持商品查询、下单、订单状态与账户信息查询。

API Version 1.0 - RESTful
开始
概览 身份验证
接口节点
创建订单 POST 订单状态 GET 订单列表 GET 商品 GET 分类 GET 余额 GET 账户信息 GET
参考
错误码

API 概览

系统 API 基本信息

Base URL https://gejuge.com/api/v1
API Key 管理 API 密钥
Content-Type application/json
Response JSON
管理 API 密钥 访问 API 密钥页面 以创建、管理并查看您的 API 使用历史。

API 身份验证

API 请求身份验证方式

所有 API 请求需要包含以下 headers：

Header 描述
X-API-Key 您的 API Key（40 个字符，以 sk_live_ 开头）
X-API-Secret 您的 API Secret（74 个字符，以 sk_secret_ 开头）
Content-Type application/json （用于 POST 请求）
Headers 示例
HTTP Headers 
X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
Content-Type: application/json
安全提示 请妥善保管 API Key 和 API Secret。不要共享或提交到源代码中。建议使用环境变量存储。

创建订单

创建订单并完成支付

POST https://gejuge.com/api/v1/orders/create
请求体
Parameter Type 描述
items 必填 array 需要购买的商品列表
items[].product_id 必填 integer 商品 ID（从 /products/list 获取）
items[].quantity integer 购买数量（默认：1）
items[].fields object 附加字段（如果商品要求）
coupon_code string 优惠码（如有）
代码示例
PHP 
<?php
$apiKey = 'sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';
$apiSecret = 'sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2';

$data = [
    'items' => [
        ['product_id' => 18, 'quantity' => 1, 'fields' => ['email' => 'user@example.com']]
    ],
    'coupon_code' => ''
];

$ch = curl_init('https://gejuge.com/api/v1/orders/create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey,
        'X-API-Secret: ' . $apiSecret
    ]
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
?>
响应示例
成功响应 
{
  "success": true,
  "message": "订单创建成功",
  "data": {
    "orders": [{
      "trans_id": "ORD1703750400ABC",
      "product_name": "高级产品",
      "status": "completed",
      "total": 100000
    }],
    "summary": {
      "total_amount": 100000,
      "new_balance": 400000
    }
  }
}

订单状态

查询订单状态与交付内容

GET https://gejuge.com/api/v1/orders/status?trans_id={trans_id}
查询参数
Parameter Type 描述
trans_id 必填 string 创建订单后返回的交易号
代码示例
PHP 
<?php
$transId = 'ORD1703750400ABC';
$url = 'https://gejuge.com/api/v1/orders/status?trans_id=' . $transId;

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
        'X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2'
    ]
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);
?>
响应示例
成功响应 
{
  "success": true,
  "timestamp": 1770020629,
  "request_id": "req_69805f15a5ed77.94324321",
  "data": {
    "order": {
      "id": 36,
      "trans_id": "PO8153690",
      "user_id": 1,
      "product": {
        "id": 21,
        "name": "Figma 产品",
        "slug": "san-pham-figma",
        "image": "https://example.com/product.jpg"
      },
      "quantity": 2,
      "total_price": 1600000,
      "sale_price": 400000,
      "discount_amount": 0,
      "coupon_code": null,
      "final_amount": 400000,
      "fields_data": [],
      "status": "completed",
      "payment_status": "paid",
      "order_source": "api",
      "created_at": "2026-02-02 15:23:14",
      "updated_at": "2026-02-02 15:23:14"
    },
    "delivery": {
      "items": ["Account: user@mail.com | Pass: abc123", "Account: user2@mail.com | Pass: xyz789"],
      "delivered_count": 2,
      "expected_count": 2
    },
    "execution_time": 0.0238
  }
}

订单列表

分页查询订单列表

GET https://gejuge.com/api/v1/orders/list
查询参数
Parameter Type 描述
page integer 页码（默认：1）
limit integer 每页数量（默认：20，最大：100）
status string 过滤：pending, processing, completed, cancelled
代码示例
cURL 
curl "https://gejuge.com/api/v1/orders/list?page=1&limit=20&status=completed" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
响应示例
成功响应 
{
  "success": true,
  "data": {
    "orders": [{
      "id": 1234,
      "trans_id": "ORD-1705678901-ABC123",
      "product": {
        "id": 10,
        "name": "Windows 11 Pro 密钥",
        "slug": "windows-11-pro-key"
      },
      "quantity": 2,
      "total_price": 1500000,
      "final_amount": 1350000,
      "status": "completed",
      "payment_status": "paid",
      "created_at": "2026-01-19 10:30:00"
    }],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 45,
      "total_pages": 3,
      "has_more": true
    },
    "execution_time": 0.0234
  }
}

商品列表

查询商品列表

GET https://gejuge.com/api/v1/products/list
查询参数
Parameter Type 描述
page integer 页码（默认：1）
limit integer 每页数量（默认：10，最大：100）
category_id integer 按分类过滤
search string 按名称搜索
sort string 排序：newest, oldest, price_asc, price_desc, bestseller
分页 API 每页最多返回 100 个商品。使用 page 参数并检查响应中的 pagination.has_more 以获取所有商品。
代码示例
PHP - 获取所有商品（分页） 
<?php
$apiKey = 'sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';
$apiSecret = 'sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2';
$baseUrl = 'https://gejuge.com/api/v1';

$allProducts = [];
$page = 1;
$limit = 100; // 每页最多 100 个商品

do {
    $url = $baseUrl . '/products/list?page=' . $page . '&limit=' . $limit;

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $apiKey,
            'X-API-Secret: ' . $apiSecret
        ]
    ]);

    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if (!$response['success']) break;

    $products = $response['data']['products'] ?? [];
    $allProducts = array_merge($allProducts, $products);

    $hasMore = $response['data']['pagination']['has_more'] ?? false;
    $page++;
} while ($hasMore);

echo '总商品数: ' . count($allProducts);
?>
响应字段（商品）
Field Type 描述
id integer 商品 ID
name string 商品名称
price float 价格
is_instant boolean 自动发货
stock_count integer 库存数量（如果 is_instant = true）
in_stock boolean 是否有货
fields array 下单时需要填写的字段列表
响应示例
成功响应 
{
  "success": true,
  "timestamp": 1769604661,
  "request_id": "req_697a063503ed57.32834148",
  "data": {
    "products": [{
      "id": 29,
      "name": "Adobe Creative Cloud 全应用密钥",
      "slug": "key-adobe-creative-cloud-all-apps",
      "image": "https://example.com/product.jpg",
      "description": "<p>商品描述...</p>",
      "category": {
        "id": 5,
        "name": "办公软件",
        "slug": "office-software",
        "image": "https://example.com/category.jpg"
      },
      "categories": [
        {"id": 5, "name": "办公软件", "slug": "office-software", "image": "https://example.com/category.jpg"},
        {"id": 14, "name": "工作", "slug": "lam-viec", "image": null}
      ],
      "min_price": 375000,
      "max_price": 375000,
      "sold": 24,
      "rating": 4.5,
      "plans": [{
        "id": 319,
        "name": "Adobe Creative Cloud 全应用密钥",
        "price": 375000,
        "sale_price": 0,
        "final_price": 375000,
        "is_instant": true,
        "stock_count": 50,
        "in_stock": true,
        "description": "",
        "fields": []
      }]
    }],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total": 21,
      "total_pages": 3,
      "has_more": true
    },
    "execution_time": 0.0828
  }
}

分类列表

查询商品分类

GET https://gejuge.com/api/v1/categories/list
查询参数
Parameter Type 描述
parent_id integer 按父分类过滤
include_children boolean 包含子分类（0 或 1）
include_products boolean 包含商品数量（0 或 1）
代码示例
cURL 
curl "https://gejuge.com/api/v1/categories/list?include_children=1" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
响应示例
成功响应 
{
  "success": true,
  "timestamp": 1770022554,
  "request_id": "req_6980669a4793d9.70486853",
  "data": {
    "categories": [{
      "id": 3,
      "name": "娱乐",
      "slug": "giai-tri",
      "description": "",
      "image": "https://example.com/category/DOQ4.png",
      "parent_id": 1,
      "sort_order": 9
    }, {
      "id": 5,
      "name": "办公软件",
      "slug": "office-software",
      "description": "",
      "image": "https://example.com/category/9IRK.png",
      "parent_id": 1,
      "sort_order": 4
    }, {
      "id": 1,
      "name": "工具",
      "slug": "tien-ich",
      "description": "",
      "image": "https://example.com/category/EIT3.png",
      "parent_id": 0,
      "sort_order": 0
    }],
    "total": 15,
    "execution_time": 0.0341
  }
}

检查余额

查询当前账户余额

GET https://gejuge.com/api/v1/account/balance
代码示例
cURL 
curl "https://gejuge.com/api/v1/account/balance" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
响应示例
成功响应 
{
  "success": true,
  "timestamp": 1770022345,
  "request_id": "req_698065c9694a56.14017855",
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@cmsnt.co"
    },
    "balance": {
      "current": 93537500,
      "total_deposited": 100000000,
      "currency": "VND",
      "formatted": "93.537.500đ"
    },
    "execution_time": 0.0258
  }
}

账户信息

查询账户信息

GET https://gejuge.com/api/v1/account/info
代码示例
cURL 
curl "https://gejuge.com/api/v1/account/info" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
响应示例
成功响应 
{
  "success": true,
  "timestamp": 1770022432,
  "request_id": "req_69806620805ae3.29218122",
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@cmsnt.co",
      "phone": "",
      "balance": 93537500,
      "total_deposited": 100000000,
      "created_at": null
    },
    "api_key": {
      "name": "API Key",
      "permissions": [
        "orders.create",
        "orders.list",
        "orders.status",
        "products.list",
        "account.balance",
        "account.info"
      ],
      "rate_limit": 60,
      "daily_limit": 10000,
      "expires_at": null,
      "created_at": "2026-02-02 14:53:35"
    },
    "orders_summary": {
      "total": 12,
      "pending": 3,
      "completed": 8
    },
    "api_usage_today": {
      "period": "day",
      "start_time": "2026-02-02 00:00:00",
      "total_requests": 5,
      "success_requests": 5,
      "failed_requests": 0,
      "success_rate": 100
    },
    "execution_time": 0.0449
  }
}

错误码

常见错误码说明

错误码 HTTP 描述
INVALID_API_KEY 401 无效的 API Key
INVALID_API_SECRET 401 API Secret 不正确
DISABLED_API_KEY 401 API Key 已被禁用
RATE_LIMIT_EXCEEDED 429 超出请求频率限制
IP_NOT_ALLOWED 403 IP 不在白名单中，禁止访问
PERMISSION_DENIED 403 没有执行权限
INSUFFICIENT_BALANCE 400 余额不足
PRODUCT_NOT_FOUND 404 商品不存在
OUT_OF_STOCK 400 商品已售罄
错误响应格式
错误响应 
{
  "success": false,
  "message": "余额不足以支付",
  "data": {
    "error_code": "INSUFFICIENT_BALANCE"
  }
}