Dành cho team kỹ thuật đối tác
Hướng dẫn tích hợp đối tác XuniBOX
Tài liệu một trang giúp đội kỹ thuật của bạn tích hợp kho nhạc XuniBOX vào màn hình “Chọn nhạc” trong khoảng một buổi làm việc: checklist theo giai đoạn, ví dụ request/response thật và bộ Postman collection tải về chạy ngay.
Checklist tích hợp
Tick từng mục khi hoàn thành. Tiến độ chỉ lưu trong phiên làm việc này.
1. Chuẩn bị truy cập
2. Tích hợp dữ liệu
3. Xử lý media
4. Vận hành & độ bền
Bảng endpoint tra nhanh
Tất cả đều là GET, base URL https://xunibox.vn/api/public. Endpoint dữ liệu cần header X-API-Key; nhóm vận hành thì không.
| Endpoint | Dùng để làm gì | API key |
|---|---|---|
| /tracks | Danh sách nhạc: q, title, artist, genre, artist_id, sort, page, limit (tối đa 100). | Có |
| /tracks/{id} | Metadata đầy đủ của một bài. Không tăng play_count. | Có |
| /tracks/{id}/audio-url | Link nghe thử đã ký còn hạn + expires_at. Gọi ngay trước khi phát. | Có |
| /tracks/by-ids | Làm mới hàng loạt, tối đa 50 UUID mỗi lượt. | Có |
| /genres | Danh sách thể loại đang dùng để dựng tab lọc. | Có |
| /artists | Duyệt hoặc tìm nghệ sĩ, kèm track_count. | Có |
| /artists/{id}/tracks | Nghệ sĩ + toàn bộ bài nhạc của họ trong một request. | Có |
| /healthz | Kiểm tra kết nối và phiên bản API. | Không |
| /readyz | Readiness probe (GET và HEAD) cho load balancer. | Không |
| /status | Chỉ số vận hành và cấu hình rate limit hiện hành. | Không |
| /metrics | Số liệu Prometheus để hệ thống giám sát scrape. | Không |
| /openapi.v1.json | Đặc tả OpenAPI 3.1 để sinh SDK, ghim cho production. | Không |
Mỗi response 200 kèm ETag, Cache-Control và các header X-RateLimit-Limit / Remaining / Reset. Riêng /tracks/{id}/audio-url luôn no-store vì link media chỉ sống 1 giờ.
Ví dụ request / response
Thay xnb_live_your_key bằng key được cấp. Tất cả endpoint đều là GET và trả JSON UTF-8.
Request — danh sách nhạc
curl --request GET \
--url 'https://xunibox.vn/api/public/tracks?sort=popular&page=1&limit=20' \
--header 'Accept: application/json' \
--header 'X-API-Key: xnb_live_your_key'Response 200
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: public, max-age=60, stale-while-revalidate=300
ETag: "8f2a1c0b9d..."
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Nắng Sài Gòn",
"artist": "Minh Anh",
"genre": "Indie Pop",
"duration": "3:24",
"audio_url": "https://.../preview.webm?token=...",
"preview_start_seconds": 42,
"preview_duration_seconds": 30,
"cover_url": "https://.../cover.webp?token=...",
"play_count": 1240,
"created_at": "2026-08-05T01:30:00.000Z"
}
],
"meta": { "total": 128, "page": 1, "limit": 20, "total_pages": 7, "media_expires_in": 3600 }
}Request — làm mới link nghe thử
curl --request GET \
--url 'https://xunibox.vn/api/public/tracks/550e8400-e29b-41d4-a716-446655440000/audio-url' \
--header 'X-API-Key: xnb_live_your_key'Response 200
HTTP/1.1 200 OK
Cache-Control: no-store
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"audio_url": "https://.../preview.webm?token=...",
"cover_url": "https://.../cover.webp?token=...",
"media_expires_in": 3600,
"expires_at": "2026-08-05T11:03:00.000Z"
}Response 429 — vượt hạn mức
HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Remaining: 0
{
"error": "rate_limit_exceeded",
"message": "Vượt hạn mức gọi API. Vui lòng thử lại sau.",
"retry_after_seconds": 37
}Quy ước lỗi
- 401 — thiếu header X-API-Key.
- 403 — key sai, bị vô hiệu hoặc hết hạn.
- 404 — track/nghệ sĩ không tồn tại.
- 429 — vượt hạn mức, chờ theo Retry-After.
- 5xx — retry tối đa 3 lần với backoff 1s / 2s / 4s.
Chạy thử bằng Postman
- 1. Tải file collection và import vào Postman (File → Import).
- 2. Mở tab Variables của collection, điền api_key.
- 3. Chạy request Danh sách bài nhạc, copy một id vào biến track_id.
- 4. Chạy Làm mới link nghe thử để xác nhận media hoạt động đầu-cuối.