Tài Liệu API Dành Cho Khách Hàng
Đăng ký Lấy API Key

API Platform

Tích hợp hệ thống mua tài khoản số và đọc email OTP tự động vào phần mềm của bạn chỉ với vài dòng code. Toàn bộ API dùng định dạng JSON, giao thức HTTPS.

API Key Auth JSON REST Phản hồi tức thì Đọc OTP Email Hoàn tiền 1 phút
Base URL: http://localhost:8888
Tất cả endpoint đều trả về JSON. Xác thực qua header Authorization: Bearer <api_key> hoặc field api_key trong body.
 Xác Thực
POST /api/auth/login Đăng nhập · lấy API Key

Đăng nhập bằng username/password. Phản hồi trả về api_key dùng để xác thực toàn bộ các endpoint sau.

Request Body (JSON)
TênKiểuBắt buộcMô tả
usernamestringrequiredTên đăng nhập đã đăng ký
passwordstringrequiredMật khẩu
Ví dụ Request
Python
import requests

res = requests.post("http://localhost:8888/api/auth/login", json={
    "username": "your_username",
    "password": "your_password"
})
data = res.json()
api_key = data["api_key"]
print("API Key:", api_key)
JSON
{"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
JSON
{"detail": "Invalid username or password"}
Thử ngay
GET /api/auth/me Xem thông tin tài khoản & số dư

Trả về thông tin tài khoản hiện tại: username, họ tên, và số dư ví.

Endpoint này yêu cầu xác thực qua header: Authorization: Bearer <api_key>

Ví dụ Request
Python
res = requests.get("http://localhost:8888/api/auth/me",
    headers={"Authorization": f"Bearer {api_key}"}
)
print(res.json())
Response 200
{"username": "khach123", "fullname": "Nguyễn Văn A", "balance": 150000}
Thử ngay
 Danh Mục & Sản Phẩm
GET /api/products Lấy danh sách sản phẩm & giá

Trả về toàn bộ danh sách sản phẩm đang bán kèm tên danh mục, giá, số lượng còn hàng và mã danh mục dùng để mua hàng.

Endpoint này không cần xác thực – gọi tự do.
Ví dụ Request
Python
res = requests.get("http://localhost:8888/api/products")
products = res.json()
for p in products:
    print(p["category_name"], p["name"], p["price"], p["stock"], p["category_code"])
Response 200 – Array
[
  {
    "id": 1,
    "name": "Gmail Cổ 2010",
    "description": "Gmail tạo trước 2010, đã xác minh",
    "price": 5000,
    "stock": 42,
    "category_name": "Tài Khoản Mạng Xã Hội",
    "category_code": "gmail_old",
    "category_icon": "gmail"
  }
]
Thử ngay
 Mua Hàng
POST /api/buy Mua 1 tài khoản

Mua ngay 1 tài khoản từ danh mục chỉ định. Hệ thống trừ tiền và trả về nội dung tài khoản (email|password|...) trong phản hồi. Mỗi lần gọi mua 1 tài khoản.

Truyền api_key trong body JSON hoặc header Authorization: Bearer <api_key>.

Request Body (JSON)
TênKiểuBắt buộcMô tả
api_keystringrequiredAPI Key của bạn
category_codestringrequiredMã danh mục (lấy từ /api/products)
Ví dụ Request
Python
res = requests.post("http://localhost:8888/api/buy", json={
    "api_key": api_key,
    "category_code": "gmail_old"  # lấy từ /api/products
})
data = res.json()
account_content = data["data"]  # "email|password|token|..."
print("Tài khoản:", account_content)
JSON
{
  "status": "success",
  "data": "example@outlook.com|P@ssword123|eyJhbGci...|client_id_xxx",
  "balance": 145000,
  "sold_at": "2026-06-10T06:30:00.000000"
}
JSON
{"detail": "Insufficient balance"}     // Số dư không đủ
{"detail": "Out of stock"}            // Hết hàng
{"detail": "Category not found"}      // Sai mã danh mục
{"detail": "Invalid API Key"}         // API Key sai
Nội dung tài khoản data có định dạng email|password|refresh_token|client_id. Cần lưu lại email để hoàn tiền hoặc đọc email sau.
Thử ngay
POST /api/refund Hoàn tiền (trong vòng 1 phút)

Hoàn tiền và trả lại tài khoản nếu gọi trong vòng 60 giây sau khi mua. Nếu quá thời gian, hệ thống sẽ từ chối.

Request Body (JSON)
TênKiểuBắt buộcMô tả
api_keystringrequiredAPI Key của bạn
emailstringrequiredEmail của tài khoản vừa mua (phần trước dấu | trong data)
Python
email = data["data"].split("|")[0]  # lấy email từ kết quả mua
res = requests.post("http://localhost:8888/api/refund", json={
    "api_key": api_key,
    "email": email
})
print(res.json())
Response 200
{"status": "success", "message": "Refunded successfully", "balance": 150000}
Chỉ được hoàn tiền trong 60 giây kể từ lúc mua. Sau thời gian đó: {"detail": "Refund period expired (max 1 minute)"}
 Đọc Email & OTP
POST /api/read_email Đọc OTP từ hộp thư Outlook

Đọc 10 email mới nhất trong hộp thư đến của tài khoản Outlook/Hotmail đã mua. Hệ thống tự lấy Access Token qua OAuth2 (Refresh Token), tìm email theo từ khóa và trích xuất mã OTP (6–8 chữ số).

Chỉ hoạt động với tài khoản được mua từ danh mục có Refresh Token + Client ID (định dạng 4 trường: email|pass|refresh_token|client_id).

Request Body (JSON)
TênKiểuBắt buộcMô tả
api_keystringrequiredAPI Key của bạn
emailstringrequiredEmail của tài khoản đã mua
keywordstringrequiredTừ khóa tìm trong tiêu đề / nội dung email (vd: "Microsoft", "verification", "OTP")
Ví dụ Request
Python
res = requests.post("http://localhost:8888/api/read_email", json={
    "api_key": api_key,
    "email": "example@outlook.com",
    "keyword": "Microsoft account"  # tìm email chứa chuỗi này
})
data = res.json()
if data["status"] == "success":
    print("OTP:", data["code"])
    print("Tiêu đề:", data["full_subject"])
else:
    print("Chưa có email:", data["message"])
JSON – Tìm thấy OTP
{
  "status": "success",
  "code": "847291",
  "full_subject": "Microsoft account security code",
  "body_preview": "Your Microsoft account security code is 847291..."
}
JSON – Chưa nhận được email
{"status": "pending", "message": "No matching email found"}
JSON
{"detail": "Account not found or not owned by you"}
{"detail": "Account format does not support reading email via OAuth2"}
{"detail": "Failed to get access token from Microsoft. Token might be expired."}
Tip – Polling OTP: Sau khi đăng ký/xác nhận trên website, gọi endpoint này lặp lại mỗi 2–3 giây cho đến khi status == "success". 
import time
for _ in range(15):       # thử tối đa 15 lần
    r = requests.post(...).json()
    if r.get("status") == "success":
        print("OTP:", r["code"]); break
    time.sleep(3)          # chờ 3 giây
Thử ngay
 Lịch Sử
GET /api/user/history Lịch sử tài khoản đã mua

Trả về danh sách tất cả tài khoản đã mua, kèm nội dung tài khoản và thời gian mua.

Query Parameters
TênKiểuBắt buộcMô tả
api_keystringrequiredAPI Key
Python
res = requests.get("http://localhost:8888/api/user/history",
    params={"api_key": api_key}
)
history = res.json()
for item in history:
    print(item["content"], item["sold_at"])
Response 200 – Array
[
  {
    "id": 10,
    "product_name": "Gmail Cổ 2010",
    "category": "Tài Khoản Mạng Xã Hội",
    "content": "abc@outlook.com|P@ss|token|client_id",
    "sold_at": "2026-06-10T05:00:00"
  }
]
Thử ngay
GET /api/user/transactions Lịch sử nạp tiền & giao dịch

Trả về lịch sử toàn bộ giao dịch: nạp tiền, mua hàng, hoàn tiền – kèm số tiền thay đổi và thời gian.

Query Parameters
TênKiểuBắt buộcMô tả
api_keystringrequiredAPI Key
Python
res = requests.get("http://localhost:8888/api/user/transactions",
    params={"api_key": api_key}
)
for tx in res.json():
    sign = "+" if tx["amount"] > 0 else ""
    print(f"{tx['type']:10} {sign}{tx['amount']:,}đ  {tx['created_at']}")
Response 200 – Array
[
  {"id":5, "type":"TOPUP",    "amount":100000, "description":"Nạp tiền SePay", "created_at":"..."},
  {"id":6, "type":"PURCHASE", "amount":-5000,  "description":"Mua Gmail Cổ",   "created_at":"..."},
  {"id":7, "type":"REFUND",   "amount":5000,   "description":"Hoàn tiền ...",   "created_at":"..."}
]
Thử ngay
 Bảng Tổng Hợp Endpoint
MethodEndpointXác thựcMô tả
GET/api/productsKhôngDanh sách sản phẩm & giá
POST/api/auth/loginKhôngĐăng nhập · lấy api_key
GET/api/auth/meBearerThông tin tài khoản & số dư
POST/api/buyapi_key bodyMua 1 tài khoản
POST/api/refundapi_key bodyHoàn tiền (≤60s)
POST/api/read_emailapi_key bodyĐọc email · tìm OTP
GET/api/user/historyapi_key queryLịch sử tài khoản đã mua
GET/api/user/transactionsapi_key queryLịch sử giao dịch