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.
Câu hỏi thường gặp
Gọi API có làm tăng play_count không?
Không. play_count chỉ tăng khi người dùng nghe trên xunibox.vn liên tục đủ 10 giây. Mọi endpoint API đều không đụng tới con số này.
Có webhook báo khi kho nhạc có bài mới không?
Chưa có. Cách hiện tại là poll /tracks?sort=newest&limit=20 theo chu kỳ (15–60 phút là hợp lý) và so created_at với lần đồng bộ trước.
Nên dùng /tracks/:id hay /tracks/:id/audio-url để làm mới link?
Dùng /tracks/:id/audio-url nếu bạn chỉ cần media: response nhỏ hơn và có sẵn expires_at để bạn đặt lịch làm mới. Dùng /tracks/:id khi cần cả metadata (title, artist, genre, play_count).
Làm mới link cho cả playlist thì sao?
Gọi /tracks/by-ids?ids=… tối đa 50 UUID mỗi lượt thay vì lặp từng bài — tiết kiệm hạn mức rate limit đáng kể.
Tôi tải hết kho về database của mình được không?
Được, và nên làm với phần metadata (id, title, artist, genre, duration). Nhưng không cache URL media và không lưu file audio dài hạn.
Vì sao ảnh bìa lúc có lúc null?
cover_url là tùy chọn. Hãy chuẩn bị sẵn ảnh placeholder trong UI thay vì giả định luôn có ảnh.
Tìm kiếm có bỏ dấu tiếng Việt không?
Chưa. "mua he" sẽ không khớp "mùa hè". Nếu người dùng của bạn hay gõ không dấu, nên tự chuẩn hóa phía bạn hoặc đồng bộ metadata về để tìm cục bộ.
Một key dùng cho nhiều môi trường được không?
Được nhưng không nên — hạn mức tính chung. Xin key riêng cho staging để traffic test không làm production bị 429.
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.