logo logo
userLogin
Trang chủ Đơ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://shopkey.appstoreviet.com/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://shopkey.appstoreviet.com/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' => '[email protected]']]
    ],
    'coupon_code' => ''
];

$ch = curl_init('https://shopkey.appstoreviet.com/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://shopkey.appstoreviet.com/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://shopkey.appstoreviet.com/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,
  "data": {
    "trans_id": "ORD1703750400ABC",
    "status": "completed",
    "total_amount": 100000,
    "delivery": {
      "items": ["Account: [email protected] | Pass: abc123"],
      "delivered_count": 1
    }
  }
}

Danh sách đơn hàng

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

GET https://shopkey.appstoreviet.com/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://shopkey.appstoreviet.com/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://shopkey.appstoreviet.com/api/v1/products/list
Query Parameters
Parameter Type Mô tả
category_id integer Lọc theo danh mục
search string Tìm kiếm theo tên
Code mẫu
cURL 
curl "https://shopkey.appstoreviet.com/api/v1/products/list" \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-API-Secret: sk_secret_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2"
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"
      },
      "categories": [
        {"id": 5, "name": "Học Tập", "slug": "hoc-tap"},
        {"id": 14, "name": "Làm việc", "slug": "lam-viec"}
      ],
      "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://shopkey.appstoreviet.com/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://shopkey.appstoreviet.com/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,
  "data": {
    "categories": [{
      "id": 1,
      "name": "Netflix",
      "slug": "netflix",
      "description": "Tài khoản Netflix Premium",
      "parent_id": 0,
      "sort_order": 1,
      "children": []
    }],
    "total": 1
  }
}

Kiểm tra số dư

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

GET https://shopkey.appstoreviet.com/api/v1/account/balance
Code mẫu
cURL 
curl "https://shopkey.appstoreviet.com/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,
  "data": {
    "balance": 500000,
    "currency": "VND",
    "formatted": "500,000 ₫"
  }
}

Thông tin tài khoản

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

GET https://shopkey.appstoreviet.com/api/v1/account/info
Code mẫu
cURL 
curl "https://shopkey.appstoreviet.com/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,
  "data": {
    "id": 123,
    "username": "johndoe",
    "email": "[email protected]",
    "balance": 500000,
    "total_orders": 25
  }
}

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"
  }
}