Optifora API necə işləyir
Bu səhifə API-nin qəlibini izah edir: kimliyin necə doğrulandığını, versiyaların necə irəlilədiyini, sorğunun hansı hədlər daxilində qaldığını, xətanın hansı formada qayıtdığını və məlumatın kənarla necə mübadilə olunduğunu.
Məhsul hazırlanma mərhələsindədir və API səthi tamamlanır. Son nöqtələrin istinad sənədi ayrıca dərc olunacaq; bu səhifədə ünvan və nümunə çağırış yer almır, yalnız iş prinsipi izah edilir.
Kimliyin doğrulanması
Hər sorğu ya bir şəxsə, ya da qeydə alınmış tətbiqə aiddir. Kimliyi olmayan sorğu qorunan son nöqtəyə çatdıqda təsdiqlənməmiş cavabı ilə geri qayıdır.
- Daşıyıcı tokenGiriş tokeni sorğunun avtorizasiya başlığında daşınır. Token imzalanmışdır və yalnız sorğunun kimə aid olduğunu bildirir.
- Qısa ömürGiriş tokeni dəqiqələrlə ölçülən müddətin sonunda etibarsız olur; müddət yerləşdirmə parametridir və standart dəyəri otuz dəqiqədir.
- Yeniləmə və dövretməSessiya yeniləmə tokeni ilə uzadılır və hər uzatmada yeni token cütü verilir. İstifadə olunmuş yeniləmə tokeni ikinci dəfə təqdim edilərsə, həmin şəxsin bütün sessiyaları ləğv edilir.
- Səlahiyyət tokenin içinə yazılmırToken yalnız kimliyi daşıyır; şəxsin nəyi görə biləcəyi hər sorğuda verilənlər bazasından soruşulur. Beləliklə, geri alınan səlahiyyət, əldəki tokenin müddəti bitməmiş də qüvvədən düşür.
- İnteqrator açarıQeydə alınmış tətbiq öz açarı ilə qoşulur. Açarın açıq dəyəri yalnız yaradıldığı anda göstərilir; saxlanılan isə onun heş dəyəri və açarı tanımağa yarayan gizli olmayan prefiksidir.
- İcazəni təşkilat verirTətbiq nə qədər geniş yayılmış olsa da, təşkilatın verdiyi icazə qeydi yoxdursa, bir sətir belə məlumat görmür. İcazə tarixlidir, əhatəsi müəyyəndir və geri alına bilər.
Versiyalaşdırma
- Versiya yolun içindədirSon nöqtələr versiya prefiksi ilə dərc olunur; bugünkü səth birinci versiyadır.
- Pozucu dəyişiklik yeni yol açırMövcud son nöqtənin müqaviləsi yerində pozulmur. Uyğunsuz dəyişiklik yeni versiya yolunda dərc olunur, köhnəsi işləməyə davam edir.
- Sənəd öz versiyasını bildirirİstinad sənədi yaradıldığı versiya nömrəsini öz içində daşıyır; hansı versiyaya baxdığınız sənədin özündən oxunur.
Mühitlər və hədlər
İstinad sənəddə iki mühit elan edilir: istehsal və yerli hazırlıq. Kök ünvan açarla birlikdə inteqratora verilir; bu səhifədə dərc olunmur.
- Canlılıq və hazırlıq ayrıca ölçülürBir son nöqtə prosesin ayaqda olduğunu bildirir; ikincisi verilənlər bazasına həqiqi sorğu göndərib əlçatan olduğunu təsdiqləyir. Trafikin yönləndirilib-yönləndirilməyəcəyinə ikincisi qərar verir.
- Brauzer mənbəyi siyahı ilə məhdudlaşırÇarpaz mənbəli sorğular yalnız əvvəlcədən elan edilmiş mənbələrdən qəbul edilir; siyahı boş olduqda brauzerdən gələn çarpaz sorğu rədd edilir.
- Gövdə həddiSorğunun gövdəsi beş meqabaytı keçə bilməz. Böyük dəstlər tək sorğu ilə deyil, öz vəziyyət qeydi olan toplu ötürmə işi ilə daşınır.
- Sirr jurnala yazılmırServer jurnalında avtorizasiya başlığı, kuki, parol və şəxsiyyət nömrəsi saxlanmır.
Sürət həddi
Hədd ünvan başına və dəqiqəlikdir. Standart dəyər dəqiqədə 120 sorğudur və yerləşdirmə parametri ilə dəyişdirilir. Qalan haqq hər cavabda başlıqlarla bildirilir.
| Cavab başlığı | Nə bildirir |
|---|---|
| x-ratelimit-limit | Pəncərə daxilində tanınan ümumi sorğu haqqı. |
| x-ratelimit-remaining | Bu pəncərədə qalan haqq. |
| x-ratelimit-reset | Haqqın yenilənməsinə qalan saniyə. |
| retry-after | Neçə saniyə sonra yenidən cəhd edilə bilər. Yalnız sorğunu rədd edən cavabda olur. |
Hədd aşıldıqda sorğu rədd edilir və cavab nə qədər gözləmək lazım olduğunu saniyə ilə bildirir. Təkrar cəhd dərhal deyil, həmin müddət bitdikdən sonra edilir.
Xəta formatı
Hər xəta eyni zərflə qayıdır: maşının şaxələnəcəyi qısa kod sahəsi və insanın oxuyacağı izahat sahəsi.
- errorMüştərinin qərar verəcəyi qısa kod.
- messageNə baş verdiyini izah edən mətn.
| Vəziyyət | Kod sahəsi | Nə deməkdir |
|---|---|---|
| 400 | Bad Request | Sorğu sxemə uyğun gəlmir. İzahat hansı sahənin əskik və ya etibarsız olduğunu bildirir. |
| 401 | unauthenticated | Etibarlı kimlik yoxdur: token ümumiyyətlə göndərilməyib, müddəti bitib və ya doğrulanmayıb. |
| 404 | Not Found | Belə bir son nöqtə və ya belə bir qeyd yoxdur. |
| 429 | Too Many Requests | Sürət həddi aşıldı; cavab nə qədər gözləmək lazım olduğunu bildirir. |
| 5xx | internal_error | Gözlənilməyən xəta. Təfərrüat müştəriyə verilmir, server jurnalına yazılır. |
Səhifələmə
Siyahı qaytaran son nöqtələr eyni iki parametri alır və eyni sayğacları qaytarır. Beləliklə səhifələyən müştəri hər son nöqtə üçün yenidən yazılmır.
- limitBir səhifədə neçə qeyd istənilir. Ən az bir, ən çox iki yüz; göstərilməzsə əlli.
- offsetNeçə qeydin keçiləcəyi. Sıfırdan başlayır.
- totalSüzgəclərə uyğun gələn ümumi qeyd sayı.
- countBu cavabda həqiqətən qayıdan qeydlərin sayı.
Cavab istifadə etdiyi limit və offset dəyərlərini də geri qaytarır; müştəri öz mövqeyini təxmin etmir, cavabdan oxuyur.
Məlumat mübadiləsi və webhook
Mübadilə rejimi bir parametrdir, ayrıca məhsul deyil: qeydə alınmış hər tətbiq hansı rejimlə işlədiyini öz qeydində daşıyır.
| Rejim | Nə deməkdir |
|---|---|
| Birtərəfli — çıxış | Optifora məlumat dərc edir; qarşı tərəf onu oxuyur və ya hadisəyə abunə olur. |
| Birtərəfli — giriş | Qarşı tərəf məlumat göndərir; Optifora onu yoxlayır və yazır. |
| İkitərəfli | Hər iki tərəf yazır; ziddiyyət qaydası əvvəlcədən müəyyən edilir. |
| Əlsıxma ilə | Hər ötürmə bir sessiya açır: təklif, doğrulama, təsdiq, transfer və qəbz. Qəbz hər iki tərəfdə qalır. |
- Hadisə kənara ötürülürWebhook hadisəni qeydə alınmış tətbiqin bildirdiyi geri çağırış ünvanına göndərir. Çatdırıla bilməyən hadisə növbədə qalır və yenidən cəhd edilir; səssizcə itmir.
- Eyni sorğu iki dəfə yazmırYazma sorğusu təkrarsızlıq açarı daşıyır. Eyni açarla gələn ikinci sorğu yeni qeyd yaratmır.
- Hər çağırış ölçülürKim, nə vaxt, hansı əhatə ilə və hansı nəticə ilə çağırdı — hamısı qeyd olunur. Eyni qeyd həm xətanın araşdırılmasının, həm də bu məlumatı kimin çəkdiyi sualının tək mənbəyidir.
- Öz tətbiqlərimiz də eyni qapıdan keçirİmtiyazlı ikinci yol açılmır. Öz inteqrasiyamız kənardan qoşulan tərtibatçının qarşılaşdığı səthin sübutudur.
Mübadilə qatının məlumat modeli quruldu; son nöqtələri hələ dərc olunmayıb. Dərc olunduqda bu bölmə istinad sənədindəki qarşılıqlarına bağlanacaq.
İstinad sənədləri
İstinad sənədi əllə yazılmır; son nöqtələrin sxemindən yaradılır. Bir son nöqtə öz sxemini təhvil verdikcə sənəddəki qarşılığı öz-özünə dolur, beləliklə sənəd ilə davranış bir-birindən ayrılmır.
- Bugünkü vəziyyət: hazırlanırSxemlər modul-modul köçürülür. Sənəd yayıma verilməzdən əvvəl hər son nöqtənin sorğusu və cavabı orada görünəcək.
- İki format dərc olunacaqMaşının oxuya bildiyi OpenAPI sənədi və eyni sənəddən çəkilən, brauzerdə gəzilə bilən istinad səhifəsi.
- Giriş pilləlidirÜmumi baxış hamıya açıqdır. Tam istinad sənədi qeydə alınmış inteqratora verilən sənəd açarının arxasında dura bilər; istehsal açarları və geri çağırış ünvanları isə sənəd mövzusu deyil, tətbiq qeydinin mövzusudur.
- Ünvan standartıİki istinad sənədi dərc olunur və ünvanları sabitdir: client-api.optifora.com/docs kənara açıqdır, admin-api.optifora.com/docs səlahiyyət tələb edir və kənara bağlıdır. Bu gün heç biri yayımda deyil; yayıma alındıqda keçidləri bu bölməyə əlavə ediləcək.
İnteqrasiya planınız bu gündən bəllidirsə, əlaqə səhifəsindən bizə yazın: səth yayıma açılanda ilk xəbər veriləcəklər arasında olacaqsınız.
Konkret müraciətiniz var?
Bu səhifələr dəstək prosesinin necə işlədiyini izah edir. Müraciətiniz və ya sualınız varsa əlaqə səhifəsindən bizə yazın.
Əlaqə səhifəsinə keçin