واجهة API للموزعين - التوثيق التقني

آخر تحديث:

واجهة API للموزعين - التوثيق التقني
اربط متجرك أو البوت أو لوحتك مباشرة بـ SuperCoinsy. تحقق من المخزون والأسعار لحظياً، أنشئ الطلبات وادفع ثمنها، تابع حالتها وراسل فريقنا - كل ذلك دون فتح لوحة الموزع. تجد في الأسفل كل ما يحتاجه المطوّر لديك: كيف تُفعّل الوصول، وكيف توثّق الطلبات، وما الذي تُعيده كل نقطة نهاية.
ما تحتاجه قبل البدء
حساب موزّع فعّال
تعمل الواجهة فوق رصيدك كموزّع، وتُخصم الطلبات منه مباشرة، لذا اشحن الرصيد قبل أول طلب.
تفعيل الوصول إلى API من طرف الإدارة
هذه خطوة تتم مرة واحدة من جهتنا. راسلنا على [email protected] أو عبر Discord على supercoinsy وسنفعّله على حسابك.
عنوان IP ثابت
كل مستخدم API مرتبط بعنوان IP واحد يُسمح له بالاتصال منه. جهّز العنوان قبل إنشاء أول رمز وصول.
كيف تحصل على رمز الوصول
1
اطلب تفعيل الوصول إلى API على حساب الموزع الخاص بك عبر وسائل التواصل أعلاه.
2
بعد التفعيل، افتح supercoinsy.com/account/reseller/api-users - من هنا تدير جميع مستخدمي API لديك.
3
اضغط CREATE وأدخل عنوان IP الذي ستتصل منه. أي طلب من عنوان آخر يُرفض. يمكنك إدخال * لتخطي التحقق من العنوان، لكن على مسؤوليتك. هذا يعمل في API v1 فقط.
4
انسخ رمز الوصول المكوّن من 60 حرفاً واحفظه في مكان آمن: يظهر مرة واحدة فقط ولا يمكن عرضه لاحقاً. بجانبه يظهر أيضاً معرّف من 6 أحرف يميّز مستخدم API في سجلات العمليات لدينا.
5
اضغط Turn ON في الجدول لتفعيل مستخدم API، وعندها يصبح الاتصال جاهزاً. يمكنك تعطيله مؤقتاً أو حذفه نهائياً في أي وقت.
يمكنك الاحتفاظ بعدة مستخدمي API في الوقت نفسه - مثلاً واحد للمتجر في بيئة الإنتاج وآخر للاختبار - لكل منهما عنوان IP ورمز وصول خاص به.
التوثيق
يتم التوثيق عبر ترويسات الطلب. الأسطر الثلاثة كلها مطلوبة في كل طلب، ويجب أن يصدر الطلب من عنوان IP المخصص لمستخدم API نفسه.
Content-Type: application/json
X-Authorization: <رمز الوصول المكوّن من 60 حرفاً>
X-UserID: <المعرّف المكوّن من 6 أحرف>
العنوان الأساسي
جميع نقاط النهاية تقع تحت https://supercoinsy.com/api/ وكل الاستجابات بصيغة JSON.
نقاط النهاية (اضغط للتوسيع)
GET - المخزون المتاح
يعرض ما يمكننا تسليمه الآن لكل منصة. طلب مناسب لتنفيذه أولاً قبل إظهار زر الشراء في متجرك.
GET https://supercoinsy.com/api/reseller/available-stock
الاستجابة
{
  "status": 1,
  "data": [
    { "platform": "PC", "stock_available": 10 },
    { "platform": "PS5, PS4, XSX, XSS, XONE, Stadia", "stock_available": 10 }
  ]
}
GET - الأسعار الحالية
سعرك كموزّع لكل منصة. استعلم عنه بانتظام بدلاً من تثبيت القيم في الكود، حتى يبقى هامش ربحك كما تريده.
GET https://supercoinsy.com/api/reseller/prices
الاستجابة
{
  "status": 1,
  "data": [
    { "platform": "PC", "price": "1.00" },
    { "platform": "PS5, PS4, XSX, XSS, XONE, Stadia", "price": "2.00" }
  ]
}
POST - إنشاء طلب جديد ودفع قيمته
ينشئ الطلب ويخصم قيمته من رصيدك كموزّع في نداء واحد. إذا كان الرصيد غير كافٍ، لا يتم إنشاء الطلب.
POST https://supercoinsy.com/api/reseller/new-transaction
المعاملات
quantity (مطلوب) - القيمة بوحدة K، أي أن 150 تعني 150,000 coins.
platform (مطلوب) - pc أو ps. انتبه: القيمة ps تشمل جميع أجهزة الكونسول، أي PlayStation وXbox وStadia معاً.
emailapp (مطلوب) - البريد الإلكتروني لحساب EA المستخدم لتسجيل الدخول إلى WebApp.
passapp (مطلوب) - كلمة مرور حساب EA نفسه.
codesapp (مطلوب) - رموز backup codes الخاصة بـ EA، مفصولة بفواصل. أرسل ثلاثة رموز جديدة على الأقل.
userorderid (اختياري) - رقم الطلب لديك؛ يعود إليك في الحقل your_id.
usernotes (اختياري) - ملاحظة موجهة لفريقنا.
جسم الطلب
{
  "quantity": 150,
  "platform": "pc",
  "emailapp": "[email protected]",
  "passapp": "pass-app-test1",
  "codesapp": "one, two, three",
  "userorderid": "MY-ID2586",
  "usernotes": "please process quickly"
}
الاستجابة
{
  "status": 1,
  "message": "Payment accepted",
  "number": "R_QWERTY"
}
احفظ قيمة number المُعادة
القيمة في الحقل number هي المعرّف المستخدم في كل نداء لاحق: التفاصيل والرسائل والإلغاء.
GET - قائمة العمليات
يعيد طلباتك مقسّمة على صفحات، من الأحدث إلى الأقدم. استخدمه لمزامنة قاعدة بياناتك مع بياناتنا.
GET https://supercoinsy.com/api/reseller/list-transactions?page=1
page (اختياري، عدد صحيح) - بدونه تصلك الصفحة الأولى. تخبرك الاستجابة بعدد الصفحات الإجمالي.
الاستجابة
{
  "total": 10,
  "pages": 1,
  "orders": [
    {
      "number": "R_ABCDEF",
      "placed": "2021-08-17 16:11:57",
      "your_id": "",
      "platform": "PS5, PS4, XSX, XSS, XONe, Stadia",
      "quantity": 100,
      "status": "Paid, waiting for delivery",
      "max_delivery_time": "2021-08-17 18:11:57"
    }
  ]
}
GET - تفاصيل العملية
كل ما لدينا عن طلب واحد، بما في ذلك البيانات التي أرسلتها والمهلة التي نعمل ضمنها.
GET https://supercoinsy.com/api/reseller/get-transaction/{identifier}?currency=EUR
identifier (مطلوب) - رقم الطلب، مثل R_ABCDEF.
currency (اختياري) - EUR أو USD. القيمة الافتراضية هي EUR.
الاستجابة
{
  "number": "R_ABCDEF",
  "your_id": "TEST123",
  "placed": "2021-08-17 16:11:57",
  "value": "6.40 EUR",
  "platform": "PS5, PS4, XSX, XSS, XONe, Stadia",
  "quantity": 100,
  "emailapp": "[email protected]",
  "passapp": "test_pass",
  "usernotes": "notes-example-text",
  "codesapp": "test_code",
  "status": "Paid, waiting for delivery",
  "max_delivery_time": "2021-08-17 16:11:57"
}
POST - إرسال رسالة إلى طلب
يضيف رسالة إلى محادثة الطلب، تماماً كما لو كتبتها في لوحة الموزع. استخدمه لإرسال رموز backup codes جديدة أو لتنبيه فريقنا إلى أي أمر.
POST https://supercoinsy.com/api/reseller/transaction/{identifier}/message
جسم الطلب
{
  "message": "My new message to the order"
}
الاستجابة
{
  "status": 1,
  "message": "Message has been sent"
}
GET - إلغاء طلب
يرسل طلب إلغاء. هو طلب وليس إلغاءً فورياً: تعتمده إدارتنا أولاً، وعندها فقط يعود المبلغ إلى رصيدك باليورو (EUR).
GET https://supercoinsy.com/api/reseller/cancel-transaction/{identifier}
الاستجابة
{
  "status": 1,
  "message": "A cancellation request has been sent. SC Points will be refund to your account after approval by the admin."
}
API v2 وwebhooks
يعمل API v2 إلى جانب v1، وv1 لا يتغيّر. يضيف v2 منتجات أكثر والرصيد وسجل الرصيد والتصدير وwebhooks. المنتجات التي يمكنك طلبها تعتمد على حسابك: يعرضها GET /products.
رمز خاص وعنوان أساسي
لـ API v2 مستخدمو API خاصون به. أنشئهم في لوحة الموزعين ضمن API & webhooks (supercoinsy.com/account/reseller/api-v2). يبدأ رمز v2 بـ sc2_ ويعمل في v2 فقط، ولا يعمل رمز v1 هناك. الترويسات نفسها: X-UserID وX-Authorization. يحتاج كل مستخدم API إلى قائمة عناوين IP مسموحة: القائمة الفارغة ترفض كل الطلبات. الحدود: 120 طلباً في الدقيقة لكل مستخدم API و300 لكل حساب موزع.
https://supercoinsy.com/api/reseller/v2
نقاط النهاية
GET   /stock
GET   /prices
GET   /products
GET   /orders
POST  /orders          (header Idempotency-Key, up to 20 items, all or nothing)
GET   /orders/{id}
PATCH /orders/{id}/account
POST  /orders/{id}/cancel
GET   /orders/{id}/proof
GET   /orders/{id}/messages
POST  /orders/{id}/messages
GET   /division-rivals/quote
GET   /balance
GET   /ledger
GET   /topups
POST  /exports
GET   /exports/{id}
GET   /webhooks
PUT   /webhooks
POST  /webhooks/rotate
POST  /webhooks/test
GET   /webhooks/deliveries
تأتي الأخطاء بصيغة JSON فيها error وmessage. القائمة الكاملة مع الأمثلة في صفحة التوثيق داخل اللوحة: supercoinsy.com/account/reseller/api-v2/docs
الفروق عن v1
  • الكمية. للـ coins: quantity_k بالآلاف (150 تعني 150,000 coins). للأكواد والحسابات وسائر منتجات الكتالوج: quantity وهي عدد صحيح من القطع (150 تعني 150 قطعة). يعرض GET /products حقول النموذج لكل منتج.
  • المنصة. للـ coins: pc أو ps. للـ boosting: pc أو ps أو xbox (xbox لخدمة boosting على Xbox فقط). في المنتجات ذات السعر الواحد للكونسول تشمل ps كلاً من PlayStation وXbox.
  • رموز backup codes (للـ coins). اثنان على الأقل، ونوصي بستة.
  • الإلغاء. يعيد POST /orders/{id}/cancel المبلغ فوراً إذا لم يبدأ شيء. وإذا بدأ التسليم فهو طلب يؤكده فريقنا.
  • قائمة IP. عناوين عامة ونطاقات (IPv4 بما لا يتجاوز /16، وحتى 20 إدخالاً). الرمز * يعمل في v1 فقط.
Webhooks
  • حدّد عنوان https واحداً في اللوحة (API & webhooks) أو عبر PUT /webhooks: المنفذ 443، واسم مضيف (لا عنوان IP)، بلا إعادة توجيه.
  • اختر الأحداث: order.created, order.status_changed, order.needs_action, order.delivered, order.cancelled, export.ready.
  • نرسل POST بجسم JSON فيه id (معرّف الحدث) وevent وcreated_at وdata. في أحداث الطلبات تكون data هي الطلب بالصيغة نفسها المستخدمة في API. وفي export.ready تحتوي على id (معرّف التصدير) وkind وready_at. وفي webhook.test تحتوي على test: true وsent_at.
  • الترويسات: X-SC-Event وX-SC-Delivery وX-SC-Signature.
  • تحقق من التوقيع: قيمة X-SC-Signature بالشكل t=<unix time>,v1=<hex>، وv1 هو HMAC-SHA256 للنص "<t>.<body>" بسرّك (whsec_...). يظهر السر مرة واحدة، ويصدر POST /webhooks/rotate سراً جديداً.
  • أجب بأي رمز 2xx خلال 4 ثوانٍ. وإلا نعيد المحاولة بعد 1 و5 و15 و60 و240 دقيقة، وبعد 6 محاولات تُسجَّل الرسالة بالحالة failed.
  • إذا انتظر أكثر من 1000 حدث عنوانك، نوقف الـ webhook ونراسلك بالبريد. أصلح العنوان وأعد تشغيله من اللوحة.
  • يرسل POST /webhooks/test حدث webhook.test. ويعرض GET /webhooks/deliveries آخر عمليات الإرسال (حتى 100، وتُحفظ السجلات 30 يوماً).
  • الـ webhooks متاحة في API v2 فقط، ولا يوجد webhooks في API v1.
{
  "id": "<event id>",
  "event": "order.delivered",
  "created_at": "2026-11-05T10:15:00Z",
  "data": { "id": "R_A2B3C4", "type": "coins", ... }   (order event)
}
أمور يُستحسن معرفتها
API v1: قيمة quantity دائماً بوحدة K
أرسل 150 عندما تقصد 150,000 coins. إرسال الرقم كاملاً يُنشئ طلباً أكبر ألف مرة مما تريد.
API v1: القيمة "ps" تعني أي كونسول
لا توجد سوى قيمتين للمنصة. طلبات Xbox وStadia تُرسل بالقيمة ps مع PlayStation، لأنها تشترك في المخزون نفسه.
رموز backup codes للاستخدام مرة واحدة
في v1 أرسل ثلاثة رموز جديدة على الأقل مع كل طلب. الرموز المستخدمة في طلب سابق لن تسمح لنا بتسجيل الدخول، ويبقى الطلب معلقاً حتى ترسل غيرها.
حالة الطلب: استعلام دوري في v1 وwebhooks في v2
لا يوجد callback في API v1، لذا استعلم عن قائمة الطلبات أو عن نقطة التفاصيل على فترات معقولة، لا في حلقة متواصلة. أما API v2 فيستطيع استدعاء خادمك عند تغيّر الحالة: راجع قسم webhooks أعلاه.
رمز واحد، عنوان IP واحد
إذا تغيّر عنوان خادمك، عدّل مستخدم API أولاً وإلا رُفضت كل الطلبات. وإذا تسرّب رمز الوصول، عطّل ذلك المستخدم وأنشئ آخر.
واجهت مشكلة؟
إذا تصرّف أحد الطلبات بشكل مختلف عمّا هو موصوف هنا، أخبرنا بما أرسلته وبما وصلك، وسنراجع السجلات لدينا. راسلنا على [email protected] أو عبر Discord على supercoinsy.
لست بصدد الربط البرمجي بعد؟
كل ما تفعله الواجهة يمكن فعله يدوياً من لوحة الموزع: شحن الرصيد وإنشاء الطلبات ومتابعة حالتها.
دليل لوحة الموزع ←
جاهز للربط؟ أنشئ مستخدم API الخاص بك على supercoinsy.com/account/reseller/api-users
deliver
Check

Order or selling order status