ربط لاعب بحسابه على Lingara

إصدار API 2026-10-virile-dragon

put https://api.getlingara.com/v1/embed/players/{player_ref}/link

يربط أحد لاعبيك بحساب Lingara الذي منح تطبيقك الوصول للتو. استدعِه بالرمز المفوَّض الذي تلقاه خادمك لذلك الحساب، وليس أبدًا برمز عميلك نفسه. من ذلك الحين تعمل رموز اللاعب باسم الحساب، في حدود ما يسمح به التفويض: اطلب events:read وإلا فلن تعرف شيئًا عن اللاعب بعد الربط. تنتقل الخطط المكتملة إلى الحساب، وتبقى الخطة التي ما زالت تُكتب حتى تستدعيه مجددًا. التكرار آمن: يُجيب التكرار بـ existing وينقل ما لم يكن ممكنًا نقله من قبل. الربط لا يكلّفك شيئًا.

النطاقات embed:play

المعاملات

Lingara-Versionheaderstringاختياري: إصدار API الذي يُجاب عن هذا الطلب به. بدونه، يحصل رمز الوصول على الإصدار الذي رُبط به عميله، ويحصل الطلب الذي لا رمز مميز فيه على الإصدار الحالي. لا يمكن الوصول إلى الإصدار الذي لا يزال قيد التطوير إلا بذكره هنا. الإصدار غير المعروف يُجاب عنه بـ 400 مع الرمز api_version_unknown. يسرد GET /v1/versions الإصدارات.
player_refpathstringمطلوب: قيمة player_ref التي أصدرت بها رموز اللاعب، مرمّزةً بالنسبة المئوية: guild/42 تصبح guild%2F42.

الاستجابات

200 ربط اللاعب

statusLinkStatusمطلوب
subjectstringمطلوب: قيمة lgr_sub_ الخاصة بالحساب: ما تحمله أحداث هذا اللاعب من الآن فصاعدًا.
previous_subjectstringمطلوب: قيمة lgr_sub_ الخاصة بالضيف: ما تحتفظ به أحداث اللاعب السابقة. وجّه كلتيهما إلى player_ref نفسه.
linked_atstringمطلوب: وقت إنشاء الربط. في إجابة existing، وقت الاستدعاء الأول.
scopesarray of stringمطلوب: أقصى ما يمكن أن يحمله رمز هذا اللاعب الآن: ما منحه الحساب، من بين النطاقات التي يمكن أن يحملها رمز اللاعب.
carriedobjectمطلوب: الصفوف التي نقلها هذا الاستدعاء إلى الحساب، لكل جدول. تظهر فقط الجداول التي لها عدد.
keptobjectمطلوب: الصفوف التي تركها هذا الاستدعاء مع الضيف، لكل جدول: خطة ما زالت تُكتب، أو صف كان لدى الحساب من قبل. استدعِه مجددًا بمجرد أن يكون في lesson_plans هنا خطة اكتملت.

الأخطاء

402application/json: رُفض استدعاء عميل يُفوتَر بحسب الاستهلاك قبل أن يُنفق أي شيء. spend_cap_reached: بلغ العميل أو حسابه حدّ الإنفاق الشهري؛ ارفع الحد في صفحة عمليات التكامل. metered_billing_inactive: الفوترة بحسب الاستهلاك غير مفعّلة لهذا الحساب؛ فعّلها أو حدّث طريقة الدفع في صفحة عمليات التكامل.
410application/json: تم إيقاف إصدار API الذي يُجاب عن هذا الطلب به. أرسل إصدارًا مدعومًا في Lingara-Version، أو اربط العميل بإصدار آخر.
4XXapplication/json: رُفض الطلب. يوضّح code السبب، ويشرحه error بالكلمات.
503application/json · text/plain: الخدمة غير متاحة مؤقتًا؛ أعد المحاولة بعد عدد الثواني المذكور في Retry-After. أثناء الصيانة يكون المتن نصًا عاديًا بدلًا من غلاف الخطأ.
5XXapplication/json: رُفض الطلب. يوضّح code السبب، ويشرحه error بالكلمات.

codestringمطلوب: سبب رفض الطلب، في صورة رمز ثابت يمكن التفرّع بناءً عليه: مثل insufficient_scope (403) وrate_limited (429)، ولعميل يُفوتَر بحسب الاستهلاك spend_cap_reached (402) وmetered_billing_inactive (402).
errorstringمطلوب

مثال

curl -X PUT "https://api.getlingara.com/v1/embed/players/$PLAYER_REF/link" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

تفضّل مكتبة؟ راجع قسم المكتبات.

إذا اختلفت ترجمةٌ عن المرجع الإنجليزي، فالمرجع الإنجليزي هو الصحيح.