Rastandin

Guhertoya API 2026-10-affable-towhee

Her bangeke ji API ya Lingara re tokeneke gihîştinê bi xwe re dibe. Server wê bi guhertina nasname û nepeniya klientekî OAuth li endpointa tokenê distîne: ev grant-a client credentials a OAuth 2.0 ye, ji bo serverekê ku ji bo xwe tevdigere. Klientan li rûpela Entegrasyon a sepana webê ya Lingara çêke, li app.getlingara.com/admin.

Danişînek an klientek

Sepanên Lingara te bi danişînekê têxin hundir, ku hemû scopeyan digire û mafê bikaranînê yê plana te xerc dike. Klient tengtir e: dema ku tu wî çêdikî, tu hildibijêrî ka kîjan scope jê re destûrdayî ne, û her tokena gihîştinê ya ku ew distîne tenê wan scopeyan digire ku ew dixwaze.

Sê nirx

Nasnameya klient bi lgr_cid_ dest pê dike û li endpointa tokenê navê klient dide. Ew ne nepenî ye.

Nepeniya klient bi lgr_cs_ dest pê dike û tenê ji endpointa tokenê re tê şandin. Ew tenê carekê tê nîşandan, dema ku tu wê çêdikî: wê demê kopî bike, ji ber ku Lingara tenê hasheke wê tomar dike.

Tokena gihîştinê bi lgr_at_ dest pê dike û saetekê dom dike. Ew dikeve sernivîsa Authorization: Bearer ya bangên di bin /v1/ de, û ne cihekî din. Ew nirxa tenê ye ku di wê sernivîsê de cih digire: nepeniyeke klient a ku li wir were şandin bi 401 tê redkirin.

Tokeneke gihîştinê bistîne

Formekê bi grant_type=client_credentials bi POST ji endpointa tokenê re bişîne. Nasname û nepeniya klient an bi rastandina HTTP Basic an wek qadên formê client_id û client_secret bişîne, tu carî herduyan bi hev re na. scope lîsteyeke scopeyan e ku bi valahiyan ji hev hatine veqetandin û ji klient re destûrdayî ne; wê nenivîse da ku her scopeya ku ji klient re destûrdayî ye bistînî. Fermana li jêr tenê usage:read dixwaze, ew scopeya ku mînaka GET /v1/usage ya li jêrtir hewce dike.

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"

Bersiv access_token, token_type (Bearer), expires_in (3600, bi çirkeyan) û scope dihewîne, ango ew scopeyên ku token bi rastî digire. Guhertineke têkçûyî bi şêweya çewtiyê ya OAuth, {error, error_description}, bersiv dide, ne bi zerfa {code, error} a /v1/. Nepeniyeke şaş an betalkirî, an klientekî jêbirî, bi 401 û invalid_client tê redkirin. Scopeyeke ku klient nikare bixwaze tevahiya guhertinê bi 400 û invalid_scope red dike; ew tu carî bi bêdengî nayê tengkirin.

Ji bo bikarhênerekî din ê Lingara tevbigere

Sepaneke ku ji bo bikarhênerekî din ê Lingara tevdigere grant-a koda destûrê bi kar tîne. Geroka bikarhêner bi response_type=code, client_id, redirect_uri-yeke ku tam bi yek ji yên ku te tomar kirine re li hev tê, scope, state û code_challenge-eke S256 re bişîne URL-ya destûrê. Bikarhêner rûpela razîbûnê ya Lingara dibîne û bi code, state û iss re vedigere redirect_uri-ya te. Berî ku kodê bi kar bînî, kontrol bike ku state ew e ku te şandiye û iss https://api.getlingara.com e.

PKCE mecbûrî ye

Her klient PKCE bi kar tîne, tenê bi rêbaza S256. code_verifier-eke rasthatî çêke, hasha wê ya SHA-256, bi base64url kodkirî, wek code_challenge bi code_challenge_method=S256 re bişîne, û wê bi xwe ji bo guhertinê bihêle. Daxwazeke bê rêbaz, an bi plain, bi invalid_request tê redkirin.

Kodê biguherîne

Di nav 60 çirkeyan de, bi POST ji endpointa tokenê re grant_type=authorization_code, code, heman redirect_uri û code_verifier bişîne, û wek klient rastandinê bike; klienteke giştî tenê client_id dişîne. Bersiv refresh_token-ekê jî zêde dike, ku bi lgr_rt_ dest pê dike. Kod bi lgr_ac_ dest pê dike û tenê carekê dixebite: bikaranîna duyemîn bi invalid_grant tê redkirin û dawî li tokenên ku guhertina yekem derxistine tîne.

Nûkirin

Dema ku tokena gihîştinê diqede, bi POST ji endpointa tokenê re grant_type=refresh_token û refresh_token bişîne, û dîsa wek klient rastandinê bike. Her nûkirin tokeneke nûkirinê ya nû vedigerîne: tenê ya herî nû bihêle. Nûkirinên xwe yek li dû yekê bike: tokeneke nûkirinê ya kevn ku zêdetirî 60 çirkeyan piştî ku hate guhertin tê bikaranîn wek dizî tê hesibandin, û bi invalid_grant dawî li tokenên wê sazkirinê tîne. Tokeneke nûkirinê ku 30 rojan neyê bikaranîn diqede. Endpointa tokenê daxwazan ji bo her navnîşanê sînordar dike, ji ber vê yekê tenê dema ku tokenek diqede nû bike.

Sepanên xwecihî klientên giştî ne

Sepaneke sermasê, mobîl an rêza fermanê nikare nepeniyekê biparêze, ji ber vê yekê ew klienteke giştî ye: nepeniya wê tune, tenê client_id ji endpointa tokenê re dişîne, û beralîkirineke herêmî (loopback) wek http://127.0.0.1/callback (her port) an şemayeke taybet wek com.example.app:/callback tomar dike. Bikarhêner her carê rûpela razîbûnê dibîne. Rûpeleke webê nikare bibe klient: ne endpointa tokenê û ne jî /v1/ bersiva preflighteke cross-origin didin.

Dema ku bikarhêner sepana te radike

Bikarhêner dikare her dem sepana te di Sepanên girêdayî de rake, an jî, ger wî ew saz kiribe, bi rakirina sazkirinê, û banga wê ya din bi 401 têk diçe. Dema ku bikarhêner ji sepana te derdikeve, tokena wê ya nûkirinê li endpointa betalkirinê betal bike, ku dawî li tokenên wê sazkirinê tîne.

Dema ku token diqede

Piştî saetekê, /v1/ bi koda unauthorized û çewtiyeke ku bi invalid_token dest pê dike 401 bersiv dide. Dema ku bangek 401 distîne, an hinekî berî ku expires_in biqede, dîsa biguherîne û bangê carekê dubare bike. Ger guhertin bi xwe bi invalid_client an invalid_scope têk biçe, klient an nepeniya wî hatiye jêbirin, betalkirin an tengkirin: raweste û li rûpela Entegrasyon wê çareser bike, ji ber ku dubarekirin nikare biserkeve. Tokenê di navbera bangan de bihêle: endpointa tokenê guhertinan ji bo her klient û her navnîşanê sînordar dike, û bernameyeke ku di her bangê de diguherîne di nav saetê de bi 429 û rate_limited tê redkirin (li benda Retry-After bimîne). Di vê grant-ê de tokena nûkirinê tune: nepenî dîsa tê guhertin.

Tokenên gihîştinê tenê digihîjin rêyên API

Tokena gihîştinê tenê li ser rêyên di bin /v1/ de dixebite. Ger ji rêyeke din a Lingara re were şandin, bi 401 tê redkirin, û naverok bi api_token_not_accepted dest pê dike, wek nivîsa sade an di nav qadeke error de, tu carî ne di zerfa {code, error} de ku rêyên /v1/ bikar tînin. Tokena gihîştinê di sernivîsa Authorization de bişîne, wek li jêr.

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

Scope

Her operasyon tam yek scope hewce dike, ku navê wê li ser rûpela wê hatiye dayîn. Tokeneke gihîştinê ya bê wê scopeyê bi 403 û koda insufficient_scope tê redkirin. Ji bo bangkirina operasyonê, di dema guhertinê de scopeya wê bixwaze, heke ji klient re destûrdayî be. Tabloya li jêr her scopeyê û operasyonên ku ew destûr dide rêz dike.

Kî heqê bangekê dide

Klient bi yek ji du awayan tê fatûrekirin, ku dema çêkirinê tê hilbijartin. Klienteke allowance mafê bikaranînê yê xwediyê xwe xerc dike, heman mafê bikaranînê yê sepanên te, û tokenên wê yên gihîştinê jî wî xerc dikin; GET /v1/usage nîşan dide ka çi maye. Klienteke metered tu mafê bikaranînê xerc nake: ew ji bo her krediyekê bi rêya abonetiyeke fatûrekirina li gorî bikaranînê tê fatûrekirin, ku tu li rûpela Entegrasyon saz dikî. Bangên wê bi 402 û spend_cap_reached tên redkirin gava ku klient an hesabê te bigihîje sînorê xercê yê mehane, û bi 402 û metered_billing_inactive heta ku fatûrekirina li gorî bikaranînê ne çalak be. Planeke dersê 10 kredî ye, gereke bi mamoste re 1 kredî û çêkirineke peyvan 3 kredî, ji ber vê yekê ew units ku GET /v1/usage radigihîne bi van giraniyan tên veguhertin bo kredî. Bangeke ku sepanek ji bo bikarhênerekî din, bi tokeneke ji koda destûrê, dike her tim mafê bikaranînê yê wî bikarhênerî xerc dike, moda klient çi dibe bila bibe.

Nepenî û tokenan li ser serverekê bihêle

Nepeniya klient divê li ser serverekê be ku tu kontrol dikî, tu carî ne di rûpeleke webê, pêvekeke gerokê an pakêteke sepanê de, ku her kes dikare wê bixwîne. Sepaneke xwecihî klienteke giştî ye û tu nepeniyê nagire. Ne /v1/ û ne jî endpointa tokenê bersiva preflighteke cross-origin didin, ji ber vê yekê gerokeke li ser malpereke din jixwe nikare wan bang bike.

Rêvebirina klientan

Li rûpela Entegrasyon, li app.getlingara.com/admin, klientan çêke, navê wan biguherîne û wan jê bibe, biguherîne ka her yek dikare çi bike û bi kîjan guhertoyê ve girêdayî ye, û nepeniyên wî çêke û betal bike. Jêbirina klientekî her tokena gihîştinê ya ku ew digire yekser radiwestîne, û dawî li destûra ku her bikarhênerekî dayê tîne. Betalkirina nepeniyekê her tokena gihîştinê ya ku bi wê nepeniyê hatiye guhertin yekser radiwestîne. Tengkirina scopeyên klientekî jî yekser derbas dibe; firehkirina wan, an guhertina guhertoya wî, ji guhertina din pê ve derbas dibe.

Nepeniyekê nû bike

Klientek dikare di heman demê de du nepeniyan bigire. Ji bo nûkirinê, nepeniyeke nû çêke, wê bi cih bike, û ya kevn betal bike dema ku dîroka wê ya Bikaranîna dawî li rûpela Entegrasyon êdî naguhere. Pêvajoyeke ku nepeniya nû jixwe heye lê hê tokeneke ji ya kevn digire carekê 401 distîne û dîsa diguherîne. Nepeniya tenê ya klientekî nayê betalkirin: pêşî nepeniya ku dê cihê wê bigire çêke, an klientê jê bibe.

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