MineList API cho chủ server

MineList API cho phép server của bạn kiểm tra người chơi đã bình chọn chưa, trao thưởng đúng một lần và đọc thống kê công khai. Mọi endpoint đều trả về JSON và dùng yêu cầu HTTPS GET thông thường nên dùng được với mọi ngôn ngữ lập trình.

Lấy API key

Hãy thêm server, xác nhận quyền sở hữu và mở bảng điều khiển chủ server. API key hiển thị trên trang cài đặt server. Hãy giữ bí mật vì nó xác định server của bạn. Nếu bị lộ, hãy tạo key mới trong bảng điều khiển và cập nhật plugin hoặc script của bạn.

Địa chỉ gốc của mọi endpoint là https://minelist.eu.

Kiểm tra phiếu bầu

GET /api/v1/vote?key=API_KEY&username=NICK

Cho biết hôm nay người chơi đã bình chọn chưa và phần thưởng đã được nhận chưa.

{"voted":true,"claimed":false,"next_vote_utc":"2026-10-31T00:00:00Z"}

voted là true nếu nick có phiếu cho server của bạn trong ngày UTC hiện tại.
claimed là true nếu bạn đã đánh dấu phiếu đó là đã nhận.
next_vote_utc là thời điểm người chơi có thể bình chọn lại.

Nhận phiếu bầu

GET /api/v1/vote/claim?key=API_KEY&username=NICK

Đánh dấu phiếu hôm nay là đã nhận. Hãy gọi ngay trước khi trao thưởng để người chơi không nhận hai lần. Các kết quả có thể có:

Phản hồi	Ý nghĩa
`{"voted":true,"claimed":true}`	Phiếu hợp lệ và giờ đã được nhận. Hãy trao thưởng.
`{"voted":true,"claimed":false,"already_claimed":true}`	Phiếu đã được nhận trước đó. Đừng trao gì.
`{"voted":false,"claimed":false}`	Hôm nay người chơi chưa bình chọn.

Danh sách phiếu bầu tháng này

GET /api/v1/votes?key=API_KEY

Trả về tất cả phiếu server của bạn nhận được trong tháng hiện tại. Rất hữu ích để thưởng top bình chọn hằng tháng và làm bảng xếp hạng trên website của bạn.

Thống kê công khai của server

GET /api/v1/server/<slug>

Endpoint này không cần key. Slug là phần cuối của địa chỉ server trên MineList. Các trường ví dụ trong phản hồi:

Trường	Mô tả
`name`	Tên server
`url`	Website của server
`ip`	Địa chỉ kết nối
`online`	Lần kiểm tra gần nhất có thành công không
`players`	Số người chơi online ở lần kiểm tra gần nhất
`max_players`	Số slot người chơi
`version`	Phiên bản server
`votes_month`	Phiếu bầu tháng này
`votes_total`	Phiếu bầu kể từ khi thêm server
`uptime_30`	Uptime 30 ngày gần nhất, tính theo phần trăm
`rating`	Đánh giá trung bình
`last_check`	Thời điểm kiểm tra gần nhất

Ví dụ với curl

Đây là toàn bộ logic ở dạng shell. Mọi ngôn ngữ gửi được yêu cầu HTTP, như Java, PHP, Python hay Node.js, đều làm tương tự.

curl -s "https://minelist.eu/api/v1/vote/claim?key=API_KEY&username=Steve"

Hãy phân tích JSON, và nếu claimed là true thì chạy lệnh trao thưởng, ví dụ give Steve diamond 3.

Hỗ trợ NuVotifier

Nếu bạn muốn trao thưởng tức thì mà không cần hỏi liên tục, MineList có thể đẩy phiếu bầu đến server qua NuVotifier. Cả hai phiên bản giao thức đều được hỗ trợ. Phiên bản 1 dùng khóa công khai RSA, phiên bản 2 dùng token.

Cài NuVotifier lên server rồi khởi động lại.
Trong bảng điều khiển chủ server, nhập host, port (mặc định 8192) và khóa công khai (v1) hoặc token (v2).
Bấm Gửi phiếu thử và kiểm tra xem server của bạn có ghi nhận phiếu không.

Nếu thử không thành công, hãy chắc chắn port Votifier đã mở trong firewall và khóa được sao chép không thừa dấu cách hay xuống dòng.

Banner trực tiếp

Mỗi server có một banner trực tiếp kích thước 468x60 pixel hiển thị trạng thái và số người chơi hiện tại:

https://minelist.eu/banner/<slug>.png

Ví dụ nhúng HTML:

<a href="https://minelist.eu/vi/server/slug-cua-ban">
  <img src="https://minelist.eu/banner/slug-cua-ban.png" width="468" height="60" alt="Bình chọn cho chúng tôi trên MineList">
</a>

Lưu ý khi sử dụng

Hãy cache thống kê công khai ít nhất một phút thay vì gọi API mỗi lần có người xem trang.
Không bao giờ đặt API key vào mã phía người dùng hoặc kho mã công khai.
Chỉ dùng endpoint claim một lần cho mỗi phần thưởng.