يمنح API العامة مسؤولي المنظمة وصولًا مباشرًا عبر HTTP إلى بيانات منظمتك الحية — اسحبها إلى أي موقع أو تطبيق أو بوت أو أتمتة تستطيع إرسال طلب HTTP. وهي ميزة في خطة Business.
المفتاح مقصور على منظمتك — وتعمل جميع نقاط النهاية على تلك المجموعة تلقائيًا. الرابط الأساسي: https://api.ludoya.com/public/v1. ترويسة المصادقة: X-Api-Key: YOUR_KEY. حد المعدل: 100 طلب في الدقيقة، وبعدها تحصل على 429.
تبدأ المفاتيح بـldy_ وطولها 36 حرفًا، فيسهل تمييزها في ملف إعدادات — ويسهل البحث عنها إن انتهى أحدها يومًا في مكان لا ينبغي. تعامل معه كأنه كلمة مرور: على الخادم فقط، واسحبه من الصفحة نفسها إن تسرّب.
ما الذي يمكنك الوصول إليه
- المواقع — أماكن مجموعتك المتاحة ومواضعها؛ تُستخدم مدخلًا عند إنشاء الفعاليات
- الفعاليات (قراءة) — الفعاليات القادمة والسابقة بعنوانها ووصفها وتاريخها ووقتها ومنطقتها الزمنية وسعتها وعدد مشاركيها وحالتها
- الفعاليات (كتابة) — أنشئ الفعاليات وحدّثها عبر POST وPUT، مع تحكم كامل في الموقع والسعة والصلاحيات والظهور والصورة
- الفعاليات الفرعية — اسرد الفعاليات المتداخلة داخل فعالية أب
- المشاركون — أضف شخصًا إلى فعالية، أو غيّر حضوره، أو أزِله
- الأعضاء — قائمة الأعضاء بملفاتهم وأدوارهم (مالك، مسؤول، عضو)، مقسمة إلى صفحات
- الدعوات — ادعُ شخصًا إلى مجموعتك
- البحث — ابحث عن مستخدمي Ludoya وعن فهرس ألعاب الطاولة، لتحويل الأسماء إلى معرّفات قبل الكتابة
- المجموعة — مجموعة الألعاب مع التصفية حسب الملكية والاسم وعدد اللاعبين والقائمة؛ قابلة للترتيب ومقسمة إلى صفحات؛ وكل لعبة تتضمن بيانات BGG الوصفية
- الإحصاءات — إحصاءات اللعب لأي فترة زمنية: الإجماليات والمتوسطات وأفضل اللاعبين بانتصاراتهم ونتائجهم، وتوزيعات حسب عدد اللاعبين والموقع واللعبة
- الحملات (قراءة) — اسرد حملات المجموعة بأعداد الأعضاء والجلسات؛ واحصل على تفاصيل الحملة كاملة بما فيها الأعضاء والجلسات السابقة والفعاليات المجدولة
- الحملات (كتابة) — أنشئ حملات للمجموعة وحدّث اسمها ووصفها وحالتها وظهورها
- أعضاء الحملة — أضف الأشخاص في الحملة وحدّثهم وأزِلهم
نقاط النهاية
GET /locations
تُعيد المواقع المتاحة للمجموعة. ولكل موقع id وname وaddress اختياري وcapacity وراية isDefault ومصفوفة spots (ولكل موضع id وname وcapacity خاص به). استخدم معرّفات المواقع والمواضع عند إنشاء الفعاليات.
تسجيل الدخول عبر Ludoya
الصفحة نفسها التي تحوي مفتاح API تحوّل منظمتك أيضًا إلى مزوّد تسجيل دخول. دع الناس يسجّلون الدخول إلى موقعك أو منتداك أو منصة مجتمعك بحساباتهم على Ludoya — بلا كلمة مرور منفصلة ينسونها، وبلا قاعدة بيانات مستخدمين تديرها أنت.
لماذا يستحق ذلك
حين يوافق أحدهم على تسجيل الدخول، يُربط بمنظمتك: فبحسب سياسة الانضمام في مجموعتك إما يصير عضوًا فورًا (مفتوحة)، أو يقدّم طلب انضمام يوافق عليه مسؤول (بالطلب)، أو يسجّل الدخول فحسب دون انضمام (بالدعوة فقط). وفي كل الأحوال يظهر في نقطة النهاية /members كأي شخص آخر — فيبقى تسجيل الدخول في موقعك وقائمة أعضائك في Ludoya متوافقَين تلقائيًا.
كيفية الإعداد
إنه OpenID Connect القياسي، فلا تحتاج معظم المنصات إلى أكثر من رابط المُصدِر (issuer) ومعرّف العميل وسرّه. سجّل تطبيقك من صفحة API العامة للحصول على تلك البيانات، واذكر عناوين إعادة التوجيه التي سيستخدمها موقعك — يمكنك تسجيل عدة عناوين، وعلى كل واحد أن يطابق redirect_uri الذي يرسله موقعك حرفًا بحرف، بما في ذلك الشرطة المائلة الأخيرة. والتطابق شبه التام هو السبب الأشيع لفشل أول محاولة تسجيل دخول.
- Discourse — ثبّت إضافة OpenID Connect، والصق رابط الاكتشاف، وأضف البيانات
- WordPress — أي إضافة OpenID Connect عامة، باستخدام خيار "auto discover" فيها
- أي شيء آخر — إن كان يتحدث OIDC فوجّهه إلى رابط المُصدِر وسيضبط نفسه
ويُعيد كل تسجيل دخول المعرّف الدائم للشخص واسم المستخدم والاسم المعروض والصورة الرمزية والبريد الإلكتروني. أما تعليمات الإعداد الكاملة، بما فيها التدفق اليدوي، فتوجد في دليل المطورين داخل التطبيق تحت Developers → Sign in with Ludoya.
لمن يسجّلون الدخول
كل من استخدم Ludoya لتسجيل الدخول في مكان ما يستطيع مراجعة تلك الاتصالات ضمن الإعدادات ← التطبيقات المتصلة، ورؤية متى رُبط كل منها ومتى استُخدم آخر مرة، وقطع أي منها في أي وقت. وقطع الاتصال ينهي وصول الموقع فورًا لكنه لا يزيله من مجموعتك.
GET /events
تُعيد الفعاليات القادمة والسابقة في قائمتين منفصلتين مقسمتين إلى صفحات.
| المعامل | النوع | الافتراضي | الوصف |
|---|---|---|---|
onlyFuture |
boolean | true |
اضبطها على false لإعادة الفعاليات السابقة أيضًا |
تتضمن كل فعالية: type (MEETUP أو PLANNED_PLAY)، وtitle، وdescription، وstartsAt، وendsAt، وtimeZone، وimageUrl، وcapacity، وparticipantCount، وcanceled، وteacher (كائن مستخدم أو null)، وmaster (كائن مستخدم أو null). وتحتوي كائنات المستخدم على id، وusername، وname، وavatarUrl.
POST /events
تُنشئ فعالية في المجموعة. الحقول المطلوبة: type وtitle. وإن أُغفل locationId فيُستخدم الموقع الافتراضي للمجموعة؛ وإن لم يوجد فتُعيد 400.
تشمل الحقول الاختيارية: description، وlocationId، وspotId، وgameId، وparentEventId (للفعاليات الفرعية)، وstartsAt، وendsAt، وrestrictedAttendance، وcapacity، وminParticipants، وestimatedDurationMinutes، وmaxReservationsPerUser، وtakeGamesPermission، وorganizePlaysPermission، وteacherUserId، وmasterUserId، وvisibility، وimage.
يقبل الحقل image إما {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. بحد أقصى 5 ميغابايت.
تُعيد {"id": "string"} بالحالة 201.
PUT /events/{eventId}
يحدّث فعالية قائمة. بنية الطلب نفسها المستخدمة في POST — أدرج الحقول التي تريد تغييرها فقط. يجب أن يكون المُرسِل هو منظم الفعالية (حساب المجموعة). يُعيد 202 مع جسم فارغ.
GET /events/{eventId}
يجلب حدثًا واحدًا حسب المعرّف، بالبنية نفسها المستخدمة في عناصر GET /events.
GET /events/{eventId}/children
يعرض الفعاليات الفرعية المتداخلة داخل فعالية رئيسية — المسارات أو الجلسات الفردية ضمن تجمّع أكبر. لكل فعالية فرعية البنية نفسها المستخدمة في الفعالية العادية.
إدارة المشاركين
تتيح لك ثلاث نقاط نهاية إدارة قائمة حضور فعالية من خارج Ludoya — وهو أمر مفيد إن كان التسجيل يجري على موقعك أنت، أو إن كنت تستورد قائمة بالفعل.
| الطريقة | المسار | ماذا تفعل |
|---|---|---|
POST |
`/events/ |
GET /members
يعيد قائمة أعضاء مقسّمة إلى صفحات.
| معامل | النوع | الافتراضي |
|---|---|---|
pagination.size |
int | 50 |
pagination.offset |
int | 0 |
يتضمن كل عضو: id, username, name, avatarUrl, role (OWNER, ADMIN, أو MEMBER).
POST /members/invite
يدعو شخصًا إلى مجموعتك. تقبل هذه النقطة username مباشرةً – دون الحاجة إلى البحث عن المعرّف – حتى تتمكن من إضافة الأعضاء مباشرةً من موقعك أو أداة الإدارة الخاصة بك.
GET /search/users and GET /search/boardgames
نقطتا البحث. فمعظم عمليات الكتابة تريد معرّفًا لا اسمًا، ومن هنا تحصل عليه.
GET /search/users
| المعامل | النوع | الافتراضي |
|---|---|---|
query |
string | مطلوب |
intent |
string | — |
pagination.size |
int | 20 |
pagination.offset |
int | 0 |
GET /search/boardgames
| المعامل | النوع | الافتراضي |
|---|---|---|
query |
string | مطلوب |
filter |
string | — |
pagination.size |
int | 50 |
pagination.offset |
int | 0 |
يأخذ مرشِّح ألعاب الطاولة الصيغة نفسها key=value المفصولة بفاصلة منقوطة التي يأخذها مرشِّح المجموعة، فيمكنك البحث في الفهرس بعدد اللاعبين أو وقت اللعب أو التعقيد أو السنة أو العمر أو الوسوم.
GET /collection
تُعيد مجموعة ألعابك مع التصفية والترتيب والتقسيم إلى صفحات.
| المعامل | النوع | الافتراضي | الوصف |
|---|---|---|---|
filter |
string | — | أزواج key=value مفصولة بفاصلة منقوطة. المفاتيح: ownership (OWNED، PREVIOUSLY_OWNED، PREORDERED، WISHLISTED)، وplayed (boolean)، وlistId، وnameFilter، وplayerCountFilterType (OFFICIAL، GOOD، BEST)، وplayerCountFilter (number) |
groupExpansions |
boolean | true |
اجمع التوسعات تحت لعبتها الأساسية |
sort |
string | — | الصيغة: property,direction — مثل name,asc |
pagination |
string | — | الصيغة: size,pageIndex — مثل 20,0 |
الاستجابة: totalGames، وtotalExpansions، وgames[] — ولكل منها: id، وslug، وname، وimageUrl، وisExpansion، وyearPublished، وminPlayerCount، وmaxPlayerCount.
GET /stats
تُعيد إحصاءات اللعب لنافذة زمنية قابلة للضبط.
| المعامل | النوع | الافتراضي | الوصف |
|---|---|---|---|
period |
string | ALL_TIME | الصيغة: PERIOD,date,index. القيم: ALL_TIME، وONE_YEAR، وONE_MONTH، وTHIRTY_DAYS، وSEVEN_DAYS، وONE_DAY، وCUSTOM. ويُزيح index النافذة إلى الوراء (0 = الحالية، 1 = السابقة). مخصص: CUSTOM,startDate,0,endDate |
تتضمن الاستجابة:
- ملخصًا — إجمالي الجلسات، وإجمالي/متوسط وقت اللعب، وأعداد الألعاب واللاعبين والمواقع الفريدة
- بحسب اللاعب — جلسات كل شخص وانتصاراته ومتوسط نتيجته وأفضلها
- بحسب عدد اللاعبين — توزيع ألعاب اللاعبَين والثلاثة والأربعة وهكذا
- بحسب الموقع — عدد الجلسات والألعاب الفريدة لكل مكان
- بحسب اللعبة — عدد الجلسات وإجمالي/متوسط وقت اللعب واللاعبون الفريدون لكل عنوان
GET /campaigns
تُعيد قائمة مقسمة إلى صفحات بالحملات التابعة للمجموعة.
| المعامل | النوع | الافتراضي | الوصف |
|---|---|---|---|
status |
string | — | التصفية حسب الحالة: ACTIVE أو COMPLETED أو ARCHIVED |
pagination.size |
int | 50 | عناصر لكل صفحة |
pagination.offset |
int | 0 | الإزاحة |
تتضمن كل حملة: id، وgame (id، name، imageUrl)، وname، وimage، وstatus، وvisibility، وcreatedAt، وupdatedAt، وmemberCount، وsessionCount.
GET /campaigns/{campaignId}
تُعيد التفاصيل الكاملة لحملة تابعة للمجموعة.
تتضمن الاستجابة: كل حقول القائمة، إضافة إلى template، وdescription، وglobalNotes، وglobalState، وmembers[] (ولكل منها user، وrole، وcharacterNotes، وcharacterState)، وsessions[]، وevents[].
POST /campaigns
تُنشئ حملة للمجموعة. الحقول المطلوبة: gameId وname. وإن أُغفل الظهور فالافتراضي هو أعضاء المجموعة وحدهم (ONLY_GROUP).
الحقول الاختيارية: templateId، وdescription، وvisibility (PUBLIC أو ONLY_GROUP أو ONLY_FRIENDS أو PRIVATE).
تُعيد {"id": "string"} بالحالة 201.
PUT /campaigns/{campaignId}
يحدّث حملة قائمة. جميع الحقول اختيارية — أدرج ما تريد تغييره فقط.
الحقول الاختيارية: name، description، status (ACTIVE، COMPLETED، ARCHIVED)، visibility.
يُعيد 202 مع جسم فارغ.
أعضاء الحملة
أدِر من في الحملة، بالطريقة نفسها التي تدير بها المشاركين في الفعالية.
| الطريقة | المسار | ماذا تفعل |
|---|---|---|
POST |
`/campaigns/ |
رموز الأخطاء
| الحالة | متى |
|---|---|
| 400 | فشل التحقق (حقل مطلوب مفقود، لم يُعثر على موقع، صورة غير صالحة) |
| 401 | مفتاح API مفقود أو غير صالح |
| 403 | الإجراء غير مسموح به أو المجموعة ليست على خطة Business |
| 404 | المورد غير موجود |
| 429 | تم تجاوز حد الطلبات |
البدء
1. إنشاء مفتاح API
- انتقل إلى صفحة ملف مؤسستك
- انقر على القائمة (⋮) ← API العامة
- انقر على إنشاء مفتاح
- انسخ مفتاحك فورًا — فهو يُعرض مرة واحدة فقط ولا يمكن استرجاعه مرة أخرى
المفتاح مرتبط بمؤسستك. احتفظ به سرًا: أي شخص يملك المفتاح يمكنه قراءة كل البيانات المذكورة أعلاه والكتابة إليها.
2. السحب أو إعادة الإنشاء
لسحب مفتاح قائم، عد إلى صفحة API العامة وانقر على سحب. أكّد مربع الحوار. وسيبدأ أي نظام يستخدم المفتاح القديم في تلقي أخطاء 401 على الفور. ولإصدار مفتاح جديد، انقر على إنشاء مفتاح مرة أخرى.
راجع أيضًا: