TopVieAI topvieai.io.vn
English
Trang chủ Nạp tiền Đơn hàng Thông tin

API Documentation

Tích hợp hệ thống mua hàng tự động vào ứng dụng của bạn. Hỗ trợ đầy đủ các tính năng: tạo đơn hàng, kiểm tra trạng thái, xem danh sách sản phẩm và nhiều hơn nữa.

API Version 1.0 - RESTful
Bắt đầu
Tổng quan Xác thực
Endpoints
Tạo đơn hàng POST Trạng thái đơn GET Danh sách đơn GET Sản phẩm GET Danh mục GET Số dư GET Thông tin tài khoản GET
Tham khảo
Mã lỗi

Tổng quan API

Thông tin cơ bản về Shop API

Base URL https://topvieai.io.vn/api/v1
API Key Quản lý API Keys
Content-Type application/json
Response JSON
Quản lý API Keys Truy cập trang API Keys để tạo, quản lý và xem lịch sử sử dụng API của bạn.

Xác thực API

Cách xác thực các request đến API

Tất cả các request đến API cần có các headers sau:

Header Mô tả
X-API-Key API Key của bạn (40 ký tự, bắt đầu bằng sk_live_)
X-API-Secret API Secret của bạn (74 ký tự, bắt đầu bằng sk_secret_)
Content-Type application/json (cho POST request)
Ví dụ Headers
HTTP Headers 
X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
Content-Type: application/json
Lưu ý bảo mật Giữ API Key và API Secret an toàn. Không chia sẻ hoặc commit vào source code. Sử dụng biến môi trường để lưu trữ.

Tạo đơn hàng

Tạo đơn hàng mới và thanh toán tự động

POST https://topvieai.io.vn/api/v1/orders/create
Request Body
Parameter Type Mô tả
items Bắt buộc array Danh sách sản phẩm cần mua
items[].plan_id Bắt buộc integer ID gói sản phẩm (lấy từ /products/list)
items[].quantity integer Số lượng mua (mặc định: 1)
items[].fields object Các field bổ sung (nếu plan yêu cầu)
coupon_code string Mã giảm giá (nếu có)
Code mẫu
PHP 
<?php
$apiKey = 'sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';
$apiSecret = 'sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2';

$data = [
    'items' => [
        ['plan_id' => 18, 'quantity' => 1, 'fields' => ['email_dang_nhap' => 'user@example.com']]
    ],
    'coupon_code' => ''
];

$ch = curl_init('https://topvieai.io.vn/api/v1/orders/create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey,
        'X-API-Secret: ' . $apiSecret
    ]
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
?>
Response mẫu
Success Response 
{
  "success": true,
  "message": "Đơn hàng đã được tạo thành công",
  "data": {
    "orders": [{
      "trans_id": "ORD1703750400ABC",
      "product_name": "Sản phẩm Premium",
      "status": "completed",
      "total": 100000
    }],
    "summary": {
      "total_amount": 100000,
      "new_balance": 400000
    }
  }
}

Trạng thái đơn hàng

Kiểm tra trạng thái và nội dung giao hàng

GET https://topvieai.io.vn/api/v1/orders/status?trans_id={trans_id}
Query Parameters
Parameter Type Mô tả
trans_id Bắt buộc string Mã giao dịch từ kết quả tạo đơn
Code mẫu
PHP 
<?php
$transId = 'ORD1703750400ABC';
$url = 'https://topvieai.io.vn/api/v1/orders/status?trans_id=' . $transId;

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
        'X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2'
    ]
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);
?>
Response mẫu
Success Response 
{
  "success": true,
  "timestamp": 1770020629,
  "request_id": "req_69805f15a5ed77.94324321",
  "data": {
    "order": {
      "id": 36,
      "trans_id": "PO8153690",
      "user_id": 1,
      "product": {
        "id": 21,
        "name": "Sản phẩm Figma",
        "slug": "san-pham-figma",
        "image": "https://example.com/product.jpg"
      },
      "plan": {
        "id": 19,
        "name": "Figma Edu 1 năm - Tài khoản",
        "is_instant": true
      },
      "quantity": 2,
      "total_price": 1600000,
      "sale_price": 400000,
      "discount_amount": 0,
      "coupon_code": null,
      "final_amount": 400000,
      "fields_data": [],
      "status": "completed",
      "payment_status": "paid",
      "order_source": "api",
      "created_at": "2026-02-02 15:23:14",
      "updated_at": "2026-02-02 15:23:14"
    },
    "delivery": {
      "items": ["Account: user@mail.com | Pass: abc123", "Account: user2@mail.com | Pass: xyz789"],
      "delivered_count": 2,
      "expected_count": 2
    },
    "execution_time": 0.0238
  }
}

Danh sách đơn hàng

Lấy danh sách đơn hàng với phân trang

GET https://topvieai.io.vn/api/v1/orders/list
Query Parameters
Parameter Type Mô tả
page integer Số trang (mặc định: 1)
limit integer Số lượng/trang (mặc định: 20, max: 100)
status string Lọc: pending, processing, completed, cancelled
Code mẫu
cURL 
curl "https://topvieai.io.vn/api/v1/orders/list?page=1&limit=20&status=completed" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
Response mẫu
Success Response 
{
  "success": true,
  "data": {
    "orders": [{
      "id": 1234,
      "trans_id": "ORD-1705678901-ABC123",
      "product": {
        "id": 10,
        "name": "Windows 11 Pro Key",
        "slug": "windows-11-pro-key"
      },
      "plan": {
        "id": 5,
        "name": "Gói Retail - Vĩnh viễn"
      },
      "quantity": 2,
      "total_price": 1500000,
      "final_amount": 1350000,
      "status": "completed",
      "payment_status": "paid",
      "created_at": "2026-01-19 10:30:00"
    }],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 45,
      "total_pages": 3,
      "has_more": true
    },
    "execution_time": 0.0234
  }
}

Danh sách sản phẩm

Lấy danh sách sản phẩm và các gói

GET https://topvieai.io.vn/api/v1/products/list
Query Parameters
Parameter Type Mô tả
page integer Số trang (mặc định: 1)
limit integer Số lượng/trang (mặc định: 10, tối đa: 100)
category_id integer Lọc theo danh mục
search string Tìm kiếm theo tên
sort string Sắp xếp: newest, oldest, price_asc, price_desc, bestseller
Phân trang API trả về tối đa 100 sản phẩm/trang. Sử dụng tham số page và kiểm tra pagination.has_more trong response để lấy tất cả sản phẩm.
Code mẫu
PHP - Lấy tất cả sản phẩm (phân trang) 
<?php
$apiKey = 'sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';
$apiSecret = 'sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2';
$baseUrl = 'https://topvieai.io.vn/api/v1';

$allProducts = [];
$page = 1;
$limit = 100; // Tối đa 100 sản phẩm/trang

do {
    $url = $baseUrl . '/products/list?page=' . $page . '&limit=' . $limit;

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $apiKey,
            'X-API-Secret: ' . $apiSecret
        ]
    ]);

    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if (!$response['success']) break;

    $products = $response['data']['products'] ?? [];
    $allProducts = array_merge($allProducts, $products);

    $hasMore = $response['data']['pagination']['has_more'] ?? false;
    $page++;
} while ($hasMore);

echo 'Tổng sản phẩm: ' . count($allProducts);
?>
Response Fields (Plan)
Field Type Mô tả
id integer ID của gói sản phẩm
name string Tên gói sản phẩm
price float Giá gốc
sale_price float Giá khuyến mãi (nếu có)
final_price float Giá cuối cùng (ưu tiên sale_price nếu có)
is_instant boolean Giao hàng tự động
duration_type string Loại thời hạn: lifetime (vĩnh viễn), days (ngày), months (tháng), years (năm)
duration_value integer|null Giá trị thời hạn (VD: 30 ngày, 1 tháng). Null nếu duration_type = lifetime
stock_count integer Số lượng tồn kho (nếu is_instant = true)
in_stock boolean Còn hàng hay không
fields array Danh sách field cần nhập khi đặt hàng
Response mẫu
Success Response 
{
  "success": true,
  "timestamp": 1769604661,
  "request_id": "req_697a063503ed57.32834148",
  "data": {
    "products": [{
      "id": 29,
      "name": "Key Adobe Creative Cloud All Apps",
      "slug": "key-adobe-creative-cloud-all-apps",
      "image": "https://example.com/product.jpg",
      "description": "<p>Mô tả sản phẩm...</p>",
      "category": {
        "id": 5,
        "name": "Học Tập",
        "slug": "hoc-tap",
        "image": "https://example.com/category.jpg"
      },
      "categories": [
        {"id": 5, "name": "Học Tập", "slug": "hoc-tap", "image": "https://example.com/category.jpg"},
        {"id": 14, "name": "Làm việc", "slug": "lam-viec", "image": null}
      ],
      "min_price": 375000,
      "max_price": 1650000,
      "sold": 24,
      "rating": 4.5,
      "plans": [{
        "id": 319,
        "name": "Tài khoản 1 tháng",
        "price": 375000,
        "sale_price": 0,
        "final_price": 375000,
        "is_instant": true,
        "duration_type": "month",
        "duration_value": 1,
        "stock_count": 50,
        "in_stock": true,
        "description": "",
        "fields": []
      }, {
        "id": 320,
        "name": "Nâng chính chủ 1 Tháng",
        "price": 1650000,
        "sale_price": 0,
        "final_price": 1650000,
        "is_instant": false,
        "duration_type": "month",
        "duration_value": 3,
        "stock_count": 0,
        "in_stock": true,
        "description": "",
        "fields": [
          {"key": "email", "label": "Email", "type": "email", "required": true},
          {"key": "mat_khau", "label": "Mật khẩu", "type": "password", "required": true}
        ]
      }]
    }],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total": 21,
      "total_pages": 3,
      "has_more": true
    },
    "execution_time": 0.0828
  }
}

Danh sách danh mục

Lấy danh sách danh mục sản phẩm

GET https://topvieai.io.vn/api/v1/categories/list
Query Parameters
Parameter Type Mô tả
parent_id integer Lọc theo danh mục cha
include_children boolean Bao gồm danh mục con (0 hoặc 1)
include_products boolean Bao gồm số lượng sản phẩm (0 hoặc 1)
Code mẫu
cURL 
curl "https://topvieai.io.vn/api/v1/categories/list?include_children=1" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
Response mẫu
Success Response 
{
  "success": true,
  "timestamp": 1770022554,
  "request_id": "req_6980669a4793d9.70486853",
  "data": {
    "categories": [{
      "id": 3,
      "name": "Giải Trí",
      "slug": "giai-tri",
      "description": "",
      "image": "https://example.com/category/DOQ4.png",
      "parent_id": 1,
      "sort_order": 9
    }, {
      "id": 5,
      "name": "Học Tập",
      "slug": "hoc-tap",
      "description": "",
      "image": "https://example.com/category/9IRK.png",
      "parent_id": 1,
      "sort_order": 4
    }, {
      "id": 1,
      "name": "Tiện Ích",
      "slug": "tien-ich",
      "description": "",
      "image": "https://example.com/category/EIT3.png",
      "parent_id": 0,
      "sort_order": 0
    }],
    "total": 15,
    "execution_time": 0.0341
  }
}

Kiểm tra số dư

Xem số dư tài khoản hiện tại

GET https://topvieai.io.vn/api/v1/account/balance
Code mẫu
cURL 
curl "https://topvieai.io.vn/api/v1/account/balance" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
Response mẫu
Success Response 
{
  "success": true,
  "timestamp": 1770022345,
  "request_id": "req_698065c9694a56.14017855",
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@cmsnt.co"
    },
    "balance": {
      "current": 93537500,
      "total_deposited": 100000000,
      "currency": "VND",
      "formatted": "93.537.500đ"
    },
    "execution_time": 0.0258
  }
}

Thông tin tài khoản

Lấy thông tin tài khoản người dùng

GET https://topvieai.io.vn/api/v1/account/info
Code mẫu
cURL 
curl "https://topvieai.io.vn/api/v1/account/info" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
Response mẫu
Success Response 
{
  "success": true,
  "timestamp": 1770022432,
  "request_id": "req_69806620805ae3.29218122",
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@cmsnt.co",
      "phone": "",
      "balance": 93537500,
      "total_deposited": 100000000,
      "created_at": null
    },
    "api_key": {
      "name": "API Key",
      "permissions": [
        "orders.create",
        "orders.list",
        "orders.status",
        "products.list",
        "account.balance",
        "account.info"
      ],
      "rate_limit": 60,
      "daily_limit": 10000,
      "expires_at": null,
      "created_at": "2026-02-02 14:53:35"
    },
    "orders_summary": {
      "total": 12,
      "pending": 3,
      "completed": 8
    },
    "api_usage_today": {
      "period": "day",
      "start_time": "2026-02-02 00:00:00",
      "total_requests": 5,
      "success_requests": 5,
      "failed_requests": 0,
      "success_rate": 100
    },
    "execution_time": 0.0449
  }
}

Mã lỗi

Danh sách các mã lỗi có thể gặp

Mã lỗi HTTP Mô tả
INVALID_API_KEY 401 API Key không hợp lệ
INVALID_API_SECRET 401 API Secret không chính xác
DISABLED_API_KEY 401 API Key đã bị vô hiệu hóa
RATE_LIMIT_EXCEEDED 429 Vượt quá giới hạn request
IP_NOT_ALLOWED 403 IP không được phép truy cập
PERMISSION_DENIED 403 Không có quyền thực hiện
INSUFFICIENT_BALANCE 400 Số dư không đủ
PRODUCT_NOT_FOUND 404 Sản phẩm không tồn tại
OUT_OF_STOCK 400 Sản phẩm đã hết hàng
Error Response Format
Error Response 
{
  "success": false,
  "message": "Số dư không đủ để thanh toán",
  "data": {
    "error_code": "INSUFFICIENT_BALANCE"
  }
}