API üzerinden SMM panelinde otomatik bakiye yükleme nasıl yapılandırılır

Otomatik bakiye yüklemeden önce hazırlanması gerekenler

Otomatik bakiye yükleme, SMM paneli bakiyesini bir ödeme hizmetine veya dahili faturalandırmaya bağlar. Hizmet bakiyeyi kontrol eder, belirlenen eşiğe ulaşıldığında ödeme oluşturur ve parayı yalnızca ödeme onaylandıktan sonra yükler. Bunun için panelin API belgelerine, ödeme API'sine erişime, test ve canlı ortam için ayrı anahtarlara ve tüm işlemlerin günlüğüne ihtiyaç vardır.

Geliştirmeye başlamadan önce panelin API'sinin bakiye döndürüp döndürmediğini, yükleme talebi alıp almadığını, yükleme geçmişini gösterip göstermediğini ve harici işlem kimliğini kabul edip etmediğini kontrol edin. Panel API üzerinden yükleme desteklemiyorsa otomasyon yalnızca talep oluşturabilir veya operatöre bildirim gönderebilir. Bu seçeneğin dezavantajı, paranın yine de manuel olarak yatırılması gerektiğidir.

Bakiye kontrolünü ve ödeme kararını ayırın

Bakiye kontrolünü ayrı bir zamanlanmış görev olarak çalıştırmak daha iyidir. Görev bakiyeyi alır, eşikle karşılaştırır ve sonucu yükleme işleyicisine iletir. Mevcut tamamlanmamış işlemleri kontrol etmeden doğrudan API yanıtı anında ödeme oluşturmayın: paralel görevler aynı düşük bakiyeyi görebilir ve birden fazla ödeme oluşturabilir.

Yeni bir ödemeden önce işleyici, "oluşturuldu", "ödeme bekliyor" veya "onaylanıyor" durumunda bir işlem olup olmadığını kontrol etmelidir. Böyle bir kayıt varsa, mutabakat tamamlanana kadar yeni deneme başlatılmaz. Sıralı işlemenin dezavantajı, harici API'nin yanıtı uzun sürdüğünde yüklemenin birkaç paralel isteğe göre daha geç başlayabilmesidir.

Eşiği ve yükleme tutarı mantığını seçin

Bakiye eşiği, aktif siparişler, tedarikçi kuyruğu ve ödeme gecikmeleri için pay bırakılarak seçilir. Düzensiz etkinliğe sahip bir kanal için yalnızca ortalama harcamaya dayanmak risklidir: yayın, reklam başlatma veya toplu sipariş sonrasında kesintiler keskin biçimde artabilir. Ayrıca, bildirimin geldiği ancak ödemenin otomatik olarak oluşturulmasının zorunlu olmadığı kritik bir seviye belirlenir.

Yükleme tutarı sabit olabilir veya seçilen dönemdeki harcamaya göre hesaplanabilir. Sabit tutarın kontrolü ve mutabakatı daha kolaydır. Dezavantajı, sakin dönemde bakiyede gereksiz para kalabilmesi, siparişlerin hızla artması durumunda ise tek bir yüklemenin yetmeyebilmesidir. Hesaplanan tutar daha esnektir, ancak istatistiklerin anormal kesintilerden ve iadelerden arındırılmasını gerektirir.

Finansal sınırları eşikten ayrı yapılandırın

Eşik yalnızca sisteme yükleme sürecine ne zaman başlamasına izin verildiği sorusunu yanıtlar. Sınırlar başka bir soruyu yanıtlar: sistemin ne kadar para çekme hakkı vardır. Tek işlem için maksimum tutarı, dönem için toplam limiti ve yüklemeden sonra izin verilen bakiyeyi belirleyin. Bu kurallar ödeme oluşturulmadan önce kontrol edilir, ödendikten sonra değil.

Otomatik bakiye yükleme, işlem ve dönem limiti olmadan para çekmemelidir. Hesaplanan tutar izin verilenden yüksekse, işlemi manuel kontrole aktarmak ve bildirim göndermek daha iyidir. Katı limitlerin dezavantajı, harcamalar hızla arttığında sorumlu çalışan limit artışını onaylayana kadar bakiyenin tükenebilmesidir.

Ayrı anahtarlar oluşturun ve erişimi koruyun

Otomatik bakiye yükleme betiği için minimum yetkilere sahip ayrı API anahtarları kullanın: bakiye okuma, ödeme oluşturma, durum kontrolü ve onaylanmış işlemi yükleme. Kullanıcılara, hizmet ayarlarına, siparişlere ve para çekme işlemlerine erişim bu anahtar için gerekli değildir. Hizmet IP adresi kısıtlamasını destekliyorsa, yalnızca entegrasyon sunucusundan gelen isteklere izin verin.

Anahtarlar ortam değişkenlerinde veya güvenli bir sır deposunda saklanır. Bunları tarayıcı koduna, günlüklere, genel depolara ve hata mesajlarına aktarmayın. Her anahtarın bir sahibi ve net bir değiştirme prosedürü olmalıdır. Anahtarların sık döndürülmesinin dezavantajı, yeni sır tüm çalışma süreçlerinde güncellenmezse yüklemenin durmasıdır.

Benzersiz tanımlayıcıyla ödeme oluşturun

Her yüklemeye ödeme API'sine başvurmadan önce dahili bir tanımlayıcı atanır. Bu tanımlayıcı günlüğe kaydedilir ve idempotentlik anahtarı veya harici işlem numarası olarak iletilir. Ağ zaman aşımı durumunda aynı istek aynı tanımlayıcıyla tekrarlanabilir: ödeme hizmeti parayı yeniden çekmek yerine zaten oluşturulmuş işlemi döndürmelidir.

Aşağıda genel bir istek örneği verilmiştir. Alan adlarını ve adresleri belirli sağlayıcının belgelerindeki değerlerle değiştirin. PAYMENT_ID değişkeninde önceden oluşturulmuş benzersiz bir kimlik saklanır, CALLBACK_URL ise webhook işleyicisine yönlendirir.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

Ödemenin benzersizliğini yalnızca tutar ve oluşturulma zamanına göre belirlemeyin. İki aynı yükleme meşru olabilir, ancak bir arıza sonrasındaki tekrarlanan istek olamaz. Kendi veritabanınızdaki harici kimliğin dezavantajı, güvenilir biçimde saklanması ve işlem iptal edildikten sonra yeniden kullanılmaması gerektiğidir.

Bakiyeyi kontrol edin ve işlem durumunu saklayın

Bakiye isteği, yeni yükleme kararından önce ve başarılı yüklemeden sonra yapılmalıdır. Genel istek şu şekilde olabilir: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". Yanıtta yalnızca tutarı değil, kontrol zamanını da saklayın, böylece eski verilere dayanarak karar vermezsiniz.

Her işlem için dahili kimlik, sağlayıcıdaki ödeme kimliği, tutar, para birimi, oluşturulma zamanı, durum, API yanıtları ve hata nedeni içeren bir kayıt tutun. Uygun durum zinciri şöyledir: "oluşturuldu", "ödeme bekliyor", "ödendi", "yükleniyor", "yüklendi", "iptal edildi", "kontrol gerekiyor".

Panele yükleme yalnızca onaylanmış ve henüz işlenmemiş bir ödeme için izinlidir. Durumları geçmiş olmadan yeniden yazmayın: bir anlaşmazlık durumunda hangi isteğin gönderildiği ve işlemin neden değiştirildiği görülebilmelidir. Ayrıntılı günlüğün dezavantajı, hassas veriler içerebilmesidir, bu nedenle erişim kısıtlanır.

Webhook'u alın ve ödeme durumunu doğrulayın

Başarılı ödeme sayfası ve kullanıcı yönlendirmesi paranın geldiğini doğrulamaz. Onay, ödeme hizmetinden gelen webhook veya hizmetin API'si üzerinden tekrar yapılan durum kontrolüdür. Webhook alındığında imzayı, gönderim zamanını, ödeme kimliğini, harici kimliği, tutarı ve para birimini kontrol edin. Ancak bundan sonra işlemi onaylanmış ödeme durumuna geçirin.

Webhook'u kontrol ettikten sonra sağlayıcıdan güncel ödeme durumunu istemek faydalıdır. Örneğin: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Durumu günlük verileriyle karşılaştırın, ardından aynı dahili kimlikle SMM paneline yükleme isteği gönderin.

Tekrarlanan webhook ikinci bir yükleme oluşturmamalıdır. İşleyici işlemi harici kimliğe göre bulur, "yüklendi" durumunu görür ve yeni işlem yapmadan başarılı yanıt döndürür. Webhook'ların dezavantajı, işleyici kullanılamadığında gecikebilmeleri veya hiç ulaşamayabilmeleridir.

Zaman aşımlarını, yeniden denemeleri ve takılı kalan ödemeleri işleyin

Ödeme oluşturulduktan sonra zaman aşımı durumunda farklı bir kimlikle yeni istek göndermeyin. Önce işlemi dahili tanımlayıcıya göre bulun veya isteği aynı idempotentlik anahtarıyla tekrarlayın. Sağlayıcı ilk isteği kabul ettiyse mevcut ödemeyi döndürür. Bu, bağlantı kesildiğinde çift çekimi önler.

Webhook belirlenen süre içinde gelmezse, arka plan görevi ödeme durumunu API üzerinden sorgular. Tekrarlanan kontroller, API'yi ve günlüğü aşırı yüklememek için artan aralıklarla ve sınırlı sayıda denemeyle yapılır. Uzun süre beklemede kalan işlem, mutabakat yapılmadan iptal edilmiş sayılmak yerine manuel kontrole aktarılır.

Geçici ağ hatası veya API kullanılamaması yanıtlarında yeniden denemelere izin verilir. Ödeme reddi, yanlış tutar, geçersiz webhook imzası veya limit aşımı durumunda isteği otomatik olarak tekrarlamamak gerekir. Yeniden denemelerin dezavantajı, durum mantığını karmaşıklaştırmaları ve sağlayıcıda toplu bir arıza sırasında gereksiz yük oluşturabilmeleridir.

Onaylanmış ödemeyi SMM paneline yükleyin

Yüklemeden önce işleyici bir kez daha kontrol eder: tutar limiti aşmıyor, para birimi eşleşiyor, işlem iptal edilmemiş ve durumu henüz "yüklendi" değil. İstekte tutar ve ödemenin harici kimliği iletilir. Panelin API'si idempotentlik anahtarını destekliyorsa aynı dahili işlem kimliğini kullanın.

İsteğin genel görünümü: curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

Panelin yanıtından sonra bakiyeyi tekrar isteyin ve sonucu günlüğe kaydedin. Ödeme hizmetinden para çekildiyse ancak panelin API'si hata döndürdüyse yeni bir ödeme oluşturmayın. İşlem, yükleme yeniden denenene veya manuel mutabakat yapılana kadar "kontrol gerekiyor" durumunda kalır. Bu temkinli şemanın dezavantajı, bakiyenin geçici olarak otomatik yüklenemeyebilmesidir.

Bildirimler, anahtar ve başlatma kontrolü ekleyin

Bildirimler sapmalar için gereklidir: bakiye kritik seviyenin altına düştü, ödeme reddedildi, webhook alınmadı, limit aşıldı, API kullanılamıyor veya işlem manuel kontrol gerektiriyor. Mesajda dahili kimliği, durumu ve nedeni belirtmek yeterlidir. API anahtarlarını, webhook imzalarını ve ödeme bilgilerini mesaja dahil etmeyin.

Entegrasyonu kaldırmadan otomatik bakiye yükleme için ayrı bir anahtar bırakın. Bu anahtar, sağlayıcı değişikliği, teknik çalışmalar, hata şüphesi veya harcamalarda ani değişiklik durumunda gereklidir. Anahtarın dezavantajı açıktır: çalışmalardan sonra tekrar açılmazsa, aktif siparişler sırasında bakiye tükenebilir.

Otomatik bakiye yüklemeyi açmadan önce kontrol listesi

• Tamamlanmamış bir işlem varken bakiye kontrolü ödeme oluşturmaz.
• Her ödeme için benzersiz bir dahili kimlik ve idempotentlik anahtarı oluşturulur.
• Tek işlem ve seçilen dönem için limitler yapılandırılmıştır.
• Webhook'lar imza, tutar, para birimi ve tanımlayıcıya göre kontrol edilir.
• Webhook gelmediğinde API üzerinden tekrar durum doğrulaması başlatılır.
• Zaman aşımı, ilki kontrol edilmeden ikinci bir ödeme oluşturulmasına yol açmaz.
• Panele yükleme bir kez yapılır ve günlüğe kaydedilir.
• Test modu başarı, ret, yinelenen webhook ve API kullanılamaması durumlarında kontrol edilmiştir.