واجهة برمجة السيرفر

ما تعرضه الواجهة

الواجهة للقراءة فقط ومحصورة في سيرفر واحد. وهي مخصصة لصفحات الحالة وجداول البيانات والأدوات الداخلية التي تريد الأرقام التي تعرضها لوحة التحكم دون تسجيل دخول. ولا تستطيع تغيير الإعدادات أو إغلاق التذاكر أو إنشاء فواتير.

تقع كل نقاط النهاية تحت https://noxyrbot.com/api/v1 وتُرجع JSON. والمفتاح يحدد السيرفر، لذلك لا تطلب أي نقطة نهاية معرّف سيرفر.

GET /api/v1/: النطاقات المفعّلة لهذا المفتاح ونقاط النهاية التي يستطيع الوصول إليها.
GET /api/v1/server: الاسم، والأيقونة، وعدد الأعضاء، وعدد المتصلين، وتعزيزات السيرفر، وتاريخ الإنشاء.
GET /api/v1/tickets: الإجماليات، وعدد المفتوحة والمغلقة، وحجم التذاكر خلال 7 و30 يومًا، ومتوسط التقييم.
GET /api/v1/activity?days=30: الرسائل والانضمامات والمغادرات اليومية، حتى 90 يومًا.
GET /api/v1/invoices: عدد الفواتير، والإيرادات حسب العملة، وحالة الدفع. ومع نطاق «روابط الفواتير» تضيف ?limit= أحدث الفواتير مع رابط صورة قابل للتنزيل.
GET /api/v1/reviews: متوسط التقييم، وتوزيع النجوم، وآخر خمسة تقييمات عامة.
GET /api/v1/giveaways: عدد النشطة والمنتهية، وإجمالي المشاركات، والمسابقات الحالية.

إنشاء مفتاح

لكل سيرفر مفتاح واحد. ويُنشأ من صفحة API الخاصة بالسيرفر ويُعرض مرة واحدة فقط، ولا يُخزَّن إلا تجزئته (hash). لذلك إذا ضاع المفتاح يجب إنشاء مفتاح جديد، وهذا يُبطل القديم.

افتح السيرفر في لوحة التحكم وانتقل إلى API.
اضغط «إنشاء» وانسخ المفتاح الذي يبدأ بـ nxr_. لن يُعرض مرة أخرى.
أوقف أي نطاق لا تحتاجه. ونطاق «روابط الفواتير» مُعطّل افتراضيًا لأنه يكشف صور فواتير العملاء.
اختياريًا: اضغط «إعداد القناة» ليُنشئ البوت فئة وقناة للواجهة في السيرفر تحتويان قائمة نقاط النهاية.

تعرض الصفحة أيضًا آخر مرة استُخدم فيها المفتاح وعدد الطلبات التي أجراها، وهذه أسرع طريقة لاكتشاف تسريب مفتاح. عطّله بالمفتاح، أو ألغِه لحذفه نهائيًا.

النطاقات

تتحكم النطاقات في نقاط النهاية، لا في الحقول. والطلب إلى نقطة نهاية نطاقها مُعطّل يحصل على 403 مع رسالة تسمّي النطاق.

overview: /server
tickets: /tickets
activity: /activity
invoices: /invoices
invoiceLinks: يضيف قائمة الفواتير الأخيرة مع روابط الصور. وهو مُعطّل افتراضيًا.
reviews: /reviews
giveaways: /giveaways

المصادقة ومثال على الطلب

أرسل المفتاح كـ Bearer token في ترويسة Authorization. والطلبات مسموحة من المتصفح (CORS مفتوح)، لكن المفتاح في كود الواجهة الأمامية يصبح مفتاحًا عامًا، لذا نفّذ الطلبات من سيرفر تتحكم فيه.

curl -H "Authorization: Bearer nxr_your_key" https://noxyrbot.com/api/v1/tickets
الاستجابة: {"total":128,"open":4,"closed":124,"opened7d":9,"opened30d":41,"closed7d":8,"averageRating":4.6,"ratingsCount":37}

حدود الطلبات

يستطيع كل مفتاح إجراء 60 طلبًا في الدقيقة. ويُعاد الحد في ترويسات RateLimit القياسية مع كل استجابة، وتجاوزه يُرجع HTTP 429 مع الخطأ «rate_limited». لا تستعلم أسرع من تغيّر البيانات، فقراءة إجماليات التذاكر والمبيعات مرة كل دقيقة كافية.

الأخطاء

كل خطأ يأتي بصيغة JSON فيه رمز خطأ قابل للقراءة من الآلات ورسالة مفهومة للبشر.

401 غير مصرح: ترويسة Authorization مفقودة، أو ليست Bearer token، أو المفتاح غير موجود.
403 key_disabled: أُوقف المفتاح من لوحة التحكم.
403 scope_disabled: هذا النطاق مُعطّل لهذا المفتاح.
404 not_found: نقطة نهاية غير معروفة. وتسرد الرسالة النقاط الصالحة.
404 guild_unavailable: لم يعد البوت في السيرفر.
429 rate_limited: أكثر من 60 طلبًا في الدقيقة.
500 internal_error: حدث خطأ من جهة Noxyr. أعد المحاولة لاحقًا.