API máy chủ | Tài liệu Noxyr

API cung cấp gì

API chỉ đọc và giới hạn trong một máy chủ. Nó dành cho trang trạng thái, bảng tính và công cụ nội bộ muốn có các con số dashboard hiển thị mà không cần đăng nhập. Nó không thể thay đổi cài đặt, đóng ticket hay tạo hóa đơn.

Mọi endpoint nằm dưới https://noxyrbot.com/api/v1 và trả về JSON. Key xác định máy chủ, nên không endpoint nào nhận ID máy chủ.

GET /api/v1/: Những phạm vi nào đang bật cho key này và các endpoint mà nó truy cập được.
GET /api/v1/server: Tên, biểu tượng, số thành viên, số thành viên trực tuyến, lượt boost và ngày tạo.
GET /api/v1/tickets: Tổng số, số ticket đang mở và đã đóng, khối lượng trong 7 và 30 ngày, đánh giá trung bình.
GET /api/v1/activity?days=30: Số tin nhắn, lượt tham gia và rời đi theo ngày, tối đa 90 ngày.
GET /api/v1/invoices: Số lượng hóa đơn, doanh thu theo tiền tệ và trạng thái thanh toán. Với phạm vi liên kết hóa đơn, ?limit= thêm các hóa đơn gần đây kèm URL ảnh có thể tải về.
GET /api/v1/reviews: Đánh giá trung bình, phân bổ số sao và năm đánh giá công khai mới nhất.
GET /api/v1/giveaways: Số lượng đang hoạt động và đã kết thúc, tổng số lượt tham gia và các giveaway hiện tại.

Tạo key

Mỗi máy chủ có một key. Key được tạo trên trang API của máy chủ và chỉ hiển thị một lần - chỉ một hash được lưu, nên key bị mất phải được tạo lại, và điều đó sẽ vô hiệu hóa key cũ.

Mở máy chủ trên dashboard và vào API.
Nhấn Generate và sao chép key bắt đầu bằng nxr_. Key sẽ không được hiển thị lại.
Tắt mọi phạm vi bạn không cần. Liên kết hóa đơn mặc định tắt vì nó lộ hình ảnh hóa đơn của khách hàng.
Tùy chọn: nhấn Thiết lập kênh để bot tạo một danh mục và kênh API trong máy chủ kèm danh sách endpoint.

Trang này cũng hiển thị lần cuối key được dùng và số yêu cầu đã thực hiện, đây là cách nhanh nhất để phát hiện key bị rò rỉ. Tắt nó bằng công tắc, hoặc thu hồi để xóa hẳn.

Phạm vi

Phạm vi kiểm soát endpoint, không kiểm soát trường dữ liệu. Yêu cầu tới một endpoint có phạm vi đã tắt sẽ nhận 403 kèm thông báo nêu tên phạm vi đó.

overview: /server
tickets: /tickets
activity: /activity
invoices: /invoices
invoiceLinks: Thêm danh sách hóa đơn gần đây kèm liên kết ảnh. Mặc định tắt.
reviews: /reviews
giveaways: /giveaways

Xác thực và ví dụ yêu cầu

Gửi key dưới dạng Bearer token trong header Authorization. Các lời gọi từ trình duyệt được phép (CORS mở), nhưng key trong mã frontend là key công khai, nên hãy gọi API từ một máy chủ bạn kiểm soát.

curl -H "Authorization: Bearer nxr_your_key" https://noxyrbot.com/api/v1/tickets
Phản hồi: {"total":128,"open":4,"closed":124,"opened7d":9,"opened30d":41,"closed7d":8,"averageRating":4.6,"ratingsCount":37}

Giới hạn tốc độ

Mỗi key được gửi tối đa 60 yêu cầu mỗi phút. Giới hạn được trả về trong các header RateLimit tiêu chuẩn trên mọi phản hồi, và vượt quá sẽ trả về HTTP 429 với lỗi "rate_limited". Đừng truy vấn nhanh hơn tốc độ dữ liệu thay đổi - đọc tổng số ticket và doanh số mỗi phút một lần là đủ.

Lỗi

Mọi lỗi đều là JSON với một mã lỗi đọc được bằng máy và một thông báo cho người dùng.

401 không được phép: Thiếu header Authorization, không phải Bearer token, hoặc key không tồn tại.
403 key_disabled: Key đã bị tắt trên dashboard.
403 scope_disabled: Phạm vi đó đã bị tắt cho key này.
404 not_found: Endpoint không tồn tại. Thông báo liệt kê các endpoint hợp lệ.
404 guild_unavailable: Bot không còn trong máy chủ.
429 rate_limited: Vượt quá 60 yêu cầu trong một phút.
500 internal_error: Có lỗi xảy ra phía Noxyr. Hãy thử lại sau.