Tài liệu kỹ thuật đấu bot & tự động kích hoạt
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.
https://duckystore.click/api/v1
Nếu gặp khó khăn khi đấu nối API hoặc muốn nạp số lượng lớn với chiết khấu tốt hơn, hãy liên hệ Quản trị viên.
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.
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.
Gửi request POST tới /api/v1/grant với username của khách để kích hoạt Gold tức thì!
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):
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.
{
"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
}
}
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.
{
"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 }
]
}
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.
| 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). |
{
"username": "nguyenvana",
"package": "y1",
"custom_id": "ORDER_CTV_1024"
}
{
"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"
}
}
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"
}
}
{
"username": "nguyenvana"
}
{
"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"
}
}
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"
}
]
}
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:
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")
const axios = require('axios');
const API_KEY = 'ctv_live_YOUR_API_KEY_HERE';
const BASE_URL = 'https://duckystore.click/api/v1';
const client = axios.create({
baseURL: BASE_URL,
headers: {
'x-api-key': API_KEY,
'Content-Type': 'application/json'
}
});
// 1. Kiểm tra số dư lượt của CTV
async function getBalance() {
const res = await client.get('/me');
return res.data;
}
// 2. Tự động kích hoạt Locket Gold cho khách
async function grantGold(username, packageId = 'y1', customId = '') {
try {
const res = await client.post('/grant', {
username,
package: packageId,
custom_id: customId
});
return res.data;
} catch (err) {
throw new Error(err.response?.data?.message || err.message);
}
}
// Gọi thử
(async () => {
const bal = await getBalance();
console.log('Số dư hiện tại:', bal.data.slots_formatted);
})();
# 1. Kiểm tra số dư ví CTV
curl -X GET "https://duckystore.click/api/v1/me" \
-H "x-api-key: ctv_live_YOUR_API_KEY_HERE"
# 2. Tự động kích hoạt Locket Gold cho khách
curl -X POST "https://duckystore.click/api/v1/grant" \
-H "x-api-key: ctv_live_YOUR_API_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"username": "nguyenvana",
"package": "y1",
"custom_id": "ORDER_12345"
}'
# 3. Kiểm tra trạng thái Gold của user
curl -X GET "https://duckystore.click/api/v1/status?username=nguyenvana" \
-H "x-api-key: ctv_live_YOUR_API_KEY_HERE"
# 4. Thu hồi & Hoàn lượt trong 24h
curl -X POST "https://duckystore.click/api/v1/cancel" \
-H "x-api-key: ctv_live_YOUR_API_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{"username": "nguyenvana"}'
| 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. |