Tài liệu API NguyenMMO

REST API Documentation / Developer Reference cho hệ thống NguyenMMO Store

https://nguyenmmo.store/api
Hướng dẫn: Tất cả API trả về dữ liệu dạng JSON. Base URL: https://nguyenmmo.store/api
Xác thực API: BẮT BUỘC - Tất cả API yêu cầu xác thực bằng API Token trong query parameter.
Thêm token vào URL: /api/endpoint?token=YOUR_API_TOKEN
Lưu ý: Không thể sử dụng session từ web đang đăng nhập. Phải có token trong mọi request.
Cách lấy token: Đăng nhập vào tài khoản → Trang "Tài khoản của tôi" → Tạo token API

API Xác thực

POST /api/auth/register - Đăng ký tài khoản mới
Mô tả:

Tạo tài khoản người dùng mới trong hệ thống.

Request Body (JSON):
{
  "username": "newuser",
  "email": "user@example.com",
  "password": "password123"
}
Response thành công (201):
{
  "success": true,
  "message": "Đăng ký thành công",
  "data": {
    "id": 5,
    "username": "newuser",
    "email": "user@example.com"
  }
}
Response lỗi (400/409):
{
  "success": false,
  "message": "Tên đăng nhập đã tồn tại",
  "data": null
}
POST /api/auth/login - Đăng nhập
Mô tả:

Đăng nhập bằng username hoặc email. Sau khi đăng nhập thành công, sẽ trả về API token để sử dụng cho các request tiếp theo.

Request Body (JSON):
{
  "username": "admin",
  "password": "admin123"
}
Response thành công (200):
{
  "success": true,
  "message": "Đăng nhập thành công",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@shop.com",
    "role": "admin",
    "token": "abc123xyz456..." // Sử dụng token này cho các API request
  }
}
Response lỗi (401):
{
  "success": false,
  "message": "Tên đăng nhập hoặc mật khẩu không đúng",
  "data": null
}
POST /api/auth/logout?token=YOUR_TOKEN - Đăng xuất
Mô tả:

Đăng xuất người dùng hiện tại. Yêu cầu đã đăng nhập.

Headers:
Cookie: session=xxx
Response (200):
{
  "success": true,
  "message": "Đăng xuất thành công",
  "data": null
}
GET /api/auth/me?token=YOUR_TOKEN - Lấy thông tin user hiện tại
Mô tả:

Lấy thông tin tài khoản từ token. Yêu cầu token hợp lệ trong query parameter.

URL:
GET /api/auth/me?token=YOUR_API_TOKEN
Response (200):
{
  "success": true,
  "message": "Thành công",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@shop.com",
    "role": "admin",
    "is_active": true,
    "balance": 1000000.0
  }
}

API User

Lưu ý: Các API User yêu cầu quyền Admin. Cần token của tài khoản admin trong query parameter.
GET /api/users?token=YOUR_TOKEN - Danh sách user (Admin)
Query Parameters:
  • page - Số trang (mặc định: 1)
  • per_page - Số item/trang (mặc định: 10)
Response (200):
{
  "success": true,
  "message": "Thành công",
  "data": {
    "items": [
      {
        "id": 1,
        "username": "admin",
        "email": "admin@shop.com",
        "role": "admin",
        "is_active": true,
        "created_at": "2026-04-08T10:00:00"
      }
    ],
    "total": 4,
    "page": 1,
    "pages": 1
  }
}
GET /api/users/<id>?token=YOUR_TOKEN - Chi tiết user (Admin)
Response (200):
{
  "success": true,
  "message": "Thành công",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@shop.com",
    "role": "admin",
    "is_active": true,
    "created_at": "2026-04-08T10:00:00"
  }
}
POST /api/users?token=YOUR_TOKEN - Tạo user mới (Admin)
Request Body (JSON):
{
  "username": "newuser",
  "email": "new@example.com",
  "password": "password123",
  "role": "user"
}
Response (201):
{
  "success": true,
  "message": "Tạo user thành công",
  "data": {
    "id": 5,
    "username": "newuser",
    "email": "new@example.com",
    "role": "user"
  }
}
PUT /api/users/<id>?token=YOUR_TOKEN - Cập nhật user (Admin)
Request Body (JSON) - các trường tùy chọn:
{
  "username": "updated_name",
  "email": "updated@example.com",
  "password": "newpassword",
  "role": "admin",
  "is_active": true
}
DELETE /api/users/<id>?token=YOUR_TOKEN - Xóa user (Admin)
URL:
DELETE /api/users/<id>?token=YOUR_API_TOKEN
Response (200):
{
  "success": true,
  "message": "Xóa user thành công",
  "data": null
}
POST /api/users/<id>/toggle-status?token=YOUR_TOKEN - Khóa/Mở khóa user (Admin)
Response (200):
{
  "success": true,
  "message": "Tài khoản đã khóa",
  "data": {
    "is_active": false
  }
}

API Sản phẩm

Lưu ý: Tất cả API Sản phẩm yêu cầu token trong query parameter.
GET /api/products?token=YOUR_TOKEN - Danh sách sản phẩm
URL:
GET /api/products?token=YOUR_API_TOKEN&page=1&per_page=10&category=&search=
Query Parameters:
  • token - API Token (bắt buộc nếu là API riêng tư)
  • page - Số trang (mặc định: 1)
  • per_page - Số item/trang (mặc định: 10)
  • category - Lọc theo danh mục
  • search - Tìm kiếm theo tên
Response (200):
{
  "success": true,
  "message": "Thành công",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "Sản phẩm mẫu",
        "description": "Mô tả sản phẩm mẫu...",
        "price": 15990000,
        "stock": 25,
        "category": "Danh mục mẫu",
        "created_at": "2026-04-08T10:00:00"
      }
    ],
    "total": 10,
    "page": 1,
    "pages": 1
  }
}
GET /api/products/<id>?token=YOUR_TOKEN - Chi tiết sản phẩm
Response (200):
{
  "success": true,
  "message": "Thành công",
  "data": {
    "id": 1,
    "name": "Sản phẩm mẫu",
    "description": "Mô tả sản phẩm mẫu...",
    "price": 15990000,
    "stock": 25,
    "category": "Danh mục mẫu",
    "is_in_stock": true,
    "created_at": "2026-04-08T10:00:00"
  }
}
POST /api/products?token=YOUR_TOKEN - Tạo sản phẩm (Admin)
Request Body (JSON):
{
  "name": "Tên sản phẩm",
  "description": "Mô tả sản phẩm",
  "price": 1000000,
  "stock": 50,
  "category": "Danh mục",
  "image": "https://example.com/image.jpg"
}
Response (201):
{
  "success": true,
  "message": "Tạo sản phẩm thành công",
  "data": {
    "id": 11,
    "name": "Tên sản phẩm",
    "price": 1000000
  }
}
PUT /api/products/<id>?token=YOUR_TOKEN - Cập nhật sản phẩm (Admin)
Request Body (JSON) - các trường tùy chọn:
{
  "name": "Tên mới",
  "description": "Mô tả mới",
  "price": 1500000,
  "stock": 100,
  "category": "Danh mục cập nhật",
  "image": "https://example.com/new-image.jpg"
}
DELETE /api/products/<id>?token=YOUR_TOKEN - Xóa sản phẩm (Admin)
URL:
DELETE /api/products/<id>?token=YOUR_API_TOKEN
Response (200):
{
  "success": true,
  "message": "Xóa sản phẩm thành công",
  "data": null
}
POST /api/products/<id>/accounts?token=YOUR_TOKEN - Thêm tài khoản vào kho (Admin)
Mô tả:

Thêm danh sách tài khoản vào sản phẩm. Mỗi dòng là một tài khoản. Tự động đồng bộ stock.

URL:
POST /api/products/<id>/accounts?token=YOUR_API_TOKEN
Request Body (JSON):
{
  "accounts": "user1@gmail.com|password123\nuser2@gmail.com|password456\nuser3@gmail.com|password789"
}
Response (201):
{
  "success": true,
  "message": "Đã thêm 3 tài khoản",
  "data": {
    "added": 3,
    "total_available": 15
  }
}
Response lỗi (404):
{
  "success": false,
  "message": "Sản phẩm không tồn tại",
  "data": null
}
GET /api/products/<id>/accounts?token=YOUR_TOKEN - Danh sách tài khoản (Admin)
Mô tả:

Lấy danh sách tài khoản của sản phẩm, có thể lọc theo trạng thái đã bán hoặc còn lại.

URL:
GET /api/products/<id>/accounts?token=YOUR_API_TOKEN&status=available&page=1&per_page=20
Query Parameters:
  • status - Lọc theo trạng thái: "sold" (đã bán) hoặc "available" (còn lại)
  • page - Số trang (mặc định: 1)
  • per_page - Số item/trang (mặc định: 20)
Response (200):
{
  "success": true,
  "message": "Thành công",
  "data": {
    "items": [
      {
        "id": 1,
        "account_data": "user1@gmail.com|password123",
        "is_sold": false,
        "order_item_id": null,
        "sold_at": null,
        "created_at": "2026-04-15T10:00:00"
      }
    ],
    "total": 50,
    "available": 35,
    "sold": 15,
    "page": 1,
    "pages": 3
  }
}

API Đơn hàng

POST /api/orders?token=YOUR_TOKEN - Tạo đơn hàng (Mua hàng)
Mô tả:

Tạo đơn hàng mới. Yêu cầu token hợp lệ. Tự động trừ tồn kho và trừ số dư ví.

URL:
POST /api/orders?token=YOUR_API_TOKEN
Request Body (JSON):
{
  "product_id": 1,
  "quantity": 2
}
Response (201):
{
  "success": true,
  "message": "Đặt hàng thành công",
  "data": {
    "order_id": 5,
    "order_code": "ORD-00005",
    "total_amount": 31980000
  }
}
Response lỗi (số lượng vượt tồn kho):
{
  "success": false,
  "message": "Sản phẩm chỉ còn 1 cái",
  "data": null
}
GET /api/orders/my-orders?token=YOUR_TOKEN - Đơn hàng của tôi
Mô tả:

Lấy danh sách đơn hàng của user từ token.

URL:
GET /api/orders/my-orders?token=YOUR_API_TOKEN&page=1&per_page=10
Query Parameters:
  • token - API Token (bắt buộc)
  • page - Số trang (mặc định: 1)
  • per_page - Số item/trang (mặc định: 10)
Query Parameters:
  • page - Số trang
  • per_page - Số item/trang
Response (200):
{
  "success": true,
  "message": "Thành công",
  "data": {
    "items": [
      {
        "id": 1,
        "order_code": "ORD-00001",
        "total_amount": 15990000,
        "status": "pending",
        "created_at": "2026-04-08T10:00:00",
        "items": [
          {
            "product_name": "Sản phẩm mẫu",
            "quantity": 1,
            "price_at_purchase": 15990000,
            "subtotal": 15990000
          }
        ]
      }
    ],
    "total": 2,
    "page": 1,
    "pages": 1
  }
}
GET /api/orders/<id>?token=YOUR_TOKEN - Chi tiết đơn hàng
Mô tả:

User chỉ xem được đơn hàng của mình. Admin xem được tất cả. Yêu cầu token.

URL:
GET /api/orders/<id>?token=YOUR_API_TOKEN
GET /api/orders/all?token=YOUR_TOKEN - Tất cả đơn hàng (Admin)
Query Parameters:
  • page - Số trang
  • per_page - Số item/trang

API Ví & Nạp tiền (VietQR)

Thông tin tài khoản:
Ngân hàng: MB Bank
Số tài khoản: 0002092885414
Tên: Nguyen Duy Anh
Nội dung chuyển khoản có dạng: NDA + 10 ký tự ngẫu nhiên
POST /api/wallet/create-qr?token=YOUR_TOKEN - Tạo mã QR VietQR
Mô tả:

Tạo mã QR VietQR để nạp tiền vào ví. Trả về URL ảnh QR và mã giao dịch.

URL:
POST /api/wallet/create-qr?token=YOUR_API_TOKEN
Request Body (JSON):
{
  "amount": 100000
}
Response (201):
{
  "success": true,
  "message": "Tạo QR thành công",
  "data": {
    "transaction_id": 1,
    "transaction_code": "DEP-00001",
    "amount": 100000,
    "description": "NDA7X9K2M1P4",
    "qr_url": "https://img.vietqr.io/image/MB-0002092885414...",
    "bank_id": "MB",
    "account_no": "0002092885414",
    "account_name": "Nguyen Duy Anh"
  }
}
Response lỗi (400):
{
  "success": false,
  "message": "Số tiền tối thiểu 10,000 VND"
}
POST /api/wallet/confirm-deposit/<id>?token=YOUR_TOKEN - Xác nhận nạp tiền
Mô tả:

Xác nhận giao dịch nạp tiền đã hoàn thành. Cộng tiền vào số dư ví.

Headers:
Cookie: session=xxx
Response (200):
{
  "success": true,
  "message": "Nạp tiền thành công",
  "data": {
    "transaction_code": "DEP-00001",
    "amount": 100000,
    "new_balance": 150000
  }
}
GET /api/wallet/transactions?token=YOUR_TOKEN - Lịch sử giao dịch ví
URL:
GET /api/users?token=YOUR_API_TOKEN&page=1&per_page=10
Query Parameters:
  • token - API Token (bắt buộc)
  • page - Số trang (mặc định: 1)
  • per_page - Số item/trang (mặc định: 10)
  • page - Số trang (mặc định: 1)
  • per_page - Số item/trang (mặc định: 10)
Response (200):
{
  "success": true,
  "message": "Thành công",
  "data": {
    "items": [
      {
        "id": 1,
        "transaction_code": "DEP-00001",
        "amount": 100000,
        "description": "NDA7X9K2M1P4",
        "status": "completed",
        "created_at": "2026-04-08T10:00:00"
      }
    ],
    "total": 5,
    "page": 1,
    "pages": 1
  }
}
GET /api/wallet/balance?token=YOUR_TOKEN - Lấy số dư ví
Headers:
Cookie: session=xxx
Response (200):
{
  "success": true,
  "message": "Thành công",
  "data": {
    "balance": 150000,
    "total_deposited": 250000
  }
}

HTTP Status Codes

Code Mô tả Khi nào sử dụng
200 OK Thành công, trả về dữ liệu
201 Created Tạo mới thành công (user, product, order)
400 Bad Request Dữ liệu đầu vào không hợp lệ
401 Unauthorized Chưa đăng nhập
403 Forbidden Không có quyền truy cập
404 Not Found Không tìm thấy tài nguyên
409 Conflict Trùng lặp dữ liệu (username, email)
500 Internal Server Error Lỗi phía server