SHOPKEY

API Documentation

Tích hợp hệ thống mua hàng tự động vào ứng dụng của bạn.

Tổng quan API

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.

Base URL

URL

https://api-shopkey.brotemplate.com

Content-Type

Header

application/json

API Key

Quản lý API Keys tại trang API Keys.

Response Envelope

All responses are wrapped in a standard envelope.

Response Envelope

Field	Type	Description
success*	boolean	Operation result
data	object	Response payload (present on success)
error	object	Error details (present on failure)
└ message*	string	Human-readable error
└ code*	string	Machine-readable error code
meta*	object	Response metadata
└ timestamp*	string	ISO 8601 timestamp
└ requestId*	string	Unique request identifier
└ pagination	object	Pagination info (present on list endpoints)

Xác thực API

Authenticate all API requests by including your API key in the x-api-key header. You can create and manage API keys from the API Keys page in your account.

Request Headers

Field	Type	Description
x-api-key*	string	API Key của bạn (40 ký tự, bắt đầu bằng sk_live_)
Content-Type*	string	application/json (cho POST request)

Ví dụ Headers

HTTP Headers

x-api-key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Content-Type: application/json

Giữ API Key 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

POST

/v1/orders

Checkout cart with wallet balance

Creates one or more orders from the current cart and charges the wallet. Each line item references a product plan by its UUID.

Request Body (application/json)

Field	Type	Description
items*	array<object>	Danh sách sản phẩm cần mua
└ planId*	uuid	ID gói sản phẩm
└ quantity	number	Số lượng mua (mặc định: 1)
└ fields	object	Dynamic checkout fields keyed by fieldKey (nếu gói yêu cầu)
└ stockIds	array<uuid>	Optional pre-selected stock IDs from preview

cURL

curl -X POST "https://api-shopkey.brotemplate.com/v1/orders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"planId":"123e4567-e89b-12d3-a456-426614174000","quantity":2}]}'

Response Fields

Field	Type	Description
success*	boolean	Operation result
data*	array<object>	List of created orders
└ id*	uuid	Order ID
└ planId*	uuid	Plan ID
└ quantity*	number	Quantity purchased
└ status*	string	Order status (pending/completed)Enum: pending, processing, completed, cancelled, failed
└ unitPrice*	string	Price per unit
└ totalAmount*	string	Total charged amount
└ stocks*	array<object>	Delivered stock items
└ stockId*	uuid	Stock ID
└ content*	string	Delivered content (credential / key)
└ attachedContent	string	Delivery note when completed
└ completedAt	string	Completion timestamp (ISO 8601)
meta*	object	Response metadata
└ timestamp*	string	ISO 8601 timestamp
└ requestId*	string	Unique request identifier

Response Example

JSON

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "planId": "123e4567-e89b-12d3-a456-426614174000",
      "quantity": 2,
      "status": "completed",
      "unitPrice": "50000.0000",
      "totalAmount": "100000.0000",
      "stocks": [
        { "stockId": "s1", "content": "Account: [email protected] | Pass: abc123" },
        { "stockId": "s2", "content": "Account: [email protected] | Pass: xyz789" }
      ],
      "attachedContent": null,
      "completedAt": "2026-02-02T15:23:14.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-02-02T15:23:14.000Z",
    "requestId": "req-abc-123"
  }
}

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

GET

/v1/orders/{id}

Get order detail

Returns the full detail of a single order, including delivered stock items.

Request Parameters

Parameter	In	Type	Required	Description
id	Path	uuid	Yes	Mã giao dịch (UUID của đơn hàng)

cURL

curl "https://api-shopkey.brotemplate.com/v1/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-api-key: YOUR_API_KEY"

Response Fields

Field	Type	Description
success*	boolean	Operation result
data*	object	Order detail
└ id*	uuid	Order ID
└ productName*	string	Tên sản phẩm
└ planName*	string	Tên gói sản phẩm
└ quantity*	number	Số lượng
└ status*	string	Trạng thái đơn hàngEnum: pending, processing, completed, cancelled, failed
└ unitPrice*	string	Đơn giá
└ totalAmount*	string	Tổng tiền
└ stocks*	array<object>	Nội dung giao hàng
└ stockId*	uuid	Stock ID
└ content*	string	Nội dung (tài khoản \| key)
└ attachedContent	string	Nội dung đính kèm khi hoàn thành
└ createdAt*	string	Thời gian tạo (ISO 8601)
└ completedAt	string	Thời gian hoàn thành (ISO 8601)
meta*	object	Response metadata
└ timestamp*	string	Thời gian response
└ requestId*	string	Request ID

Response Example

JSON

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "productName": "Key Adobe Creative Cloud All Apps",
    "planName": "Tài khoản 1 tháng",
    "quantity": 2,
    "status": "completed",
    "unitPrice": "375000.0000",
    "totalAmount": "750000.0000",
    "stocks": [
      { "stockId": "s1", "content": "[email protected] | pass123" },
      { "stockId": "s2", "content": "[email protected] | pass456" }
    ],
    "attachedContent": "Hướng dẫn kích hoạt: https://example.com/guide",
    "createdAt": "2026-02-02T15:23:14.000Z",
    "completedAt": "2026-02-02T15:23:14.000Z"
  },
  "meta": {
    "timestamp": "2026-02-02T15:23:14.000Z",
    "requestId": "req-abc-123"
  }
}

Danh sách đơn hàng

GET

/v1/orders

List my product orders

Returns a paginated list of orders belonging to the authenticated user.

Request Parameters

Parameter	In	Type	Required	Description
status	Query	string	No	Lọc theo trạng thái: pending, processing, completed, cancelled
search	Query	string	No	Tìm kiếm theo tên sản phẩm hoặc mã đơn
page	Query	integer	No	Số trang (mặc định: 1)
limit	Query	integer	No	Số lượng/trang (mặc định: 20, tối đa: 100)

cURL

curl "https://api-shopkey.brotemplate.com/v1/orders?status=completed&page=1&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

Response Fields

Field	Type	Description
success*	boolean	Operation result
data*	array<object>	Danh sách đơn hàng
└ id*	uuid	Order ID
└ productName*	string	Tên sản phẩm
└ planName*	string	Tên gói
└ quantity*	number	Số lượng
└ status*	string	Trạng tháiEnum: pending, processing, completed, cancelled, failed
└ totalAmount*	string	Tổng tiền
└ createdAt*	string	Ngày tạo (ISO 8601)
└ completedAt	string	Ngày hoàn thành (ISO 8601)
meta*	object	Response metadata
└ timestamp*	string	Thời gian response
└ requestId*	string	Request ID
└ pagination	object	Thông tin phân trang
└ page*	integer	Trang hiện tại
└ limit*	integer	Số lượng/trang
└ total*	integer	Tổng số đơn
└ totalPages*	integer	Tổng số trang
└ hasNext*	boolean	Còn trang tiếp theo?
└ hasPrev*	boolean	Có trang trước?

Response Example

JSON

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "productName": "Key Adobe Creative Cloud All Apps",
      "planName": "Tài khoản 1 tháng",
      "quantity": 1,
      "status": "completed",
      "totalAmount": "375000.0000",
      "createdAt": "2026-02-02T15:23:14.000Z",
      "completedAt": "2026-02-02T15:23:14.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-02-02T15:23:14.000Z",
    "requestId": "req-abc-123",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Danh sách sản phẩm

GET

/v1/products

List active products

Returns a paginated list of active products with their plans and pricing.

Request Parameters

Parameter	In	Type	Required	Description
categoryId	Query	uuid	No	Lọc theo danh mục
search	Query	string	No	Tìm kiếm theo tên sản phẩm
sort	Query	string	No	Sắp xếp: newest, oldest, price_asc, price_desc, bestseller
page	Query	integer	No	Số trang (mặc định: 1)
limit	Query	integer	No	Số lượng/trang (mặc định: 10, tối đa: 100)

cURL

curl "https://api-shopkey.brotemplate.com/v1/products?page=1&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

Response Fields

Field	Type	Description
success*	boolean	Operation result
data*	array<object>	Danh sách sản phẩm
└ id*	uuid	ID sản phẩm
└ name*	string	Tên sản phẩm
└ slug*	string	Slug
└ description	string	Mô tả sản phẩm
└ isFeatured*	boolean	Sản phẩm nổi bật?
└ isBestseller*	boolean	Sản phẩm bán chạy?
└ salesCount*	number	Số lượng đã bán
└ price	string	Giá gốc
└ salePrice	string	Giá khuyến mãi
└ rating*	string	Đánh giá trung bình
└ createdAt*	string	Ngày tạo (ISO 8601)
meta*	object	Response metadata
└ timestamp*	string	Thời gian response
└ requestId*	string	Request ID
└ pagination	object	Thông tin phân trang
└ page*	integer	Trang hiện tại
└ limit*	integer	Số lượng/trang
└ total*	integer	Tổng số sản phẩm
└ totalPages*	integer	Tổng số trang
└ hasNext*	boolean	Còn trang tiếp theo?
└ hasPrev*	boolean	Có trang trước?

Response Example

JSON

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Key Adobe Creative Cloud All Apps",
      "slug": "key-adobe-creative-cloud-all-apps",
      "description": "Mô tả sản phẩm...",
      "isFeatured": false,
      "isBestseller": true,
      "salesCount": 24,
      "price": "500000.0000",
      "salePrice": "375000.0000",
      "rating": "4.5",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-02-02T15:23:14.000Z",
    "requestId": "req-abc-123",
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 21,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Danh sách danh mục

GET

/v1/categories

List active categories as a tree

Returns the full category tree with nested sub-categories.

cURL

curl "https://api-shopkey.brotemplate.com/v1/categories" \
  -H "x-api-key: YOUR_API_KEY"

Response Fields

Field	Type	Description
success*	boolean	Operation result
data*	object	Category tree
└ tree*	array<object>	Cây danh mục
└ id*	uuid	ID danh mục
└ parentId	uuid	ID danh mục cha (null nếu là root)
└ name*	string	Tên danh mục
└ slug*	string	Slug
└ iconUrl	string	URL icon
└ sortOrder*	number	Thứ tự sắp xếp
└ status*	string	Trạng tháiEnum: active, inactive
└ children	array<object>	Danh mục con (đệ quy)
meta*	object	Response metadata
└ timestamp*	string	Thời gian response
└ requestId*	string	Request ID

Response Example

JSON

{
  "success": true,
  "data": {
    "tree": [
      {
        "id": "cat-001",
        "parentId": null,
        "name": "Tiện Ích",
        "slug": "tien-ich",
        "iconUrl": "https://example.com/icon.png",
        "sortOrder": 0,
        "status": "active",
        "children": [
          {
            "id": "cat-002",
            "parentId": "cat-001",
            "name": "Giải Trí",
            "slug": "giai-tri",
            "sortOrder": 1,
            "status": "active",
            "children": []
          }
        ]
      }
    ]
  },
  "meta": {
    "timestamp": "2026-02-02T15:23:14.000Z",
    "requestId": "req-abc-123"
  }
}

Kiểm tra số dư

GET

/v1/wallet/summary

Get current user wallet summary

Returns the current wallet balance, lifetime deposit, and total spent.

cURL

curl "https://api-shopkey.brotemplate.com/v1/wallet/summary" \
  -H "x-api-key: YOUR_API_KEY"

Response Fields

Field	Type	Description
success*	boolean	Operation result
data*	object	Wallet information
└ currency*	string	Loại tiền tệ (VND)
└ balance*	string	Số dư khả dụng hiện tại
└ totalDeposited*	string	Tổng nạp tích lũy
└ totalSpent*	string	Tổng chi tiêu xấp xỉ
meta*	object	Response metadata
└ timestamp*	string	Thời gian response
└ requestId*	string	Request ID

Response Example

JSON

{
  "success": true,
  "data": {
    "currency": "VND",
    "balance": "93537500.0000",
    "totalDeposited": "100000000.0000",
    "totalSpent": "6462500.0000"
  },
  "meta": {
    "timestamp": "2026-02-02T15:23:14.000Z",
    "requestId": "req-abc-123"
  }
}

Thông tin tài khoản

GET

/v1/auth/me

Current user profile

Returns the authenticated user's profile information and account settings.

cURL

curl "https://api-shopkey.brotemplate.com/v1/auth/me" \
  -H "x-api-key: YOUR_API_KEY"

Response Fields

Field	Type	Description
success*	boolean	Operation result
data*	object	User profile
└ id*	uuid	User ID
└ email*	string	Email
└ username*	string	Tên đăng nhập
└ fullname	string	Họ tên đầy đủ
└ phone	string	Số điện thoại
└ avatarUrl	string	URL ảnh đại diện
└ role*	string	Vai tròEnum: admin, user
└ active*	boolean	Tài khoản đang hoạt động?
meta*	object	Response metadata
└ timestamp*	string	Thời gian response
└ requestId*	string	Request ID

Response Example

JSON

{
  "success": true,
  "data": {
    "id": "user-001",
    "email": "[email protected]",
    "username": "admin",
    "fullname": "Admin User",
    "phone": "0987654321",
    "avatarUrl": "/uploads/avatars/avatar.jpg",
    "role": "user",
    "active": true
  },
  "meta": {
    "timestamp": "2026-02-02T15:23:14.000Z",
    "requestId": "req-abc-123"
  }
}

Error Codes

All API endpoints return errors in a consistent envelope. Every non-2xx response contains an error object with the following structure.

Error Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid x-api-key header
FORBIDDEN	403	Insufficient permissions for this resource
NOT_FOUND	404	Requested resource does not exist
VALIDATION_ERROR	422	Request body or parameters failed validation
RATE_LIMIT_EXCEEDED	429	Too many requests — rate limit applied
INTERNAL_ERROR	500	Unexpected server error
INSUFFICIENT_BALANCE	400	Wallet balance too low for this operation
OUT_OF_STOCK	400	Requested item is currently out of stock