Hệ Thống API Tích Hợp
Dành Cho Đại Lý & Đối Tác

1. Tổng Quan & Xác Thực API

Mọi yêu cầu gửi đến API của LocketGold cần được gửi qua giao thức HTTPS. Hệ thống chấp nhận cả JSON Body lẫn form URL-encoded.

Lấy danh sách tất cả các gói dịch vụ đang mở bán trên website cùng giá niêm yết (web_price) và giá nhập đại lý của bạn (reseller_cost). Đại lý được tự do định giá bán lại cho khách lẻ, hệ thống chỉ khấu trừ giá sỉ từ số dư tài khoản của bạn.

Phản Hồi Mẫu (HTTP 200 OK):

{
  "ok": true,
  "packages": [
    {
      "code": "pro_ios",
      "name": "Locket Gold Vĩnh Viễn VIP (iOS)",
      "duration_text": "Vĩnh viễn",
      "web_price": 149000,
      "discount_percent": 20,
      "reseller_cost": 119200,
      "profit_margin": 29800,
      "os": "ios"
    },
    {
      "code": "basic_ios",
      "name": "Locket Gold 1 Năm (iOS)",
      "duration_text": "365 ngày",
      "web_price": 109000,
      "discount_percent": 20,
      "reseller_cost": 87200,
      "profit_margin": 21800,
      "os": "ios"
    }
  ],
  "partner": {
    "name": "Shop Locket VIP",
    "balance": 250000,
    "discount_percent": 20
  }
}

Kích hoạt tài khoản Locket Gold VIP cho khách hàng. Hệ thống tự động tra cứu giá gói trên website, khấu trừ tiền trực tiếp vào số dư tài khoản đại lý (theo % chiết khấu) và tự động tạo kèm liên kết cấu hình DNS Profile (.mobileconfig) gửi trả về ngay lập tức.

Tham Số Body (Request Body):

Phản Hồi Thành Công (HTTP 200 OK):

{
  "ok": true,
  "success": true,
  "uid": "Zg8dK21Lms9124kdsm12Kds1923l",
  "status": "activated",
  "package": {
    "name": "Locket Gold Vĩnh Viễn VIP (iOS)",
    "code": "pro_ios",
    "duration": "Vĩnh viễn (Trọn đời)"
  },
  "pricing": {
    "web_price": 149000,
    "discount_percent": 20,
    "amount_deducted": 119200,
    "remaining_balance": 130800
  },
  "dns": {
    "token": "a1b2c3d4e5f6...",
    "download_url": "https://locketgold.lol/locket_gold.mobileconfig?token=a1b2c3d4e5f6...",
    "doh_url": "https://locketgold.lol/dns-query/a1b2c3d4e5f6..."
  }
}

Phản Hồi Lỗi (Error Codes):

// 401 Unauthorized: API Key không chính xác
{ "ok": false, "error": "Invalid or inactive API key", "code": "UNAUTHORIZED" }

// 402 Payment Required: Số dư tài khoản không đủ để thanh toán gói
{ 
  "ok": false, 
  "error": "Số dư không đủ! Gói giá 119,200đ, số dư hiện tại: 50,000đ.", 
  "code": "INSUFFICIENT_BALANCE",
  "balance": 50000,
  "required_amount": 119200,
  "topup_api": "/api/v1/partner/deposit/create"
}

// 400 Bad Request: UID không hợp lệ
{ "ok": false, "error": "UID không hợp lệ", "code": "INVALID_UID" }

Cấp 1 lượt test dùng thử Locket Gold VIP trong 30 phút để đối tác kiểm thử tích hợp.
⚠️ Lưu ý quan trọng: Sau đúng 30 phút kể từ lúc kích hoạt, hệ thống sẽ tự động xóa hoàn toàn UID khỏi server. Mỗi tài khoản đăng nhập trên web chỉ được cấp 1 lượt test duy nhất (lưu vĩnh viễn theo tài khoản, không theo IP).

Tham Số Body (Request Body):

Phản Hồi Thành Công (HTTP 200 OK):

{
  "ok": true,
  "success": true,
  "is_trial": true,
  "uid": "Zg8dK21Lms9124kdsm12Kds1923l",
  "status": "activated",
  "duration_minutes": 30,
  "package_name": "Locket Gold VIP (Test 30P)",
  "activated_at": "2026-10-11 19:30:00",
  "expires_at": "2026-10-11 20:00:00",
  "message": "Kích hoạt test 30 phút thành công! Sau 30 phút UID sẽ tự động xóa khỏi server."
}

Phản Hồi Lỗi (Error Codes):

// 409 Conflict: Tài khoản/UID đã sử dụng hết lượt dùng thử 30 phút
{ "ok": false, "error": "Tài khoản của bạn đã sử dụng 1 lượt dùng thử 30 phút.", "code": "TRIAL_ALREADY_USED" }

// 401 Unauthorized: Chưa đăng nhập tài khoản web và không có API Key hợp lệ
{ "ok": false, "error": "Vui lòng đăng nhập tài khoản LocketGold trên web để dùng thử 30 phút.", "code": "LOGIN_REQUIRED" }

Kiểm tra xem một Firebase UID hoặc Link Locket đã được kích hoạt VIP trên hệ thống Locket Gold hay chưa.

Phản hồi mẫu:

{
  "ok": true,
  "uid": "Zg8dK21Lms9124kdsm12Kds1923l",
  "is_active": true,
  "details": {
    "package_name": "Locket Gold VIP",
    "status": "active",
    "activated_at": "2026-10-11 18:30:00"
  }
}

Tra cứu số dư tài khoản thực tế (balance), mức chiết khấu đại lý (discount_percent) và số đơn đã hoàn thành.

Phản hồi mẫu:

{
  "ok": true,
  "name": "Shop Locket VIP",
  "balance": 250000,
  "balance_formatted": "250,000đ",
  "discount_percent": 20,
  "used_quota": 48,
  "is_active": 1
}

Tạo giao dịch nạp tiền vào tài khoản đại lý. Hệ thống trả về mã QR VietQR MBBank. Sau khi chuyển khoản đúng nội dung, hệ thống ngân hàng tự động đối soát và cộng số dư trong 10-30 giây.

Body:

Phản hồi mẫu:

{
  "ok": true,
  "order_code": "NAP14F9A2B",
  "amount": 100000,
  "qr_url": "https://api.vietqr.io/image/970422-xxxx-qr_only.png?amount=100000&addInfo=NAP14F9A2B",
  "current_balance": 150000,
  "discount_percent": 20,
  "status_api": "/api/v1/partner/deposit/status?order_code=NAP14F9A2B"
}

5. Mẫu Code Tích Hợp Đa Ngôn Ngữ

Chọn ngôn ngữ lập trình của bạn để sao chép đoạn mã tích hợp sẵn:

curl -X POST https://locketgold.lol/api/v1/partner/activate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -d '{
    "uid": "https://locket.cam/u/username",
    "package_code": "pro_ios",
    "note": "Khach le 150k - Don #12345"
  }'

const axios = require('axios');

async function activateLocketGold(uidOrLink) {
  try {
    const res = await axios.post('https://locketgold.lol/api/v1/partner/activate', {
      uid: uidOrLink,
      package_code: 'pro_ios', // Lấy từ /api/v1/partner/packages
      note: 'Web Order #101'
    }, {
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR_API_KEY_HERE'
      }
    });
    console.log('Kích hoạt thành công:', res.data);
    console.log('Link cài DNS:', res.data.dns.download_url);
    console.log('Số dư còn lại:', res.data.pricing.remaining_balance);
    return res.data;
  } catch (error) {
    console.error('Lỗi kích hoạt:', error.response ? error.response.data : error.message);
  }
}

activateLocketGold('https://locket.cam/u/username');

import requests

url = "https://locketgold.lol/api/v1/partner/activate"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY_HERE"
}
payload = {
    "uid": "https://locket.cam/u/username",
    "package_code": "pro_ios",
    "note": "Shop Auto #888"
}

resp = requests.post(url, json=payload, headers=headers)
data = resp.json()
print("Kết quả:", data)
if data.get("ok"):
    print("Link DNS iOS:", data["dns"]["download_url"])
    print("Số dư còn lại:", data["pricing"]["remaining_balance"])

<?php
$apiKey = "YOUR_API_KEY_HERE";
$url = "https://locketgold.lol/api/v1/partner/activate";

$data = [
    "uid" => "https://locket.cam/u/username",
    "package_code" => "pro_ios",
    "note" => "Order PHP #99"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);

echo "Phản hồi: " . $response;
?>

🧪 Thử Nghiệm API Trực Tiếp (Sandbox)

Nhập UID hoặc Link Locket của khách hàng để thử nghiệm kích hoạt trực tiếp từ trình duyệt.

7. Bảng Mã Lỗi & HTTP Status Codes