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

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

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

المسار الرسمي هو /api/v1. يبقى المسار القديم /api/dev يعمل كاسم بديل للتوافق، لكن استخدم /api/v1 في التكاملات الجديدة.

البدء السريع

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

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

المصادقة

لعبتك المنشورة تحتاج المفتاح العام فقط (X-API-Key) — يُرسل مع كل طلب ويعرّف لعبتك. ربط اللاعب يتم عبر تدفق رمز الجهاز (معيار OAuth للعملاء العامّين)، والأمان يأتي من موافقة اللاعب على الموقع لا من مفتاح سري. بعد الربط تُصادَق طلبات اللاعب برمز الجلسة (X-Session-Token).

المفتاح العام يُرسل مع كل طلب:

X-API-Key: your_api_key

لا تملك خادماً؟ لا مشكلة — لعبتك تعمل بالكامل بالمفتاح العام وحده: ربط اللاعب، الحفظ، الصدارة، الإحصائيات، الإنجازات، الاقتصاد، وكل شيء. المفتاح السري (X-API-Secret) مخصّص حصراً لأدوات إدارة لعبتك (الضبط عن بُعد، الصيانة، الإعلانات، كتالوج الإنجازات) وتُشغّلها من لوحة المطورين أو جهازك الخاص — لا داخل اللعبة ولا على خادم. لا تضمّنه أبداً في بناء اللعبة المنشور.

ملاحظات أمنية

لا تثق بالقيم القادمة من العميل مباشرة. أي لاعب يستطيع تعديل لعبته وإرسال {"score": 999999999}. تحقّق من النقاط من جهة الخادم عند الإمكان، أو ضع حدوداً منطقية لكل وضع لعب، أو احفظ بيانات الجولة في metadata لكشف القيم الشاذة. المنصة تطبّق حداً أقصى عاماً للنقاط لكنه لا يغني عن تحققك الخاص.

تفويض اللاعب

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

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

مثال:

POST https://blindgames.info/api/v1/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/device",
  "verification_uri_complete": "https://blindgames.info/device?code=ABCD2345",
  "expires_in": 600,
  "interval": 5
}

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

POST https://blindgames.info/api/v1/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 مع الطلبات الخاصة باللاعب (مثل حفظ النقاط أو الحفظ السحابي).

إذا عاد رمز الجلسة بخطأ session_expired فالرمز انتهى ولا يمكن تجديده — أعد تشغيل تدفق رمز الجهاز. جدّد الرمز دورياً قبل اقتراب انتهائه (الصلاحية 30 يوماً).

الشخصيات (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": "..."}

`POST /session/refresh`

يجدّد رمز جلسة ما زال صالحاً ويعيد رمزاً جديداً (يُلغى القديم)، دون إعادة تدفق رمز الجهاز. لا يمكن تجديد رمز منتهٍ — أعد ربط اللاعب حينها.

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

POST https://blindgames.info/api/v1/session/refresh
X-Session-Token: current-session-token

# Response
{"session_token": "new-session-token", "expires_in": 2592000}

`GET /player`

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

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

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

`POST /score`

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

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

POST https://blindgames.info/api/v1/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/v1/leaderboard?game_id=your_game_id&mode=default&limit=20
# Optional: send X-Session-Token to also receive the caller's own rank.

# 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}}
 ],
 "me": {"rank": 5234, "score": 1000}}

إن أرسلت ترويسة X-Session-Token مع طلب الصدارة، تضيف الاستجابة حقل me فيه ترتيب اللاعب الحالي ونقاطه حتى لو كان خارج الصفحة المطلوبة (مثلاً «ترتيبك 5234»).

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

`GET /ban`

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

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

GET https://blindgames.info/api/v1/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/v1/save?game_id=your_game_id&profile=hero1&slot=default
X-Session-Token: session-token-value

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

المعامل profile اختياري في كل عمليات الحفظ؛ احذفه للحفظ على مستوى اللعبة. يقبل إما مفتاحاً حراً (مثل hero1) أو معرّف شخصية (profile_id) أنشأته عبر POST /profile — كلاهما يُخزَّن في نفس الحقل، فاختر أسلوباً واحداً والتزم به لتجنّب اللبس.

`PUT /save`

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

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

PUT https://blindgames.info/api/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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"}}

خدمات الـ Backend الكاملة

إلى جانب الدخول والحفظ والصدارة، توفّر المنصة خدمات جاهزة تغنيك عن بناء خادم خاص. كل الطلبات القرائية الخاصة باللاعب تحتاج X-API-Key + X-Session-Token. نقاط الضبط (الكتابة) للمطوّر تحتاج X-API-Secret ولا تُستخدم داخل اللعبة المنشورة.

تفويض اللاعب

تحديث ملف اللاعب: PUT /player بجسم {display_name?, bio?} لتعديل الاسم الظاهر والنبذة (الصورة تُدار من الموقع).

PUT https://blindgames.info/api/v1/player
X-Session-Token: S
{"display_name": "Hamad", "bio": "..."}

Statistics

الإحصائيات: POST /stats بجسم {game_id, profile?, mode?(increment|set), stats:{kills:5, wins:1}} لزيادة أو ضبط عدّادات، وGET /stats لقراءتها.

POST https://blindgames.info/api/v1/stats
X-Session-Token: S
{"game_id": "G", "mode": "increment", "stats": {"kills": 5, "wins": 1}}

Achievements

الإنجازات: يعرّف المطور الكتالوج عبر PUT /achievements/define (بالمفتاح السري)، ويفتح اللاعب إنجازاً عبر POST /achievement/unlock، ويقرأ GET /achievements حالته. الإنجازات السرّية تُخفى تفاصيلها حتى تُفتح.

# Developer (secret): define the catalog
PUT https://blindgames.info/api/v1/achievements/define
X-API-Secret: your_api_secret
{"game_id": "G", "achievements": [
  {"key": "first_win", "name": "First Win", "points": 10},
  {"key": "secret_boss", "name": "???", "secret": true, "points": 50}
]}

# Player: unlock + list
POST https://blindgames.info/api/v1/achievement/unlock   {"game_id": "G", "key": "first_win"}
GET  https://blindgames.info/api/v1/achievements?game_id=G

Inventory & Economy

الاقتصاد: حقيبة العناصر (GET /inventory، POST /inventory/add بكمية موجبة أو سالبة) وأرصدة العملة (GET /currency، POST /currency/add — الخصم الذي يتجاوز الرصيد يُرفض بـ insufficient_funds). كل العمليات محسوبة على الخادم.

POST https://blindgames.info/api/v1/inventory/add   {"game_id": "G", "item": "gold", "amount": 500}
GET  https://blindgames.info/api/v1/inventory?game_id=G
POST https://blindgames.info/api/v1/currency/add    {"game_id": "G", "currency": "coins", "amount": -50}
GET  https://blindgames.info/api/v1/currency?game_id=G

Daily Rewards

المكافأة اليومية: GET /daily لمعرفة إمكانية المطالبة والسلسلة، وPOST /daily/claim للمطالبة (مهلة 24 ساعة، تُحسب السلسلة على الخادم). لعبتك تقرّر محتوى المكافأة من رقم اليوم.

GET  https://blindgames.info/api/v1/daily?game_id=G        # {"can_claim": true, "streak": 3}
POST https://blindgames.info/api/v1/daily/claim           # {"claimed": true, "streak": 4, "day": 4}

Analytics

التحليلات: POST /event بجسم {game_id, event, data?} لتسجيل أحداث اللعب. يقرأ المطور ملخّصاً عبر GET /analytics (بالمفتاح السري): إجمالي الأحداث وعدد اللاعبين وأكثر الأحداث تكراراً.

POST https://blindgames.info/api/v1/event   {"game_id": "G", "event": "level_completed", "data": {"level": 5}}
GET  https://blindgames.info/api/v1/analytics?game_id=G   (X-API-Secret)

Notifications

الإشعارات: يرسلها المطور للاعب عبر POST /notification (بالمفتاح السري)، ويجلبها اللاعب عبر GET /notifications، ويعلّمها مقروءة عبر POST /notifications/read.

GET  https://blindgames.info/api/v1/notifications?game_id=G
POST https://blindgames.info/api/v1/notifications/read   {"game_id": "G"}
# Developer (secret):
POST https://blindgames.info/api/v1/notification   {"game_id": "G", "user_id": "U", "title": "..."}

Support Tickets

الدعم الفني داخل اللعبة: اللاعب يفتح تذكرة عبر POST /support/ticket فتصل مطوّر لعبته مباشرة (أو فريق المنصة بـ scope=platform)، ويتابعها ويردّ ويغلقها دون مغادرة اللعبة. أرفق context بلقطة تشخيصية (الإصدار، النظام، آخر خطأ) تصل المطوّر كملاحظة داخلية لا يراها اللاعب، وclient_ref كمفتاح تكرار يمنع ازدواج التذاكر عند انقطاع الشبكة. GET /support/summary نداء رخيص عند الإقلاع يخبرك إن كان ينتظر اللاعبَ ردّ، ويصل الردّ أيضاً في صندوق إشعارات اللعبة وفي بثّ الأحداث بنوع ticket. ويدير المطوّر طابور لعبته برمجياً عبر /support/queue بالمفتاح السري.

GET  https://blindgames.info/api/v1/support/meta
POST https://blindgames.info/api/v1/support/ticket   {"subject": "...", "body": "...", "category": "bug",
                                    "context": {"version": "1.4.2", "platform": "windows"},
                                    "client_ref": "save-bug-42"}
GET  https://blindgames.info/api/v1/support/tickets?status=open&game_id=G
GET  https://blindgames.info/api/v1/support/ticket?id=T
POST https://blindgames.info/api/v1/support/ticket/reply   {"id": "T", "body": "..."}
POST https://blindgames.info/api/v1/support/ticket/close   {"id": "T"}
GET  https://blindgames.info/api/v1/support/summary?game_id=G   # {"open": 2, "awaiting_you": 1, "latest_awaiting": {...}}
# Developer (secret):
GET  https://blindgames.info/api/v1/support/queue?game_id=G
GET  https://blindgames.info/api/v1/support/queue/ticket?id=T
POST https://blindgames.info/api/v1/support/queue/reply    {"id": "T", "body": "...", "status": "waiting_user"}
POST https://blindgames.info/api/v1/support/queue/status   {"id": "T", "status": "resolved"}

Remote Config & Feature Flags

الضبط عن بُعد وأعلام الميزات: GET /config يقرأ كائن JSON حرّاً يضبطه المطور عبر PUT /config (بالمفتاح السري) لتغيير سلوك اللعبة دون تحديث (مضاعف خبرة، فعالية موسمية، تفعيل ميزة...).

GET https://blindgames.info/api/v1/config?game_id=G   # {"config": {"xp_multiplier": 2, "holiday_event": true}}
# Developer (secret):
PUT https://blindgames.info/api/v1/config   {"game_id": "G", "config": {"xp_multiplier": 2, "boss_hp": 5000}}

Maintenance & Version

الصيانة والإصدار: GET /status يخبر إن كانت اللعبة في صيانة، وGET /version يعيد أحدث إصدار وأدنى إصدار مدعوم وهل التحديث إلزامي. يضبطهما المطور عبر PUT /status (بالمفتاح السري).

GET https://blindgames.info/api/v1/status?game_id=G    # {"maintenance": true, "message": "..."}
GET https://blindgames.info/api/v1/version?game_id=G   # {"latest": "1.3.0", "minimum": "1.2.0", "required": true}
# Developer (secret):
PUT https://blindgames.info/api/v1/status   {"game_id": "G", "maintenance": true, "min_version": "1.2.0", "required": true}

Announcements & News

الإعلانات والأخبار: GET /announcements وGET /news يعيدان العناصر النشطة للعبة (والعامة للمنصة). ينشرها المطور عبر POST /announcement (بالمفتاح السري).

GET https://blindgames.info/api/v1/announcements?game_id=G
GET https://blindgames.info/api/v1/news?game_id=G
# Developer (secret):
POST https://blindgames.info/api/v1/announcement   {"game_id": "G", "kind": "news", "title": "...", "body": "..."}

Save History

تاريخ الحفظ: كل كتابة حفظ تحفظ نسخة سابقة تلقائياً. GET /save/revisions يعرض النسخ، وPOST /save/restore يستعيد نسخة (والحالة الحالية تُحفظ أيضاً قبل الاستعادة).

GET  https://blindgames.info/api/v1/save/revisions?game_id=G&slot=default
POST https://blindgames.info/api/v1/save/restore   {"game_id": "G", "slot": "default", "revision_id": "R"}

Leaderboard Types

أنواع لوحات الصدارة: يضبط المطوّر نوع كل وضع عبر PUT /leaderboard/config — max (الأعلى)، min (الأقل، لسباقات الزمن)، أو latest (الأحدث). الافتراضي max.

# Developer (secret):
PUT https://blindgames.info/api/v1/leaderboard/config   {"game_id": "G", "mode": "time_attack", "type": "min"}

Ban Category

تصنيف الحظر: يعيد /ban الآن حقل category (cheating/abuse/spam/harassment/other) إلى جانب السبب والمدة.

تذكير أمني: كل القيم القادمة من العميل (النقاط، العملة، العناصر) يجب التحقق منها من جهتك أيضاً عند الحساسية؛ الخادم يطبّق حدوداً عامة لكنه لا يعرف منطق لعبتك.

مرجع الحقول والبيانات

كل كائن تعيده الواجهة موثّق هنا حتى تعرف بالضبط ما يصلك. أسماء الحقول ثابتة بالإنجليزية وتُقرأ كما هي في الـ SDK.

كائن اللاعب (player)

{"player": {
  "id": "rec...",
  "display_name": "...",
  "avatar": "https://...",
  "bio": "..."
}}

id: معرّف اللاعب الثابت. display_name: الاسم الظاهر (في مكتبتَي NVGT وGodot باسم player_name). avatar: رابط الصورة (تُدار من الموقع). bio: نبذة اللاعب. الصورة والنبذة يضبطهما اللاعب من حسابه على المنصة.

بقية الكائنات وحقولها (تظهر في استجابات النقاط المقابلة أعلاه):

leaderboard entry: rank, display_name, score, metadata, achieved_at
profile: id, name, data, last_played, created_at, updated_at
achievement: key, name, description, icon, points, secret, unlocked, unlocked_at
inventory item: item, amount, data
currency: balances (currency → amount)
daily: can_claim, claimed, streak, day, next_in_seconds, last_claimed
notification: id, title, body, url, read, created_at
ban: banned, reason, category, permanent, expires_at, remaining_seconds
status / version: maintenance, message — latest, minimum, required
announcement / news: id, title, body, url, created_at, global
save slot: profile, slot, size, updated_at

أي حقل جديد نضيفه لاحقاً لا يكسر لعبتك؛ تجاهل ما لا تعرفه واقرأ ما يخصّك. وحقول metadata في الصدارة حرّة تعرّفها أنت من لوحة المطورين.

مثال كامل من البداية للنهاية

السيناريو النموذجي لربط لاعب ثم حفظ تقدمه وتسجيل نقطته:

# 1) Ask for a device code (PUBLIC key only — no secret, no server)
POST https://blindgames.info/api/v1/device/code
X-API-Key: your_api_key
{"game_id": "your_game_id"}
# → open verification_uri_complete so the player approves in one click

# 2) Poll until approved, then keep the session_token (still no secret)
POST https://blindgames.info/api/v1/device/token
X-API-Key: your_api_key
{"device_code": "long-opaque-code"}
# → {"status": "approved", "session_token": "S", "player": {...}}

# 3) Read the player (key + session token)
GET https://blindgames.info/api/v1/player
X-API-Key: your_api_key
X-Session-Token: S

# 4) Save progress to the cloud
POST https://blindgames.info/api/v1/save
X-API-Key: your_api_key
X-Session-Token: S
{"game_id": "your_game_id", "slot": "default", "data": "..."}

# 5) Submit a score (server caps it; verify on your side too)
POST https://blindgames.info/api/v1/score
X-API-Key: your_api_key
X-Session-Token: S
{"game_id": "your_game_id", "score": 1500, "mode": "default"}

# Later: refresh the session instead of re-linking
POST https://blindgames.info/api/v1/session/refresh
X-API-Key: your_api_key
X-Session-Token: S

الصمود وقت توقّف الخادم

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

الخطأ العابر (لا استجابة، أو رمز خادم 5xx مثل 502/503) يُعاد فيه إرسال الطلب تلقائياً بعد مهلة قصيرة، بخلاف الردّ النهائي (2xx نجاح أو 4xx خطأ في الطلب).
عمليات الكتابة من نوع «أطلِق وانسَ» (النقاط، الحفظ السحابي، الأحداث، الإحصائيات، الإنجازات) تدخل طابوراً في الذاكرة إن كان الخادم متوقّفاً، وتُرسَل تلقائياً بالترتيب حين يعود — فلا تضيع.
تستدعي لعبتك pump() دورياً (كل إطار) لتفريغ الطابور حين يعود الخادم؛ وهي رخيصة وتعيد المحاولة كل فترة فقط. وإن تكاملت مباشرة بلا الـ SDK فطبّق المنطق نفسه: راقب 502/انقطاع الاتصال، واصطفّ الكتابات، وأعد الإرسال عند العودة.

للتحقق السريع أن الخادم عاد قبل إعادة الإرسال، استعلم نقطة الحياة العامة (لا تحتاج مصادقة):

GET /api/health   →   {"status": "ok"}

رموز الأخطاء

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

{"error": "invalid_credentials"}

missing_credentials / invalid_credentials
missing_session_token / invalid_session / session_expired
invalid_request
too_many_pending
too_many_requests (HTTP 429) — معدل الطلبات: 120 طلباً في الدقيقة لكل عميل. تجاوزها يعيد رمز الحالة 429 Too Many Requests.
invalid_device_code / expired_token / access_denied
score_out_of_range
save_too_large
profile_not_found
insufficient_funds / achievement_not_found / revision_not_found
config_too_large / invalid_type / too_many_stats
forbidden
server_error

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

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

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

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