حالة خدمات API
حالة الاتصال بالخدمات وتوفرها، تتحدّث تلقائيًا كل دقيقة.
تفاصيل التوفر وآخر التغييرات
النسبة محسوبة من الفحوص المسجّلة، ولا تعني ضمان نجاح كل عملية شراء. تنفيذ الطلب يعتمد أيضًا على توفر الفئة والخدمة الخارجية.
تعليمات الربط البرمجي
كل ما تحتاجه للمصادقة، قراءة الكتالوج، إنشاء الطلبات ومتابعة نتائجها، بأمثلة جاهزة بلغتك البرمجية.
ابدأ الربط بخطوات واضحة
واجهة REST لشحن الألعاب وتطبيقات اللايف والبطاقات الرقمية. جميع الأسعار والطلبات في هذه الواجهة بالدولار الأمريكي USD.
https://sgc-game.shop- فعّل وصول API لحسابك واحصل على المفتاح والسر من حسابك.
- اجلب الكتالوج وحدّد المنتج والباقة ومعرّف اللاعب عند الحاجة.
- أنشئ الطلب بمفتاح منع تكرار مستقل لكل عملية شراء.
- استعلم عن الطلب حتى تصل حالته إلى نتيجة نهائية؛ كود البطاقة يظهر بعد الاكتمال.
الأرقام والأكواد في هذه الصفحة أمثلة توضيحية فقط. صفحة التوثيق لا تعرض مفاتيح حسابك ولا تنفّذ عمليات شراء.
المصادقة وحفظ المفاتيح
كل المسارات المحميةX-API-Key: YOUR_API_KEY
X-API-Secret: YOUR_API_SECRET
Accept: application/jsonأرسل المفتاح والسر من خادمك داخل الترويسات. لا تضعهما في الرابط أو تطبيق الواجهة أو مستودع الكود. خزّنهما في متغيري البيئة SGC_API_KEY وSGC_API_SECRET.
يجب أن يكون الحساب بالدولار وصلاحية API مفعّلة. إذا حدّدت قائمة IP للمفتاح، يجب أن يطابقها عنوان خادم الربط. التزم بالحد المخصّص لمفتاحك؛ عند تجاوزه قد يصلك 429.
جلب الرصيد
/balance{
"success": true,
"message": "Success",
"data": {
"balance": 42.5,
"currency": "USD"
},
"request_id": "example-request-id",
"timestamp": "2026-10-20T09:00:00Z"
}يعيد رصيد الحساب المرتبط بمفتاح API بالدولار.
كتالوج المنتجات
/games/apps/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"
}إنشاء طلب
/ordersأرسل JSON يحتوي على عنصر واحد داخل items. استخدم Idempotency-Key من 16 إلى 80 محرفاً: أحرف أو أرقام أو ._-.
أنشئ مفتاحاً جديداً لكل عملية شراء مختلفة، واحفظه قبل الإرسال. عند انقطاع الاتصال أعد نفس الطلب بنفس المفتاح؛ لا تنشئ مفتاحاً جديداً قبل التحقق من نتيجة الطلب والرصيد.
| المعامل | الوصف |
type | game أو 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
}
]
}{
"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 ثم استعلم عن نتيجته.
حالة الطلب وتسليم البطاقة
/orders/{order_number}مرّر رقم الطلب كما أُعيد من الإنشاء. يمكن أيضاً استخدام /orders/get?id=ORDER_NUMBER. يمكنك الوصول لطلبات حسابك فقط.
{
"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 | نتيجة نهائية غير مكتملة؛ راجع الطلب والرصيد قبل إعادة الشراء |
قائمة الطلبات
/orders?type=card&status=completed&limit=10&offset=0| المعامل | القيم |
type | all, game, direct_charge, app, live_app, card |
status | اختياري؛ إحدى الحالات المبيّنة أعلاه |
limit | من 1 إلى 100، الافتراضي 50 |
offset | عدد صحيح من 0 فما فوق |
{
"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 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.
}
}
# Python 3.10+; pip install requests
import os
import uuid
from urllib.parse import quote
import requests
KEY = os.environ["SGC_API_KEY"]
SECRET = os.environ["SGC_API_SECRET"]
def sgc_request(method, path, body=None, idempotency_key=None):
headers = {"Accept": "application/json",
"X-API-Key": KEY, "X-API-Secret": SECRET}
if idempotency_key:
headers["Idempotency-Key"] = idempotency_key
response = requests.request(method, "https://sgc-game.shop" + path,
headers=headers, json=body, timeout=(10, 45), allow_redirects=False)
payload = response.json()
if not response.ok or not payload.get("success"):
raise RuntimeError(payload.get("message", "API request failed"))
return payload["data"]
balance = sgc_request("GET", "/balance")
# Replace product ID using the current catalog. Persist this key BEFORE sending.
idempotency_key = "purchase-" + uuid.uuid4().hex
order = sgc_request("POST", "/orders", {
"type": "card", "items": [{"product_id": 309, "quantity": 1}]
}, idempotency_key)
# Query later using the saved number; never purchase again just to check status.
details = sgc_request("GET", "/orders/" + quote(order["order_number"], safe=""))
if details["status"] == "completed":
for card in details.get("card_codes", []):
# Securely deliver card["card_number"] and card["card_code"] to its buyer.
pass
// Node.js 20+; built-in fetch. Run on your server, not in the browser.
import { randomUUID } from "node:crypto";
const { SGC_API_KEY: key, SGC_API_SECRET: secret } = process.env;
if (!key || !secret) throw new Error("Missing API credentials");
async function sgcRequest(method, path, body, idempotencyKey) {
const headers = { Accept: "application/json",
"X-API-Key": key, "X-API-Secret": secret };
if (body !== undefined) headers["Content-Type"] = "application/json";
if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
const response = await fetch("https://sgc-game.shop" + path, {
method, headers, body: body === undefined ? undefined : JSON.stringify(body),
signal: AbortSignal.timeout(45000), redirect: "error"
});
const payload = await response.json();
if (!response.ok || !payload.success)
throw new Error(payload.message || "API request failed");
return payload.data;
}
const balance = await sgcRequest("GET", "/balance");
// Replace 309 with a current catalog item ID. Persist this key BEFORE sending.
const idempotencyKey = "purchase-" + randomUUID();
const order = await sgcRequest("POST", "/orders", {
type: "card", items: [{ product_id: 309, quantity: 1 }]
}, idempotencyKey);
// Query later using the saved number; do not create a second purchase.
const details = await sgcRequest("GET", "/orders/" + encodeURIComponent(order.order_number));
if (details.status === "completed") {
for (const card of details.card_codes ?? []) {
// Securely deliver card.card_number and card.card_code to its buyer.
}
}
# Set these variables on your server. Use the CURRENT catalog item ID.
export SGC_API_KEY="YOUR_API_KEY"
export SGC_API_SECRET="YOUR_API_SECRET"
# Generate once per purchase; persist and reuse for the exact same request on retry.
export SGC_IDEMPOTENCY_KEY="purchase-example-20261020-0001"
curl --fail-with-body --connect-timeout 10 --max-time 45 \
"https://sgc-game.shop/orders" \
-H "X-API-Key: $SGC_API_KEY" \
-H "X-API-Secret: $SGC_API_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SGC_IDEMPOTENCY_KEY" \
--data '{"type":"card","items":[{"product_id":309,"quantity":1}]}'
# Replace this number with order_number returned by the API.
curl --fail-with-body --connect-timeout 10 --max-time 45 \
"https://sgc-game.shop/orders/API-CR20261020090000ABCDEF12" \
-H "X-API-Key: $SGC_API_KEY" \
-H "X-API-Secret: $SGC_API_SECRET"
فهم الاستجابات والأخطاء
{
"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 ثانية والتزم بحد مفتاحك، وأوقف الاستعلام عند الحالة النهائية.
- اعتمد الحالة والبيانات الصادرة من الخادم؛ لا تمنح رصيداً أو تسلّم منتجاً بناءً على طلب المستخدم وحده.
استرجاع الطلب بعد انقطاع الرد
/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 كما هي. استخدم مفتاحًا فريدًا لكل عملية، وتجنّب توليد مفتاح جديد تلقائيًا بعد انقطاع الرد. لا توجد مدة انتهاء معلنة للمفتاح.
الاشتراكات
/subscriptionsيعرض الاشتراكات المتاحة وخياراتها وأسعار حسابك بالدولار. استخدم رقم الاشتراك ورقم الخيار من الكتالوج. القيمة صفر للخيار تعني أن الاشتراك له مدة واحدة. يحدد الحقل email_required وجوب البريد.
/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"}}