Lingara Lingara Belge Rêbername API Pirtûkxane Sepan Avakirin Sepana webê
Ziman: Kurdî

Ewropa

Asya

Rojhilata Navîn

Afrîka

Webhook û bûyer

Guhertoya API 2026-10-affable-towhee

Lingara tiştên ku bi planên dersê û bikaranîna hesabê te re diqewimin wek bûyer tomar dike, û bûyeran ji lîstik an sepana te qebûl dike. Her bûyer, bi kîjan rêyê biçe bila biçe, heman zerfê digire, û kataloga bûyeran hemûyan rêz dike.

Zerf

Her bûyer şeş qadan digire. id bi lgr_evt_ dest pê dike, yekta ye, û mifteya rakirina dubareyan e. type navê bûyerê dide. created_at dema ku ew qewimî ye. api_version ew guherto ye ku data li gorî wê hatiye şêwekirin: guhertoya ku klientê te pê ve girêdayî ye, an jî, li ser feed û stream, guhertoya ku daxwaza te di Lingara-Version de navê wê daye. subject bi lgr_sub_ dest pê dike û dibêje bûyer derbarê kê de ye: ew ji bo klientê te sabît e lê ji bo her klientî cuda ye, û tu carî ne e-name, nav an nasnameya hesabekî ye. data biçûk e û li şûna ku çavkaniyan kopî bike navê wan dide: çavkaniyekê bi wê scopeya ku hewce dike bîne.

Du cure her yek hevokekê hewce dikin. lesson_plan.ready dikare ji bo planekê du caran bigihîje, pêşî bi data.status partial û paşê complete: ji bo planeke bikêr li gorî ya yekem tevbigere, an li benda complete bimîne da ku her set hebe. usage.threshold_reached tenê ji bo hesab û klientên ku li gorî bikaranînê tên fatûrekirin tê şandin, û bazdaneke ku ji çend sînoran derbas dibe tenê sînorê herî bilind ê derbasbûyî radigihîne, ji ber vê yekê ji bo her sînorî bûyerekê hêvî neke.

Qeydek, sê rêyên bihîstina wê

Webhook ji serverekê re guncav in ku xaleke dawî ya HTTPS a giştî heye. Feed û stream ji bernameyeke re guncav in ku tune ye, wek lîstikeke li ser makîneya lîstikvanekî. Zerf li ser her rêyê heman e, ji ber vê yekê bername dikare bi feedê dest pê bike û paşê derbasî webhookan bibe bêyî ku awayê xwendina bûyerekê biguherîne. Rêyên bûyeran bersiva bernameyên xwecihî didin. Lîstikeke ku di gerokê de dixebite hîn nikare wan bang bike, ji ber ku /v1/ bersiva tu preflighteke cross-origin nade.

Kî bûyerekê dibihîze

Klientek bûyerekê dibihîze dema ku events:read û scopeya cureya bûyerê bi xwe, ku kataloga bûyeran rêz dike, digire, û dema ku bûyer derbarê xwediyê klient de be. Li ser feed û stream, scopeyên tokena gihîştinê vê hê bêtir teng dikin, û types wê bi wan cureyan ve sînordar dike ku tu navê wan didî. webhook.test tenê diçe wê xala dawî ya ku jê re hatiye şandin, tu carî naçe feedê, û abonetî lê nayê kirin. app.installed û app.uninstalled tenê diçin klientê sepanê bi xwe, tu carî naçin klientekî din ê heman hesabî.

Xaleke dawî tomar bike

Li rûpela Webhook a sepana webê ya Lingara, li app.getlingara.com/admin/webhooks, xaleke dawî tomar bike, û pêşî klientê hilbijêre. Divê URL-ya wê https li ser porta 443 bikar bîne, û divê hosta wê tenê li navnîşanên giştî çareser bibe. Bûyerên ku bêne şandin hilbijêre: tenê ew cure tên pêşkêşkirin ku scopeyên klient destûr didin. URL û bûyer paşê nayên guhertin: xaleke dawî ya nû lê zêde bike û ya kevn jê bibe. Nepeniya îmzeyê bi lgr_whsec_ dest pê dike û tenê carekê tê nîşandan.

Radestkirinekê piştrast bike

Her radestkirin POSTek e bi sê sernivîsan, li gorî taybetmendiya Standard Webhooks: webhook-id (id a bûyerê), webhook-timestamp û webhook-signature. Mifteya HMAC beşa nepeniyê ya piştî lgr_whsec_ e, ji base64 vekirî, tu carî ne nepenî wek rêzenivîs. Berî ku naverokê şîrove bikî, li ser baytên wê yên xav piştrast bike, wek li jêr. Radestkirineke ku mohra wê ya demê ji niha zêdetirî pênc deqeyan dûr e red bike, ku ev pêşdanasîna pirtûkxaneyên Standard Webhooks e: bi vî awayî radestkirineke ku hatiye girtin nikare dîsa were lîstin.

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 ji bo piraniya zimanan piştrastkeran diweşîne. Ew li benda nepeniyeke ne ku wek whsec_ û paşê base64, an wek base64 a tazî hatiye nivîsandin, ji ber vê yekê beşa nepeniya Lingara ya piştî lgr_whsec_ bide wan. Pirtûkxaneyên Lingara bi xwe tevahiya nepeniyê qebûl dikin.

Zû bersiv bide, li benda dubarekirinan be

Di nav 10 çirkeyan de bi her 2xx bersiv bide, û karê paşê bike. Her tiştekî din, di nav de derbasbûna demê an 3xx (beralîkirin nayên şopandin), bi navberên ku mezin dibin nêzî rojekê dîsa tê ceribandin. 410 wek bersiva radestkirineke otomatîk xala dawî yekser neçalak dike; 410 wek bersiva ceribandinekê an radestkirineke dîsa wiha nake. Piştî pênc rojên radestkirinên bi ser neketî xala dawî jî tê neçalakkirin. Di herdu rewşan de, e-name ji xwediyê wê re tê şandin. Xeletiyeke li aliyê Lingara tu carî ji bo neçalakkirina xaleke dawî nayê hesibandin. Ji rûpela Webhook tu dikarî ceribandinê bişînî, an her radestkirineke 30 rojên dawî dîsa radest bikî. Her yek hewldanek e, tu carî nayê dubarekirin, û heta ji xaleke dawî ya neçalak re jî tê şandin.

Radestkirin herî kêm carekê û bê rêz e. Heman bûyer dikare du caran bigihîje, û dubarekirinek dikare piştî bûyereke paşîn bigihîje. webhook-id li ser her dubarekirinê heman e, û li ser radestkirineke dîsa heta 30 rojan paşê jî. Her id a ku te pêvajo kiriye ji bo 30 rojan tomar bike, û dubareyê paşguh bike. Ger rêz girîng be, li gorî created_at rêz bike.

Nepeniya îmzeyê nû bike

Xaleke dawî dikare di heman demê de du nepeniyên îmzeyê bigire. Heta ku herdu çalak bin, webhook-signature du têketinên v1, digire, û wergirekî ku yek ji wan qebûl dike dixebite. Nepeniya nû li servera xwe zêde bike, bi cih bike, paşê ya kevn betal bike.

Feed a bûyeran

GET /v1/events bi tokena gihîştinê ya klientekî items (zerf), next_cursor û has_more vedigerîne. Token hewceyî events:read û scopeya her cureya ku tu dixwazî bibihîzî ye: tenê bi events:read, feed vala ye. Ew ji niha dest pê dike. Ji bo bûyerên nêzî 30 rojên dawî start=oldest bişîne. Ew ne hewceyî xaleke dawî ya giştî ye û ne jî nepeniyeke îmzeyê: tokena gihîştinê îspat dike ka kî dipirse. Guhertina li jêr herdu scopeyên ku bûyerên plana dersê hewce dikin dixwaze.

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 her tim heye: wê tomar bike û wek cursor paşve bişîne. Naveroka wê ne ji bo xwendinê ye. has_more true tê wateya niha dîsa bang bike, û false tê wateya ku tu gihîştî dawiyê: paşê dîsa bipirse, an stream veke. Kursoreke ji 30 rojan kevntir bi 410 û cursor_expired tê redkirin. Bê kursor feed ji niha dest pê dike, û bûyerên di navberê de tên derbaskirin. Ji bo vegerandina wan, bi start=oldest bang bike, ku heta wê demê paşve diçe ku bûyer tên hilanîn, û nirxên id ên ku te berê pêvajo kirine derbas bike.

Stream a bûyeran

GET /v1/events/stream heman bûyeran wek server-sent events dibe. data ya her çarçoveyeke event zerfek e, û id: ya her çarçoveyê kursorek e, heman nirxa next_cursor, ji ber vê yekê tu dikarî bêyî valahiyê di navbera feed û stream de derbas bibî. Piştî girêdaneke qutbûyî, çarçoveyeke done (stream carinan xwe bi xwe diqedîne) an çarçoveyeke error, bi Last-Event-ID ku li ser id: a dawî ya ku te wergirtiye hatiye danîn dîsa girê bide. Piraniya klientên SSE vê ji bo te dikin, û tailEvents di pirtûkxaneyên Lingara de jî (streamEvents li wir girêdaneke tenê ye). Ew kursorek e, ne id a bûyerê. Stream nîşaneyeke jiyanê (heartbeat) dişîne, ji ber vê yekê girêdaneke bêdeng girêdaneke mirî ye.

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

Bûyerekê ji Lingara re bişîne

POST /v1/events bi events:write bûyerekê wek {type, data} ji Lingara re dişîne: world.context_changed (scene, source_lang, target_lang, level, û bi bijarte npc bi name û persona, û tags) an world.practice_requested (topic û heman ziman û ast). Idempotency-Key pêwîst e: heta 255 tîpên ASCII yên xuya, wek UUID. Bêyî wê bersiv 400 û idempotency_key_required e. Ji bo her bûyerê carekê wê saz bike, û di dubarekirinê de heman mifteyê bişîne. Mifteyek bûyerek e: di nav rojekê de, daxwazeke duyem bi heman mifteyê bersiva yekem distîne (wek JSON wekhev, ne bayt bi bayt), heta ku naveroka wê cuda be jî, û piştî wê heman bûyerê distîne, wek li jêr. Bûyerên hatinê nayên îmzekirin: tokena te ya gihîştinê îspat e. Dinyayê rave bike, tu carî lîstikvan na: di scene, npc, topic an tags de tu nav an sohbet tune.

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}}'

Her qada nivîsê rêzeke tîpên xuya ye, ku piştî jêkirina valahiyên dor tê hejmartin: scene û topic heta 160, npc.name heta 32, û npc.persona heta 120. Rêzbirîn, tab û tîpên din ên kontrolê tên redkirin, û tîpên nexuya û şêwekirinê jî: guhertinên rêgezê, tîpên bê-firehî ji bilî wan girêdekên ku hin nivîsar û emoji hewce dikin, bloka etîketan û tîpên bikaranîna taybet. tags heta 8 tokenên makîneyê yên bi tîpên biçûk digire, her yek heta 24 tîpan, û tu carî nagihîje plana dersê. level ji 1 heta 9 e, û divê herdu ziman cuda bin. Daxwazeke derveyî van sînoran bi 400 tê redkirin û tu bûyerê tomar nake.

Bi "generate": true (pêşdanasîna world.practice_requested), token hewceyî lesson_plans:write jî ye. Bêyî wê daxwaz bi 403 tê redkirin û tu bûyer nayê tomarkirin. Bi wê re, Lingara planeke dersê dest pê dike, bi heman kontrol û heman fatûreyê wek çêkirina rasterast, û reaction a bersiva 202 dibêje çi qewimî. Bi started û plan_status generating, lesson_plan.ready an lesson_plan.failed ku data.plan_id a wê plan_id a bersivê ye tê, li ser her rêya ku tu bikar tînî. Bi partial an complete, plan ji pirtûkxaneyê hatiye û niha dikare were xwendin, û tu bûyer nayê soz dayîn: dibe ku yek dîsa jî bigihîje, ji ber vê yekê tenê generating hêjayî li benda mayînê ye. Bi refused an failed, bûyer dîsa jî dimîne. Ew bi heman mifteyê nayê dubarekirin, ji ber vê yekê ji bo ceribandina dîsa bûyereke nû bişîne.

Dubarekirinek di nav rojekê de bersiva yekem paşve distîne. Dubarekirinek piştî wê ji bûyera tomarkirî ji nû ve tê avakirin, ku plana ku dest pê kiriye diparêze lê ne sedema ku reaksiyonek hatiye redkirin. Ji ber vê yekê dubarekirineke dereng dikare bi reaction failed û internal bersiv bide: ev tê wateya ku encama yekem nehatiye tomarkirin, ne ku tu plan tune ye. Heke te plan_id a planê hilgirtibe planê pê bixwîne, an bûyereke nû bişîne.

Tidewater Games: lîstikeke bê server

Tidewater Games, studyoyeke xeyalî, lîstikeke Godot çêdike ku tê de lîstikvan bazareke şevê vedikole. Pêşdebirê wê lîstikê li ser makîneya xwe, bi klientê xwe dixebitîne.

Lîstikvan dikeve dikaneke şehriyeyê. Lîstik world.context_changed bi "generate": true dişîne, fermana di beşa bûyerên hatinê ya li jor de, û plan_id ji bersivê digire.

Ger plan_status generating be, lîstik stream dixwîne, an feedê dipirse, heta ku lesson_plan.ready bi wê plan_id bigihîje. Paşê planê bi lesson_plans:read dixwîne, wek li jêr. Ger plan jixwe complete bû, wê yekser dixwîne.

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"

Paşê studyo serverekî biçûk bi xaleke dawî ya HTTPS lê zêde dike û wê ji bo lesson_plan.ready tomar dike. Heman bûyer digihîje wir, bi heman id, û koda lîstikê ya ku wê dixwîne naguhere.

Divê nepeniya klient tu carî di nav pakêta lîstikê de neyê belavkirin, ji ber ku her tiştê li ser amûra lîstikvanekî dikare were xwendin. Heta ku Lingara têketinê li şûna lîstikvanekî piştgirî neke, lîstikeke li ser makîneyên lîstikvanan bi servera xwe re diaxive, û tenê kopiya pêşdebir bi xwe rasterast bi Lingara re diaxive.

Bûyer çiqas biha ne

Bikaranîna klientê te her bûyereke hatinê ya qebûlkirî, her banga feedê û her streameke vekirî dihejmêre, wek ku her banga /v1/ dihejmêre. Bûyereke ku bi "generate": true tê şandin wek planeke dersê jî tê hejmartin. Her radestkirina webhookê ji bo her bûyerê û her xala dawî carekê tê hejmartin, di 2xx a wê ya yekem de, kîjan hewldan be bila bibe. Ew tu carî dîsa nayê hejmartin, û ceribandin tu carî nayê hejmartin. GET /v1/usage meha heta niha nîşan dide.

Ger wergerek û referansa Îngilîzî ji hev cuda bin, referansa Îngilîzî rast e.