Hạ Tầng Luseller API Specification

Kết Nối Bán Hàng Trực Tiếp Qua Bot Telegram

Luseller API chạy đồng thời và kết nối 1:1 với bot Telegram. Tự động áp dụng giá CTV, trừ ví bot an toàn và xử lý đồng bộ cả sản phẩm kho tự động lẫn sản phẩm duyệt thủ công (Youtube Premium, Canva Edu 2 năm).

34+ Sản Phẩm

Danh mục số & tài khoản bản quyền

Youtube 10k · Canva 5k

Giá CTV cố định & không lo hết hàng

Ví Bot 1:1

API Key gắn theo Telegram ID cá nhân

Tải Toàn Bộ Tài Liệu READAPI.md Bao gồm chi tiết 7 Endpoints, mã hóa ID sản phẩm, cơ chế duyệt đơn & code mẫu Python / Node.js

Live API Console (Playground)

Chưa Đăng Nhập (Locked)

Yêu Cầu API Key Để Mở Khóa Console

Live Console kết nối trực tiếp với tài khoản Telegram bot của bạn. Vui lòng nhập API Key (lấy bằng cách gửi lệnh /api trong bot) để mở khóa console và thử nghiệm request.

Chưa có Key? Mở bot Telegram của bạn, nhắn tin /api để nhận API Key miễn phí.

Đã Xác Thực Người dùng Telegram | Ví Bot: 0đ | Hạng: CTV Đồng

Thử nghiệm các API trực tiếp ngay trên trình duyệt. Nhấn vào các Preset dưới đây để nạp nhanh tham số:

Method

Endpoint URL

Xác Thực & Quản Lý API Key

Mỗi API Key liên kết 1:1 với tài khoản Telegram trên bot. Để tạo hoặc lấy API Key của bạn, hãy mở bot Telegram và gửi lệnh /api.

Cấu trúc HTTP Header xác thực

X-API-Key: sk_bot_YOUR_API_KEY
Content-Type: application/json

Bảng Giá & Chiết Khấu CTV

Khi request gửi kèm API Key của CTV, trường user_price sẽ tự động tính theo giá CTV đã làm tròn xuống hàng nghìn:

Hạng CTV	Mức Chi Tiêu Tích Lũy	Chiết Khấu Thêm	Youtube 1M / Canva 2Y
Hạng Đồng	0 - 5.000.000 VNĐ	Giá gốc CTV (+0%)	10.000đ / 5.000đ
Hạng Bạc	5.000.000 - 10.000.000 VNĐ	Giảm thêm -5% đơn hàng	Áp dụng theo rank
Hạng Vàng	> 10.000.000 VNĐ	Giảm thêm -10% đơn hàng	Áp dụng theo rank

Vòng Đời Đơn Hàng & Quy Trình Duyệt Thủ Công

Một số sản phẩm đặc thù (như Youtube Premium #103 và Canva Edu 2 năm #104) yêu cầu Admin duyệt và kích hoạt thủ công trên email khách hàng. Quy trình xử lý khép kín diễn ra như sau:

Gửi POST /api/orders/buy

Gửi kèm product_id và email khách hàng cần kích hoạt.

Trừ Ví & Đặt Chờ Duyệt

Số dư ví bot bị trừ ngay. Đơn nhận trạng thái NEEDS_REVIEW.

Bot Báo Admin Telegram

Admin nhận tin nhắn kèm 2 nút: [Xác Nhận Kích Hoạt] và [Hủy & Hoàn Tiền].

Polling Check Trạng Thái

Đối tác gọi GET /api/orders/:id hoặc GET /api/orders?status=NEEDS_REVIEW.

Hoàn Tất Hoặc Hoàn Tiền

Admin duyệt -> COMPLETED. Admin hủy -> CANCELLED (tự hoàn 100% ví).

GET /api/products Auth Tùy Chọn (Tính Giá CTV)

GET https://lucius.top/api/products

Lấy toàn bộ danh sách sản phẩm đang mở bán trên bot. Nếu gửi kèm X-API-Key, hệ thống tự động tính toán user_price theo đúng cấp bậc CTV của tài khoản.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`X-API-Key`	Header	String	Tùy chọn	API Key CTV để áp dụng giá chiết khấu riêng vào trường `user_price`

cURL Request Mẫu

curl -X GET "https://lucius.top/api/products"   -H "X-API-Key: sk_bot_YOUR_API_KEY"

200 OK Phản hồi mẫu (JSON tinh gọn)

{
  "success": true,
  "count": 34,
  "is_authenticated": true,
  "caller_is_ctv": true,
  "data": [
    {
      "id_product": "7ABo5OI",
      "product_id": "7ABo5OI",
      "name": "Youtube Premium 1 tháng",
      "category_id": 1,
      "description": "- Sử dụng trong vòng 25-30 ngày...",
      "status": "active",
      "in_stock": true,
      "public_price": 20000,
      "ctv_price": 10000,
      "user_price": 10000,
      "is_ctv_applied": true,
      "requires_email": true,
      "manual_activation": true
    },
    {
      "id_product": "7ARQMFn",
      "product_id": "7ARQMFn",
      "name": "Canva Edu 2 năm (BHF)",
      "category_id": 1,
      "description": "- Kích hoạt Canva Edu 2 Năm trực tiếp...",
      "status": "active",
      "in_stock": true,
      "public_price": 15000,
      "ctv_price": 5000,
      "user_price": 5000,
      "is_ctv_applied": true,
      "requires_email": true,
      "manual_activation": true
    }
  ]
}

GET /api/products/:id Auth Tùy Chọn

GET https://lucius.top/api/products/:id

Tra cứu thông tin chi tiết của 1 sản phẩm cụ thể theo id mã hóa (ví dụ: 7ABo5OI cho Youtube Premium, 7ARQMFn cho Canva Edu) hoặc theo ID số cũ (103, 104).

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`id`	Path	String \| Number	Bắt buộc	Mã sản phẩm mã hóa (ví dụ: `7ABo5OI`) hoặc ID số (`103`)
`X-API-Key`	Header	String	Tùy chọn	API Key để tính `user_price` theo rank CTV

cURL Request Mẫu

curl -X GET "https://lucius.top/api/products/7ABo5OI"   -H "X-API-Key: sk_bot_YOUR_API_KEY"

200 OK Phản hồi mẫu

{
  "success": true,
  "data": {
    "id_product": "7ABo5OI",
    "product_id": "7ABo5OI",
    "name": "Youtube Premium 1 tháng",
    "category_id": 1,
    "description": "- Sử dụng trong vòng 25-30 ngày...",
    "status": "active",
    "in_stock": true,
    "public_price": 20000,
    "ctv_price": 10000,
    "user_price": 10000,
    "is_ctv_applied": true,
    "requires_email": true,
    "manual_activation": true
  }
}

POST /api/orders/buy Yêu Cầu X-API-Key

POST https://lucius.top/api/orders/buy

Thực hiện mua sản phẩm qua API. Tiền được trừ tự động từ số dư ví bot Telegram của bạn. Nếu là sản phẩm duyệt thủ công (Youtube 7ABo5OI, Canva 7ARQMFn), đơn lập tức vào trạng thái NEEDS_REVIEW và được gửi thông báo tới Telegram của Admin để kích hoạt.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`X-API-Key`	Header	String	Bắt buộc	API Key của tài khoản thanh toán tiền ví
`product_id`	Body	String \| Number	Bắt buộc	Mã sản phẩm (ví dụ: `"7ABo5OI"`, `"7ARQMFn"` hoặc ID số `103`)
`quantity`	Body	Integer	Tùy chọn	Số lượng cần mua (mặc định là `1`)
`email`	Body	String	Tùy SP	Bắt buộc với SP có `requires_email: true` (Youtube Premium, Canva Edu)

cURL Request Mẫu (Mua Youtube Premium 10k)

curl -X POST "https://lucius.top/api/orders/buy"   -H "X-API-Key: sk_bot_YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "product_id": "7ABo5OI",
    "quantity": 1,
    "email": "[email protected]"
  }'

200 OK Phản hồi mẫu — SP Chờ Duyệt Thủ Công (Youtube / Canva)

{
  "success": true,
  "status": "NEEDS_REVIEW",
  "status_text": "Chờ duyệt thủ công (Admin đang kích hoạt)",
  "order_id": "101026606658",
  "id_product": "7ABo5OI",
  "product_id": "7ABo5OI",
  "product_name": "Youtube Premium 1 tháng",
  "quantity": 1,
  "unit_price": 10000,
  "total_price": 10000,
  "is_ctv": true,
  "email": "[email protected]",
  "is_manual_review": true,
  "balance_remaining": 40000,
  "check_status_url": "/api/orders/101026606658",
  "message": "Đơn hàng đã được thanh toán từ số dư ví bot và đang chờ Admin kích hoạt thủ công cho email [email protected]. Kiểm tra tiến độ qua GET /api/orders/101026606658"
}

200 OK Phản hồi mẫu — SP Kho Tự Động (Nhận Ngay)

{
  "success": true,
  "status": "COMPLETED",
  "status_text": "Hoàn tất (Đã giao hàng thành công)",
  "order_id": "101026889922",
  "id_product": "7HZIVHq",
  "product_id": "7HZIVHq",
  "product_name": "Gemini AI Pro 18 tháng",
  "quantity": 1,
  "unit_price": 17000,
  "total_price": 17000,
  "is_ctv": true,
  "delivered_content": "https://families.google.com/join/...",
  "balance_remaining": 23000,
  "check_status_url": "/api/orders/101026889922",
  "message": "Đơn hàng đã hoàn tất thành công."
}

GET /api/orders Yêu Cầu X-API-Key

GET https://lucius.top/api/orders

Lấy danh sách toàn bộ lịch sử đơn hàng của tài khoản. Đặc biệt: Hỗ trợ tham số ?status=NEEDS_REVIEW để chỉ lấy ra các đơn hàng đang chờ Admin duyệt thủ công.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`X-API-Key`	Header	String	Bắt buộc	API Key của tài khoản cần kiểm tra đơn hàng
`status`	Query	String	Tùy chọn	Lọc trạng thái: `NEEDS_REVIEW` (chờ duyệt), `COMPLETED` (xong), `CANCELLED` (hủy)
`limit`	Query	Integer	Tùy chọn	Giới hạn số lượng đơn trả về (ví dụ: `10`, `50`)

cURL Request (Lọc tất cả đơn chờ duyệt thủ công)

curl -X GET "https://lucius.top/api/orders?status=NEEDS_REVIEW"   -H "X-API-Key: sk_bot_YOUR_API_KEY"

200 OK Phản hồi mẫu

{
  "success": true,
  "count": 1,
  "filter_status": "NEEDS_REVIEW",
  "data": [
    {
      "order_id": "101026606658",
      "id_product": "7ABo5OI",
      "product_id": "7ABo5OI",
      "product_name": "Youtube Premium 1 tháng",
      "quantity": 1,
      "total_price": 10000,
      "payment_method": "BALANCE",
      "status": "NEEDS_REVIEW",
      "status_text": "Chờ duyệt thủ công (Admin đang kích hoạt)",
      "is_manual_review": true,
      "email": "[email protected]",
      "delivered_content": null,
      "check_status_url": "/api/orders/101026606658",
      "created_at": "2026-10-10 10:45:00"
    }
  ]
}

GET /api/orders/:order_id Yêu Cầu X-API-Key

GET https://lucius.top/api/orders/:order_id

Trọng tâm: Check Trạng Thái Đơn Chờ Duyệt Thủ Công

Kiểm tra chi tiết và trạng thái mới nhất của đơn hàng. Đây là endpoint đối tác dùng để polling định kỳ (khoảng 15-30s một lần) để biết ngay khi Admin kích hoạt xong gói cho khách.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`order_id`	Path	String	Bắt buộc	Mã đơn hàng được trả về từ `POST /api/orders/buy` (ví dụ: `101026606658`)
`X-API-Key`	Header	String	Bắt buộc	API Key của tài khoản đã đặt đơn hàng

cURL Request Mẫu

curl -X GET "https://lucius.top/api/orders/101026606658"   -H "X-API-Key: sk_bot_YOUR_API_KEY"

Trường Hợp 1: Đơn ĐANG CHỜ DUYỆT THỦ CÔNG (NEEDS_REVIEW)

{
  "success": true,
  "data": {
    "order_id": "101026606658",
    "id_product": "7ABo5OI",
    "product_id": "7ABo5OI",
    "product_name": "Youtube Premium 1 tháng",
    "quantity": 1,
    "total_price": 10000,
    "payment_method": "BALANCE",
    "status": "NEEDS_REVIEW",
    "status_text": "Chờ duyệt thủ công (Admin đang kích hoạt)",
    "is_manual_review": true,
    "email": "[email protected]",
    "delivered_content": null,
    "check_status_url": "/api/orders/101026606658",
    "created_at": "2026-10-10 10:45:00"
  }
}

Trường Hợp 2: Admin ĐÃ BẤM DUYỆT THÀNH CÔNG (COMPLETED)

{
  "success": true,
  "data": {
    "order_id": "101026606658",
    "id_product": "7ABo5OI",
    "product_id": "7ABo5OI",
    "product_name": "Youtube Premium 1 tháng",
    "quantity": 1,
    "total_price": 10000,
    "payment_method": "BALANCE",
    "status": "COMPLETED",
    "status_text": "Hoàn tất (Đã kích hoạt / Giao hàng thành công)",
    "is_manual_review": true,
    "email": "[email protected]",
    "delivered_content": "Đã kích hoạt thành công trên email: [email protected]",
    "check_status_url": "/api/orders/101026606658",
    "created_at": "2026-10-10 10:45:00"
  }
}

Trường Hợp 3: Admin ĐÃ HỦY & HOÀN TIỀN (CANCELLED)

{
  "success": true,
  "data": {
    "order_id": "101026606658",
    "id_product": "7ABo5OI",
    "product_id": "7ABo5OI",
    "product_name": "Youtube Premium 1 tháng",
    "quantity": 1,
    "total_price": 10000,
    "payment_method": "BALANCE",
    "status": "CANCELLED",
    "status_text": "Đã hủy & hoàn tiền vào ví bot",
    "is_manual_review": true,
    "email": "[email protected]",
    "delivered_content": null,
    "check_status_url": "/api/orders/101026606658",
    "created_at": "2026-10-10 10:45:00"
  }
}

GET /api/user/me Yêu Cầu X-API-Key

GET https://lucius.top/api/user/me

Tra cứu thông tin tài khoản Telegram gắn với API Key: số dư ví hiện tại, cấp bậc CTV, tổng tiền đã chi tiêu và tổng số đơn hàng đã mua.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`X-API-Key`	Header	String	Bắt buộc	API Key của tài khoản cần kiểm tra thông tin

cURL Request Mẫu

curl -X GET "https://lucius.top/api/user/me"   -H "X-API-Key: sk_bot_YOUR_API_KEY"

200 OK Phản hồi mẫu

{
  "success": true,
  "data": {
    "user_id": 6372286539,
    "username": "Ngthlu24",
    "full_name": "Nope",
    "balance": 18624000,
    "total_spent": 1922000,
    "total_orders": 59,
    "points": 1663,
    "is_ctv": true,
    "ctv_spent": 1922000,
    "ctv_orders": 59,
    "ctv_rank": {
      "rank": 1,
      "shortName": "Hạng Đồng",
      "bonusPercent": 0,
      "needMore": 3078000
    }
  }
}

POST /api/wallet/topup Yêu Cầu X-API-Key

POST https://lucius.top/api/wallet/topup

Tạo mã QR chuẩn VietQR nạp tiền vào ví bot Telegram. Hệ thống TPBank tự động quét biến động số dư và cộng tiền vào ví trong 1-3 phút khi nhận tiền chuyển đúng nội dung NAP<telegram_id>NAP. Hỗ trợ cả POST (body JSON) và GET ?amount=....

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
`X-API-Key`	Header	String	Bắt buộc	API Key của tài khoản bot cần nạp tiền
`amount`	Body / Query	Integer	Tùy chọn	Số tiền muốn nạp (VNĐ, tối thiểu `1000`). Nếu bỏ trống, mã QR cho phép khách tự điền số tiền trên app ngân hàng.

cURL Request Mẫu (Tạo QR Nạp 50.000 VNĐ)

curl -X POST "https://lucius.top/api/wallet/topup"   -H "X-API-Key: sk_bot_YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{ "amount": 50000 }'

200 OK Phản hồi mẫu

{
  "success": true,
  "message": "Tạo mã QR nạp tiền ví bot thành công",
  "data": {
    "user_id": 6372286539,
    "username": "Ngthlu24",
    "transfer_code": "NAP6372286539NAP",
    "amount": 50000,
    "amount_formatted": "50.000 VNĐ",
    "bank_info": {
      "bank_name": "TPBank",
      "account_number": "10004923706",
      "account_holder": "NGUYEN THANH LUAN"
    },
    "qr_url": "https://img.vietqr.io/image/TPB-10004923706-qr_only.png?amount=50000&addInfo=NAP6372286539NAP",
    "qr_code_image": "https://img.vietqr.io/image/TPB-10004923706-qr_only.png?amount=50000&addInfo=NAP6372286539NAP",
    "current_balance": 18624000,
    "current_balance_formatted": "18.624.000 VNĐ",
    "instructions": "Quét mã QR hoặc chuyển khoản đến TPBank STK 10004923706 với NỘI DUNG CHUYỂN KHOẢN là NAP6372286539NAP. Tiền sẽ được cộng tự động vào ví bot trong 1-3 phút.",
    "check_balance_url": "/api/user/me"
  }
}

GET /api/health Công Khai

GET https://lucius.top/api/health

Kiểm tra trạng thái máy chủ Luseller API và trạng thái sẵn sàng của kết nối Telegram Bot.

Tham số	Vị trí	Kiểu	Bắt buộc	Mô tả
Không yêu cầu tham số hoặc khóa API

cURL Request Mẫu

curl -X GET "https://lucius.top/api/health"

200 OK Phản hồi mẫu

{
  "success": true,
  "status": "ok",
  "service": "luseller-api",
  "timestamp": "2026-10-10T10:45:00.000Z",
  "bot_connected": true
}

Lưu Ý Bắt Buộc Khi Sử Dụng Luseller API

Kết Nối Bán Hàng Trực Tiếp Qua Bot Telegram

Yêu Cầu API Key Để Mở Khóa Console