وثائق واجهة الموزّعين البرمجية

واجهة SHOP2TOPUP البرمجية للموزّعين هي واجهة REST بصيغة JSON لبيع شحن الألعاب وأكواد البطاقات من متجرك أو واجهة بيعك أو بوتك. يوثّق هذا المرجع كل نقطة نهاية عامة، ومعاملاتها، واستجاباتها.

العنوان الأساسي والنقل

كل مسار في هذا المرجع نسبيّ إلى العنوان الأساسي أدناه. الطلبات والاستجابات بصيغة JSON فوق HTTPS، والمبالغ نصوص حتى لا يتسلّل أي تقريب عشري، وكل طابع زمني بتوقيت UTC بصيغة ISO 8601.

https://shop2topup.com/api/endpoints/v1

المصادقة

يحمل كل طلب رأسًا واحدًا. يُصدَر زوج المفاتيح من صفحة API Access في لوحة الموزّع ويمكن تقييده بقائمة عناوين IP مسموح بها؛ ويُرفض أي نداء من عنوان آخر بالكود IP_NOT_ALLOWED قبل أن يصل إلى أي منطق عمل.

رأس الطلب

Authorization: Bearer <keyId>.<secret>

نداء أول

لا شيء لتثبيته. ضع مفتاحك مكان المفتاح هنا وستحصل على بيانات كتالوج حيّة.

الطلب - cURL

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

أعراف الاستجابة

تحمل كل استجابة حقلًا منطقيًا اسمه success، فيكفي شرط واحد للفصل بين المسار الناجح وكل إخفاق.
تعيد الإخفاقات كائن error يحمل كودًا ثابتًا ورسالة للبشر وتفاصيل اختيارية. تفرّع على الكود، لا على الرسالة أبدًا.
المبالغ دائمًا نصّ عشري مثل "0.950000" بالدولار الأمريكي. لا تحوّله إلى عدد عشري ثنائي قبل المقارنة أو الجمع.
نقاط القوائم تعيد كائن pagination يضمّ page و limit و total و total_pages.
إنشاء الطلب idempotent على الـ UUID الذي ترسله في order_id، فلا يمكن لإعادة المحاولة أن تخصم مرتين.

استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "PRICE_INCREASED",
    "message": "Price has increased beyond expected",
    "details": {
      "expected_unit_price": "0.950000",
      "current_unit_price": "0.980000"
    }
  }
}

أقسام المرجع

الكتالوجالكتالوج شجرة من ثلاثة مستويات: الفئات الكبرى تضمّ الفئات، والفئات تضمّ الفئات الفرعية، والفئة الفرعية هي العنصر الذي تشتريه فعلًا. تتيح لك هذه النقاط نسخ تلك الشجرة إلى قاعدة بياناتك وتسعير أي عنصر مباشرةً قبل طلبه.التحقق من اللاعبيحلّ التحقق من اللاعب حسابًا داخل اللعبة قبل تحرّك أي مال. فهو يؤكّد وجود المعرّف لذلك المنتج، ويعيد الاسم داخل اللعبة ليتأكّد مشتريك منه، ويكشف المنطقة فيُرفض الطلب عابر المناطق مبكرًا بدل أن يفشل بعد الدفع.الطلباتتُنشأ الطلبات بـ UUID تولّده أنت. ذلك الـ UUID هو مفتاح idempotency: إعادة إرساله تعيد الطلب الأصلي بدل الخصم مرتين. ثم تُقرأ الحالة لكل طلب على حدة، أو في دفعات تصل إلى خمسين، أو كقائمة مرقَّمة الصفحات.الحساب والمصادقةيحمل كل طلب رأسًا واحدًا. و GET /account هي النقطة التي تناديها لتثبت أن المفتاح يعمل، ولتقرأ رصيد المحفظة الذي تُخصم منه طلباتك، ولتتأكّد أن الحساب مفعّل قبل بدء أي تشغيل دفعي.أكواد الأخطاءيعيد كل إخفاق كودًا ثابتًا يقرأه الحاسوب إلى جانب حالة HTTP. تفرّع على الكود، لا على نصّ الرسالة أبدًا: الرسائل مكتوبة للبشر وقد يُعاد صياغتها، أما الأكواد فجزء من العقد.

حدود المعدل

الحدود لكل حساب على نافذة متحرّكة. تحمل كل استجابة الرؤوس X-RateLimit-Limit و X-RateLimit-Remaining و X-RateLimit-Reset، ويردّ النداء المكبوح بالحالة 429 مع رأس Retry-After.

المسار	الطلبات	النافذة	تُحسب لكل
GET /catalog/* (all five)	80	60s	per account
POST /orders/create	120	60s	per account
GET /orders/:orderId	3	60s	per account + order id
POST /orders/batch	2	60s	per account
GET /orders	2	60s	per account
GET /account	60	60s	per account
POST /player/validate	dedicated limiter	—	per account

خطافات الويب

تُدفع نتائج الطلبات إلى نقطة HTTPS تسجّلها أنت، موقَّعة بـ HMAC-SHA256 على الجسم الخام. قائمة الأحداث وقائمة الرؤوس وشكل الحمولة ومقتطف التحقق موثّقة جميعها في صفحة نظرة عامة على الواجهة البرمجية.

اقرأ مرجع حمولة خطاف الويب والتوقيع

جديد على المنصة؟ ابدأ من نظرة عامة على واجهة شحن الألعاب للموزّعين، أو اقرأ نظرة عامة على برنامج موزّعي SHOP2TOPUP لمعرفة كيفية عمل حساب الشريك.