پشتڕاستکردنەوەی ناسنامە

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

هەر بانگکردنێکی Lingara API تۆکنێکی دەستگەیشتن هەڵدەگرێت. سێرڤەرێک تۆکنی دەستگەیشتن وەردەگرێت بە گۆڕینەوەی ناسنامە و نهێنیی کلاینتێکی OAuth لە خاڵی کۆتایی تۆکن: ئەمە بەخشینی client credentials ـی OAuth 2.0 ـە، بۆ سێرڤەرێک کە لە جیاتی خۆی کار دەکات. کلاینتەکان لە پەڕەی یەکخستنەکان لە وێب ئەپی Lingara دروست بکە، لە app.getlingara.com/admin.

دانیشتن یان کلاینت

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

سێ بەها

ناسنامەی کلاینت بە lgr_cid_ دەست پێدەکات و کلاینتەکە لە خاڵی کۆتایی تۆکن دەناسێنێت. نهێنی نییە.

نهێنیی کلاینت بە lgr_cs_ دەست پێدەکات و تەنها بۆ خاڵی کۆتایی تۆکن دەنێردرێت. تەنها یەک جار پیشان دەدرێت، کاتێک دروستی دەکەیت: هەر ئەو کاتە کۆپی بکە، چونکە Lingara تەنها هاشەکەی هەڵدەگرێت.

تۆکنی دەستگەیشتن بە lgr_at_ دەست پێدەکات و یەک کاتژمێر دەمێنێت. دەچێتە ناو سەرپەڕەی Authorization: Bearer ـی بانگکردنەکانی ژێر /v1/، و هیچ شوێنێکی تر نا. تاکە بەهایە کە شوێنی لەو سەرپەڕەیەدایە: نهێنیی کلاینتێک کە لەوێ بنێردرێت بە 401 ڕەتدەکرێتەوە.

تۆکنێکی دەستگەیشتن وەربگرە

فۆرمێک بە POST بنێرە بۆ خاڵی کۆتایی تۆکن لەگەڵ grant_type=client_credentials. ناسنامە و نهێنیی کلاینت یان بە پشتڕاستکردنەوەی HTTP Basic بنێرە یان وەک خانەکانی فۆرمی client_id و client_secret، هەرگیز هەردووکیان پێکەوە نا. scope لیستێکی بە بۆشایی جیاکراوەی ئەو مەودایانەیە کە بە کلاینتەکە ڕێگە دراون؛ ئەگەر نەینووسیت، هەموو ئەو مەودایانە وەردەگریت کە بە کلاینتەکە ڕێگە دراون. فەرمانی خوارەوە تەنها داوای usage:read دەکات، ئەو مەودایەی کە نموونەی GET /v1/usage لە خوارترەوە پێویستی پێیەتی.

curl -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read"

وەڵامەکە access_token، token_type (Bearer)، expires_in (3600، بە چرکە) و scope لەخۆ دەگرێت، واتە ئەو مەودایانەی کە تۆکنەکە بە ڕاستی هەیەتی. گۆڕینەوەیەکی سەرنەکەوتوو بە شێوەی هەڵەی OAuth وەڵام دەداتەوە، {error, error_description}، نەک پێچراوەی {code, error} ـی /v1/. نهێنییەکی هەڵە یان هەڵوەشێنراو، یان کلاینتێکی سڕاوە، بە 401 و invalid_client ڕەتدەکرێتەوە. مەودایەک کە کلاینتەکە بۆی نییە داوای بکات هەموو گۆڕینەوەکە بە 400 و invalid_scope ڕەتدەکاتەوە؛ هەرگیز بە بێدەنگی بەرتەسک ناکرێتەوە.

لە جیاتی بەکارهێنەرێکی تری Lingara کار بکە

ئەپێک کە لە جیاتی بەکارهێنەرێکی تری Lingara کار دەکات بەخشینی کۆدی ڕێپێدان بەکاردەهێنێت. وێبگەڕی بەکارهێنەرەکە بنێرە بۆ URLی ڕێپێدان لەگەڵ response_type=code، client_id، redirect_uriـێک کە ڕێک وەک یەکێک لەوانە بێت کە تۆمارت کردوون، scope، state و code_challengeـێکی S256. بەکارهێنەرەکە پەڕەی ڕەزامەندیی Lingara دەبینێت و لەگەڵ code، state و iss دەگەڕێتەوە بۆ redirect_uriـەکەت. پێش ئەوەی کۆدەکە بەکاربهێنیت، دڵنیابەرەوە کە state هەمان ئەوەیە کە ناردت و iss بریتییە لە https://api.getlingara.com.

PKCE پێویستە

هەموو کلاینتێک PKCE بەکاردەهێنێت، تەنها بە ڕێگای S256. code_verifierـێکی هەڕەمەکی دروست بکە، هاشی SHA-256ـەکەی، بە base64url کۆدکراو، وەک code_challenge لەگەڵ code_challenge_method=S256 بنێرە، و خودی ئەو کۆدە بۆ گۆڕینەوەکە هەڵبگرە. داواکارییەک بێ ڕێگا، یان بە plain، بە invalid_request ڕەتدەکرێتەوە.

کۆدەکە بگۆڕەوە

لە ماوەی 60 چرکەدا، بە POST بنێرە بۆ خاڵی کۆتایی تۆکن لەگەڵ grant_type=authorization_code، code، هەمان redirect_uri و code_verifier، و وەک کلاینتەکە پشتڕاستکردنەوە بکە؛ کلاینتێکی گشتی تەنها client_id دەنێرێت. وەڵامەکە refresh_tokenـێکیش زیاد دەکات، کە بە lgr_rt_ دەست پێدەکات. کۆدەکە بە lgr_ac_ دەست پێدەکات و تەنها یەک جار کار دەکات: بەکارهێنانی دووەم بە invalid_grant ڕەتدەکرێتەوە و کۆتایی بەو تۆکنانە دەهێنێت کە گۆڕینەوەی یەکەم دەریکردوون.

نوێکردنەوە

کاتێک تۆکنی دەستگەیشتن بەسەردەچێت، بە POST بنێرە بۆ خاڵی کۆتایی تۆکن لەگەڵ grant_type=refresh_token و refresh_token، و دووبارە وەک کلاینتەکە پشتڕاستکردنەوە بکە. هەر نوێکردنەوەیەک تۆکنێکی نوێکردنەوەی نوێ دەگەڕێنێتەوە: تەنها نوێترینیان هەڵبگرە. نوێکردنەوەکانت یەک لە دوای یەک ئەنجام بدە: تۆکنێکی نوێکردنەوەی کۆن کە زیاتر لە 60 چرکە دوای جێگرتنەوەی بەکاربهێنرێت وەک دزراو هەژمار دەکرێت، و بە invalid_grant کۆتایی بە تۆکنەکانی ئەو دامەزراندنە دەهێنێت. تۆکنێکی نوێکردنەوە کە 30 ڕۆژ بەکارنەهێنرێت بەسەردەچێت. خاڵی کۆتایی تۆکن داواکارییەکان بۆ هەر ناونیشانێک سنووردار دەکات، بۆیە تەنها کاتێک نوێی بکەرەوە کە تۆکنێک تەواو دەبێت.

ئەپە ڕەسەنەکان کلاینتی گشتین

ئەپێکی دێسکتۆپ، مۆبایل یان هێڵی فەرمان ناتوانێت نهێنییەک بپارێزێت، بۆیە کلاینتێکی گشتییە: هیچ نهێنییەکی نییە، تەنها client_id دەنێرێت بۆ خاڵی کۆتایی تۆکن، و ئاراستەکردنەوەیەکی ناوخۆیی (loopback) وەک http://127.0.0.1/callback (هەر پۆرتێک) یان سکیمێکی تایبەت وەک com.example.app:/callback تۆمار دەکات. بەکارهێنەرەکە هەموو جارێک پەڕەی ڕەزامەندی دەبینێت. پەڕەیەکی وێب ناتوانێت کلاینت بێت: نە خاڵی کۆتایی تۆکن و نە /v1/ وەڵامی داواکارییەکی preflight ی نێوان-سەرچاوە نادەنەوە.

کاتێک بەکارهێنەر ئەپەکەت لادەبات

بەکارهێنەر دەتوانێت لە هەر کاتێکدا ئەپەکەت لە «ئەپە پەیوەستکراوەکان» لاببات، یان ئەگەر دایمەزراندبێت بە سڕینەوەی، و بانگکردنی داهاتووی بە 401 سەرناکەوێت. کاتێک بەکارهێنەر لە ئەپەکەت دەچێتە دەرەوە، تۆکنی نوێکردنەوەکەی لە خاڵی کۆتایی هەڵوەشاندنەوە هەڵبوەشێنەوە، کە کۆتایی بە تۆکنەکانی ئەو دامەزراندنە دەهێنێت.

کاتێک تۆکنەکە بەسەردەچێت

دوای کاتژمێرێک، /v1/ بە 401 لەگەڵ کۆدی unauthorized و هەڵەیەک کە بە invalid_token دەست پێدەکات وەڵام دەداتەوە. کاتێک بانگکردنێک 401 وەردەگرێت، یان کەمێک پێش ئەوەی expires_in تەواو ببێت، دووبارە بیگۆڕەوە و یەک جار بانگکردنەکە دووبارە بکەرەوە. ئەگەر خودی گۆڕینەوەکە بە invalid_client یان invalid_scope سەرنەکەوت، کلاینتەکە سڕاوەتەوە، نهێنییەکەی هەڵوەشێنراوەتەوە یان مەوداکانی بەرتەسک کراونەتەوە: بوەستە و لە پەڕەی یەکخستنەکان چاکی بکە، چونکە هەوڵدانەوە ناتوانێت سەرکەوتوو بێت. تۆکنەکە لە نێوان بانگکردنەکاندا هەڵبگرە: خاڵی کۆتایی تۆکن ژمارەی گۆڕینەوەکان بۆ هەر کلاینتێک و هەر ناونیشانێک سنووردار دەکات، و بەرنامەیەک کە لە هەر بانگکردنێکدا دەیگۆڕێتەوە لە ماوەی کاتژمێرەکەدا بە 429 و rate_limited ڕەتدەکرێتەوە (چاوەڕێی Retry-After بکە). ئەم بەخشینە تۆکنی نوێکردنەوەی نییە: نهێنییەکە دووبارە دەگۆڕدرێتەوە.

تۆکنەکانی دەستگەیشتن تەنها دەگەنە ڕێڕەوەکانی API

تۆکنی دەستگەیشتن تەنها لەسەر ڕێڕەوەکانی ژێر /v1/ کار دەکات. ئەگەر بۆ هەر ڕێڕەوێکی تری Lingara بنێردرێت بە 401 ڕەتدەکرێتەوە، و ناوەڕۆکەکە بە api_token_not_accepted دەست پێدەکات، وەک دەقی سادە یان لەناو خانەی error، هەرگیز لەناو پێچراوەی {code, error} کە ڕێڕەوەکانی /v1/ بەکاری دەهێنن. تۆکنی دەستگەیشتنەکە لە سەرپەڕەی Authorization بنێرە، وەک خوارەوە.

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

مەوداکانی دەسەڵات

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

کێ پارەی بانگکردنێک دەدات

کلاینت بە یەکێک لە دوو ڕێگا پارەی لێ وەردەگیرێت، کە لە کاتی دروستکردنیدا هەڵدەبژێردرێت. کلاینتێکی allowance بڕی ڕێپێدراوی خاوەنەکەی خەرج دەکات، هەمان ئەو بڕە ڕێپێدراوەی ئەپەکانت، و تۆکنەکانی دەستگەیشتنیشی هەمان بڕ خەرج دەکەن؛ GET /v1/usage پیشان دەدات چی ماوە. کلاینتێکی metered هیچ بڕی ڕێپێدراو خەرج ناکات: بۆ هەر کرێدیتێک پارەی لێ وەردەگیرێت لە ڕێگەی بەشداربوونێکی پارەدانی بەپێی بەکارهێنانەوە کە لە پەڕەی یەکخستنەکان ڕێکی دەخەیت. بانگکردنەکانی بە 402 و spend_cap_reached ڕەت دەکرێنەوە کاتێک کلاینتەکە یان هەژمارەکەت دەگاتە سنووری خەرجیی مانگانە، و بە 402 و metered_billing_inactive تا ئەو کاتەی پارەدانی بەپێی بەکارهێنان چالاک نییە. پلانێکی وانە 10 کرێدیتە، نۆرەیەکی مامۆستا 1 کرێدیت و دروستکردنی وشەکان 3 کرێدیت، بۆیە ئەو unitsـەی GET /v1/usage ڕاپۆرتی دەکات بەم کێشانە دەگۆڕدرێن بۆ کرێدیت. بانگکردنێک کە ئەپێک لە جیاتی بەکارهێنەرێکی تر دەیکات، بە تۆکنێک کە لە کۆدی ڕێپێدانەوە هاتووە، هەمیشە بڕی ڕێپێدراوی ئەو بەکارهێنەرە خەرج دەکات، شێوازی کلاینتەکە هەرچییەک بێت.

نهێنی و تۆکنەکان لەسەر سێرڤەر هەڵبگرە

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

بەڕێوەبردنی کلاینتەکان

لە پەڕەی یەکخستنەکان، لە app.getlingara.com/admin، کلاینتەکان دروست بکە، ناویان بگۆڕە و بیانسڕەوە، ئەوە بگۆڕە کە هەر یەکێکیان دەتوانێت چی بکات و بە کام وەشانەوە بەستراوە، و نهێنییەکانی دروست بکە و هەڵیانبوەشێنەوە. سڕینەوەی کلاینتێک یەکسەر هەموو تۆکنێکی دەستگەیشتن کە هەیەتی ڕادەگرێت، و کۆتایی بە ڕێپێدانی هەموو بەکارهێنەرێک بۆی دەهێنێت. هەڵوەشاندنەوەی نهێنییەک یەکسەر هەموو ئەو تۆکنانەی دەستگەیشتن ڕادەگرێت کە ئەو نهێنییە بۆیان گۆڕدراوەتەوە. بەرتەسککردنەوەی مەوداکانی کلاینتێکیش یەکسەر جێبەجێ دەبێت؛ فراوانکردنیان، یان گۆڕینی وەشانەکەی، لە گۆڕینەوەی داهاتووەوە جێبەجێ دەبێت.

گۆڕینی نهێنییەک

کلاینتێک دەتوانێت لە یەک کاتدا دوو نهێنیی هەبێت. بۆ گۆڕین، نهێنییەکی نوێ دروست بکە، دایبمەزرێنە، و کۆنەکە هەڵبوەشێنەوە کاتێک بەرواری «دوایین بەکارهێنان» ـی لە پەڕەی یەکخستنەکان چیتر ناگۆڕێت. پرۆسەیەک کە نهێنییە نوێیەکەی هەیە بەڵام هێشتا تۆکنێکی نهێنییە کۆنەکەی پێیە یەک جار 401 وەردەگرێت و دووبارە دەیگۆڕێتەوە. تاکە نهێنیی کلاینتێک ناتوانرێت هەڵبوەشێنرێتەوە: سەرەتا جێگرەوەکەی دروست بکە، یان کلاینتەکە بسڕەوە.

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