⚡
LOCKET GOLD CTV REST API v1.0

Tài liệu kỹ thuật đấu bot & tự động kích hoạt

Hệ thống API hoạt động 24/7 • Kích hoạt tức thì 1-3s

Bộ API Kích Hoạt Locket Gold Dành Cho Cộng Tác Viên & Đại Lý

Tích hợp dễ dàng vào Bot Telegram riêng, Website shop bán hàng tự động hoặc script quản lý. Tự động kiểm tra số dư, trừ lượt và cấp Gold ngay cho khách.

BASE URL:
https://duckystore.click/api/v1

1 Quy Trình 3 Bước Để Đấu Bot Tự Động

Bước 1
Lấy API Key

Mở Bot Telegram, gõ lệnh /api hoặc vào ví bấm 🔑 API Đấu Bot để copy API Key bí mật của bạn.

Bước 2
Nạp Lượt Số Dư

Nạp số dư lượt qua VietQR Auto Pay2S trực tiếp trên bot hoặc liên hệ Admin cấp hạn mức.

Bước 3
Gọi Endpoint Kích Hoạt

Gửi request POST tới /api/v1/grant với username của khách để kích hoạt Gold tức thì!

2 Xác Thực (Authentication)

Mỗi yêu cầu gửi đến hệ thống đều yêu cầu phải có API Key hợp lệ của CTV. Bạn có thể truyền API Key bằng một trong hai cách dưới đây (khuyên dùng Header):

# Cách 1: Sử dụng Header x-api-key (Khuyên dùng)
x-api-key: ctv_live_5322128759_9f4b7a1e0c82d4...
# Cách 2: Sử dụng Bearer Token
Authorization: Bearer ctv_live_5322128759_9f4b7a1e0c82d4...

Chi Tiết Các Endpoint API

Chuẩn JSON RESTful
GET /api/v1/me
Lấy thông tin tài khoản & số dư ví CTV

Dùng để kiểm tra số dư lượt còn lại trước khi bot của bạn cho phép khách hàng đặt đơn.

Ví dụ Response Thành công (HTTP 200) 200 OK
{
  "status": "success",
  "data": {
    "user_id": "5322128759",
    "username": "ducky_reseller",
    "name": "Ducky Reseller",
    "balance_slots": 25,
    "balance_money": 625000,
    "balance_formatted": "625.000 đ",
    "slots_formatted": "25 lượt",
    "total_granted": 142,
    "api_enabled": true,
    "price_per_slot": 25000
  }
}
GET /api/v1/packages
Danh sách các gói Gold đang mở bán

Lấy danh sách các gói thời hạn (1 tháng, 3 tháng, 6 tháng, 1 năm, Vĩnh viễn) cùng số lượt tương ứng.

Ví dụ Response (HTTP 200) 200 OK
{
  "status": "success",
  "packages": [
    { "id": "m1", "name": "1 tháng", "days": 30, "slots_required": 1, "price": 25000 },
    { "id": "m3", "name": "3 tháng", "days": 90, "slots_required": 1, "price": 25000 },
    { "id": "m6", "name": "6 tháng", "days": 180, "slots_required": 1, "price": 25000 },
    { "id": "y1", "name": "1 năm", "days": 365, "slots_required": 1, "price": 25000 },
    { "id": "forever", "name": "Vĩnh viễn", "days": 0, "slots_required": 2, "price": 50000 }
  ]
}
POST /api/v1/grant Chính
Tự động kích hoạt Locket Gold cho khách

Khi khách hàng hoàn tất thanh toán trên Bot hoặc Web của bạn, gọi endpoint này để tự động cấp Gold. Hệ thống sẽ kiểm tra số dư lượt của bạn, trừ lượt và cấp ngay lập tức.

Các tham số Request Body (JSON)

Tham số Kiểu Bắt buộc Mô tả
username String Có Username Locket (vd: nguyenvana) hoặc link profile (vd: https://locket.cam/nguyenvana).
package String / Int Tùy chọn ID gói (y1, m1, forever) hoặc số ngày (365, 30). Mặc định là gói 1 năm (365 ngày).
custom_id String Tùy chọn Mã đơn hàng riêng của bạn để đối soát (vd: BOT_ORD_9876).
Request Payload (JSON)
{
  "username": "nguyenvana",
  "package": "y1",
  "custom_id": "ORDER_CTV_1024"
}
Response Thành công (HTTP 200) 200 OK
{
  "status": "success",
  "message": "Kích hoạt Locket Gold thành công!",
  "data": {
    "order_id": "ORD_1790675849_A8F2E",
    "custom_id": "ORDER_CTV_1024",
    "username": "nguyenvana",
    "package": {
      "id": "y1",
      "name": "1 năm",
      "days": 365
    },
    "slots_deducted": 1,
    "balance_remaining": 24,
    "dns_instructions": {
      "web_url": "https://dns.duckystore.click",
      "download_url": "https://dns.duckystore.click/LocketGold.mobileconfig"
    },
    "timestamp": "2026-09-29T17:05:00.000Z"
  }
}
GET /api/v1/status
Kiểm tra trạng thái Gold của tài khoản

Tham số query: ?username=nguyenvana

{
  "status": "success",
  "username": "nguyenvana",
  "data": {
    "has_gold": true,
    "state": "active",
    "in_list": true,
    "uid": "1a2b3c4d5e",
    "expiresAt": "2027-09-29 17:05:00"
  }
}
POST /api/v1/cancel
Thu hồi & Hoàn lại lượt (Chính sách 24h)
⚠️ Lưu ý chính sách hoàn lượt: Chỉ tài khoản do chính CTV nâng cấp trong vòng 24 giờ qua và chưa bị hoàn lượt trước đó mới được chấp nhận thu hồi và hoàn trả lại số lượt vào ví.
Payload (JSON)
{
  "username": "nguyenvana"
}
Response (HTTP 200)
{
  "status": "success",
  "message": "Thu hồi và hoàn lượt thành công!",
  "data": {
    "username": "nguyenvana",
    "slots_refunded": 1,
    "balance_remaining": 25,
    "timestamp": "2026-09-29T17:10:00.000Z"
  }
}
GET /api/v1/history
Xem lịch sử các đơn gọi qua API

Tham số tùy chọn: ?limit=20 (tối đa 100).

{
  "status": "success",
  "total": 2,
  "history": [
    {
      "order_id": "ORD_1790675849_A8F2E",
      "custom_id": "ORDER_CTV_1024",
      "type": "api_grant_gold",
      "username": "nguyenvana",
      "days": "365 ngày",
      "slots": 1,
      "timestamp": "2026-09-29T17:05:00.000Z"
    }
  ]
}
🧪

Công Cụ Gửi Thử Nghiệm API Trực Tiếp

Test trực tiếp từ trình duyệt

Dán mã API Key của bạn vào bên dưới để thử nghiệm gửi request trực tiếp đến hệ thống:

💻 Code Mẫu Tích Hợp Vào Bot

Bạn chỉ cần copy đoạn code dưới đây và dán thẳng vào mã nguồn Bot Telegram của mình:

import requests

API_KEY = "ctv_live_YOUR_API_KEY_HERE"
BASE_URL = "https://duckystore.click/api/v1"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}

# 1. Kiểm tra số dư ví CTV
def check_balance():
    res = requests.get(f"{BASE_URL}/me", headers=headers)
    return res.json()

# 2. Tự động kích hoạt Gold cho khách
def activate_locket_gold(username, package_id="y1", custom_id=""):
    payload = {
        "username": username,
        "package": package_id,
        "custom_id": custom_id
    }
    res = requests.post(f"{BASE_URL}/grant", headers=headers, json=payload)
    data = res.json()
    if res.status_code == 200 and data.get("status") == "success":
        print(f"✅ Kích hoạt thành công cho {username}!")
        return data["data"]
    else:
        print(f"❌ Kích hoạt thất bại: {data.get('message')}")
        return None

# Chạy thử
if __name__ == "__main__":
    print("Số dư:", check_balance())
    # activate_locket_gold("nguyenvana", package_id="y1", custom_id="DON_01")

⚠️ Danh Sách Mã Lỗi (Error Codes)

HTTP Code Mã lỗi (error_code) Mô tả & Hướng xử lý
401 UNAUTHORIZED Chưa truyền API Key hoặc header rỗng.
401 INVALID_API_KEY API Key không tồn tại hoặc đã bị đổi mới.
403 API_DISABLED Tài khoản CTV bị khóa quyền gọi API. Liên hệ Admin để mở.
402 INSUFFICIENT_BALANCE Số dư lượt cấp của CTV không đủ. Cần nạp thêm lượt.
400 MISSING_USERNAME Thiếu username cần kích hoạt trong request body.
400 NOT_OWNER / EXPIRED Không thể thu hồi: Tài khoản không do CTV nâng hoặc đã quá 24 giờ.
500 SERVER_ERROR Lỗi kết nối máy chủ hoặc máy chủ Locket bận.