مرجع واجهة Lingara البرمجية

إصدار API 2026-10-affable-towhee

أنشئ قوائم مفردات وخطط دروس، وأجرِ محادثات مع المعلّم، باللغات التي تعلّمها Lingara. يدفع ثمن كل استدعاء العميلُ الذي يجريه: عميل allowance يستهلك من حصة مالكه، وعميل metered تُحتسب عليه فاتورة استخدامه.

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

عنوان URL الأساسي https://api.getlingara.com

رمز وصول OAuth 2.0 يُرسَل بالشكل Authorization: Bearer <token>. الخادم الذي يعمل باسمه هو يستبدل معرّف عميله وسرّه عند عنوان URL الخاص بالرمز (client_credentials). أما التطبيق الذي يعمل نيابةً عن مستخدم Lingara وافق على ذلك فيستخدم رمز التفويض (authorization_code) ثم يجدّد الرمز. يدوم الرمز ساعة واحدة. تحتاج كل عملية إلى نطاق واحد.

عنوان URL للرمز https://api.getlingara.com/oauth/token

النطاقات
`vocab:generate`	إنشاء قوائم المفردات.	إنشاء قائمة مفردات
`lesson_plans:read`	قراءة خطط دروسك وإعادة الاتصال بتقدّمها.	الحصول على خطة درس إعادة الاتصال بخطة درس
`lesson_plans:write`	إنشاء خطط الدروس.	إنشاء خطة درس
`tutor:converse`	إجراء محادثات مع المعلّم. يتطلب خطة مدفوعة.	إرسال دور إلى المعلّم
`usage:read`	معرفة حصتك المتبقية، أو استخدام عميل `metered` هذا الشهر.	الحصول على حصتك المتبقية
`events:read`	قراءة الأحداث المتعلقة بحسابك، وتسجيل نقاط النهاية التي تستقبلها.	عرض الأحداث بث الأحداث
`events:write`	إرسال الأحداث من لعبتك أو تكاملك إلى Lingara.	إرسال حدث

الأخطاء

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مطلوب

المفردات

إنشاء قوائم مفردات بمستوى المتعلّم.

إنشاء قائمة مفردات POST /v1/vocab/stream

خطط الدروس

إنشاء خطط الدروس وقراءتها وإعادة الاتصال بخطة لا يزال إنشاؤها جاريًا.

إنشاء خطة درس POST /v1/lesson-plans
الحصول على خطة درس GET /v1/lesson-plans/{id}
إعادة الاتصال بخطة درس GET /v1/lesson-plans/{id}/stream

المعلّم

إجراء محادثة مع معلّم اللغة، دورًا تلو الآخر.

إرسال دور إلى المعلّم POST /v1/tutor/message

الأحداث

اقرأ الأحداث التي تقع في حسابك، صفحة بصفحة أو كتدفق.

عرض الأحداث GET /v1/events
إرسال حدث POST /v1/events
بث الأحداث GET /v1/events/stream

الحساب

اعرف كم تبقّى من حصتك.

الحصول على حصتك المتبقية GET /v1/usage

المرجع

هذا المستند بصيغة قابلة للقراءة آليًا.

الحصول على هذا المستند GET /v1/openapi.json
الحصول على مستند الأحداث GET /v1/asyncapi.json
عرض إصدارات الواجهة البرمجية GET /v1/versions
الحصول على إصدار من الواجهة البرمجية GET /v1/versions/{id}

كتالوج الأحداث

تسجّل Lingara ما يطرأ على خطط الدروس واستخدام حسابك في صورة أحداث، وتستقبل الأحداث من لعبتك أو تطبيقك. لكل حدث، أيًّا كان الطريق الذي يسلكه، الغلاف نفسه، ويسرد كتالوج الأحداث جميعها. خطافات الويب والأحداث

Lingara ← أنت lesson_plan.ready
Lingara ← أنت lesson_plan.failed
Lingara ← أنت usage.threshold_reached
Lingara ← أنت webhook.test
Lingara ← أنت app.installed
Lingara ← أنت app.uninstalled

أنت ← Lingara world.context_changed
أنت ← Lingara world.practice_requested

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