دليل الواجهة البرمجية API

كل ما تحتاجه لدمج لعبتك مع المنصة: تسجيل دخول اللاعبين دون مشاركة كلمات المرور، ولوحات الصدارة، والحفظ السحابي.

API Base URL: https://blindgames.info/api/dev

البدء السريع

ثلاث خطوات لتشغيل لعبتك على المنصة:

أنشئ حساب مطور (أو اطلب ترقية حسابك إلى مطور)، ثم أضف لعبتك من لوحة المطورين.
أنشئ مفتاح API من لوحة المطورين. ستحصل على مفتاح (API Key) وسرّ (API Secret) يظهر مرة واحدة فقط، فاحفظه فوراً.
استخدم المفتاح والسرّ في ترويسات الطلبات لمصادقة لعبتك مع الـ API.

المصادقة

كل طلب إلى الـ API يجب أن يحمل ترويستي المفتاح والسرّ. لا ترسل السرّ في كود اللعبة المنشور للاعبين؛ ضعه في الخادم الخاص بلعبتك إن أمكن.

الترويسات المطلوبة في كل طلب:

X-API-Key: your_api_key
X-API-Secret: your_api_secret

تفويض اللاعب

يربط اللاعب حسابه بلعبتك دون أن يعطيك كلمة مروره، عبر تدفق رمز الجهاز:

تدفق رمز الجهاز: تطلب لعبتك رمزاً، يعرضه اللاعب، ثم يوافق عليه من صفحة /device في المنصة. بعدها تحصل لعبتك على رمز جلسة (session token).

مثال:

POST https://blindgames.info/api/dev/device/code
Content-Type: application/json

{"game_id": "your_game_id"}

# Response
{
  "user_code": "ABCD2345",
  "device_code": "long-opaque-code",
  "verification_uri": "https://blindgames.info/api/dev/../device",
  "verification_uri_complete": "https://blindgames.info/api/dev/../device?code=ABCD2345",
  "expires_in": 600,
  "interval": 5
}

يتحقق من حالة الموافقة. أعد المحاولة كل 5 ثوانٍ حتى تتغير الحالة من authorization_pending.

POST https://blindgames.info/api/dev/device/token
Content-Type: application/json

{"device_code": "long-opaque-code"}

# Response while waiting
{"status": "authorization_pending"}

# Response after approval
{
  "status": "approved",
  "session_token": "session-token-value",
  "player": {"id": "...", "display_name": "...", "avatar": "..."}
}

رمز الجلسة يُرسل في ترويسة X-Session-Token مع الطلبات الخاصة باللاعب (مثل حفظ النقاط أو الحفظ السحابي).

الشخصيات (Profiles)

يمكن للاعب الواحد امتلاك عدة شخصيات داخل اللعبة، ولكل شخصية خاناتها المستقلة للحفظ. الحقل profile يربط كل خانة بشخصية معينة، وتركه فارغاً يعني حفظاً على مستوى اللعبة دون شخصية (متوافق مع السلوك القديم).

الطريقة البسيطة: استخدم أي نص حر في profile كمفتاح للشخصية (مثل hero1 أو char2) دون الحاجة لإنشاء سجل شخصية.
الطريقة الموسّعة: أنشئ شخصية عبر POST /profile لتحصل على معرّف (profile_id) وحقل بيانات وصفية حر (data) للإحصائيات والمظهر وأي شيء، ثم استخدم المعرّف في خانات الحفظ.

الهرمية الكاملة:

player
└── profile (character)   ← optional, free-form key OR profile_id
    └── slot              ← e.g. "default", "checkpoint", "settings"
        └── data          ← up to 1 MiB, any text you serialize

مرجع نقاط النهاية (Endpoints)

`POST /device/code`

يبدأ تدفق رمز الجهاز ويعيد رمزاً للاعب ورابطاً جاهزاً للموافقة.

جسم الطلب: {"game_id": "..."}

`POST /device/token`

يتحقق من حالة الموافقة. أعد المحاولة كل 5 ثوانٍ حتى تتغير الحالة من authorization_pending.

جسم الطلب: {"device_code": "..."}

`GET /player`

يعيد المعلومات العامة للاعب المرتبط بالجلسة.

الترويسات: X-Session-Token

{"player": {"id": "...", "display_name": "...", "avatar": "..."}}

`POST /score`

يسجّل نقطة في لوحة الصدارة. يُحفظ أعلى رقم فقط لكل لاعب ووضع.

الترويسات: X-Session-Token

POST https://blindgames.info/api/dev/score
X-Session-Token: session-token-value
Content-Type: application/json

{"game_id": "your_game_id", "score": 1500, "mode": "default", "display_name": "Knight", "profile": "rec123", "metadata": {"difficulty": "hard", "duration": 95, "items": false}}

# Response
{"ok": true, "improved": true}

الحقلان display_name وprofile اختياريان: اسمح للاعب باختيار الاسم الظاهر في الصدارة (اسم حسابه أو اسم شخصيته). إن تركت display_name فارغاً يُستخدم اسم الحساب تلقائياً.

الحقل metadata اختياري وحرّ: كائن JSON بمفاتيح تعرّفها أنت لتمييز كيف تحققت النتيجة (الصعوبة، مدة الجولة، أي شيء يخص لعبتك). عرّف الأعمدة المقابلة من لوحة المطورين عبر «حقول لوحة الصدارة»، وأي مفتاح بلا حقل معرَّف يُحفظ دون أن يُعرض.

`GET /leaderboard`

يعيد أعلى النقاط للعبة ووضع محدد.

GET https://blindgames.info/api/dev/leaderboard?game_id=your_game_id&mode=default&limit=20

# Response
{"fields": [
  {"key": "difficulty", "label": "Difficulty", "type": "text"},
  {"key": "duration", "label": "Time", "type": "duration"}
],
 "leaderboard": [
  {"rank": 1, "display_name": "...", "score": 9000, "metadata": {"difficulty": "hard", "duration": 95}},
  {"rank": 2, "display_name": "...", "score": 7500, "metadata": {"difficulty": "easy", "duration": 140}}
]}

تُعرض الصدارة أيضاً تلقائياً في صفحة عامة بالموقع على /games/SLUG/leaderboard بالأعمدة التي عرّفتها، فيراها الجميع دون أي عمل إضافي منك.

`GET /ban`

يتحقق إن كان اللاعب الحالي محظوراً من لعب لعبتك. يتطلّب جلسة لاعب نشطة. أنت تضبط الحظر والسبب والمدة من لوحة المطورين.

الترويسات: X-Session-Token

GET https://blindgames.info/api/dev/ban?game_id=your_game_id
X-Session-Token: session-token-value

# Response (not banned)
{"banned": false}

# Response (banned)
{"banned": true, "reason": "...", "permanent": false, "expires_at": "2025-01-01T00:00:00Z", "remaining_seconds": 86400}

عند الحظر النهائي يكون permanent=true بلا remaining_seconds، فلا تعرض وقتاً متبقياً. ينتهي الحظر المؤقت تلقائياً عند انقضاء مدته. السبب خاص بهذا اللاعب فقط.

`GET /save`

يقرأ خانة الحفظ السحابي للاعب.

الترويسات: X-Session-Token

GET https://blindgames.info/api/dev/save?game_id=your_game_id&profile=hero1&slot=default
X-Session-Token: session-token-value

# Response
{"data": "...", "exists": true}

المعامل profile اختياري في كل عمليات الحفظ؛ احذفه للحفظ على مستوى اللعبة.

`PUT /save`

يكتب خانة الحفظ السحابي للاعب (الحد الأقصى 1 ميجابايت لكل خانة).

الترويسات: X-Session-Token

PUT https://blindgames.info/api/dev/save
X-Session-Token: session-token-value
Content-Type: application/json

{"game_id": "your_game_id", "profile": "hero1", "slot": "default", "data": "..."}

# Response
{"ok": true}

`GET /saves`

يعرض قائمة خانات الحفظ الموجودة للاعب (الأسماء والأحجام) دون البيانات.

الترويسات: X-Session-Token

GET https://blindgames.info/api/dev/saves?game_id=your_game_id
X-Session-Token: session-token-value

# Response (omit profile to list every character's slots)
{"saves": [
  {"profile": "hero1", "slot": "default", "size": 1240, "updated_at": "2026-06-14T10:00:00Z"},
  {"profile": "hero2", "slot": "checkpoint", "size": 980, "updated_at": "2026-06-14T11:30:00Z"}
]}

`DELETE /save`

يحذف خانة حفظ سحابي للاعب. عملية مكرّرة الأثر (idempotent).

الترويسات: X-Session-Token

DELETE https://blindgames.info/api/dev/save
X-Session-Token: session-token-value
Content-Type: application/json

{"game_id": "your_game_id", "profile": "hero1", "slot": "default"}

# Response
{"ok": true, "deleted": true}

`GET /profiles`

يعرض قائمة شخصيات اللاعب في اللعبة مع بياناتها الوصفية.

الترويسات: X-Session-Token

GET https://blindgames.info/api/dev/profiles?game_id=your_game_id
X-Session-Token: session-token-value

# Response
{"profiles": [
  {"id": "rec123", "name": "Knight", "data": "...", "last_played": "2026-06-15T09:00:00Z", "created_at": "...", "updated_at": "..."}
]}

الحقل last_played يُحدَّث تلقائياً عند كل حفظ تحت الشخصية، أو يدوياً عبر POST /profile/select. اعرضه في قائمة الشخصيات ليرى اللاعب آخر مرة لعب بكل شخصية.

`POST /profile`

ينشئ شخصية جديدة للاعب ويعيد معرّفها. حقل البيانات الوصفية حر حتى 1 ميجابايت.

الترويسات: X-Session-Token

POST https://blindgames.info/api/dev/profile
X-Session-Token: session-token-value
Content-Type: application/json

{"game_id": "your_game_id", "name": "Knight", "data": "..."}

# Response
{"profile": {"id": "rec123", "name": "Knight", "data": "...", "created_at": "...", "updated_at": "..."}}

استخدم القيمة id الناتجة كقيمة profile في خانات الحفظ لربطها بهذه الشخصية.

`PUT /profile`

يعدّل اسم الشخصية أو بياناتها الوصفية. الحقول اختيارية، يُحدّث المُرسل منها فقط.

الترويسات: X-Session-Token

PUT https://blindgames.info/api/dev/profile
X-Session-Token: session-token-value
Content-Type: application/json

{"game_id": "your_game_id", "profile_id": "rec123", "name": "Paladin", "data": "..."}

# Response
{"ok": true, "profile": { ... }}

`DELETE /profile`

يحذف الشخصية وكل خانات الحفظ المرتبطة بها (حذف متتالٍ).

الترويسات: X-Session-Token

DELETE https://blindgames.info/api/dev/profile
X-Session-Token: session-token-value
Content-Type: application/json

{"game_id": "your_game_id", "profile_id": "rec123"}

# Response
{"ok": true, "deleted": true}

`POST /profile/select`

يسجّل وقت آخر لعب للشخصية عند اختيار اللاعب لها، ويعيد بياناتها المحدّثة.

الترويسات: X-Session-Token

POST https://blindgames.info/api/dev/profile/select
X-Session-Token: session-token-value
Content-Type: application/json

{"game_id": "your_game_id", "profile_id": "rec123"}

# Response
{"ok": true, "profile": { ..., "last_played": "2026-06-15T09:00:00Z"}}

رموز الأخطاء

تعيد نقاط النهاية رمز حالة HTTP مناسباً مع حقل error يصف المشكلة:

{"error": "invalid_credentials"}

missing_credentials / invalid_credentials
missing_session_token / invalid_session / session_expired
invalid_request
too_many_pending
invalid_device_code / expired_token / access_denied
score_out_of_range
save_too_large
profile_not_found
forbidden
server_error

الحدود والقيود

معدل الطلبات: 120 طلباً في الدقيقة لكل عميل.
حجم الحفظ السحابي: 1 ميجابايت كحد أقصى لكل خانة.
النقاط: قيمة موجبة لا تتجاوز الحد الأقصى المسموح لمنع الغش.
مفاتيح API: حتى 10 مفاتيح لكل مطور.

تحتاج مساعدة؟

إن واجهتك مشكلة أو كان لديك اقتراح، تواصل معنا عبر صفحة التواصل. اتصل بنا