REST API · v1

Tài liệu API XuniBOX

API chỉ đọc để lấy danh sách nhạc, nghệ sĩ và thể loại từ kho XuniBOX. Mỗi chủ đề dưới đây là một trang riêng, có đường dẫn riêng để bạn chia sẻ cho đội kỹ thuật.

Bắt đầu nhanh Xem endpoints Tra cứu yêu cầu

OpenAPI / Swagger và thử ngay

Toàn bộ /api/public/* được mô tả bằng file OpenAPI 3.1, phát hành theo từng phiên bản. Nạp thẳng URL vào Swagger UI, Postman, Insomnia, Stoplight hoặc trình sinh SDK — đây là các endpoint duy nhất không cần API key.

Chọn phiên bản đặc tả

Phiên bản ổn định hiện tại. Cố định đường dẫn này khi tích hợp production để không bị ảnh hưởng khi XuniBOX phát hành phiên bản mới.

https://xunibox.vn/api/public/openapi.v1.json

Tải xunibox-openapi.v1.jsonXem trực tiếp

Bí danh https://xunibox.vn/api/public/openapi.json luôn trỏ tới phiên bản mới nhất (v1). Khi tích hợp production nên cố định URL có số phiên bản để không bị ảnh hưởng lúc XuniBOX phát hành bản mới.

Trong Postman: Import → Link rồi dán URL trên. Trong Swagger UI: bấm Authorize và nhập key vào ô X-API-Key.

Thử ngay · cURL (copy nguyên khối)

# 1. Đặt key vào biến môi trường (đừng commit vào repo)
export XUNIBOX_API_KEY="xnb_live_your_key"

# 2. Gọi thử — copy nguyên khối này là chạy
curl -sS --url 'https://xunibox.vn/api/public/tracks?sort=popular&limit=3' \
  --header "X-API-Key: $XUNIBOX_API_KEY" \
  --header 'Accept: application/json' | jq

# 3. Thử luôn nghệ sĩ và thể loại
curl -sS --url 'https://xunibox.vn/api/public/artists?limit=3' --header "X-API-Key: $XUNIBOX_API_KEY" | jq
curl -sS --url 'https://xunibox.vn/api/public/genres' --header "X-API-Key: $XUNIBOX_API_KEY" | jq

Tải đặc tả v1 & sinh SDK · Terminal

# Tải đặc tả (không cần API key)
curl -sSL https://xunibox.vn/api/public/openapi.v1.json -o xunibox-openapi.v1.json

# Sinh SDK TypeScript từ đặc tả
npx openapi-typescript xunibox-openapi.v1.json -o xunibox-api.d.ts

Nhúng Swagger UI · HTML

<!-- Swagger UI đọc thẳng đặc tả của XuniBOX -->
<div id="swagger"></div>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
<script>
  SwaggerUIBundle({
    url: "https://xunibox.vn/api/public/openapi.v1.json",
    dom_id: "#swagger",
    // Nhập key một lần ở nút Authorize, Swagger tự gắn header X-API-Key
    requestInterceptor: (req) => {
      req.headers["X-API-Key"] = "xnb_live_your_key";
      return req;
    }
  });
</script>

Lỗi mẫu khi header X-API-Key sai

401 · Thiếu header X-API-Key

HTTP/1.1 Unauthorized

{
  "error": "Thiếu API key. Gửi khóa qua header X-API-Key."
}

403 · Key sai hoặc đã bị thu hồi

HTTP/1.1 403 Forbidden

{
  "error": "API key không hợp lệ hoặc đã bị vô hiệu hóa."
}

429 · Vượt hạn mức request mỗi phút

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1785921060

{
  "error": "Đã vượt quá giới hạn request của API key.",
  "code": "RATE_LIMIT_EXCEEDED",
  "limit": 120,
  "retry_after_seconds": 37,
  "reset_at": "2026-08-05T09:31:00.000Z"
}

Gặp 429 thì chờ đúng số giây trong Retry-After rồi thử lại; theo dõi X-RateLimit-Remaining để chủ động giãn nhịp gọi. Cần nâng hạn mức, hãy liên hệ để tăng quota cho key của bạn.

Request / Response Cấu trúc dữ liệu

Sẵn sàng tích hợp?

Gửi thông tin sản phẩm để admin XuniBOX xét duyệt và cấp API key.

Xin quyền tích hợp