API v1 & Legacy CloneV7 CompatibleTốc độ cao & Bảo mật

Tài liệu Tích hợp API

Hệ thống cung cấp chuẩn RESTful API mạnh mẽ cho phép đối tác, đại lý và nhà phát triển tự động hóa toàn diện quy trình kiểm tra số dư, duyệt sản phẩm tồn kho, đặt mua hàng tự động và tra cứu đơn hàng theo thời gian thực.

Root Endpoint:https://domain-cua-ban.com/api/v1

Thử nghiệm API trực tiếp

Mục lục:Xác thực API Key Cơ chế Rewrite .PHP /profile /products /product /buy_product /order API Tester

Cơ chế Xác thực (Authentication)

Toàn bộ request đến hệ thống đều cần mã API Key định danh.

Mỗi tài khoản thành viên trong hệ thống được cấp duy nhất một mã api_key. Bạn có thể tra cứu hoặc tạo lại mã này trong trang Cài đặt hồ sơ cá nhân.

Lưu ý bảo mật quan trọng

API Key đại diện cho quyền thanh toán và mua hàng từ số dư ví tài khoản của bạn. Tuyệt đối không để lộ mã này trên giao diện client-side (Frontend JavaScript) công khai. Hãy luôn thực hiện gọi API từ máy chủ Backend của bạn.

1. Query Parameter?api_key=YOUR_API_KEY

2. JSON Body (POST){ "api_key": "..." }

3. Form Data (POST)api_key=YOUR_API_KEY

Cơ chế Tương thích ngược (Legacy CloneV7 Rewrites)

Được cấu hình tự động tại next.config.ts để tương thích các script PHP cũ.

Nếu bạn đang sử dụng mã nguồn hoặc plugin cũ tích hợp theo chuẩn CloneV7 (các đường dẫn kết thúc bằng đuôi .php), hệ thống đã thiết lập URL Rewrites nội bộ tại next.config.ts:

Đường dẫn Legacy (.php cũ)	Ánh xạ nội bộ (Next.js v1)	Trạng thái tương thích
/api/profile.php	/api/v1/profile	Tương thích 100% GET & POST
/api/products.php	/api/v1/products	Tương thích 100% GET & POST
/api/product.php	/api/v1/product	Tương thích 100% GET & POST
/api/buy_product	/api/v1/buy_product	Tương thích 100% GET & POST
/api/order.php	/api/v1/order	Tương thích 100% GET & POST

* Bạn có thể tiếp tục sử dụng các URL dạng /api/products.php hoặc chuyển dần sang URL hiện đại chuẩn mực /api/v1/products mà không cần sửa đổi bất kỳ logic nào.

1. Lấy thông tin tài khoản & Số dư

GET / POST

Trả về thông tin cơ bản của tài khoản người dùng liên kết với API Key, bao gồm tên đăng nhập (username) và số dư hiện tại (balance).

Endpoint v1:/api/v1/profile

Legacy Rewrite:/api/profile.php

Danh sách Tham số (Parameters)

Tên tham số	Kiểu	Bắt buộc	Vị trí truyền	Ví dụ	Mô tả
api_key	string	Bắt buộc	Query / JSON / Form	sk_live_9a8b7c6d5e...	Mã API Key bí mật của tài khoản bạn được cấp trong trang Cài đặt hồ sơ.

curl -X GET "https://domain-cua-ban.com/api/v1/profile?api_key=YOUR_API_KEY"

Phản hồi mẫu (200 OK)

{
  "status": "success",
  "msg": "Lấy thông tin thành công!",
  "username": "nguyenvana",
  "balance": 500000,
  "discount": 5,
  "data": {
    "username": "nguyenvana",
    "money": 500000
  }
}

Các phản hồi lỗi thường gặp:

Thiếu tham số api_key:{"status":"error","msg":"Thiếu api_key"}

API Key không chính xác hoặc đã bị xóa:{"status":"error","msg":"API Key không hợp lệ"}

2. Lấy danh sách sản phẩm & Tồn kho

GET / POST

Trả về cây danh mục và toàn bộ danh sách sản phẩm đang hoạt động, số lượng tồn kho và giá tiền tự động tính theo tỷ lệ chiết khấu riêng của cấp bậc tài khoản.

Endpoint v1:/api/v1/products

Legacy Rewrite:/api/products.php

Danh sách Tham số (Parameters)

Tên tham số	Kiểu	Bắt buộc	Vị trí truyền	Ví dụ	Mô tả
api_key	string	Bắt buộc	Query / JSON / Form	sk_live_9a8b7c6d5e...	Mã API Key bí mật của tài khoản.

curl -X GET "https://domain-cua-ban.com/api/v1/products?api_key=YOUR_API_KEY"

Phản hồi mẫu (200 OK)

{
  "status": "success",
  "msg": "Lấy dữ liệu thành công!",
  "categories": [
    {
      "id": "1",
      "parent_id": 0,
      "name": "Tài khoản Mạng xã hội",
      "icon": null,
      "products": []
    },
    {
      "id": "2",
      "parent_id": 1,
      "name": "Clone Facebook Việt Nam",
      "icon": null,
      "products": [
        {
          "id": "101",
          "name": "Clone Via Ngoại Cổ 2018 - 2020",
          "price": "15000",
          "amount": 45,
          "description": "Đã bật 2FA, kèm cookie và email gốc",
          "flag": null,
          "min": "1",
          "max": "50"
        }
      ]
    }
  ]
}

Các phản hồi lỗi thường gặp:

Thiếu api_key hoặc API key không đúng:{"status":"error","msg":"API Key không hợp lệ"}

3. Tra cứu chi tiết một sản phẩm

GET / POST

Truy vấn thông tin chi tiết một sản phẩm cụ thể theo numerical ID (mã số), bao gồm tên, mô tả chi tiết, giá tiền đã chiết khấu và tồn kho trực tiếp.

Endpoint v1:/api/v1/product

Legacy Rewrite:/api/product.php

Danh sách Tham số (Parameters)

Tên tham số	Kiểu	Bắt buộc	Vị trí truyền	Ví dụ	Mô tả
api_key	string	Bắt buộc	Query / JSON / Form	sk_live_9a8b7c6d5e...	Mã API Key bí mật của tài khoản.
product	string \| number	Bắt buộc	Query / JSON / Form	101	Mã số định danh của sản phẩm (hỗ trợ cả param 'product' hoặc 'id').

curl -X GET "https://domain-cua-ban.com/api/v1/product?api_key=YOUR_API_KEY&product=101"

Phản hồi mẫu (200 OK)

{
  "status": "success",
  "msg": "Lấy dữ liệu thành công!",
  "product": [
    {
      "id": 101,
      "name": "Clone Via Ngoại Cổ 2018 - 2020",
      "price": 15000,
      "amount": 45,
      "description": "Đã bật 2FA, kèm cookie và email gốc",
      "flag": null,
      "min": 1,
      "max": 50
    }
  ]
}

Các phản hồi lỗi thường gặp:

Thiếu tham số product hoặc id:{"status":"error","msg":"Thiếu product"}

Sản phẩm không tồn tại hoặc bị ẩn:{"status":"success","msg":"Lấy dữ liệu thành công!","product":[]}

4. Đặt mua sản phẩm tự động (CloneV7)

GET / POST

Thực hiện mua hàng tự động thông qua cơ chế khóa phân tán Redis an toàn (Atomic lock), trừ số dư tài khoản người dùng và bàn giao ngay tài nguyên tài khoản đã mua.

Endpoint v1:/api/v1/buy_product

Legacy Rewrite:/api/buy_product

Danh sách Tham số (Parameters)

Tên tham số	Kiểu	Bắt buộc	Vị trí truyền	Ví dụ	Mô tả
api_key	string	Bắt buộc	Query / JSON / Form	sk_live_9a8b7c6d5e...	Mã API Key bí mật (hỗ trợ alias 'key').
action	string	Bắt buộc	Query / JSON / Form	buyProduct	Bắt buộc giá trị cố định là 'buyProduct'.
id	string \| number	Bắt buộc	Query / JSON / Form	101	Mã sản phẩm numericalId hoặc UUID sản phẩm (hỗ trợ alias 'product').
amount	number	Bắt buộc	Query / JSON / Form	2	Số lượng sản phẩm cần mua (phải lớn hơn 0 và không vượt quá tồn kho/giới hạn mua).

curl -X POST "https://domain-cua-ban.com/api/v1/buy_product" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "action": "buyProduct",
    "id": 101,
    "amount": 2
  }'

Phản hồi mẫu (200 OK)

{
  "status": "success",
  "msg": "Mua hàng thành công!",
  "trans_id": "c8e6b12a-345f-4a67-b89c-d01234567890",
  "data": [
    "1000123456789|MatKhau123|2FA_SECRET_KEY|[email protected]",
    "1000987654321|MatKhau456|2FA_SECRET_KEY|[email protected]"
  ]
}

Các phản hồi lỗi thường gặp:

Số dư tài khoản không đủ để thanh toán:{"status":"error","msg":"Số dư không đủ để thực hiện thanh toán"}

Số lượng tồn kho trong kho không đủ:{"status":"error","msg":"Số lượng trong kho không đủ"}

action không hợp lệ:{"status":"error","msg":"action không hợp lệ"}

5. Kiểm tra & Nhận lại dữ liệu đơn hàng

GET / POST

Tra cứu trạng thái một đơn hàng đã mua và lấy lại toàn bộ nội dung tài khoản đã được giao của đơn hàng đó.

Endpoint v1:/api/v1/order

Legacy Rewrite:/api/order.php

Danh sách Tham số (Parameters)

Tên tham số	Kiểu	Bắt buộc	Vị trí truyền	Ví dụ	Mô tả
api_key	string	Bắt buộc	Query / JSON / Form	sk_live_9a8b7c6d5e...	Mã API Key bí mật của tài khoản người mua.
order	string	Bắt buộc	Query / JSON / Form	c8e6b12a-345f-4a67-b89c-d01234567890	Mã đơn hàng UUID (trans_id) hoặc numericalId của đơn hàng cần tra cứu.

curl -X GET "https://domain-cua-ban.com/api/v1/order?api_key=YOUR_API_KEY&order=c8e6b12a-345f-4a67-b89c-d01234567890"

Phản hồi mẫu (200 OK)

{
  "status": "success",
  "msg": "Lấy đơn hàng thành công!",
  "trans_id": "c8e6b12a-345f-4a67-b89c-d01234567890",
  "data": [
    "1000123456789|MatKhau123|2FA_SECRET_KEY|[email protected]",
    "1000987654321|MatKhau456|2FA_SECRET_KEY|[email protected]"
  ]
}

Các phản hồi lỗi thường gặp:

Đơn hàng không thuộc sở hữu của bạn hoặc không tồn tại:{"status":"error","msg":"Không tìm thấy đơn hàng"}

API Live Playground (Thử nghiệm trực tiếp)

Kiểm tra ngay kết quả phản hồi của từng endpoint trực tiếp từ trình duyệt của bạn với API Key thực tế.

Chọn Endpoint cần kiểm tra

API Key của bạn *Lấy key tại đây

Kết quả phản hồi trực tiếp (Live Output)

Chọn endpoint, nhập API Key và bấm "Gửi yêu cầu thử nghiệm" để xem dữ liệu.

Bảng mã thông báo lỗi hệ thống

Quy chuẩn định dạng phản hồi khi có lỗi phát sinh.

Thông điệp lỗi (msg)	Nguyên nhân	Giải pháp khắc phục
Thiếu api_key	Không truyền tham số api_key trong URL hoặc body.	Bổ sung tham số ?api_key=... vào request.
API Key không hợp lệ	Mã key không khớp với bất kỳ tài khoản nào trong hệ thống.	Kiểm tra lại mã key chính xác trong trang Hồ sơ cá nhân.
Số dư không đủ để thực hiện thanh toán	Số dư ví của bạn thấp hơn tổng số tiền của đơn hàng.	Nạp thêm tiền vào ví tài khoản trước khi mua.
Số lượng trong kho không đủ	Số lượng mua vượt quá số lượng tài khoản còn tồn trong kho.	Kiểm tra tồn kho qua endpoint /api/v1/products trước khi mua.
Xung đột hệ thống khi lấy hàng	Có nhiều yêu cầu mua cùng lúc đang tranh chấp khóa (Lock contention).	Chờ 1-2 giây và gửi lại request.