واجهة برمجة تطبيقات مؤلفي الكتالوج

كل ما يفعله المؤلف بمواده على الموقع يمكن تنفيذه من سكربتك أو خط بناء المشروع الخاص بك: إنشاء مسودة، رفع نسخة جديدة، تعديل الصفحة، تغيير السعر، وعرض المبيعات. للقيام بذلك، تحتاج إلى مفتاح المؤلف — سلسلة نصية مثل mca_live_….

يعمل المفتاح مع موادك فقط: تلك التي أنت مؤلفها. لا يمكنك المساس بعمل شخص آخر به، حتى لو كنت تعرف عنوانه.

المفتاح

يُصدر المفتاح في ملفك الشخصي، في قسم المؤلف. سمِّ المفتاح واختر النطاقات؛ يُعرض المفتاح مرة واحدة — احفظه في أسرار خط البناء الخاص بك. إذا فقدته، أبطله وأصدر مفتاحًا جديدًا. يمكنك امتلاك ما يصل إلى عشرة مفاتيح نشطة. تغيير كلمة المرور أو البريد الإلكتروني يبطل جميع مفاتيح الحساب — أصدر مفاتيح جديدة بعد ذلك.

امنح خط البناء ما يحتاجه فقط: مفتاح البناء عادةً ما يكون مع versions:write و stats:read.

جميع نقاط النهاية تحت https://api.millida.net/v2؛ يوضع المفتاح في الترويسة:

Authorization: Bearer mca_live_…

موادّي

GET /catalog/author-api/items

[
  {
    "slug": "my-pack",
    "type": "MODPACK",
    "title": "My modpack",
    "status": "PUBLISHED",
    "moderationStatus": "PUBLISHED",
    "pricing": "ONE_TIME",
    "priceKopecks": 49900,
    "versionsCount": 12,
    "downloads": 5310,
    "publicUrl": "/modpacks/my-pack"
  }
]

مادة جديدة

POST /catalog/author-api/items
{ "type": "MOD", "title": "My mod", "summary": "Briefly about the mod" }

تظهر المادة كمسودة. يُؤخذ العنوان (slug) من الاسم؛ العنوان المحجوز يعيد 409 مع اقتراح عنوان متاح. السعر عند الإنشاء (pricing، priceKopecks) يمكن تمريره فقط بمفتاح يمتلك نطاق pricing:write؛ وإلا فالاستجابة 403 MISSING_SCOPE.

نسخة جديدة

1. رابط الرفع:

POST /catalog/author-api/items/my-pack/upload-url
{ "version": "1.4.0", "fileName": "my-pack-1.4.0.zip", "size": 734003200 }

{ "uploadUrl": "https://…", "storageKey": "catalog/packs/my-pack/…", "expiresIn": 3600 }

2. ارفع الملف بطلب PUT إلى uploadUrl — مباشرة إلى التخزين، دون وساطة منّا:

curl -X PUT --upload-file my-pack-1.4.0.zip "$UPLOAD_URL"

3. سجّل النسخة:

POST /catalog/author-api/items/my-pack/versions
{
  "version": "1.4.0",
  "storageKey": "catalog/packs/my-pack/…",
  "gameVersions": ["1.20.1"],
  "loaders": ["fabric"],
  "loaderVersion": "0.16.0",
  "changelog": "New quests"
}

تذهب النسخة إلى المراجعة التلقائية وتظهر للاعبين بعدها. كل رفع هو ملف جديد: لا يمكنك الكتابة فوق نسخة منشورة بالفعل.

الإرسال للمراجعة

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

POST /catalog/author-api/items/my-pack/authorship

{ "ok": true }

ثم أرسل المادة:

POST /catalog/author-api/items/my-pack/submit

{ "ok": true, "status": "PENDING" }

بدون التأكيد، تكون الاستجابة 400 «أكّد أن حزمة المودات لك وأن الترخيص اختيارك»؛ وبدون نسخة، 400 «ارفع ملف حزمة المودات أولًا».

الصفحة

PUT /catalog/author-api/items/my-pack/page
{ "title": "My modpack", "summary": "…", "descriptionMd": "## What's inside\n…" }

هذه مسودة: يرى اللاعبون الصفحة السابقة حتى تجتاز الجديدة المراجعة. يجب رفع الصور في الوصف إلينا فقط؛ ويجب أن تشير الروابط إلى صفحات Millida فقط. ارفع الأيقونة (iconUrl)، ولقطات الشاشة (gallery)، وصور الوصف أولًا:

curl -H "Authorization: Bearer $MCA_KEY" -F "file=@icon.png" https://api.millida.net/v2/catalog/author-api/images

{ "url": "https://…/uploads/…/icon.png" }

يُدعم PNG و JPG و WebP و AVIF حتى 15 ميغابايت؛ ولا يُدعم GIF. يتطلب الرفع نطاق page:write؛ وتحتوي الاستجابة على عنوان يمكنك وضعه في الصفحة. أرسل للمراجعة:

POST /catalog/author-api/items/my-pack/page/submit

السعر

PUT /catalog/author-api/items/my-pack/pricing
{ "pricing": "ONE_TIME", "priceKopecks": 49900 }

• المبالغ بالكوبيكات. الحد الأدنى لسعر مادة مدفوعة هو 300 ₽ (30000)، وللسكنات والعباءات — 50 ₽ (5000)؛ والحد الأقصى 100,000 ₽ (10000000).
• تأخذ المنصة 30% من كل عملية بيع؛ والباقي يذهب إلى محفظتك في Millida.
• يمكن إنفاق المال من عملية بيع داخل Millida فورًا، لكن السحب متاح بعد 7 أيام من الشراء.
• فقط من يمتلك الوصول يمكنه تنزيل ملفات مادة مدفوعة. بصفتك المؤلف، لديك الوصول دائمًا.

الإحصاءات

GET /catalog/author-api/items/my-pack/stats

{
  "versions": [{ "version": "1.4.0", "downloads": 312, "reviewStatus": "APPROVED" }],
  "players": { "players": 1204, "playersRecent": 380, "days": [{ "day": "2026-09-24", "players": 41 }] },
  "sales": {
    "totalKopecks": 998000,
    "netKopecks": 698600,
    "count": 20,
    "refundedCount": 0,
    "holdDays": 7,
    "last30d": [{ "day": "2026-09-24", "count": 3, "netKopecks": 104790 }]
  }
}

المبيعات عبر جميع المواد دفعة واحدة:

GET /catalog/author-api/sales

الأخطاء

تحتوي استجابة الخطأ دائمًا على message — يمكنك عرضه للشخص كما هو — وغالبًا على code — وهو مناسب للتفرع في السكربت.

الحدود

• 120 طلبًا في الدقيقة لكل مفتاح.
• المواد الجديدة — 10 في الساعة، روابط الرفع والنسخ — 30 في الساعة لكل منهما، تعديلات الصفحة — 120 في الساعة، الصور — 60 في الساعة، تغييرات السعر — 60 في الساعة.