واجهة برمجة تطبيقات أرباح الشركاء

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

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

المفتاح

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

• يمكنك تحديد ما يصل إلى عشرة عناوين أو شبكات فرعية. يجب ألا تكون الشبكة الفرعية أوسع من /24 لعناوين IPv4 و/48 لعناوين IPv6.
• لا تُقبل العناوين المنزلية والمحلية (127.0.0.1، 10.x، 192.168.x): فأنت بحاجة إلى العنوان العام للخادم.
• يُعرض المفتاح مرة واحدة. احفظه على الخادم، في متغيرات البيئة، أو في مخزن أسرار، ولا تكشفه أبدًا للمتصفح.
• يمكنك امتلاك ما يصل إلى خمسة مفاتيح نشطة. إذا فقدت مفتاحًا أو غيّرت الخوادم، فأبطِل المفتاح القديم وأصدر مفتاحًا جديدًا. يتوقف المفتاح المُبطَل عن العمل فورًا.

جميع نقاط النهاية نسبية إلى https://api.millida.net/v2. يُمرَّر المفتاح في الترويسة:

Authorization: Bearer mek_live_…

الملخص

GET /earnings-api/v1/summary?from=2026-09-01T00:00:00.000Z&to=2026-09-30T23:59:59.999Z

from وto هما حدود الفترة بصيغة ISO 8601. كلا المعاملين اختياريان: بدونهما تغطي الفترة كل الأوقات.

{
  "currency": "RUB",
  "balance": {
    "balanceKopecks": 1254000,
    "availableKopecks": 1204000,
    "withdrawableKopecks": 980000,
    "heldKopecks": 50000,
    "pendingPayoutKopecks": 0,
    "tradeHoldKopecks": 0,
    "tradeHoldReadyAt": null,
    "marketHoldKopecks": 0,
    "marketWithdrawalReadyAt": null
  },
  "period": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-09-30T23:59:59.999Z",
    "earnedKopecks": 3108000,
    "heldKopecks": 0,
    "spentKopecks": 0,
    "toppedUpKopecks": 0,
    "paidOutKopecks": 2000000,
    "refundKopecks": 0,
    "netKopecks": 1108000,
    "operations": 142,
    "earnedBySource": [
      { "source": "catalog", "amountKopecks": 2950000, "operations": 131 },
      { "source": "hosting", "amountKopecks": 158000, "operations": 11 }
    ],
    "truncated": false
  },
  "subscriptions": {
    "subscribers": 14,
    "bundleSubscribers": 2,
    "packSubscribers": 12
  }
}

جميع المبالغ بالكوبيكات: 1254000 تعني 12 540 ₽.

قيم source:

قد تُضاف قيم جديدة بمرور الوقت. إذا لم تتعرّف على قيمة، فاعرضها كما هي ولا تعاملها كخطأ.

المشتركون

GET /earnings-api/v1/subscriptions?from=2026-09-01T00:00:00.000Z&to=2026-09-30T23:59:59.999Z

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

تُرجع واجهة برمجة التطبيقات أرقامًا فقط. لا يمكنك معرفة من المشترك تحديدًا من خلالها.

يحدّد from وto الفترة بالطريقة نفسها كما في الملخص. يؤثران فقط في كتلة period؛ أما كتل total وactive وrenewal وpacks فتُظهر دائمًا الحالة وقت الطلب.

{
  "from": "2026-09-01T00:00:00.000Z",
  "to": "2026-09-30T23:59:59.999Z",
  "generatedAt": "2026-09-28T16:30:00.000Z",
  "total": {
    "subscribers": 14,
    "bundleSubscribers": 2,
    "packSubscribers": 12
  },
  "partners": [
    {
      "partner": { "slug": "arcania-labs", "name": "Arcania Labs" },
      "active": {
        "subscribers": 14,
        "bundleSubscribers": 2,
        "packSubscribers": 12,
        "packSubscriptions": 12
      },
      "renewal": {
        "autoRenewing": { "bundle": 2, "packs": 12 },
        "canceledStillActive": { "bundle": 0, "packs": 0 }
      },
      "packs": [
        { "slug": "arcania", "title": "Arcania 1.4.3", "published": true, "activeSubscribers": 14, "viaPack": 12, "viaBundle": 2 },
        { "slug": "dread", "title": "DREAD - A Horror Survival Pack", "published": true, "activeSubscribers": 2, "viaPack": 0, "viaBundle": 2 }
      ],
      "period": {
        "newSubscriptions": { "bundle": 2, "packs": 12 },
        "canceled": { "bundle": 0, "packs": 0 },
        "expired": { "bundle": 0, "packs": 0 },
        "refunded": { "bundle": 0, "packs": 0 }
      },
      "truncated": false
    }
  ]
}

يسرد packs جميع حزم موداتك، بما في ذلك تلك التي لا مشتركين فيها.

يحتسب bundle الأشخاص، بينما يحتسب packs الاشتراكات في حزم المودات الفردية. إذا أُلغي اشتراك، فإنه يظهر في canceled في يوم الإلغاء، وفي expired عند انتهاء المدة المدفوعة.

الأخطاء

الحدود

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

مثال

curl -s https://api.millida.net/v2/earnings-api/v1/summary \
  -H "Authorization: Bearer $MILLIDA_EARNINGS_KEY"

curl -s https://api.millida.net/v2/earnings-api/v1/subscriptions \
  -H "Authorization: Bearer $MILLIDA_EARNINGS_KEY"