البدء السريع

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

خمس خطوات من لا شيء إلى قائمة مفردات مبثوثة: أنشئ عميلًا، وضعه في الصدفة (shell)، واستبدله برمز وصول، ونفّذ استدعاءً واحدًا، واحصل على رمز جديد حين تنتهي صلاحيته.

1. أنشئ عميلًا

في صفحة عمليات التكامل في تطبيق Lingara على الويب، على العنوان app.getlingara.com/admin، ضمن عملاء OAuth، أنشئ عميلًا يستطيع «توليد المفردات» (النطاق vocab:generate). انسخ معرّف العميل وسرّه. لا يُعرض السرّ إلا مرة واحدة.

2. ضعه في الصدفة

خزّن معرّف العميل وسرّه في متغيري البيئة LINGARA_CLIENT_ID وLINGARA_CLIENT_SECRET، فلا يُكتب أي سرّ داخل أمر أبدًا.

export LINGARA_CLIENT_ID="<your client id>"
export LINGARA_CLIENT_SECRET="<your client secret>"

3. احصل على رمز وصول

يستبدل هذا الأمر العميل برمز وصول ويحفظه في LINGARA_TOKEN، الذي يقرؤه كل مثال في هذا المرجع. يحتاج إلى jq وإلى curl 7.76 أو أحدث. إذا فشل الاستبدال، يطبع الأمر رمز الخطأ (مثل invalid_client: تحقّق من المعرّف والسرّ) ويترك LINGARA_TOKEN فارغًا، فيفشل الاستدعاء التالي بالحالة 401 إلى أن ينجح استبدال. ومن دون jq، نفّذ الاستبدال الوارد في دليل المصادقة وانسخ access_token من الرد يدويًا.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=vocab:generate" | jq -r '.access_token // error(.error)')"

4. أنشئ قائمة مفردات

شغّل هذا الأمر. يوقف -N التخزين المؤقت في curl، فيُطبع كل حدث فور وصوله.

curl -N -X POST "https://api.getlingara.com/v1/vocab/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level":2,"source_lang":"en","target_lang":"zh","count":8}'

ما الذي ينبغي أن تراه

حدث started مع تفاصيل القائمة، وحدث item واحد لكل كلمة، ثم done. ستختلف كلماتك عن هذا المثال.

event: started
data: {"meta":{"level":2,"source_lang":"en","target_lang":"zh","framework":"HSK","count":2,"ai_generated":true}}

event: item
data: {"word":"你好","pronunciation":"nǐ hǎo","translation":"hello","example":{"sentence":"你好，我叫小明。","translation":"Hello, my name is Xiaoming."}}

event: item
data: {"word":"谢谢","pronunciation":"xiè xie","translation":"thank you"}

event: done
data: {}

5. عندما تنتهي الساعة

يجيب الاستدعاء بالحالة 401. نفّذ الخطوة 3 مجددًا. وإذا فشلت الخطوة 3 الآن، فقد تغيّر العميل أو سرّه في صفحة عمليات التكامل. أما البرنامج فيتبع قاعدة دليل المصادقة: استبدل من جديد مرة واحدة لكل 401، وتوقّف إذا فشل الاستبدال.

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