نقاط الكتالوج

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

GET

/catalog/big-categories

عرض الفئات الكبرى

يعرض جميع الفئات العليا (مثل ألعاب الجوال وألعاب الكمبيوتر وبطاقات الهدايا).

حدّ المعدل5000 طلب / 60 ثانية لكل حساب (حد مشترك بين جميع نقاط نهاية الكتالوج)

معاملات الاستعلام

الاسمالنوعمطلوبالوصفمثال
for_uibooleanلاإضافة روابط الصور إلى الاستجابة.true
الطلب
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/big-categories?for_ui=true" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
مثال استجابة
{
  "success": true,
  "big_categories": [
    {
      "id": 1,
      "name": "Mobile Games",
      "description": "Popular mobile game top-ups"
    },
    {
      "id": 2,
      "name": "PC Games",
      "description": "PC game credits and items"
    }
  ]
}
GET

/catalog/categories

عرض الفئات

يعيد الفئات، ويمكن تصفيتها حسب الفئة الكبرى. تمثّل كل فئة لعبة أو خدمة.

حدّ المعدل5000 طلب / 60 ثانية لكل حساب (حد مشترك بين جميع نقاط نهاية الكتالوج)

معاملات الاستعلام

الاسمالنوعمطلوبالوصفمثال
bigCategoryIdnumberلاالتصفية حسب معرّف الفئة الكبرى.1
for_uibooleanلاإضافة روابط الصور إلى الاستجابة.true
الطلب
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1&for_ui=true" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
مثال استجابة
{
  "success": true,
  "categories": [
    {
      "id": 12,
      "name": "Free Fire",
      "description": "Garena Free Fire diamonds",
      "big_category_id": 1,
      "big_category_name": "Mobile Games"
    }
  ]
}
GET

/catalog/subcategories

عرض الفئات الفرعية (المنتجات)

يعرض المنتجات والباقات المتاحة. كل فئة فرعية منتج قابل للشراء.

حدّ المعدل5000 طلب / 60 ثانية لكل حساب (حد مشترك بين جميع نقاط نهاية الكتالوج)

ملاحظة: تكون قيمة product_type هي 'topup' عند الشحن المباشر إلى حساب اللاعب، و'voucher' عندما يُسلِّم المنتج كوداً. الحقلان fulfillment_type ('api' للشحن، و'voucher' للكود) وreturns_voucher (true للكود) مُهمَلان، فهما يكرّران قيمة product_type لا أكثر. وإن ظهر الحقل id فقيمته تساوي item_id.

معاملات الاستعلام

الاسمالنوعمطلوبالوصفمثال
categoryIdnumberلاالتصفية حسب معرّف الفئة.12
الطلب
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/subcategories?categoryId=12" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
مثال استجابة
{
  "success": true,
  "subcategories": [
    {
      "item_id": 999,
      "name": "FF 100 Diamonds",
      "description": "100 Free Fire Diamonds",
      "category_id": 12,
      "category_name": "Free Fire",
      "price": "0.99",
      "product_type": "topup",
      "fulfillment_type": "api",
      "returns_voucher": false
    }
  ]
}
GET

/catalog/subcategory/:itemId/price

جلب سعر المنتج

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

حدّ المعدل5000 طلب / 60 ثانية لكل حساب (حد مشترك بين جميع نقاط نهاية الكتالوج)

ملاحظة: قيمة unit_price هي المبلغ الذي ستدفعه فعلياً. ضعها في expected_unit_price عند إنشاء الطلبات.

معاملات المسار

الاسمالنوعمطلوبالوصفمثال
itemIdnumberنعممعرّف الفئة الفرعية أو المنتج.999
الطلب
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/subcategory/999/price" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
مثال استجابة
{
  "success": true,
  "price": {
    "item_id": 999,
    "item_name": "FF 100 Diamonds",
    "unit_price": "0.950000",
    "currency": "USD",
    "original_price": "0.990000",
    "discount_applied": true,
    "timestamp": "2024-06-15T12:00:00Z"
  }
}
GET

/catalog/category/:categoryId/requirements

جلب متطلبات الفئة

يعيد حقول المتطلبات الديناميكية لفئة محددة. توضّح هذه الحقول البيانات المطلوبة عند التحقق من اللاعب أو إنشاء الطلب (مثل معرّف اللاعب أو الخادم أو المنطقة).

حدّ المعدل5000 استدعاء / 60 ثانية لكل حساب (حد مشترك بين جميع نقاط الوصول في الكتالوج)

ملاحظة: استعن بالحقول المُعادة لبناء نماذج ديناميكية للتحقق من اللاعب وإنشاء الطلبات. يحدد كل حقل نوع بياناته في data_type (text أو number أو single_select أو multi_select)، إلى جانب الخيارات المتاحة لحقول الاختيار.

معاملات المسار

الاسمالنوعمطلوبالوصفمثال
categoryIdnumberنعممعرّف الفئة المطلوب جلب متطلباتها.12
الطلب
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/category/12/requirements" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
مثال استجابة
{
  "success": true,
  "requirements": [
    {
      "field_name": "player_id",
      "data_type": "text",
      "placeholder": "Enter player ID"
    },
    {
      "field_name": "server",
      "data_type": "single_select",
      "placeholder": "Select server",
      "select_options": [
        "Asia",
        "Europe",
        "America"
      ]
    }
  ]
}

أرسل طلبًا حقيقيًا من هذه الصفحة

الصق مفتاح API لمناداة هذه النقاط مباشرةً. يبقى المفتاح في تبويب المتصفّح هذا ولا يُرسل إلا إلى الواجهة البرمجية نفسها.

Enter your API key to use the interactive playground. Get your API key

اختر نقطة نهاية

Enter your API key above to try this endpoint.

Response will appear here after sending a request.

مستكشف الكتالوج

Catalog Explorer

Browse the product hierarchy and copy IDs for use in API calls.

Enter your API key above to browse the catalog.

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

مرجع API الكتالوج — الفئات والفئات الفرعية والأسعار