Kütləvi sifariş buraxılışından əvvəl API vasitəsilə balansın yoxlanılması

Növbənin buraxılışından əvvəl balansı niyə sorğulamaq lazımdır

Təzə balans yoxlaması olmadan kütləvi sifariş buraxılışı qismən imtinalara gətirib çıxarır: ilk müraciətlər yaradılır, sonrakılar isə vəsait çatışmazlığı xətası alır. Belə vəziyyəti paralel göndərmə, müxtəlif xidmətlər və bir hesabla işləyən bir neçə proses zamanı araşdırmaq ən çətindir.

Buraxılış üçün vacib olan artırmaların ümumi həcmi və ya şəxsi kabinetdəki mühasibat qalığı deyil. Lazım olan məbləğ, xidmətin yeni sifariş yaradılarkən silinməsinə icazə verdiyi məbləğdir. Aktiv müraciətlər altındakı pul artıq rezervdə ola bilər, baxmayaraq ki, yekun silinmə hələ əməliyyatlar tarixçəsində əks olunmayıb.

Növbə büdcəsini hesabdakı ümumi məbləğlə deyil, mövcud qalıq sahəsi ilə müqayisə edin.

Balans metodunun cavabı necə görünür

Sahələrin adlarını konkret platformanın sənədləşməsi müəyyən edir, lakin rahat balans metodu kontraktı adətən total, available, reserved, currency və updated_at qaytarır. Aşağıda inteqrasiya zamanı bələdçi kimi istifadə edilə biləcək struktur nümunəsi verilmişdir. Bu, hər xidmət üçün universal cavab deyil, anlaşılan məlumat sxeminin nümunəsidir.

Sorğu belə görünə bilər:

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

Cavab:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

Bu nümunədə total — hesabın bütün vəsaitləri, available — yeni sifarişlər üçün pul, reserved — əvvəllər yaradılmış əməliyyatlar altındakı məbləğdir. Yoxlama uyğun gəlir: 125.80 çıxılsa 41.30, 84.50-ə bərabərdir. currency sahəsi hesablama vahidini müəyyən edir, updated_at isə məlumatların nə qədər təzə olduğunu anlamağa kömək edir.

available və reserved-i necə təhlil etmək olar

available sahəsi buraxılış qərarı üçün istifadə olunur. Əgər növbə 80.00 təşkil edirsə və available 84.50-dirsə, vəsait yalnız API-nin ayrıca komissiya əlavə etməməsi və ya sifariş yaradılarkən qiyməti yenidən hesablamaması şərti ilə kifayətdir. reserved sahəsi mövcud qalığa əlavə edilmir: bu məbləğ artıq məşğuldur.

reserved processing, pending və ya review statuslu sifarişlərin dəyərini əhatə edə bilər — dəqiq dəst platformanın qaydalarından asılıdır. Bəzən rezerv ləğv, qismən icra və ya əl ilə yoxlamadan sonra azad edilir. Buna görə onu sifarişlər siyahısına əsasən müstəqil hesablamaq yalnız əlavə tutuşdurma kimi mümkündür.

• total artırmalar və silinmələr tarixçəsi ilə tutuşdurma üçün uyğundur;
• available yeni növbənin buraxılışa buraxılması üçün uyğundur;
• reserved aktiv əməliyyatlar altında nə qədər vəsaitin artıq bloklandığını göstərir;
• currency yalnız bir hesabla işləyərkən belə nəzərdən qaçırılmamalıdır;
• updated_at jurnal və köhnəlmiş cavabın diaqnostikası üçün faydalıdır.

Yalnız balance sahəsi olan cavabı emal etmək daha asandır, lakin onun çatışmazlığı var: bu pulun dərhal mövcud olub-olmadığını və ya məbləğin bir hissəsinin artıq digər sifarişlər altında tutulduğunu anlamaq mümkün deyil.

API sənədləşməsində məbləğlərin formatını yoxlayın

Nümunədə məbləğlər sətirlərlə ötürülür: 84.5 rəqəmi deyil, "84.50". Belə format xidmətin qaytardığı dəqiq dəyəri saxlayır. Əgər API onluq nöqtəli sətirlərdən istifadə edirsə, onları dərhal sürüşən nöqtəli ədədlərə çevirmək və float vasitəsilə müqayisə etmək lazım deyil.

Məsələn, sizin hesablamanız gözlənilən 84.50 əvəzinə 84.499999 verə bilər. Büdcə sərhədində bu, növbəni səhvən buraxa və ya əksinə, dayandıra bilər. Sətirli onluq dəyərlərlə əməliyyatlar üçün sabit kəsr hissəsinin dəqiqliyini dəstəkləyən onluq məlumat tipindən istifadə edin.

Digər geniş yayılmış kontrakt — tam minimum vahidlərdir. O zaman cavab "available_minor": 8450 və "currency": "USD" ehtiva edə bilər, sifarişin qiyməti isə "price_minor": 1250. Belə API daxilində 8450, əgər valyuta qaydaları iki kəsr mövqeyini nəzərdə tutursa, 84.50 deməkdir. Dəyəri 100-ə bölmək yalnız sənədləşmədə bu birbaşa göstərildikdə mümkündür.

Valyutaları və qiymət formatlarını qarışdırmayın

Növbəni hesablamazdan əvvəl balansdakı currency-ni qiymət metodunun və ya sifariş yaradılarkən cavabın valyutası ilə müqayisə edin. Əgər balans bir valyuta qaytarırsa, xidmətlər kataloqu isə digərini, rəqəmləri birbaşa yerinə qoymaq olmaz. Ya platformanın özünün təqdim etdiyi hesablama, ya da ayrıca təsdiqlənmiş konvertasiya metodu lazımdır.

Öz tərəfinizdə ilkin konvertasiya planlaşdırma üçün rahatdır, lakin onun çatışmazlığı var: xidmət silinmə anında fərqli məzənnə, komissiya və ya yuvarlaqlaşdırma qaydası tətbiq edə bilər. Sifarişi API-nin balans valyutasında yekun dəyəri qaytardığı parametrlərlə göndərmək və ya qiymət hesablamasını birbaşa yaradılmadan əvvəl almaq daha etibarlıdır.

Əgər qiymət metodu "price": "12.345" cavabını verirsə, balans isə dəyərləri iki işarə ilə saxlayırsa, yuvarlaqlaşdırma qaydasını dəqiqləşdirin. Avtomatik aşağı yuvarlaqlaşdırmayın: faktiki silinmə daha yüksək ola bilər. Növbənin buraxılışı üçün API-nin sifarişin yekun dəyəri adlandırdığı məbləğdən istifadə edin.

Növbə büdcəsini ilk sorğudan əvvəl hesablayın

Buraxılışdan əvvəl bütün müraciətləri toplayın və onların dəyərini həcm, seçilmiş xidmət, region, əlavə seçimlər və ayrıca ötürülürsə, komissiya nəzərə alınmaqla hesablayın. available-ı interfeysdəki baza qiymətlə müqayisə etməyin: API-də yekun konkret sifarişin parametrlərindən asılı ola bilər.

Tutaq ki, növbədə üç sifariş var. Qiymət hesablama API-si onlar üçün balance.currency-də göstərilən eyni valyutada 18.40, 27.15 və 31.60 qaytardı. Büdcə 77.15-ə bərabərdir. Əgər balance.available 84.50-dirsə, planlı buraxılışdan sonra 7.35 qalır. Əgər available 76.90-dırsa, bütün növbəni buraxmaq olmaz.

1. Hər sifarişin faktiki parametrlərinə görə qiymətləri əldə edin.
2. Yekun dəyərləri formatını və valyutasını dəyişmədən toplayın.
3. Büdcəni təzə balans cavabındakı available ilə müqayisə edin.
4. Kifayət qədər qalıq olduqda məbləği lokal buraxılış rezervi kimi qeyd edin.
5. Hər müraciət yaradıldıqdan sonra lokal rezervi təsdiqlənmiş dəyər qədər azaldın.

Ehtiyat əlavə silinmə zamanı imtina riskini azaldır, lakin onun çatışmazlığı var: mövcud vəsaitin bir hissəsi istifadəsiz qalacaq, halbuki növbə tam keçə bilərdi.

Göndərmədən dərhal əvvəl ikinci yoxlama aparın

Kampaniya hazırlanarkən alınan balans tez aktuallığını itirir. Hesablama ilə buraxılış arasındakı müddətdə başqa operator, avtomatlaşdırma və ya aktiv sifariş available və reserved-i dəyişə bilər. Təkrar sorğu növbə formalaşdıqdan sonra və birbaşa ilk müraciətdən əvvəl lazımdır.

İşçi sxem iki mərhələdən ibarətdir: əvvəlcə qiymətləri alıb büdcəni qiymətləndirin, sonra balance-ı yenidən sorğulayın. Əgər available dəyəri azalıb hesablanmış məbləğdən aşağı düşübsə, növbə tam göndərilmir. Yekun yoxlama ilə buraxılış arasında həmin hesabdan başqa silinmələr etmək lazım deyil.

Bütün buraxılış üçün bir sorğu API-yə yükü azaldır, lakin onun çatışmazlığı ondadır ki, uzun növbə hələ emal olunarkən mövcud qalıq dəyişə bilər.

Vəsait çatışmazlığı zamanı növbəni necə buraxmaq olar

Əgər available büdcədən azdırsa, bir hissəsinin keçəcəyinə ümid edərək bütün sorğuları göndərməyin. Növbəni dəyəri mövcud limitə sığan paketlərə bölün. 76.90 qalıq nümunəsində 45.55 dəyərində ilk iki sifarişi göndərmək, sonra dayanmaq olar: 31.60 dəyərində üçüncü sifariş təkrar yoxlama tələb edir.

Batçinq zamanı müraciətlərin sırasını açıq şəkildə müəyyən edin. Əvvəlcə prioritet sifarişləri göndərmək və ya dəyəri yaxın olan paketlər formalaşdırmaq olar. Hər variantın çatışmazlığı var: prioritet sırası daha az vacib mövqeləri təxirə salacaq, qiymətə görə sıralama isə kampaniyanın ilkin planını poza bilər.

• Məbləği cari available-dan yüksək olmayan paket formalaşdırın.
• Paketdən sifarişlər yaradın və onların identifikatorlarını saxlayın.
• Cavabları gözləyin və ya taym-autlardan sonra əməliyyatların statuslarını yoxlayın.
• API limitləri və ya xidmət qaydaları tələb edirsə, fasilə verin.
• Növbəti paketdən əvvəl balance-ı təkrar sorğulayın.

Hər paketdən sonra yalnız əvvəlki balansdan lokal çıxışa deyil, yeni API cavabına əsaslanın. Lokal hesablama nəzarət üçün faydalıdır, lakin o, qaytarmaları, xarici silinmələri və rezervlərin yenidən hesablanmasını görmür.

Paralel göndərmə zamanı büdcəni qoruyun

Ardıcıl emal zamanı sifariş təsdiqləndikdən sonra lokal limiti azaltmaq kifayətdir. Paralel modeldə iki işçi eyni vaxtda available 84.50 görə və hər biri 60.00 xərc planlaşdıra bilər. Hər iki qərar ayrılıqda məqbul görünür, lakin birlikdə mövcud qalığı aşır.

Qoruma üçün ümumi lokal rezerv sayğacı və ya girişi atomar şəkildə həyata keçirilən növbə lazımdır. Göndərmədən əvvəl işçi bu sayğacda sifarişin məbləğini tutmağa çalışır. Əgər sərbəst limit çatmırsa, müraciət balansın təkrar yoxlanmasını gözləyərək qalır.

• Ardıcıl növbəni idarə etmək daha asandır, lakin daha yavaş buraxılır.
• Paralel göndərmə buraxılış vaxtını azaldır, lakin ümumi büdcənin bloklanmasını tələb edir.
• Lokal rezervləşdirmə konfliktləri azaldır, lakin işçi sıradan çıxdıqdan sonra dona bilər.
• API tərəfində rezervləşdirmə daha etibarlıdır, lakin hər platformada mövcud deyil.

Əgər proses cavab alınmadan başa çatıbsa, lokal rezervi dərhal xərclənmiş və ya sərbəst hesab etmək olmaz. Əvvəlcə sifarişin yaradılıb-yaradılmadığını onun xarici identifikatoru və ya əməliyyatların axtarışı metodu ilə yoxlayın.

Nəzərdə tutulubsa, API rezervindən istifadə edin

Bəzi API-lər əməliyyatlar dəsti altında rezerv yaratmağa və ya sifarişi iki addımda keçirməyə imkan verir: hesablama, məbləğin bloklanması, təsdiq. Belə sxemdə yoxlama ilə silinmə arasında başqa prosesin hesabın vəsaitlərini xərcləyə biləcəyi pəncərə daha kiçikdir.

Belə metod varsa, rezervin identifikatorunu, məbləğini, valyutasını, etibarlılıq müddətini və statusunu saxlayın. Sonra API kontraktı tələb edirsə, sifarişlər yaradılarkən bu identifikatoru ötürün. Növbə bitdikdən sonra istifadə olunmamış hissəni və blokun götürülməsi faktını tutuşdurun.

API rezervi bütün problemləri həll etmir: onun qısa etibarlılıq müddəti ola bilər, komissiyaları əhatə etməyə bilər və ya təsdiq xətasından sonra azad edilə bilər. Lokal rezervi tətbiq etmək daha asandır, lakin onun çatışmazlığı ondadır ki, o, tətbiqinizdən kənarda yaradılan xərclərdən qorumur.

Balans xətasını sıfır qalıqdan ayırın

Xəta kodu ilə cavab, taym-aut və ya sorğu tezliyi məhdudiyyəti available-ın sıfıra bərabər olduğu anlamına gəlmir. Böyük buraxılış ondan asılıdırsa, son məlum dəyəri avtomatik yerinə qoymayın. Təzə balans əldə etmək mümkün olmadıqda növbəni fasiləyə qoymaq lazımdır.

Sifariş yaradılarkən imtinanı ayrıca emal edin. O, vəsait çatışmazlığı ilə bağlı ola bilər, lakin həmçinin yanlış xidmət identifikatoru, yol verilməz həcm, kanal üzrə məhdudiyyət və ya bir əməliyyatın təkrarı ilə də bağlı ola bilər. Xəta kodunu və mətnini müraciətin xarici identifikatoru ilə birlikdə saxlayın.

• Avtorizasiya xətası zamanı girişi yeniləyin və yalnız sonra sorğunu təkrarlayın.
• Sorğu limiti zamanı API qaydalarına uyğun fasilə verin.
• Yaradılma taym-autu zamanı əvvəlcə əməliyyatın faktiki yaranıb-yaranmadığını yoxlayın.
• Vəsait çatışmazlığı xətası zamanı paketi dayandırın və balance-ı yenidən sorğulayın.

Taym-autdan sonra dublikatlar yaratmayın

Taym-aut müştərinizin cavab almadığı, serverin sorğunu emal etmədiyi anlamına gəlmir. Yoxlama olmadan təkrar göndərmə ikinci sifariş yarada və pulu yenidən tuta bilər. Bu, xüsusilə avtomatik təkrarın bir neçə cəhdə qurulduğu növbədə təhlükəlidir.

API client_order_id, external_id və ya idempotency_key sahəsini dəstəkləyirsə, unikal xarici sifariş identifikatoru ötürün. Onu sorğu göndərilməzdən əvvəl saxlayın. Taym-autdan sonra əməliyyatı bu dəyərlə tapın və ya əvvəllər alınmış identifikatorla statusu sorğulayın.

Yoxlamasız təkrar daha sürətlidir, lakin onun çatışmazlığı birbaşadır: sifariş dublikatları, ikiqat rezervləşdirmə və büdcə hesablamanızla faktiki silinmələr arasında uyğunsuzluqlar mümkündür.

Buraxılış jurnalında nə saxlamaq lazımdır

Jurnal kütləvi əməliyyatın gedişatını bərpa etməyə və konkret paketin niyə dayandığını izah etməyə kömək edir. Hər buraxılış üçün iki yoxlamanın vaxtını, total, available, reserved, currency, hesablanmış büdcəni, lokal rezervin ölçüsünü və müraciətlərin xarici identifikatorlarının siyahısını saxlayın.

Hər yaradılma cəhdi üçün dəyəri, cavab kodunu, əməliyyatın texniki identifikatorunu və yekun statusu qeyd edin. Sirlər jurnala düşmür: avtorizasiya tokenləri, API açarları, tam sorğu başlıqları və şəxsi məlumatlar yazılmazdan əvvəl maskalanmalı və ya çıxarılmalıdır.

Tam loqlaşdırma sazlama zamanı rahatdır, lakin onun çatışmazlığı var: filtrləmə olmadan anbara giriş məlumatları və müştərilər haqqında məlumatlar düşə bilər.

Sxemi kiçik növbədə yoxlayın

Böyük buraxılışdan əvvəl qısa ssenari keçirin: balance alın, yekun qiymətləri sorğulayın, məhdud paket yaradın, yenidən balance sorğulayın və available və reserved-də gözlənilən dəyişikliyi faktiki cavabla müqayisə edin. Beləliklə, xidmətin məbləği nə vaxt rezervləşdirdiyini, nə vaxt isə yekun olaraq sildiyini görmək olar.

Test paketi böyük yük altında eyni davranışa zəmanət vermir: limitlər, paralel proseslər və ya konkret xidmətin məhdudiyyətləri işə düşə bilər. Buna görə kütləvi növbədə buraxılışı paketlərə bölməyə, aralarında mövcud qalığı yoxlamağa və hər imtinanı ayrıca araşdırmağa davam edin.