وێبهووکەکان و ڕووداوەکان

وەشانی API 2026-10-affable-towhee

Lingara ئەوەی بەسەر پلانەکانی وانە و بەکارهێنانی هەژمارەکەتدا دێت وەک ڕووداو تۆمار دەکات، و ڕووداوەکان لە یاری یان ئەپەکەتەوە وەردەگرێت. هەموو ڕووداوێک، بە هەر ڕێگەیەکدا بڕوات، هەمان بەرگی هەیە، و لیستی ڕووداوەکان هەموویان دەژمێرێت.

بەرگەکە

هەر ڕووداوێک شەش خانە هەڵدەگرێت. id بە lgr_evt_ دەست پێدەکات، بێهاوتایە، و ئەو کلیلەیە کە دووبارەبوونەوەکانی پێ لادەبرێن. type ناوی ڕووداوەکەیە. created_at کاتی ڕوودانییەتی. api_version ئەو وەشانەیە کە data لەسەری شێوە دەگرێت: ئەو وەشانەی کلاینتەکەت پێیەوە بەستراوە، یان لە فید و پەخشدا، ئەو وەشانەی داواکارییەکەت لە Lingara-Version دا ناوی بردووە. subject بە lgr_sub_ دەست پێدەکات و دەڵێت ڕووداوەکە دەربارەی کێیە: بۆ کلاینتەکەت جێگیرە بەڵام بۆ هەر کلاینتێک جیاوازە، و هەرگیز ئیمەیڵ یان ناو یان ناسنامەی هەژمار نییە. data بچووکە و ناوی سەرچاوەکان دەبات لە جیاتی کۆپیکردنیان: هەر سەرچاوەیەک بەو مەودایەی پێویستیەتی وەربگرە.

دوو جۆر هەریەکەیان ڕستەیەکیان پێویستە. lesson_plan.ready دەکرێت دوو جار بۆ یەک پلان بگات، یەکەم جار بە data.status ی partial و پاشان complete: بۆ پلانێکی بەکارهاتوو لەسەر یەکەمیان کار بکە، یان چاوەڕێی complete بکە بۆ ئەوەی هەموو کۆمەڵەکانت هەبێت. usage.threshold_reached تەنها بۆ هەژمار و کلاینتەکانی پارەدان بەپێی بەکارهێنان دەنێردرێت، و ئەگەر بەکارهێنان بە یەکجار لە چەند سنوورێک تێپەڕێت تەنها بەرزترین سنووری تێپەڕێنراو ڕاپۆرت دەکرێت، بۆیە چاوەڕێی ڕووداوێک بۆ هەر سنوورێک مەکە.

یەک تۆمار، سێ ڕێگە بۆ بیستنی

وێبهووکەکان بۆ سێرڤەرێک دەگونجێن کە خاڵێکی کۆتایی HTTPS ی گشتی هەیە. فید و پەخش بۆ پرۆگرامێک دەگونجێن کە هیچی نییە، وەک یارییەک لەسەر ئامێری یاریزانێک. بەرگەکە لە هەموو دەرگایەکدا وەک یەکە، بۆیە پرۆگرامێک دەتوانێت بە فید دەست پێبکات و دواتر بچێتە سەر وێبهووکەکان بەبێ گۆڕینی شێوازی خوێندنەوەی ڕووداوێک. ڕێڕەوەکانی ڕووداو وەڵامی پرۆگرامە ڕەسەنەکان (native) دەدەنەوە. یارییەک کە لە وێبگەڕێکدا کار دەکات هێشتا ناتوانێت بانگیان بکات، چونکە /v1/ وەڵامی هیچ داواکارییەکی پێشوەختی (preflight) نێوان-سەرچاوە ناداتەوە.

کێ ڕووداوێک دەبیستێت

کلاینتێک ڕووداوێک دەبیستێت کاتێک events:read و مەودای تایبەتی جۆری ڕووداوەکەی هەبێت، کە لیستەکە دەیژمێرێت، و کاتێک ڕووداوەکە دەربارەی خاوەنی کلاینتەکە بێت. لە فید و پەخشدا، مەوداکانی تۆکنی دەستگەیشتن ئەمە زیاتر تەسک دەکەنەوە، و types تەسکی دەکاتەوە بۆ ئەو جۆرانەی ناویان دەبەیت. webhook.test تەنها دەچێت بۆ ئەو خاڵی کۆتاییەی بۆی نێردراوە، هەرگیز بۆ فید نا، و ناتوانرێت بەشداری تێدا بکرێت. app.installed و app.uninstalled تەنها دەچن بۆ کلاینتی خودی ئەپەکە، هەرگیز بۆ کلاینتێکی تری هەمان هەژمار نا.

خاڵێکی کۆتایی تۆمار بکە

خاڵێکی کۆتایی لە پەڕەی وێبهووکەکان لە وێب ئەپی Lingara تۆمار بکە، لە app.getlingara.com/admin/webhooks، و یەکەم جار کلاینتەکە هەڵبژێرە. URL ـەکەی دەبێت https لەسەر دەرگای 443 بەکاربهێنێت، و هۆستەکەی دەبێت تەنها بۆ ناونیشانی گشتی شی بکرێتەوە. ڕووداوەکان بۆ ناردن هەڵبژێرە: تەنها ئەو جۆرانە پێشکەش دەکرێن کە مەوداکانی کلاینتەکە ڕێگەیان پێدەدەن. URL و ڕووداوەکان دواتر دەستکاری ناکرێن: خاڵێکی کۆتایی نوێ زیاد بکە و کۆنەکە بسڕەوە. نهێنیی واژوو بە lgr_whsec_ دەست پێدەکات و تەنها یەک جار پیشان دەدرێت.

گەیاندنێک پشتڕاست بکەرەوە

هەر گەیاندنێک POST ێکە بە سێ سەرپەڕە، بەپێی تایبەتمەندیی Standard Webhooks: webhook-id (id ی ڕووداوەکە)، webhook-timestamp و webhook-signature. کلیلی HMAC ئەو بەشەی نهێنییەکەیە کە دوای lgr_whsec_ دێت و لە base64 کراوەتەوە، هەرگیز نهێنییەکە خۆی وەک دەق نا. پێش شیکردنەوەی ناوەڕۆکەکە، لەسەر بایتە خاوەکانی پشتڕاستی بکەرەوە، وەک خوارەوە. گەیاندنێک ڕەت بکەرەوە کە مۆری کاتەکەی زیاتر لە پێنج خولەک لە ئێستاوە دوور بێت، کە بنەڕەتی کتێبخانەکانی Standard Webhooks ـە: ئەمە ڕێگە لە دووبارە لێدانەوەی گەیاندنێکی گیراو دەگرێت.

signed   = webhook-id + "." + webhook-timestamp + "." + raw request body
key      = base64_decode(the secret after its prefix)
expected = "v1," + base64(hmac_sha256(key, signed))
accept   if |now - webhook-timestamp| <= 5 minutes
         and some entry of webhook-signature (space-separated) equals expected
             (compare in constant time)

Standard Webhooks پشتڕاستکەرەوە بۆ زۆربەی زمانەکان بڵاو دەکاتەوە. چاوەڕێی نهێنییەک دەکەن کە وەک whsec_ و دوایدا base64، یان تەنها base64 نووسرابێت، بۆیە ئەو بەشەی نهێنیی Lingara یان بدەرێ کە دوای lgr_whsec_ دێت. کتێبخانەکانی خودی Lingara هەموو نهێنییەکە وەردەگرن.

خێرا وەڵام بدەرەوە، چاوەڕێی هەوڵدانەوە بکە

لە ماوەی 10 چرکەدا بە هەر 2xx ێک وەڵام بدەرەوە، و کارەکە دواتر بکە. هەر شتێکی تر، لەوانە تەواوبوونی کات یان 3xx (ئاڕاستەکردنەوەکان پەیڕەو ناکرێن)، بە بۆشایی گەورەتربوو بۆ نزیکەی یەک ڕۆژ هەوڵی دەدرێتەوە. 410 وەک وەڵامی گەیاندنێکی خۆکار یەکسەر خاڵی کۆتایی ناچالاک دەکات؛ 410 وەک وەڵامی تاقیکردنەوەیەک یان دووبارە گەیاندنەوەیەک وا ناکات. دوای پێنج ڕۆژ لە گەیاندنی سەرنەکەوتوو خاڵی کۆتاییەکە هەروەها ناچالاک دەکرێت. لە هەردوو حاڵەتدا ئیمەیڵ بۆ خاوەنەکەی دەنێردرێت. هەڵەیەک لە لای Lingara هەرگیز بۆ ناچالاککردنی خاڵێکی کۆتایی ناژمێردرێت. لە پەڕەی وێبهووکەکانەوە دەتوانیت تاقیکردنەوەیەک بنێریت، یان هەر گەیاندنێکی دوایین 30 ڕۆژ دووبارە بگەیەنیتەوە. هەریەکەیان یەک هەوڵە، هەرگیز دووبارە ناکرێتەوە، و تەنانەت بۆ خاڵێکی کۆتایی ناچالاکیش دەنێردرێت.

گەیاندن لانیکەم یەک جارە و بێ ڕیزبەندییە. هەمان ڕووداو دەکرێت دوو جار بگات، و هەوڵدانەوەیەک دەکرێت دوای ڕووداوێکی دواتر بگات. webhook-id لە هەموو هەوڵدانەوەیەکدا وەک خۆیەتی، و لە دووبارە گەیاندنەوەیەکیشدا تا 30 ڕۆژ دواتر. هەر id ێک کە مامەڵەت لەگەڵ کردووە بۆ 30 ڕۆژ تۆمار بکە، و دووبارەبووەکە پشتگوێ بخە. ئەگەر ڕیزبەندی گرنگە بەپێی created_at ڕیزیان بکە.

گۆڕینی نهێنیی واژوو

خاڵێکی کۆتایی دەتوانێت لە یەک کاتدا دوو نهێنیی واژووی هەبێت. تا هەردووکیان کارا بن، webhook-signature دوو تۆماری v1, هەڵدەگرێت، و وەرگرێک کە هەریەکێکیان قبووڵ بکات بەردەوام دەبێت لە کارکردن. نهێنییە نوێیەکە بۆ سێرڤەرەکەت زیاد بکە، دایبمەزرێنە، پاشان کۆنەکە هەڵبوەشێنەرەوە.

فیدەکە

GET /v1/events لەگەڵ تۆکنی دەستگەیشتنی کلاینتێک items (بەرگەکان)، next_cursor و has_more دەگەڕێنێتەوە. تۆکنەکە پێویستی بە events:read و مەودای هەر جۆرێکە کە دەتەوێت بیبیستیت: تەنها بە events:read، فیدەکە بەتاڵە. لە ئێستاوە دەست پێدەکات. start=oldest بنێرە بۆ ڕووداوەکانی نزیکەی دوایین 30 ڕۆژ. پێویستی بە خاڵێکی کۆتایی گشتی و نهێنیی واژوو نییە: تۆکنی دەستگەیشتن دەیسەلمێنێت کێ داوا دەکات. گۆڕینەوەکەی خوارەوە هەردوو ئەو مەودایانە داوا دەکات کە ڕووداوەکانی پلانی وانە پێویستیانە.

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=events:read lesson_plans:read" | jq -r '.access_token // error(.error)')"

curl "https://api.getlingara.com/v1/events" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

next_cursor هەمیشە هەیە: هەڵیبگرە و وەک cursor بینێرەوە. ناوەڕۆکەکەی نادیارە. has_more بە true واتە ئێستا دووبارە بانگ بکە، و false واتە گەیشتوویتە کۆتایی: دواتر دووبارە بپرسە، یان پەخشەکە بکەرەوە. نیشانەیەکی کۆنتر لە 30 ڕۆژ بە 410 و cursor_expired ڕەت دەکرێتەوە. بەبێ نیشانە فیدەکە لە ئێستاوە دەست پێدەکات، و ڕووداوەکانی نێوانیان دەپەڕێنرێن. بۆ گەڕاندنەوەیان، بە start=oldest بانگ بکە، کە تا ئەو جێیە دەگەڕێتەوە کە ڕووداوەکان تێدا هەڵدەگیرێن، و ئەو بەهایانەی id بپەڕێنە کە پێشتر مامەڵەت لەگەڵ کردوون.

پەخشەکە

GET /v1/events/stream هەمان ڕووداوەکان وەک ڕووداوی نێردراو لەلایەن سێرڤەرەوە (server-sent events) دەگوازێتەوە. data ی هەر چوارچێوەیەکی event یەک بەرگە، و id: ی هەر چوارچێوەیەک نیشانەیەکە، هەمان بەهای next_cursor، بۆیە دەتوانیت بەبێ بۆشایی لە نێوان فید و پەخشدا بگوازیتەوە. دوای پچڕانی پەیوەندی، چوارچێوەیەکی done (پەخشەکە جار جار خۆی کۆتایی پێدەهێنێت) یان چوارچێوەیەکی error، دووبارە پەیوەندی بکەرەوە بە دانانی Last-Event-ID بۆ دوایین id: کە وەرتگرتووە. زۆربەی کلاینتەکانی SSE ئەمە بۆت دەکەن، هەروەها tailEvents لە کتێبخانەکانی Lingara (streamEvents لەوێ یەک پەیوەندییە). ئەمە نیشانەیە، نەک id ی ڕووداوەکە. پەخشەکە لێدانی دڵ (heartbeat) دەنێرێت، بۆیە پەیوەندییەکی بێدەنگ پەیوەندییەکی مردووە.

curl -N "https://api.getlingara.com/v1/events/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

ڕووداوێک بۆ Lingara بنێرە

POST /v1/events لەگەڵ events:write ڕووداوێک وەک {type, data} بۆ Lingara دەنێرێت: world.context_changed (scene، source_lang، target_lang، level، و بە ئارەزوو npc ێک بە name و persona، و tags) یان world.practice_requested (topic و هەمان زمانەکان و ئاست). Idempotency-Key پێویستە: تا 255 پیتی بینراوی ASCII، وەک UUID. بەبێ ئەو وەڵامەکە 400 و idempotency_key_required ـە. بۆ هەر ڕووداوێک یەک جار دایبنێ، و لە هەوڵدانەوەدا هەمان کلیل بنێرە. یەک کلیل یەک ڕووداوە: لە ماوەی یەک ڕۆژدا، داواکارییەکی دووەم بە هەمان کلیل یەکەم وەڵام وەردەگرێت (یەکسان وەک JSON، نەک بایت بە بایت)، تەنانەت ئەگەر ناوەڕۆکەکەی جیاواز بێت، و دوای ئەوە هەمان ڕووداو وەردەگرێت، وەک خوارەوە. ڕووداوە هاتووەکان واژوو ناکرێن: تۆکنی دەستگەیشتنەکەت بەڵگەکەیە. جیهانەکە وەسف بکە، هەرگیز یاریزانەکە نا: هیچ ناو یان چاتێک لە scene، npc، topic یان tags دا نەبێت.

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=events:write lesson_plans:write" | jq -r '.access_token // error(.error)')"

curl -X POST "https://api.getlingara.com/v1/events" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"world.context_changed","data":{"scene":"A night market in Taipei, just after rain","npc":{"name":"Auntie Lin","persona":"a street-food vendor who likes to haggle"},"source_lang":"en","target_lang":"zh","level":3,"tags":["market","food","chapter-2"],"generate":true}}'

هەر خانەیەکی دەق یەک دێڕە لە پیتی بینراو، دوای لابردنی بۆشاییەکانی دوو سەر دەژمێردرێت: scene و topic تا 160، npc.name تا 32، و npc.persona تا 120. دابڕینی دێڕ، تاب و پیتە کۆنترۆڵییەکانی تر ڕەت دەکرێنەوە، هەروەها پیتە نەبینراو و ڕێکخەرەکان: پیتەکانی تێپەڕاندنی ئاراستە، پیتە بێپانەکان جگە لەو پێکەوەلکێنەرانەی هەندێک نووسین و ئیمۆجی پێویستیانە، بلۆکی تاگەکان (tag block) و پیتەکانی بەکارهێنانی تایبەت. tags تا 8 نیشانەی ئامێری بە پیتی بچووک هەڵدەگرێت، هەریەکەیان تا 24 پیت، و هەرگیز ناگاتە پلانی وانە. level لە 1 تا 9 ـە، و دوو زمانەکە دەبێت جیاواز بن. داواکارییەک لە دەرەوەی ئەم سنوورانە بە 400 ڕەت دەکرێتەوە و هیچ ڕووداوێک تۆمار ناکات.

لەگەڵ "generate": true (بنەڕەت بۆ world.practice_requested)، تۆکنەکە پێویستی بە lesson_plans:write یش هەیە. بەبێ ئەو داواکارییەکە بە 403 ڕەت دەکرێتەوە و هیچ ڕووداوێک تۆمار ناکرێت. لەگەڵیدا، Lingara پلانێکی وانە دەست پێدەکات، بە هەمان پشکنین و هەمان پارەدان وەک دروستکردنی ڕاستەوخۆی، و reaction لە وەڵامی 202 دا دەڵێت چی ڕوویدا. لەگەڵ started و plan_status ی generating، lesson_plan.ready یان lesson_plan.failed ێک کە data.plan_id ـەکەی هەمان plan_id ی وەڵامەکەیە بەدوایدا دێت، لە هەموو ئەو دەرگایانەی بەکاریان دەهێنیت. لەگەڵ partial یان complete، پلانەکە لە کتێبخانەکەوە هاتووە و ئێستا دەخوێنرێتەوە، و هیچ ڕووداوێک بەڵێن نادرێت: ڕەنگە هێشتا یەکێک بگات، بۆیە تەنها generating شایەنی چاوەڕوانییە. لەگەڵ refused یان failed، ڕووداوەکە هەر دەمێنێت. بە هەمان کلیل هەوڵ نادرێتەوە، بۆیە بۆ هەوڵدانەوە ڕووداوێکی نوێ بنێرە.

هەوڵدانەوەیەک لە ماوەی یەک ڕۆژدا یەکەم وەڵام وەردەگرێتەوە. هەوڵدانەوەیەک دوای ئەوە لە ڕووداوە هەڵگیراوەکەوە دووبارە دروست دەکرێتەوە، کە ئەو پلانەی دەستی پێکردووە دەیپارێزێت بەڵام هۆی ڕەتکرانەوەی کاردانەوەیەک نا. بۆیە هەوڵدانەوەیەکی دواکەوتوو دەکرێت بە reaction ی failed و internal وەڵام بداتەوە: واتە ئەنجامی یەکەم تۆمار نەکراوە، نەک ئەوەی هیچ پلانێک نییە. ئەگەر plan_id ـت هەڵگرتووە پلانەکە پێی بخوێنەوە، یان ڕووداوێکی نوێ بنێرە.

Tidewater Games: یارییەک بەبێ سێرڤەر

Tidewater Games، ستۆدیۆیەکی خەیاڵی، یارییەکی Godot دروست دەکات کە تێیدا یاریزان بازاڕێکی شەوانە دەگەڕێت. گەشەپێدەرەکەی یارییەکە لەسەر ئامێری خۆی، بە کلاینتی خۆی، کار پێدەکات.

یاریزانەکە دەچێتە ناو کۆشکێکی نودڵ. یارییەکە world.context_changed لەگەڵ "generate": true دەنێرێت، هەمان فەرمانی بەشی ڕووداوە هاتووەکانی سەرەوە، و plan_id لە وەڵامەکەوە هەڵدەگرێت.

ئەگەر plan_status بریتی بێت لە generating، یارییەکە پەخشەکە دەخوێنێتەوە، یان فیدەکە دووبارە دەپشکنێت، تا lesson_plan.ready ێک بەو plan_id ـە دەگات. پاشان پلانەکە بە lesson_plans:read دەخوێنێتەوە، وەک خوارەوە. ئەگەر پلانەکە پێشتر complete بوو، یەکسەر دەیخوێنێتەوە.

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=lesson_plans:read" | jq -r '.access_token // error(.error)')"

curl "https://api.getlingara.com/v1/lesson-plans/$ID" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

دواتر ستۆدیۆکە سێرڤەرێکی بچووک بە خاڵێکی کۆتایی HTTPS زیاد دەکات و بۆ lesson_plan.ready تۆماری دەکات. هەمان ڕووداو، بە هەمان id، دەگاتە ئەوێ، و کۆدی یارییەکە بۆ خوێندنەوەی ناگۆڕێت.

نهێنیی کلاینت هەرگیز نابێت لەناو بنیاتی یارییەکدا بڵاو بکرێتەوە، چونکە هەر شتێک لەسەر ئامێری یاریزانێک بێت دەتوانرێت بخوێنرێتەوە. تا Lingara پشتگیریی چوونەژوورەوە لە جیاتی یاریزانێک نەکات، یارییەک لەسەر ئامێری یاریزانەکان قسە لەگەڵ سێرڤەری خۆی دەکات، و تەنها کۆپییەکەی خودی گەشەپێدەر ڕاستەوخۆ قسە لەگەڵ Lingara دەکات.

ڕووداوەکان چەند دەکەن

بەکارهێنانی کلاینتەکەت هەر ڕووداوێکی هاتووی قبووڵکراو، هەر بانگکردنێکی فید و هەر پەخشێکی کراوە دەژمێرێت، هەروەک چۆن هەموو بانگکردنێکی /v1/ دەژمێرێت. ڕووداوێک کە لەگەڵ "generate": true نێردرابێت وەک پلانێکی وانەش دەژمێردرێت. هەر گەیاندنێکی وێبهووک بۆ هەر ڕووداوێک و هەر خاڵێکی کۆتایی یەک جار دەژمێردرێت، لە یەکەم 2xx دا، هەر هەوڵێک بێت. هەرگیز دووبارە ناژمێردرێتەوە، و تاقیکردنەوە هەرگیز ناژمێردرێت. GET /v1/usage مانگەکە تا ئێستا پیشان دەدات.

ئەگەر وەرگێڕانێک و سەرچاوە ئینگلیزییەکە جیاواز بن، سەرچاوە ئینگلیزییەکە دروستە.