Toplu sipariş başlatmadan önce API üzerinden bakiye kontrolü

Kuyruğu başlatmadan önce bakiye neden sorgulanır

Güncel bakiye kontrolü yapılmadan toplu sipariş başlatmak kısmi redlere yol açar: ilk talepler oluşturulur, sonrakiler ise yetersiz bakiye hatası alır. Bu durumu paralel gönderimde, farklı hizmetlerde ve aynı hesapla çalışan birden fazla süreçte çözmek en zorudur.

Başlatma için önemli olan toplam yükleme tutarı veya kişisel paneldeki muhasebe bakiyesi değildir. Gereken, hizmetin yeni bir sipariş oluşturma anında çekilmesine izin verdiği tutardır. Aktif talepler için para, işlem geçmişine henüz yansımamış olsa bile rezervde olabilir.

Kuyruk bütçesini hesaptaki toplam tutarla değil, kullanılabilir bakiye alanıyla karşılaştırın.

Bakiye yönteminin yanıtı nasıl görünür

Alan adlarını ilgili platformun dokümantasyonu belirler, ancak kullanışlı bir bakiye yöntemi sözleşmesi genellikle total, available, reserved, currency ve updated_at döndürür. Aşağıda entegrasyonda referans olarak kullanabileceğiniz örnek bir yapı verilmiştir. Bu, her hizmet için geçerli evrensel bir yanıt değil, anlaşılır bir veri şeması örneğidir.

İstek şöyle görünebilir:

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

Yanıt:

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

Bu örnekte total hesabın tüm bakiyesini, available yeni siparişler için kullanılabilir parayı, reserved ise daha önce oluşturulan işlemler için ayrılan tutarı gösterir. Kontrol tutarlıdır: 125.80 eksi 41.30, 84.50'ye eşittir. currency alanı hesaplama birimini belirler, updated_at ise verilerin ne kadar güncel olduğunu anlamaya yardımcı olur.

available ve reserved nasıl yorumlanır

available alanı başlatma kararında kullanılır. Kuyruk 80.00 tutuyorsa ve available 84.50 ise, yalnızca API'nin ayrı bir komisyon eklememesi veya talep oluşturma anında fiyatı yeniden hesaplamaması koşuluyla bakiye yeterlidir. reserved alanı kullanılabilir bakiyeye eklenmez: bu tutar zaten ayrılmıştır.

reserved, processing, pending veya review durumundaki siparişlerin maliyetini içerebilir — kesin küme platformun kurallarına bağlıdır. Bazen rezerv, iptal, kısmi tamamlama veya manuel incelemeden sonra serbest bırakılır. Bu nedenle rezervi sipariş listesine göre kendi başınıza hesaplamak yalnızca ek bir doğrulama olarak yapılabilir.

• total, yükleme ve çekim geçmişiyle karşılaştırma için uygundur;
• available, yeni kuyruğun başlatılmasına izin vermek için uygundur;
• reserved, aktif işlemler için ne kadar tutarın bloke edildiğini gösterir;
• currency, yalnızca tek bir hesapla çalışılsa bile göz ardı edilmemelidir;
• updated_at, günlük ve eski yanıt teşhisi için faydalıdır.

Yalnızca balance alanı içeren bir yanıtı işlemek daha kolaydır, ancak bir dezavantajı vardır: bu paranın hemen kullanılabilir olup olmadığını veya tutarın bir kısmının diğer siparişler için zaten tutulup tutulmadığını anlayamazsınız.

API dokümantasyonunda tutar formatını kontrol edin

Örnekte tutarlar 84.5 sayısı olarak değil, "84.50" dizeleri olarak aktarılmıştır. Bu format, hizmetin döndürdüğü kesin değeri korur. API ondalık noktalı dizeler kullanıyorsa, bunları hemen kayan noktalı sayılara dönüştürüp float ile karşılaştırma yapmamalısınız.

Örneğin, hesaplamanız beklenen 84.50 yerine 84.499999 verebilir. Bütçe sınırında bu, kuyruğu hatalı şekilde geçirebilir veya tam tersine durdurabilir. Dizeli ondalık değerlerle işlem yaparken, sabit ondalık kısmın hassasiyetini destekleyen bir ondalık veri türü kullanın.

Diğer yaygın bir sözleşme, tam sayı en küçük birimlerdir. Bu durumda yanıt "available_minor": 8450 ve "currency": "USD" içerebilir, sipariş fiyatı ise "price_minor": 1250 olabilir. Böyle bir API'de, para birimi kuralları iki ondalık basamak öngörüyorsa 8450, 84.50 anlamına gelir. Değeri 100'e bölmek yalnızca dokümantasyonda açıkça belirtildiğinde yapılabilir.

Para birimlerini ve fiyat formatlarını karıştırmayın

Kuyruğu hesaplamadan önce bakiyedeki currency ile fiyat yönteminin veya sipariş oluşturma yanıtının para birimini karşılaştırın. Bakiye bir para birimi döndürürken hizmet kataloğu başka bir para birimi döndürüyorsa, rakamlar doğrudan yerleştirilemez. Ya platformun sağladığı bir hesaplama ya da ayrı bir doğrulanmış dönüştürme yöntemi gerekir.

Kendi tarafınızda önceden dönüştürme yapmak planlama için uygundur, ancak bir dezavantajı vardır: hizmet, çekim anında farklı bir kur, komisyon veya yuvarlama kuralı uygulayabilir. Siparişi, API'nin nihai maliyeti bakiye para biriminde döndürdüğü parametrelerle göndermek veya fiyat hesaplamasını doğrudan oluşturmadan hemen önce almak daha güvenilirdir.

Fiyat yöntemi "price": "12.345" döndürürken bakiye değerleri iki basamakla saklıyorsa, yuvarlama kuralını netleştirin. Otomatik olarak aşağı yuvarlamayın: gerçek çekim daha yüksek olabilir. Kuyruğu kabul etmek için API'nin siparişin nihai maliyeti olarak adlandırdığı tutarı kullanın.

Kuyruk bütçesini ilk istekten önce hesaplayın

Başlatmadan önce tüm talepleri toplayın ve maliyetlerini hacim, seçilen hizmet, bölge, ek seçenekler ve ayrıca aktarılıyorsa komisyon dikkate alarak hesaplayın. available değerini arayüzdeki temel fiyatla karşılaştırmayın: API'de toplam, belirli siparişin parametrelerine bağlı olabilir.

Diyelim ki kuyrukta üç sipariş var. Fiyat hesaplama API'si bunlar için balance.currency'de belirtilen para biriminde 18.40, 27.15 ve 31.60 döndürdü. Bütçe 77.15'tir. balance.available 84.50 ise, planlanan başlatmadan sonra 7.35 kalır. available 76.90 ise, tüm kuyruk başlatılamaz.

1. Her siparişin gerçek parametrelerine göre fiyatları alın.
2. Nihai maliyetleri formatını ve para birimini değiştirmeden toplayın.
3. Bütçeyi güncel bakiye yanıtındaki available ile karşılaştırın.
4. Bakiye yeterliyse tutarı yerel başlatma rezervi olarak sabitleyin.
5. Her talep oluşturulduktan sonra yerel rezervi onaylanan maliyet kadar azaltın.

Pay, ek çekim durumunda red riskini azaltır, ancak bir dezavantajı vardır: kuyruk tamamen geçebilecekken kullanılabilir bakiyenin bir kısmı kullanılmadan kalır.

Göndermeden hemen önce ikinci kontrolü yapın

Kampanya hazırlığı sırasında alınan bakiye hızla güncelliğini yitirir. Hesaplama ile başlatma arasındaki sürede başka bir operatör, otomasyon veya aktif bir sipariş available ve reserved değerlerini değiştirebilir. Tekrarlanan istek, kuyruk oluşturulduktan sonra ve ilk talepten hemen önce gereklidir.

Çalışma şeması iki aşamadan oluşur: önce fiyatları alıp bütçeyi değerlendirin, ardından balance'ı bir kez daha sorgulayın. available değeri azaldıysa ve hesaplanan tutarın altına düştüyse, kuyruk tamamen gönderilmez. Son kontrol ile başlatma arasında aynı hesapla başka çekimler yapılmamalıdır.

Tüm başlatma için tek bir istek API yükünü azaltır, ancak dezavantajı, uzun kuyruk hâlâ işlenirken kullanılabilir bakiyenin değişebilmesidir.

Bakiye yetersizken kuyruk nasıl başlatılır

available bütçeden azsa, bir kısmının geçeceği umuduyla tüm istekleri göndermeyin. Kuyruğu, maliyeti kullanılabilir limite sığan paketlere bölün. 76.90 bakiye örneğinde, ilk iki siparişi 45.55 için gönderebilir, sonra durmalısınız: 31.60 tutarındaki üçüncü sipariş tekrar kontrol gerektirir.

Toplu işlemede talep sırasını açıkça belirleyin. Önce öncelikli siparişleri gönderebilir veya benzer maliyetli paketler oluşturabilirsiniz. Her seçeneğin bir dezavantajı vardır: öncelikli sıra daha az önemli kalemleri erteler, fiyata göre sıralama ise kampanyanın orijinal planını bozabilir.

• Tutarı mevcut available değerini aşmayan bir paket oluşturun.
• Paketteki siparişleri oluşturun ve kimliklerini kaydedin.
• Yanıtları bekleyin veya zaman aşımlarından sonra işlem durumlarını kontrol edin.
• API limitleri veya hizmet kuralları gerektiriyorsa ara verin.
• Bir sonraki paketten önce balance'ı tekrar sorgulayın.

Her paketten sonra yalnızca önceki bakiyeden yerel düşüme değil, yeni API yanıtına göre hareket edin. Yerel hesaplama kontrol için faydalıdır, ancak iadeleri, harici çekimleri ve rezerv yeniden hesaplamalarını görmez.

Paralel gönderimde bütçeyi koruyun

Sıralı işlemede sipariş onaylandıktan sonra yerel limiti azaltmak yeterlidir. Paralel modelde iki işçi aynı anda available 84.50 değerini görebilir ve her biri 60.00 harcama planlayabilir. Her iki karar tek başına uygun görünür, ancak birlikte kullanılabilir bakiyeyi aşar.

Koruma için ortak bir yerel rezerv sayacı veya atomik olarak erişilen bir kuyruk gerekir. Göndermeden önce işçi, sipariş tutarını bu sayaçta ayırmaya çalışır. Boş limit yetersizse talep, bakiye tekrar kontrolü için bekler.

• Sıralı kuyruk kontrol edilmesi daha kolaydır, ancak daha yavaş başlar.
• Paralel gönderim başlatma süresini kısaltır, ancak ortak bütçe kilidi gerektirir.
• Yerel rezervasyon çakışmaları azaltır, ancak işçi arızasından sonra takılı kalabilir.
• API tarafında rezervasyon daha güvenilirdir, ancak her platformda mevcut değildir.

Süreç yanıt almadan sona erdiyse, yerel rezerv hemen harcanmış veya serbest sayılamaz. Önce siparişin oluşturulup oluşturulmadığını harici kimliğine göre veya işlem arama yöntemiyle kontrol edin.

API rezervi varsa kullanın

Bazı API'ler bir dizi işlem için rezerv oluşturmaya veya siparişi iki adımda yürütmeye izin verir: hesaplama, tutar blokajı, onay. Böyle bir şemada kontrol ile çekim arasında başka bir sürecin hesap bakiyesini harcayabileceği pencere daha küçüktür.

Böyle bir yöntem varsa rezervin kimliğini, tutarını, para birimini, geçerlilik süresini ve durumunu kaydedin. Ardından API sözleşmesi gerektiriyorsa sipariş oluştururken bu kimliği aktarın. Kuyruk tamamlandıktan sonra kullanılmayan kısmı ve blokajın kaldırıldığını doğrulayın.

API rezervi tüm sorunları çözmez: kısa geçerlilik süresi olabilir, komisyonları kapsamayabilir veya onay hatasından sonra serbest bırakılabilir. Yerel rezervi uygulamak daha kolaydır, ancak dezavantajı, uygulamanız dışında oluşturulan harcamalara karşı korumamasıdır.

Bakiye hatasını sıfır bakiyeden ayırın

Hata kodu içeren bir yanıt, zaman aşımı veya istek hızı sınırlaması, available değerinin sıfır olduğu anlamına gelmez. Büyük bir başlatma buna bağlıysa, son bilinen değeri otomatik olarak yerleştirmeyin. Güncel bakiye alınamıyorsa kuyruk duraklatılmalıdır.

Sipariş oluşturma reddini ayrıca ele alın. Bu, yetersiz bakiye ile ilgili olabilir, ancak aynı zamanda hatalı hizmet kimliği, geçersiz hacim, kanal kısıtlaması veya aynı işlemin tekrarıyla da ilgili olabilir. Hata kodunu ve metnini talebin harici kimliğiyle birlikte kaydedin.

• Yetkilendirme hatasında erişimi yenileyin ve ancak sonra isteği tekrarlayın.
• İstek limitinde API kurallarına göre ara verin.
• Oluşturma zaman aşımında önce işlemin gerçekten ortaya çıkıp çıkmadığını kontrol edin.
• Yetersiz bakiye hatasında paketi durdurun ve balance'ı yeniden sorgulayın.

Zaman aşımından sonra kopya oluşturmayın

Zaman aşımı, istemcinizin yanıt almadığı anlamına gelir, sunucunun isteği işlemediği anlamına değil. Kontrol yapmadan yeniden göndermek ikinci bir sipariş oluşturabilir ve parayı tekrar ayırabilir. Bu özellikle otomatik tekrarın birkaç denemeye ayarlandığı kuyruklarda tehlikelidir.

API client_order_id, external_id veya idempotency_key alanını destekliyorsa benzersiz bir harici sipariş kimliği aktarın. İsteği göndermeden önce bunu kaydedin. Zaman aşımından sonra işlemi bu değere göre bulun veya daha önce alınan kimlikle durumunu sorgulayın.

Kontrolsüz tekrar daha hızlıdır, ancak dezavantajı doğrudandır: sipariş kopyaları, çift rezervasyon ve bütçe hesaplamanız ile gerçek çekimler arasında tutarsızlıklar olabilir.

Başlatma günlüğünde neler saklanmalı

Günlük, toplu işlemin gidişatını yeniden oluşturmaya ve belirli bir paketin neden durduğunu açıklamaya yardımcı olur. Her başlatma için iki kontrolün zamanını, total, available, reserved, currency değerlerini, hesaplanan bütçeyi, yerel rezerv boyutunu ve taleplerin harici kimlik listesini kaydedin.

Her oluşturma denemesi için maliyeti, yanıt kodunu, işlemin teknik kimliğini ve nihai durumu kaydedin. Gizli bilgiler günlüğe girmez: yetkilendirme belirteçleri, API anahtarları, tam istek başlıkları ve kişisel veriler kayıttan önce maskelenmeli veya hariç tutulmalıdır.

Tam günlükleme hata ayıklamada kullanışlıdır, ancak bir dezavantajı vardır: filtreleme olmadan depoya erişim verileri ve müşteri bilgileri girebilir.

Şemayı küçük bir kuyrukta test edin

Büyük bir başlatmadan önce kısa bir senaryo yürütün: balance'ı alın, nihai fiyatları sorgulayın, sınırlı bir paket oluşturun, balance'ı tekrar sorgulayın ve available ile reserved değerlerindeki beklenen değişimi gerçek yanıtla karşılaştırın. Böylece hizmetin tutarı ne zaman rezerve ettiğini ve ne zaman kesin olarak çektiğini fark edebilirsiniz.

Test paketi, büyük yük altında aynı davranışı garanti etmez: limitler, paralel süreçler veya belirli hizmet kısıtlamaları devreye girebilir. Bu nedenle toplu kuyrukta başlatmayı paketlere bölmeye, aralarında kullanılabilir bakiyeyi kontrol etmeye ve her reddi ayrı ayrı ele almaya devam edin.