مرجع الخادم

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

#المبادئ الأساسية

استدعِها من خادمك فقط. مفتاحك سرّي: لا تضعه في صفحتك.

curl https://api.lialabs.org/api/apps/v1/pool \
  -H "Authorization: Bearer $LIA_KEY"

مساعد صغير يستخدم في الأمثلة التالية:

const LIA = "https://api.lialabs.org/api/apps/v1";

export async function lia(method, path, body) {
  const res = await fetch(LIA + path, {
    method,
    headers: { Authorization: `Bearer ${process.env.LIA_KEY}`, "Content-Type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const data = await res.json();
  if (!res.ok) throw Object.assign(new Error(data.error), { status: res.status, data });
  return data;
}

#المفاتيح والوضعيات

مفتاح يرى فقط تطبيقه الخاص، ويستخدم فقط وضعه الخاص: المفتاح التجريبي يرى جلسات تجريبية، ورسوم، وأعوام، وإعلانات؛ والمفتاح الحي يرى تلك الحقيقية. شيء من الوضع الآخر هو not_found (أو valid: false. راجع اختبار وحقيقي.

#الأخطاء

تُجيب الأخطاء بحالة 4xx وجسم يحتوي على error الكود، أحيانًا مع المزيد من الحقول:

{ "error": "pool_empty", "pool": 3.5 }

كل نقطة نهاية تُعرض محتواها الخاص. كل كود موجود في أكواد الأخطاء.

#الجلسات

#POST/session/verify

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/session/verify' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "session": "lias_example_session"
}'

يحقق من رمز جلسة من Lia.init() أو Lia.session(), ويُخبرك بمن يملكه.

POST /api/apps/v1/session/verify
Authorization: Bearer lia_live_…
Content-Type: application/json

{ "session": "lias_eyJhcHAiOi…" }

الإجابات 200 بأي حال من الأحوال:

{ "valid": true, "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "mode": "live", "exp": 1761998400000 }

{ "valid": false }

رمز صالح عندما قام Lia بتوقيعه، إنه'لتطبيقك ولمفتاحك'الوضع، ولا يوجد'انتهت (15 دقائق بعد إنشائها).

#المنتجات

#GET/products

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/products' \
  --header "Authorization: Bearer $LIA_KEY"

ما تبيعه تطبيقك، بأسعار Lia'السجلات. فقط المنتجات النشطة، الأرخص أولًا.

{
  "products": [
    { "id": "extra-lives", "name": "3 extra lives", "price": 5, "active": true },
    { "id": "gold-pack", "name": "Gold pack", "price": 25, "active": true }
  ]
}

#الرسوم

الرسوم هي دفعة واحدة على Lia'ورقة الدفع الخاصة به. راجع المدفوعات.

كائن الرسوم:

#GET/charges/:id

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/charges/id_example' \
  --header "Authorization: Bearer $LIA_KEY"

هل هذه الرسوم حقيقية ودفعها من قبل من؟ تحقق دائمًا من هنا قبل التسليم: لا تأخذ الصفحة'أو ويب هوك'كلمة لها.

{
  "charge": {
    "id": "ch_9b1f4c2e7a0d5b8f3e6a1c4d",
    "playerId": "p_3f9c0a6d1b2e4f5a6b7c",
    "productId": "extra-lives",
    "amount": 5,
    "status": "paid",
    "mode": "live",
    "createdAt": 1761998400000,
    "deliveredAt": null,
    "refundedAt": null
  }
}

#POST/charges/:id/deliver

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/charges/id_example/deliver' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Idempotency-Key: example-request-1'

يُشير إلى دفع تم تسليمه، مرة واحدة بعد أن'لقد قدموا للشخص ما اشتراه. آمن للتكرار: توصيل الشحنة المُرسلة لا يغير شيئًا ويُجيب نفس الشيء. لا وجود لجسم.

{ "charge": { "id": "ch_9b1f…", "status": "delivered", "deliveredAt": 1761998405000, "…": "…" } }

#POST/charges/:id/refund

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/charges/id_example/refund' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Idempotency-Key: example-request-1'

يعيد إرسال ⁦$LIA⁩ إلى الشخص، عندما يمكنك ذلك'لإيصالها بعد.

{ "charge": { "id": "ch_9b1f…", "status": "refunded", "refundedAt": 1761998410000, "…": "…" } }

السعر الكامل يعود إلى الشخص'رصيده، في الوضع الحي، من Lia'جزءه ونسبة مشاركتك. أ charge.refunded يتم إرسال الويب هوك.

#المكافآت

انظر خزائن المكافآت.

#POST/rewards

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/rewards' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "playerId": "player_example",
  "amount": 1,
  "key": "reward-example-1",
  "reason": "Level completed"
}'

يدفع لاعبًا من تطبيقك'مصدر المكافآت، مرة لكل مفتاح.

POST /api/apps/v1/rewards
Authorization: Bearer lia_live_…
Content-Type: application/json

{
  "playerId": "p_3f9c0a6d1b2e4f5a6b7c",
  "amount": 25,
  "key": "tournament-2026-11-01:p_3f9c0a6d1b2e4f5a6b7c",
  "reason": "Weekly tournament, 1st place"
}

مدفوع:

{ "status": "paid", "amount": 25, "pool": 975 }

نفس المفتاح يدفع شيئًا ولا يجيب بمال المفتاح الأول:

{ "status": "duplicate", "amount": 25, "pool": 975 }

pool هو ما'الذي تتركه في حوضك بعد ذلك. في الوضع التجريبي، المكافأة وهمية: لا يوجد حوض.'لديه مستخدم وحدة الحد اليوم لا'ت التطبيق.

A reward.paid يتم إرسال الويب هوك لكل مكافأة تم دفعها (وليس للنسخ المكررة).

#GET/pool

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/pool' \
  --header "Authorization: Bearer $LIA_KEY"

ماذا'الذي تتركه في حوض المكافأة، والأقصى الذي يمكن للاعب واحد الحصول عليه في اليوم.

{ "balance": 975, "dailyCapPerPlayer": 50, "mode": "live" }

dailyCapPerPlayer هو 0 عندما'لا يوجد حد يومي. balance هو المجموعة الحية، وكذلك عندما تطلب بملفات تعريف الارتباط الخاصة بك.

#الإشعارات

انظر الإشعارات.

#POST/notifications

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/notifications' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "playerId": "player_example",
  "text": "Ready for another round?",
  "startParam": "round_2"
}'

يُرسل إشعارًا للاعب الذي وافق عليه. يظهر تحت تطبيقك'اسمها ويفتح تطبيقك بـ startParam.

POST /api/apps/v1/notifications
Authorization: Bearer lia_live_…
Content-Type: application/json

{ "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "text": "It's your move against @amara.", "startParam": "match-8k2d" }

تم الإرسال:

{ "sent": true, "pushed": true }

pushed هو false عندما وصل إلى Lia'جرسه ولكن ليس الهاتف (لديه Lia'يتم إيقاف الطرد).

#إعلانات

انظر إعلانات.

#POST/ads/verify

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/ads/verify' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "adId": "ad_example"
}'

هل كان هذا الإعلان مُشاهدًا حقًا، ومن قبل من؟ تحقق قبل منح أي شيء مقابل فيديو مكافأة.

POST /api/apps/v1/ads/verify
Authorization: Bearer lia_live_…
Content-Type: application/json

{ "adId": "ad_8e1c4b0f2a9d47c6b3e15a07" }

{ "adId": "ad_8e1c4b0f2a9d47c6b3e15a07", "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "format": "rewarded", "watched": true, "watchedAt": 1761998400000 }

اسأل باستخدام مفتاح وضع الإعلان الذي تم عرضه: إعلان في وضع الاختبار (يكون دائمًا أحد Google'إعلانات الاختبار، لا تُحسب في الأرباح) هي not_found للمشاهدة

Lia لم تتمكن'لا تُعلّم إعلانًا كمستخدم عند التحقق منه، لذلك ادفع كل adId مرة واحدة (استخدم ad:<adId> كما هو مفتاح المكافأة).

#الغرفة المشتركة

الجداول العامة التي يمكن لأي شخص على Lia العثور عليها. Lia يحتفظ فقط بالقائمة: خادمك يشغل الجدول. انظر الجداول العامة.

كائن الجدول:

#POST/lobby/tables

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/lobby/tables' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "tableId": "table_example",
  "hostPlayerId": "player_example",
  "seats": 2,
  "taken": 1,
  "title": "A friendly game",
  "stake": 1,
  "pot": 1,
  "expiresIn": 1800
}'

يُسجل جدولًا يخص'في انتظار اللاعبين، أو تحديث قائمة العرض (يحتفظ بمكانته في القائمة). قم بإدراجها مرة أخرى عندما تتغير مقاعدها.

{ "tableId": "t8k2d", "hostPlayerId": "p_3f9c0a6d1b2e4f5a6b7c", "seats": 2, "taken": 1, "title": "Quick game", "stake": 5, "expiresIn": 900 }

{ "listed": true, "tableId": "t8k2d", "seats": 2, "taken": 1, "expiresAt": 1761999300000 }

متى taken يصل seats, يتم أخذ الجدول من القائمة بدلاً من ذلك، والجواب هو { "listed": false }.

#GET/lobby/tables

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/lobby/tables' \
  --header "Authorization: Bearer $LIA_KEY"

تطبيقك'جداول مفتوحة في مفتاحك'الوضع، الأحدث أولاً، حتى 200: كل مضيف'، مع تجاهل الكتل (التي'لكل لاعب'رأيه الخاص).

{ "tables": [{ "id": "t8k2d", "game": "your-app", "host": { "name": "amara" }, "seats": 2, "taken": 1, "title": "Quick game", "stake": 5, "pot": 0, "createdAt": 1761998400000, "expiresAt": 1761999300000 }] }

#POST/lobby/tables/:id/sit

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/lobby/tables/id_example/sit' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "playerId": "player_example"
}'

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

{ "playerId": "p_8a1e0c4d2b7f9e3a5c6d" }

{ "seated": true, "taken": 2, "seats": 2, "full": true }

#DELETE/lobby/tables/:id

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request DELETE 'https://api.lialabs.org/api/apps/v1/lobby/tables/id_example' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Idempotency-Key: example-request-1'

يأخذ الجدول من القائمة، عندما تبدأ اللعبة أو تغلق. آمن للتكرار.

{ "removed": true }

removed هو false عندما لم يكن'لأنها تعيش، أو أي مفتاح أثناءها

#إعادة المحاولة

إرسال Idempotency-Key الرأسية مع كل POST, والنفس المفتاح مرة أخرى في كل محاولة إعادة لطلب معين. إذًا، لن يقوم بإعادة أي شيء مرتين، وسينتهي بنفس طريقة الطلب الأول.

POST /api/apps/v1/notifications
Authorization: Bearer lia_live_…
Content-Type: application/json
Idempotency-Key: 6f1c2a9e-0b7d-4c35-9e1a-2d8f4b7c3a10

{ "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "text": "It's your move." }

• أي مفتاح تحبه, 1 إلى 128 من الحروف والأرقام, _, -, . و :. رسوم UUID لكل عملية هي صحيحة.
• يتم تشغيل الطلب الأول. إذا نجحت (2xx)، يتم الاحتفاظ بإجابتها لمدة 24 ساعات، ويتم إعادة المحاولة بنفس المفتاح والجسم نفسه، وتحصل على نفس الإجابة مرة أخرى، مع الرأس Idempotent-Replayed: true.
• الرفض لا يحتفظ بشيء (أو 4xx أو 5xx)، لذا يمكنك إصلاح السبب والمحاولة مرة أخرى بنفس المفتاح.
• نفس المفتاح مع جسم مختلف هو 422 idempotency_key_reused.
• نفس المفتاح بينما المفتاح الأول لا يزال يعمل هو 409 idempotency_key_in_use مع Retry-After: 1. إعادة المحاولة، وتحصل على الأول'س الإجابة.
• المفاتيح هي تطبيقك'مملكتها, ويبقى كل مفتاح منفصلًا. المفتاح نفسه على نقطة نهاية أخرى هو مفتاح مختلف.

بدون الرأس، فإن معظم نقاط نهاية الوظائف ما زالت آمنة للإعادة: القراءة لا تغير شيئًا، وتسليم المكافآت وإعادة الصرف آمنة للإعادة، والمكافآت تُدفع مرة واحدة لكل key. الإشعارات هي الاستثناء: بدون العنوان، يتم إرسال الإشعار مرة أخرى عند المحاولة مرة أخرى.

تم الترجمة تلقائيًا. الإنجليزية هي مصدر الحقيقة. اقرأ باللغة الإنجليزية