واجهة برمجة مؤلفي حزم المودات: رموز التفعيل والتحديثات

لا حاجة لكتابة أي شيفرة برمجية. كل ما هو موضح أدناه متاح الآن على شكل أزرار أيضًا: إذا كانت حزمة موداتك مرتبطة بحسابك في Millida، يظهر تبويب «حزم المودات الخاصة بي» في ملفك الشخصي — وهناك ترفع الإصدارات وتحرّر البطاقة وتبني صفحات الهبوط. إن لم تكن مرتبطة — راسلنا وسنربطها. أما API فهي لمن ينشرون من نظام CI الخاص بهم.

هذا المقال موجّه لمؤلفي حزم المودات المدفوعة الذين يبيعونها بأنفسهم ويسلّمون تركيب الخادم إلينا. لا يحتاج المشتري إلى تنزيل أي شيء: يُدخل رمزًا فيحصل على حزمة مودات منشورة. لمعرفة كيف يبدو ذلك من جهته، اقرأ حزمة مودات مدفوعة عبر رمز التفعيل.

ما تحتاجه للبدء

1. أرسل إلينا الأرشيف الخادمي لحزمة موداتك — ملف .zip يحتوي على mods/ في الجذر (بدون مجلد تغليف مثل Server Files/) أو ملف .mrpack. يُحفظ الأرشيف في مخزننا الخاص، ولا يُشارك الرابط خارجيًا أبدًا.
2. أخبرنا بالنواة وإصدار اللعبة والذاكرة الدنيا — يستخدمها المعالج لاستبعاد الخطط التي لن تعمل حزمة المودات عليها.
3. احصل منا على مفتاح حزمة المودات (key، مثل arcania) ورمز الإصدار — يستخدمه موقعك لتوليد الرموز.

يُعرض الرمز مرة واحدة فقط: نحن نحفظ بصمته فقط. إذا فقدته، اطلب منا إعادة إصداره — وسيتوقف القديم عن العمل.

كيف يعمل المخطط

• أنت تستقبل الدفع بنفسك، من جهتك.
• بعد الدفع، يستدعي موقعك API الخاصة بنا ويحصل على رمز تفعيل.
• تعطي الرمز للمشتري — عبر البريد الإلكتروني أو بوت أو في صفحة «شكرًا لك».
• يُدخل المشتري الرمز من جهتنا فيحصل على خادم بحزمة المودات على خطة مدفوعة.
• تكون ملفات حزمة المودات على الخادم مقفلة: لا يمكن تنزيل mods من لوحة التحكم أو عبر SFTP.

عمليًا، لا تصل حزمة المودات الخادمية إلى يد المشتري أبدًا — بل خادم يعمل فقط.

نقطة النهاية والتفويض

عنوان الأساس — https://millida.net/v2/hosting.

يُمرَّر الرمز في ترويسة X-Pack-Token. وهو ليس JWT ولا رمز Bearer — بل سرّ منفصل خاص بحزمة موداتك.

X-Pack-Token: mpk_pack_XXXXXXXXXXXXXXXX
Content-Type: application/json

يبقى الرمز على خادمك — احفظه في متغيرات البيئة، لا في شيفرة الواجهة الأمامية.

إصدار الرموز

POST /v2/hosting/packs/{key}/keys

curl -X POST https://millida.net/v2/hosting/packs/arcania/keys \
  -H "X-Pack-Token: $PACK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"count": 1, "note": "order 4821"}'

{
  "code": "A7K2-9MHD-4RTP-QW38",
  "codes": ["A7K2-9MHD-4RTP-QW38"]
}

الحقل code هو أول رمز في الدفعة، محفوظ للتوافق؛ وعندما يكون count > 1 استخدم codes.

تُعاد الرموز هنا فقط ولا مكان غير هنا. نحن نحفظ تجزئتها — مثل كلمة المرور. إذا فقدت رمزًا، لا يمكننا استعادته: أصدر رمزًا جديدًا وأبطل القديم.

الحد هو 30 طلبًا في الدقيقة لكل حزمة مودات. الدفعات التي تصل إلى 200 رمز في الاستدعاء الواحد موجودة تحديدًا لأجل المبيعات: ولّدها بالجملة بدلًا من رمز واحد لكل طلب.

ما حدث للرموز

GET /v2/hosting/packs/{key}/keys?limit=100

[
  {
    "codeHint": "A7K29MHD",
    "note": "order 4821",
    "maxServers": 1,
    "usedCount": 1,
    "state": "spent",
    "expiresAt": null,
    "revokedAt": null,
    "createdAt": "2026-08-03T12:20:11.000Z"
  }
]

الرموز نفسها ليست في الاستجابة ولا يمكن أن تكون. codeHint هو بداية الرمز — استخدمه لمطابقة السطر بطلبك.

الحالات: free — غير مستخدم، spent — مستخدم، expired — منتهي الصلاحية، revoked — مُبطَل من قبلك.

التحقق من رمز واحد

POST /v2/hosting/packs/{key}/keys/status، والجسم {"code": "A7K2-9MHD-4RTP-QW38"}.

الاستجابة هي السطر نفسه كما في القائمة. يُمرَّر الرمز في الجسم، لا في الرابط: فالروابط تنتهي في سجلات الوسيط وفي سجل المتصفح، وقبل التفعيل يكون الرمز مفتاحًا فعّالًا.

لا تهمّ الشرطات ولا حالة الأحرف: سيُعثر على a7k29mhd4rtpqw38 تمامًا كما على A7K2-9MHD-4RTP-QW38.

إبطال رمز

POST /v2/hosting/packs/{key}/keys/revoke، والجسم {"code": "..."}.

استخدمه لعمليات الاسترداد أو الإصدارات الخاطئة أو النزاعات. الإبطال يمنع التفعيلات المستقبلية لكنه لا يزيل حزمة مودات منشورة بالفعل — فالمشتري الذي فعّلها يحتفظ بخادم يعمل.

خطاف الويب للتفعيل

إذا أعطيتنا رابط خطاف ويب، سنستدعيه لحظة استخدام رمز:

POST <your-address>
X-Millida-Pack: arcania
Content-Type: application/json

{
  "event": "pack.activated",
  "packKey": "arcania",
  "codeHint": "A7K29MHD",
  "serverId": "cm4x...",
  "activatedAt": "2026-08-04T09:14:02.000Z"
}

الاستدعاء غير موقّع: يمكنك التحقق منه بالرمز نفسه عبر keys/status — فباستخدام codeHint ستجد سطرك وترى state: "spent". بهذه الطريقة لا تحتاج إلى حفظ سرّ ثانٍ.

يُرسَل خطاف الويب دون انتظار استجابة ولا يُعاد إرساله: إذا كان خادمك متوقفًا، فقد تمّ التفعيل رغم ذلك، ويمكنك رؤيته في قائمة الرموز. يجب أن يكون الرابط عامًا — فنحن لا نستدعي العناوين الداخلية أو المحلية. ولا نتبع عمليات إعادة التوجيه.

بطاقة حزمة المودات

GET /v2/hosting/packs/{key} عام، ولا يحتاج إلى رمز. يعيد ما يراه المشتري: الاسم والنواة والإصدار والذاكرة الدنيا وقائمة الخطط وأعلام الحماية. ولا يوجد رابط الأرشيف في الاستجابة.

مفيد لصفحة «الشراء» على موقعك: تأتي متطلبات الخطط من مصدر واحد فلا تتباين مع ما يقوله معالجنا.

أنت تحرّر حقول الواجهة في بطاقتك بنفسك: PATCH /v2/hosting/packs/{key} مع الرمز يقبل name وauthorName وauthorUrl وiconUrl وwebhookUrl. أما شروط البيع (paidOnly وrequireKey وlockFiles وplanCodes) وتفعيل حزمة المودات في الواجهة وأعلام تشغيل JVM فلا يمكن تغييرها بالرمز — فهي اتفاقنا معك وعُقدنا، لذا راسلنا بشأنها.

تحديثات حزمة المودات

سابقًا كان التحديث يعني مراسلتنا بالبريد والانتظار. الآن تنشر إصدارًا بنفسك، ويختاره أصحاب الخوادم بأنفسهم في لوحة التحكم.

النقطة الجوهرية: لا نحدّث أي خادم بصمت أبدًا. فالانتقال بين إصدارات حزمة المودات قد يكون غير متوافق مع العالم، وصاحب الخادم هو من يتخذ القرار. الإصدار المنشور هو ما تحصل عليه الخوادم الجديدة وما نعرضه على الخوادم المنشورة بالفعل؛ وتبقى الإصدارات السابقة في القائمة، ويمكنك البقاء عليها أو التراجع إليها.

كيف تبدو الدورة

# 1. Create a version
curl -X POST https://millida.net/v2/hosting/packs/arcania/versions \
  -H "X-Pack-Token: $PACK_TOKEN" -H "Content-Type: application/json" \
  -d '{"label":"1.5.0","changelog":"Updated Create to 0.5.1, fixes crash on portals","minRamMb":10240}'

# 2. Upload the archive in chunks (32 MB each), addressing by offset
curl -X POST "https://millida.net/v2/hosting/packs/arcania/versions/1.5.0/archive?offset=0" \
  -H "X-Pack-Token: $PACK_TOKEN" -H "Content-Type: application/octet-stream" \
  --data-binary @part0.bin

# 3. Say the archive is finished, and publish after parsing
curl -X POST https://millida.net/v2/hosting/packs/arcania/versions/1.5.0/finish \
  -H "X-Pack-Token: $PACK_TOKEN" -H "Content-Type: application/json" \
  -d '{"archiveSha256":"<sha256 of archive>","publish":true}'

# 4. Wait for parsing
curl https://millida.net/v2/hosting/packs/arcania/versions/1.5.0 -H "X-Pack-Token: $PACK_TOKEN"

الإصدار

الرفع

POST /v2/hosting/packs/{key}/versions/{label}/archive?offset=N، المحتوى — جزء من ملف .zip، Content-Type: application/octet-stream. حجم الجزء حتى 32 ميغابايت، والأرشيف كاملًا حتى 4 غيغابايت.

يُعنون الجزء بـ الإزاحة، وليس «الإضافة إلى النهاية»: الجزء الذي انقطع في منتصفه قد استقر جزئيًا في الملف، وإعادة المحاولة ستضيف نفس البايتات مرة ثانية — فيصل الأرشيف تالفًا بصمت. تُرجع الاستجابة uploadedBytes، ويُستخدم لاستئناف الرفع بعد الانقطاع.

التحليل

POST .../finish يستجيب فورًا (status: "processing")، بينما يجري التحليل في الخلفية: فكّ إعداد خادم بحجم غيغابايت يستغرق دقائق. اقرأ الحالة من GET .../versions/{label}: processing ← ready أو failed مع نص السبب في error.

ما الذي يجب أن يجتازه الأرشيف:

• أن يكون حزمة خادم: بعد إزالة الغلاف الواحد (Server Files/ وما شابه)، يكون mods/ أو plugins/ في الجذر. حزمة عميل على خادم تنتج عالمًا فارغًا، لذا نرفضها بدل تثبيتها؛
• لا .. ولا مسارات مطلقة ولا فواصل Windows في الأسماء داخل الأرشيف؛
• لا كلمة مرور، ولا طرق ضغط غريبة (فقط store و deflate)؛
• الحدود: 60,000 ملف، 12 غيغابايت بعد الفك، نسبة ضغط حتى 200×.

الفشل لا يؤثر على الإصدار المنشور: يبقى عملاؤك على الإصدار السابق، وترفع من جديد. المسودات غير المكتملة: لا تزيد على ثلاث لكل إعداد خادم، وتُنظَّف المتروكة تلقائيًا بعد يوم.

النشر والتراجع والإزالة

ينقل النشر النواة وإصدار اللعبة وتثبيت المُحمّل و Java والحد الأدنى للذاكرة الخاص بالإصدار إلى بطاقة إعداد الخادم: تحصل عليها الخوادم الجديدة دون أي إجراء إضافي منك.

ما الذي يراه مالك الخادم

في لوحة التحكم، في كتلة إعداد الخادم المميز: أي إصدار مثبّت، وأي إصدار صدر، وchangelog الخاص بك، وقائمة إصدارات مع زر «تبديل». التحديث لا يؤثر على العالم — تُستبدل ملفات إعداد الخادم فقط، ونأخذ نسخة قبل الاستبدال. المودات المخصصة، إن سمحت بها، سيلزم إضافتها مجددًا بعد التبديل: إعداد الخادم ينتقل ككتلة واحدة، ونصف الإصدار القديم في mods/ يعني انهيارًا عند التشغيل.

إذا كانت خطة المالك لا تستوعب إصدارًا، نعرضه مع السبب بدل إخفائه: ينبغي أن يرى الشخص ما يحتاجه، لا أن يخمّن لماذا لا يتحدث إعداد الخادم.

صفحة إعداد الخادم الخاصة بك

تبني صفحة الهبوط لإعداد خادمك بنفسك في حسابك (الملف الشخصي ← «إعدادات خوادمي» ← «صفحات إعداد الخادم»): الشاشة الأولى، الميزات، لقطات الشاشة، الأسئلة والأجوبة، ألوانك. تُملأ الخطط وقائمة الإصدارات ببياناتنا حتى لا تتقادم.

تعيش الصفحة الجاهزة على millida.net/sborka/<your-address> — صفحة موقع عادية، تفهرسها محركات البحث وتُضمَّن في خريطة موقعنا. المسودة لا يراها أحد غيرك.

تُرفع الصور في المكان نفسه، في حسابك: تُقدَّم الصفحة من نطاقنا، وتُخزَّن ملفاتها عندنا — إذا تعطلت استضافتك، تبقى الصفحة سليمة.

لا يمكن تعديل الصفحات عبر الـ API: إنها شاشة، لا عملية نشر.

رموز الاستجابة

كيف تختبر كل شيء قبل البيع

اطلب منا رمزين تجريبيين: أصدر رمزًا عبر الـ API، وفعّله على خادمك على استضافتنا، وراقب ما وصل إلى الـ webhook وما يعرضه keys/status. بهذه الطريقة ترى مسار المشتري كاملًا قبل أن يمر به أول عميل يدفع.