SGC GAME DEVELOPERS
API v1 · USD
أقسام الدليل

حالة خدمات API

حالة الاتصال بالخدمات وتوفرها، تتحدّث تلقائيًا كل دقيقة.

جارٍ قراءة الحالة…
تفاصيل التوفر وآخر التغييرات

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

    دليل الربط البرمجي · الإصدار الأول

    تعليمات الربط البرمجي

    كل ما تحتاجه للمصادقة، قراءة الكتالوج، إنشاء الطلبات ومتابعة نتائجها، بأمثلة جاهزة بلغتك البرمجية.

    ابدأ الربط بخطوات واضحة

    واجهة REST لشحن الألعاب وتطبيقات اللايف والبطاقات الرقمية. جميع الأسعار والطلبات في هذه الواجهة بالدولار الأمريكي USD.

    العنوان الأساسيhttps://sgc-game.shop
    1. فعّل وصول API لحسابك واحصل على المفتاح والسر من حسابك.
    2. اجلب الكتالوج وحدّد المنتج والباقة ومعرّف اللاعب عند الحاجة.
    3. أنشئ الطلب بمفتاح منع تكرار مستقل لكل عملية شراء.
    4. استعلم عن الطلب حتى تصل حالته إلى نتيجة نهائية؛ كود البطاقة يظهر بعد الاكتمال.

    الأرقام والأكواد في هذه الصفحة أمثلة توضيحية فقط. صفحة التوثيق لا تعرض مفاتيح حسابك ولا تنفّذ عمليات شراء.

    المصادقة وحفظ المفاتيح

    HEADERSكل المسارات المحمية
    HTTP
    X-API-Key: YOUR_API_KEY
    X-API-Secret: YOUR_API_SECRET
    Accept: application/json

    أرسل المفتاح والسر من خادمك داخل الترويسات. لا تضعهما في الرابط أو تطبيق الواجهة أو مستودع الكود. خزّنهما في متغيري البيئة SGC_API_KEY وSGC_API_SECRET.

    يجب أن يكون الحساب بالدولار وصلاحية API مفعّلة. إذا حدّدت قائمة IP للمفتاح، يجب أن يطابقها عنوان خادم الربط. التزم بالحد المخصّص لمفتاحك؛ عند تجاوزه قد يصلك 429.

    جلب الرصيد

    GET/balance
    استجابة توضيحية
    {
      "success": true,
      "message": "Success",
      "data": {
        "balance": 42.5,
        "currency": "USD"
      },
      "request_id": "example-request-id",
      "timestamp": "2026-10-20T09:00:00Z"
    }

    يعيد رصيد الحساب المرتبط بمفتاح API بالدولار.

    كتالوج المنتجات

    GET/games
    GET/apps
    GET/cards

    استخدم المعرّفات والأسعار من الكتالوج الحالي. الأسعار مخصّصة لحسابك وقد تتغيّر؛ لا تعتمد على أرقام الأمثلة.

    الحالةبيانات إنشاء الطلب
    لعبة بنظام الباقاتtype: game + معرّف اللعبة product_id + الباقة category_id + player_id
    تطبيق بنظام الباقاتtype: app + معرّف التطبيق product_id + package_id + player_id
    تسعير حسب الكميةاستخدم quantity_settings.min وmax، وأرسل عدد الوحدات في quantity. للألعاب التي تعرض باقات وكميات معاً، مثل جواكر، أرسل معرّف اللعبة في product_id وpricing_type: quantity داخل عنصر الطلب من دون category_id.
    بطاقةtype: card + معرّف العنصر من items[].id داخل كتالوج البطاقات
    مثال مختصر لكتالوج البطاقات
    {
      "success": true,
      "message": "Success",
      "data": [
        {
          "id": 7,
          "name": "Example platform",
          "name_ar": "منصة تجريبية",
          "image": "/example.webp",
          "slug": "example",
          "type": "card",
          "pricing_type": "package",
          "items": [
            {
              "id": 309,
              "name": "Example card 5 USD",
              "denomination": "5",
              "price": 5.25,
              "currency": "USD"
            }
          ]
        }
      ],
      "request_id": "example-request-id",
      "timestamp": "2026-10-20T09:00:00Z"
    }

    إنشاء طلب

    POST/orders

    أرسل JSON يحتوي على عنصر واحد داخل items. استخدم Idempotency-Key من 16 إلى 80 محرفاً: أحرف أو أرقام أو ._-.

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

    المعاملالوصف
    typegame أو app أو card
    currencyاختياري؛ القيمة المقبولة USD فقط
    itemsمصفوفة بعنصر واحد؛ product_id عدد صحيح موجب
    quantityعدد صحيح موجب؛ للبطاقات من 1 إلى 20؛ حدود الكمية الأخرى حسب الكتالوج
    player_idمطلوب للألعاب والتطبيقات، غير مطلوب للبطاقات
    category_id / package_idمعرّف باقة اللعبة أو التطبيق عند التسعير بالباقات
    طلب بطاقة
    {
      "type": "card",
      "currency": "USD",
      "items": [
        {
          "product_id": 309,
          "quantity": 1
        }
      ]
    }
    طلب لعبة بباقة
    {
      "type": "game",
      "items": [
        {
          "product_id": 12,
          "category_id": 101,
          "player_id": "123456789",
          "quantity": 1
        }
      ]
    }
    طلب تطبيق بباقة
    {
      "type": "app",
      "items": [
        {
          "product_id": 8,
          "package_id": 77,
          "player_id": "123456789",
          "quantity": 1
        }
      ]
    }
    201 — قبول الطلب
    {
      "success": true,
      "message": "Order accepted.",
      "data": {
        "order_number": "API-CR20261020090000ABCDEF12",
        "status": "processing",
        "amount": 5.25,
        "currency": "USD",
        "balance_before": 42.5,
        "balance_after": 37.25
      },
      "request_id": "example-request-id",
      "timestamp": "2026-10-20T09:00:00Z"
    }

    قبول الطلب لا يعني اكتمال تنفيذه. احتفظ بـorder_number ثم استعلم عن نتيجته.

    حالة الطلب وتسليم البطاقة

    GET/orders/{order_number}

    مرّر رقم الطلب كما أُعيد من الإنشاء. يمكن أيضاً استخدام /orders/get?id=ORDER_NUMBER. يمكنك الوصول لطلبات حسابك فقط.

    200 — بطاقة مكتملة
    {
      "success": true,
      "message": "Order retrieved.",
      "data": {
        "order_number": "API-CR20261020090000ABCDEF12",
        "status": "completed",
        "amount": 5.25,
        "currency": "USD",
        "created_at": "2026-10-20 12:00:00",
        "type": "card",
        "card_codes": [
          {
            "card_number": "DEMO-CARD-NUMBER",
            "card_code": "DEMO-PIN"
          }
        ],
        "card_code": {
          "card_number": "DEMO-CARD-NUMBER",
          "card_code": "DEMO-PIN"
        }
      },
      "request_id": "example-request-id",
      "timestamp": "2026-10-20T09:00:00Z"
    }

    اقرأ جميع البطاقات من data.card_codes. الحقل card_number هو رقم البطاقة/الكود المُسلّم، وcard_code داخل كل عنصر هو PIN إن وفّره المزود وقد يكون فارغاً. لا تُسقط البطاقة لأن PIN فارغ. الحقل المفرد data.card_code للتوافق عند وجود بطاقة واحدة.

    لا تظهر أكواد التسليم قبل الاكتمال، وقد لا تتضمن طلبات الشحن المباشر أكواداً أصلاً. احفظ بيانات التسليم في خادمك وامنحها للمشتري المعني فقط.

    الحالةالمعنى
    pendingبانتظار بدء المعالجة
    processingجارٍ التنفيذ؛ استعلم لاحقاً
    completedاكتمل الطلب؛ افحص بيانات التسليم للبطاقات
    failed / cancelled / refundedنتيجة نهائية غير مكتملة؛ راجع الطلب والرصيد قبل إعادة الشراء

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

    GET/orders?type=card&status=completed&limit=10&offset=0
    المعاملالقيم
    typeall, game, direct_charge, app, live_app, card
    statusاختياري؛ إحدى الحالات المبيّنة أعلاه
    limitمن 1 إلى 100، الافتراضي 50
    offsetعدد صحيح من 0 فما فوق
    JSON
    {
      "success": true,
      "message": "USD orders retrieved.",
      "data": {
        "items": [
          {
            "order_number": "API-CR20261020090000ABCDEF12",
            "status": "completed",
            "amount": 5.25,
            "currency": "USD",
            "created_at": "2026-10-20 12:00:00",
            "type": "card",
            "card_codes": [
              {
                "card_number": "DEMO-CARD-NUMBER",
                "card_code": ""
              }
            ],
            "card_code": {
              "card_number": "DEMO-CARD-NUMBER",
              "card_code": ""
            }
          }
        ],
        "limit": 10,
        "offset": 0
      },
      "request_id": "example-request-id",
      "timestamp": "2026-10-20T09:00:00Z"
    }

    أمثلة الربط البرمجي

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

    PHP
    <?php
    // PHP 8+ with cURL. Set SGC_API_KEY and SGC_API_SECRET on your server.
    function sgcRequest(string $method, string $path, ?array $body = null,
                        ?string $idempotencyKey = null): array {
        $key = getenv('SGC_API_KEY');
        $secret = getenv('SGC_API_SECRET');
        if (!$key || !$secret) throw new RuntimeException('Missing API credentials');
        $headers = ['Accept: application/json', 'X-API-Key: '.$key,
                    'X-API-Secret: '.$secret];
        if ($body !== null) $headers[] = 'Content-Type: application/json';
        if ($idempotencyKey !== null) $headers[] = 'Idempotency-Key: '.$idempotencyKey;
        $ch = curl_init('https://sgc-game.shop'.$path);
        curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 45,
            CURLOPT_FOLLOWLOCATION => false, CURLOPT_SSL_VERIFYPEER => true,
            CURLOPT_SSL_VERIFYHOST => 2]);
        if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS,
            json_encode($body, JSON_THROW_ON_ERROR));
        $raw = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $error = curl_error($ch);
        curl_close($ch);
        if ($raw === false) throw new RuntimeException('Network error: '.$error);
        $response = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
        if ($status >= 400 || empty($response['success']))
            throw new RuntimeException($response['message'] ?? 'API request failed');
        return $response['data'];
    }
    $balance = sgcRequest('GET', '/balance');
    // Before purchasing, replace 309 with a current catalog item ID.
    // Generate ONCE and persist with your purchase before sending.
    $idempotencyKey = 'purchase-'.bin2hex(random_bytes(16));
    $order = sgcRequest('POST', '/orders', [
        'type' => 'card', 'items' => [['product_id' => 309, 'quantity' => 1]]
    ], $idempotencyKey);
    // Later, query the same saved order number (do not create another purchase).
    $details = sgcRequest('GET', '/orders/'.rawurlencode($order['order_number']));
    if ($details['status'] === 'completed') {
        foreach ($details['card_codes'] ?? [] as $card) {
            // Securely deliver $card['card_number'] and $card['card_code'] to its buyer.
        }
    }
    

    فهم الاستجابات والأخطاء

    JSON
    {
      "success": false,
      "message": "Validation failed.",
      "errors": {
        "type": "Use game, app, or card."
      },
      "request_id": "example-request-id",
      "timestamp": "2026-10-20T09:00:00Z"
    }
    HTTPالمعنى والإجراء
    200 / 201نجاح الاستعلام / قبول إنشاء الطلب
    400طلب غير صالح؛ لا تُرسل بيانات المصادقة في الرابط
    401المفتاح أو السر غير صالح؛ تحقّق من الترويسات
    403صلاحية API أو عملة الحساب أو عنوان IP غير مسموح
    404المسار أو الطلب غير موجود، أو لا يتبع حسابك
    409تعارض مفتاح منع التكرار أو الطلب ما زال قيد المعالجة
    422بيانات غير صالحة أو منتج/سعر/رصيد غير متاح؛ اقرأ الرسالة
    429تجاوز حد الطلبات؛ انتظر واتبع Retry-After إن وُجد
    500 / 502 / 503خطأ مؤقت؛ استعلم عن الطلب والرصيد قبل التفكير بإعادة الشراء

    قد يحتوي حقل errors على تفاصيل المعاملات الخاطئة. عند التواصل مع الدعم أرسل request_id ورقم الطلب، وأخفِ المفاتيح وأكواد البطاقات.

    ربط آمن وطلبات دون تكرار

    • استخدم HTTPS فقط، وأبقِ التحقق من شهادة TLS مفعّلاً.
    • احتفظ بالمفاتيح وأكواد البطاقات على خادمك، وحدّد عناوين IP المسموحة لمفتاحك.
    • لا تضع الأسرار في الروابط أو JavaScript المتصفح أو سجلات الأخطاء العامة.
    • عند انتهاء المهلة لا تفترض فشل الشراء؛ افحص الطلب والرصيد أولاً، واستخدم نفس مفتاح العملية عند إعادة نفس الطلب.
    • استعلم بفاصل معتدل مثل 15–30 ثانية والتزم بحد مفتاحك، وأوقف الاستعلام عند الحالة النهائية.
    • اعتمد الحالة والبيانات الصادرة من الخادم؛ لا تمنح رصيداً أو تسلّم منتجاً بناءً على طلب المستخدم وحده.
    SGC GAME · أمثلة توضيحية دون مفاتيح حقيقية · آخر تحديث: 20 أكتوبر 2026

    استرجاع الطلب بعد انقطاع الرد

    GET/orders/recover

    بعد انقطاع الرد أو ظهور 409 أو 502، استعلم بنفس اعتماد API ونفس مفتاح منع التكرار. أرسل المفتاح في الترويسة.

    GET /api/v1/orders/recover
    X-API-Key: <key>
    X-API-Secret: <secret>
    Idempotency-Key: example-order-0001

    مثال مختصر لرد 200.

    {
      "success": true,
      "data": {
        "attempt_status": "failed",
        "original_http_status": 502,
        "order": {
          "order_number": "API-DC2026111307034600000000",
          "status": "failed"
        }
      }
    }

    تعرض order.status الحالة الحالية للطلب. إذا كانت order تساوي null فلا يوجد طلب مرتبط يمكن استرجاعه بعد. يشمل ذلك بعض المحاولات القديمة. عند استمرار المعالجة أعد الاستعلام بعد 15 إلى 30 ثانية. يعيد المسار 404 إذا كان المفتاح غير موجود ضمن اعتمادك. استخدم قائمة الطلبات أو راجع الدعم إذا تعذرت المطابقة.

    تبقى ردود إعادة POST كما هي. استخدم مفتاحًا فريدًا لكل عملية، وتجنّب توليد مفتاح جديد تلقائيًا بعد انقطاع الرد. لا توجد مدة انتهاء معلنة للمفتاح.

    الاشتراكات

    GET/subscriptions

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

    POST/subscriptions/orders

    استخدم ترويسات المصادقة المعتادة ومفتاح Idempotency-Key فريدًا لكل طلب. القيم التالية توضيحية. يمكن إرسال expected_amount لمراجعة السعر عند الشراء. يمكن تمرير email_source بقيمة account لاستخدام بريد الحساب.

    {"subscription_id":12,"variant_id":34,"email":"[email protected]","expected_amount":4.5}

    الإنشاء يرجع 201 وإعادة نفس العملية ترجع 200. يحتوي data على رقم الطلب والحالة والمبلغ والعملة والمدة. للتأكد بعد انقطاع الرد، أرسل نفس المفتاح إلى GET /subscriptions/orders/recover أو استعلم برقم الطلب عبر GET /subscriptions/orders/{number}.

    {"success":true,"data":{"order_number":"SUB-20261113120000-0123456789","status":"pending","amount":4.5,"currency":"USD","subscription_id":12,"variant_id":34,"label":"30 يوم","duration_days":30}}

    عند اكتمال الطلب وتوفّر معلومات التسليم، يرجع الرد النص في حقل data.delivery عند الإنشاء أو إعادة الطلب أو الاستعلام أو الاسترجاع. اعرض القيمة كنص في متجرك.

    {"success":true,"data":{"order_number":"SUB-20261113120000-0123456789","status":"completed","amount":4.5,"currency":"USD","subscription_id":12,"variant_id":34,"label":"30 days","duration_days":30,"delivery":"Activation code: EXAMPLE-1234"}}