Tài liệu API v2

Xác thực (API Key)

API v2 xác thực bằng header X-Api-Key. Mỗi tài khoản có một API key duy nhất — gọi lại endpoint tạo key sẽ overwrite key cũ.

Cách lấy API key:

1Đăng nhập tài khoản tại vuavia.io
2Vào Tài khoản → Thông tin cá nhân, nhấn Tạo API Key
3Key có dạng vav_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (36 ký tự)
4Truyền key vào mỗi request qua header X-Api-Key

Giữ bí mật API key. Không commit vào source code public. Nếu bị lộ, hãy tạo lại key ngay để vô hiệu hóa key cũ.

Cách truyền header

GET /api/v2/wallet/balance HTTP/1.1
Host: api.vuavia.io
X-Api-Key: vav_a1b2c3d4e5f6...

Base URL

Production

https://api.vuavia.io/api/v2

Tất cả endpoint đều yêu cầu header X-Api-Key hợp lệ.

Định dạng phản hồi

Mọi response đều theo cấu trúc JSON chuẩn sau:

Thành công

{
  "success": true,
  "message": "Thành công",
  "data": { ... },
  "error": null
}

Lỗi

{
  "success": false,
  "message": "Mô tả lỗi",
  "data": null,
  "error": {
    "code": "ERROR_CODE"
  }
}

Endpoints

GET/wallet/balance

Lấy số dư ví hiện tại của tài khoản.

Response

{
  "success": true,
  "data": { "balance": 150000 }
}

GET/products

Danh sách sản phẩm đang bán. Hỗ trợ lọc theo danh mục và phân trang.

Query params

Tên	Kiểu	Mặc định	Mô tả
`categoryId`	number	—	Lọc theo ID danh mục
`page`	number	0	Trang (bắt đầu từ 0)
`size`	number	20	Số sản phẩm mỗi trang
`sort`	string	newest	newest \| price_asc \| price_desc

Response

{
  "success": true,
  "data": {
    "content": [
      {
        "id": 1,
        "name": "Facebook Clone VN",
        "slug": "facebook-clone-vn",
        "price": 15000,
        "stockCount": 42,
        "deliveryType": "AUTO"
      }
    ],
    "totalElements": 120,
    "totalPages": 6,
    "number": 0,
    "size": 20
  }
}

POST/orders

Mua sản phẩm. Trừ ví và giao hàng ngay (AUTO) hoặc chờ admin giao (MANUAL).

Request body

Tên	Kiểu	Mô tả
`productId`	number	ID sản phẩm cần mua (bắt buộc)
`quantity`	number	Số lượng — tối thiểu 1 (bắt buộc)

Request body

{ "productId": 1, "quantity": 2 }

Response — AUTO (giao ngay)

{
  "success": true,
  "message": "Đặt hàng thành công",
  "data": {
    "id": 101,
    "status": "DELIVERED",
    "totalAmount": 30000,
    "quantity": 2,
    "deliveredItems": [
      "account1|password1",
      "account2|password2"
    ],
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Response — MANUAL (chờ admin giao)

{
  "success": true,
  "message": "Đặt hàng thành công",
  "data": {
    "id": 102,
    "status": "PENDING_DELIVERY",
    "totalAmount": 50000,
    "quantity": 1,
    "deliveredItems": [],
    "createdAt": "2024-01-15T10:31:00Z"
  }
}

GET/orders

Lịch sử đơn hàng của tài khoản, sắp xếp theo thời gian mới nhất.

Query params

Tên	Kiểu	Mặc định	Mô tả
`page`	number	0	Trang (bắt đầu từ 0)
`size`	number	20	Số đơn mỗi trang

Response

{
  "success": true,
  "data": {
    "content": [
      {
        "id": 101,
        "productName": "Facebook Clone VN",
        "status": "DELIVERED",
        "totalAmount": 30000,
        "quantity": 2,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "totalElements": 5,
    "totalPages": 1,
    "number": 0
  }
}

GET/orders/{id}

Chi tiết một đơn hàng. Khi status là DELIVERED sẽ trả về danh sách hàng đã giao.

Response

{
  "success": true,
  "data": {
    "id": 101,
    "productName": "Facebook Clone VN",
    "status": "DELIVERED",
    "totalAmount": 30000,
    "quantity": 2,
    "deliveredItems": [
      "account1|password1",
      "account2|password2"
    ],
    "deliveryNote": null,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Ví dụ curl

Xem số dư ví

curl -s https://api.vuavia.io/api/v2/wallet/balance \
  -H "X-Api-Key: vav_your_key"

Lấy sản phẩm (trang 1, sắp xếp mới nhất)

curl -s "https://api.vuavia.io/api/v2/products?page=0&size=10&sort=newest" \
  -H "X-Api-Key: vav_your_key"

Mua hàng

curl -s -X POST https://api.vuavia.io/api/v2/orders \
  -H "X-Api-Key: vav_your_key" \
  -H "Content-Type: application/json" \
  -d '{"productId": 1, "quantity": 1}'

Xem lịch sử đơn

curl -s "https://api.vuavia.io/api/v2/orders?page=0&size=20" \
  -H "X-Api-Key: vav_your_key"

Lấy hàng đã giao (chi tiết đơn)

curl -s https://api.vuavia.io/api/v2/orders/101 \
  -H "X-Api-Key: vav_your_key"

Mã lỗi

HTTP	error.code	Nguyên nhân
401	`UNAUTHORIZED`	API key không hợp lệ hoặc thiếu header X-Api-Key
400	`INSUFFICIENT_BALANCE`	Số dư ví không đủ
409	`OUT_OF_STOCK`	Sản phẩm hết hàng
404	`NOT_FOUND`	Sản phẩm hoặc đơn hàng không tồn tại
400	`BAD_REQUEST`	Dữ liệu request không hợp lệ (thiếu field, sai kiểu...)
500	—	Lỗi máy chủ — vui lòng liên hệ hỗ trợ

Cần hỗ trợ tích hợp hoặc gặp vấn đề kỹ thuật?

Liên hệ hỗ trợ ngay