نقاط الطلبات

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

POST

/orders/create

إنشاء طلب

أنشئ طلباً جديداً. يجب أن ترسل UUID فريداً في order_id لمنع تكرار الطلب. يُخصم المبلغ من المحفظة فوراً.

حدّ المعدل5000 استدعاء / 60 ثانية لكل حساب

ملاحظة: يعمل order_id مفتاحاً لمنع التكرار. إذا أعدت المحاولة باستخدام UUID نفسه، يعيد النظام الطلب الموجود ولا ينشئ طلباً مكرراً.

جسم الطلب

الاسمالنوعمطلوبالوصفمثال
order_idstring (UUID)نعمUUID فريد لهذا الطلب (بأي صيغة: v1 أو v4 أو v7 وغيرها). يُستخدم مفتاحاً لمنع التكرار.01912345-6789-7abc-8def-0123456789ab
sub_category_idnumberنعممعرّف الفئة الفرعية للمنتج.999
quantitynumberنعمعدد الوحدات المطلوبة (عدد صحيح موجب).1
requirementsobjectنعمبيانات اللاعب اللازمة للتسليم. أرسل جميع الحقول التي تعيدها نقطة الوصول «جلب متطلبات الفئة».{"player_id": "123456789", "server": "Asia"}
expected_unit_pricestringلاحماية من تغيّر السعر. إذا تجاوز السعر الحالي هذه القيمة، يُرفض الطلب.0.950000
الطلب
curl -s -X POST "https://shop2topup.com/api/endpoints/v1/orders/create" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "01912345-6789-7abc-8def-0123456789ab",
  "sub_category_id": 999,
  "quantity": 1,
  "requirements": {
    "player_id": "123456789",
    "server": "Asia"
  },
  "expected_unit_price": 0.95
}'
مثال استجابة
{
  "success": true,
  "order": {
    "order_id": "01912345-6789-7abc-8def-0123456789ab",
    "status": "pending",
    "player_id": "123456789",
    "player_name": "ProGamer99",
    "subcategory_name": "FF 100 Diamonds",
    "quantity": 1,
    "charged_amount": "0.950000",
    "currency": "USD",
    "created_at": "2024-06-15T12:00:00Z"
  }
}
GET

/orders/:orderId

جلب حالة الطلب

احصل على الحالة الحالية لطلب محدد مع تفاصيله.

حدّ المعدل3 استدعاءات / 60 ثانية لكل حساب + order_id

ملاحظة: تكون حالة الطلب إحدى القيم pending أو completed أو refunded أو partial (وتعني partial تسليم بعض الوحدات واسترداد مبلغ الباقي). وتأخذ كل قيمة sub_transactions[].status إحدى القيم pending أو completed أو refunded، وتبقى الوحدة pending حتى تُسلَّم أو يُسترد مبلغها. الحقل sub_transactions[].id هو ترتيب الوحدة داخل الطلب (1…n) وليس معرّفاً في قاعدة البيانات. أما retry_count وmax_retries، إن ظهرا، فهما مُهمَلان وقيمتهما دائماً 0.

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

الاسمالنوعمطلوبالوصفمثال
orderIdstring (UUID)نعممعرّف الطلب المراد الاستعلام عنه.01912345-6789-7abc-8def-0123456789ab
الطلب
curl -s "https://shop2topup.com/api/endpoints/v1/orders/01912345-6789-7abc-8def-0123456789ab" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
مثال استجابة
{
  "success": true,
  "order": {
    "order_id": "01912345-6789-7abc-8def-0123456789ab",
    "status": "completed",
    "player_id": "123456789",
    "player_name": "ProGamer99",
    "subcategory_name": "FF 100 Diamonds",
    "quantity": 1,
    "charged_amount": "0.950000",
    "currency": "USD",
    "created_at": "2024-06-15T12:00:00Z",
    "completed_at": "2024-06-15T12:00:05Z",
    "vouchers": [],
    "sub_transactions": [
      {
        "id": 1,
        "status": "completed",
        "player_id": "123456789",
        "player_name": "ProGamer99",
        "amount": "0.950000",
        "created_at": "2024-06-15T12:00:00Z",
        "completed_at": "2024-06-15T12:00:05Z"
      }
    ]
  }
}
POST

/orders/batch

جلب الطلبات دفعة واحدة

احصل على عدة طلبات دفعة واحدة عبر معرّفاتها. الحد الأقصى 50 معرّف طلب في الاستدعاء الواحد.

حدّ المعدل2 استدعاء / 60 ثانية لكل حساب

جسم الطلب

الاسمالنوعمطلوبالوصفمثال
order_idsstring[]نعممصفوفة من معرّفات UUID للطلبات (بحد أقصى 50).["uuid-1", "uuid-2"]
الطلب
curl -s -X POST "https://shop2topup.com/api/endpoints/v1/orders/batch" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "order_ids": [
    "uuid-1",
    "uuid-2"
  ]
}'
مثال استجابة
{
  "success": true,
  "orders": [
    {
      "order_id": "01912345-6789-7abc-8def-0123456789ab",
      "status": "completed",
      "charged_amount": "0.950000"
    }
  ],
  "not_found": [
    "uuid-that-does-not-exist"
  ]
}
GET

/orders

قائمة الطلبات

اعرض طلباتك مقسّمة على صفحات، مع تصفية اختيارية حسب الحالة والفترة الزمنية.

حدّ المعدل2 استدعاء / 60 ثانية لكل حساب

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

الاسمالنوعمطلوبالوصفمثال
pagenumberلارقم الصفحة (الافتراضي: 1).1
limitnumberلاعدد النتائج في الصفحة، من 1 إلى 100 (الافتراضي: 50).50
statusstringلاتصفية الطلبات حسب الحالة: pending للمعلقة، completed للمكتملة، refunded للمستردة، partial للجزئية.completed
created_afterstring (ISO 8601)لايعرض الطلبات التي أُنشئت بعد هذا التاريخ.2024-01-01T00:00:00Z
created_beforestring (ISO 8601)لايقتصر على الطلبات التي أُنشئت قبل هذا التاريخ.2024-12-31T23:59:59Z
الطلب
curl -s "https://shop2topup.com/api/endpoints/v1/orders?page=1&limit=50&status=completed&created_after=2024-01-01T00:00:00Z&created_before=2024-12-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
مثال استجابة
{
  "success": true,
  "orders": [
    {
      "order_id": "01912345-6789-7abc-8def-0123456789ab",
      "status": "completed",
      "subcategory_name": "FF 100 Diamonds",
      "quantity": 1,
      "charged_amount": "0.950000",
      "created_at": "2024-06-15T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "total_pages": 1
  }
}

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

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

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

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

1
2
Order Details

Enter your API key above to try this endpoint.

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

مرجع API الطلبات — إنشاء وقراءة ودفعات وقوائم