SMM Panel API’de Aynı Siparişin İki Kez Gönderilmesi Nasıl Önlenir?

SMM panel API entegrasyonlarında en pahalı hatalardan biri, müşterinin tek sipariş vermesine rağmen sağlayıcıya aynı isteğin iki kez iletilmesidir. Kullanıcı panelde bir satır görürken arka planda iki farklı sağlayıcı siparişi oluşabilir. Bazen bu, kullanıcının butona art arda basmasından kaynaklanır; bazen de sunucu zaman aşımına uğrayan isteği yeniden gönderir. Çift siparişin çözümü yalnızca butonu kilitlemek değildir: siparişi veritabanında benzersiz tanımlamak, belirsiz API yanıtlarını güvenli yönetmek ve sağlayıcı sipariş numarasını bir kez kaydetmek gerekir.

Çift sipariş tam olarak hangi aşamada oluşur?

Bir müşteri yerel panelde #78541 numaralı siparişi oluşturduğunda sistem, bağlı sağlayıcıya add isteği gönderebilir. Sağlayıcı #994012 numarasını döndürdüğünde iki numara ilişkilendirilir. Sorun, aynı yerel siparişten ikinci bir add çağrısı çıktığında başlar. Sağlayıcı ikinci çağrıyı bağımsız kabul ederse yeni bir numara ve ayrı bir maliyet oluşur. Görünürde tek müşterinin tek talebi vardır; teknik tarafta iki üretim emri bulunur.

Bu hata yalnızca PHP, Python veya Node.js ile yapılan özel yazılımlarda görülmez. Kuyruk işleyicilerinin paralel çalışması, cron görevlerinin çakışması, panel eklentilerinin yeniden denemesi veya aynı web kancasının iki kez gelmesi de tetikleyicidir. Önce siparişin müşteride mi, yerel veritabanında mı, yoksa sağlayıcı tarafında mı çoğaldığını ayırmak gerekir. Farklı katmanlardaki tekrarların çözümleri de farklıdır.

Ağ zaman aşımı neden tehlikelidir?

API isteği gönderildikten sonra bağlantının kesilmesi, işlemin sağlayıcıya ulaşmadığını kanıtlamaz. Örneğin sağlayıcı siparişi oluşturur ama yanıtı internet bağlantısı yüzünden panele dönemeyebilir. Yerel sistem yalnızca timeout görür. Bu durumda kontrolsüz otomatik tekrar aynı siparişi ikinci kez oluşturabilir. “Yanıt gelmedi” ile “sipariş oluşturulmadı” aynı anlama gelmez; güvenli entegrasyonlarda bu iki durumun ayrılması temel ilkedir.

Timeout yaşandığında siparişi önce unknown veya needs_reconciliation gibi belirsiz bir teknik duruma almak daha doğrudur. Sağlayıcı siparişi sorgulanabiliyorsa işlem referansıyla doğrulanır; sorgulanamıyorsa destek kaydı ve operatör kontrolü devreye girer. İşlem belirsizken ikinci add çağrısının otomatik atılması yerine, sistemin neden yanıt alamadığını kayda geçirmek uzun vadede daha az masraf doğurur.

Idempotency nedir ve neyi garanti eder?

Idempotency, aynı mantıksal isteğin tekrar işlenmesinin yeni bir işlem üretmemesini hedefleyen tasarım yaklaşımıdır. Ödeme ve sipariş sistemlerinde genellikle benzersiz bir istek anahtarı kullanılır. Örneğin müşteri siparişi için order:78541:create:v1 gibi tekrar üretilebilen bir anahtar tutulabilir. Bu anahtar ilk işleme ait sonuçla eşleştirildiğinde ikinci çağrı aynı siparişe döndürülür. Ancak tüm SMM sağlayıcı API’lerinin idempotency anahtarını desteklediği varsayılamaz.

Sağlayıcı destek sunmuyorsa korumayı yerel yazılımda kurarsınız: istek göndermeden önce benzersizlik kontrolü, kilit ve durum geçişi uygulanır. Bu, kendi sisteminizden çıkan iki eş zamanlı isteği önler; fakat sağlayıcının işlemi kabul edip yanıtı kaybettiği belirsiz senaryoyu tek başına çözmez. Bu yüzden idempotency ile sonradan mutabakat kontrolü birlikte tasarlanmalıdır. SMM panel API’nin temel çalışma mantığı rehberimiz bu iki sistem arasındaki veri akışını ayrıca açıklıyor.

Yerel sipariş numarası benzersiz tutulmalı

Sipariş oluşturma ekranından gelen isteğe sunucu tarafında benzersiz bir müşteri işlem kimliği verin. Bu kimlik kullanıcıdan gelen rastgele parametreye körü körüne güvenmeden doğrulanmalıdır. Veritabanında customer_request_id veya external_reference alanına benzersiz indeks koymak, aynı işlem iki kere gönderildiğinde ikinci kaydın açılmasını engeller. Sadece uygulama seviyesinde “var mı?” sorgusu yeterli olmayabilir; iki paralel işlem aynı anda “yok” sonucunu görebilir.

Bir siparişin yerel kimliğini sağlayıcının order_id alanıyla karıştırmayın. Yerel ID müşterinin işlemini, sağlayıcı ID karşı sistemdeki işi tanımlar. Tek sağlayıcı numarası birden çok yerel siparişle hatalı eşleşirse muhasebe, refund ve durum güncellemeleri karışır. Veritabanında hangi kombinasyonun benzersiz olması gerektiği açıkça tanımlanmalı; sağlayıcı kimliği olmadan işlem tamamlandı kabul edilmemelidir.

Kuyruk işleyicilerinde yarış koşulu

İki worker aynı sıradaki siparişi aynı anda ele alabilir. Bir worker siparişin new olduğunu görürken diğeri de henüz durum güncellenmediği için new görebilir. İkisi de sağlayıcıya add isteği gönderirse aynı anda iki iş oluşur. Bu durumda çözüm yalnızca worker sayısını azaltmak değil; atomik olarak new durumundan sending durumuna geçiş yapmaktır. Geçişi kazanan işlem gönderime devam eder, diğeri siparişi bırakır.

İşleme başlanırken kayda locked_at, worker_id ve deneme sayısı eklenebilir. Worker kapanırsa kilidin sonsuza kadar kalmaması için süre aşımı politikası gerekir. Ancak kilit süresi bitti diye bilinmeyen bir siparişe hemen tekrar gönderim yapılmamalıdır. Önce önceki isteğin sağlayıcıda oluşturduğu olası sipariş araştırılır. Kısacası kilit yönetimi gönderim güvenliğinin bir parçasıdır, yerine geçmez.

Güvenli durum makinesi nasıl kurulabilir?

Siparişler için en azından new, sending, sent, unknown, failed gibi iç teknik durumlar belirlenebilir. Bu adlar panelde müşterinin gördüğü Pending, Processing veya Completed ifadeleriyle birebir aynı olmak zorunda değildir. İç durum makinesi API gönderim sürecini, müşteri durumu ise hizmetin gerçekleşme aşamasını anlatır. Yanlışlıkla aynı tablo alanında iki kavramı taşımak sorun araştırmasını zorlaştırır.

Başarılı add yanıtı alındığında sağlayıcı sipariş numarası, dönüş zamanı ve yanıtın doğrulanmış özeti tek işlemde kaydedilir. Başarısız yanıtların hepsi aynı değildir: bağlantı kurulamadıysa işlem büyük olasılıkla gönderilmemiş olabilir; bağlantı kurulup yanıt gelmediyse sonuç belirsizdir. Kesin ret yanıtıyla şüpheli zaman aşımını aynı failed durumuna atmak gereksiz tekrar riskini büyütür.

Örnek güvenli gönderim sırası

İlk adım müşterinin talebini ve benzersiz işlem anahtarını kaydetmektir. İkinci adım, veritabanında atomik sahiplenme yapmaktır. Üçüncü adımda yalnızca sahiplenen worker sağlayıcıya istek atar. Dördüncü adımda sonuç kaydedilir; belirsiz bir sonuç farklı bir kontrol kuyruğuna alınır. Beşinci adımda sağlayıcı ID elde edildiğinde yerel siparişle eşleştirilir ve normal durum sorgulamaları başlayabilir.

Bu sıranın avantajı sorunun hangi aşamada oluştuğunu gösterebilmesidir. Sistemde iki yerel kayıt varsa benzersizlik kuralına, tek yerel kayıttan iki gönderim çıktıysa kuyruk veya yeniden deneme mantığına bakılır. Tek gönderim var ama iki sağlayıcı işlemi görünüyorsa sağlayıcının kendi tarafındaki olay kayıtları incelenir. Pending ve Processing sipariş sorunları müşteriye görünen statülerin ayrıca nasıl yorumlanacağını anlatır.

API loglarında hangi alanlar tutulmalı?

Bir hata araştırmasında “sipariş gönderildi” satırı yeterli değildir. Yerel sipariş ID, benzersiz istek anahtarı, sağlayıcı kimliği, servis ID, gönderim zamanı, yanıt süresi, HTTP durum kodu, sağlayıcı sipariş numarası ve retry sayısı ilişkilendirilmelidir. Kişisel verileri gereksiz yere kaydetmeyin; API anahtarını ve kullanıcı tokenlarını loglara açık biçimde yazmayın. İşlem izleme için gerektiğinde bağlantıların maskelenmiş veya hashlenmiş gösterimi kullanılabilir.

Operasyon ekibi için unknown siparişleri günlük ayrı bir listede izlemek faydalıdır. Hangi kayıt kaç dakikadır çözümlenmedi, sağlayıcı hangi yanıtı verdi, destek kaydı açıldı mı, işlem manuel mi kapatıldı gibi alanlar tutulabilir. Böylece tekrar oluştuğunda yalnızca maliyet değil, kök neden de görünür. Gözlemlenebilirlik kurulmadan retry sayısını artırmak, çoğu zaman hatayı düzeltmek yerine daha fazla gizler.

Üç örnek hata senaryosu

Senaryo A: Müşteri ödeme sonrasında sipariş butonuna çift tıklıyor. İki HTTP isteği geliyor ama aynı benzersiz müşteri işlem anahtarına bağlanıyor; veritabanı ikinci kaydı reddediyor. Kullanıcıya aynı sipariş ekranı gösteriliyor. Bu örnekte sorun ön yüzde değil, arka uçta garanti altına alınmış oluyor. Butonu geçici devre dışı bırakmak yine de iyi kullanıcı deneyimidir, fakat tek güvenlik katmanı olamaz.

Senaryo B: Sağlayıcı yanıtı 12 saniye sonra geliyor, panele bağlı ağ 10 saniyede timeout veriyor. Sistem işlemi belirsiz listeye alıyor; desteklenen sorgu yöntemiyle kontrol ediyor veya operatöre bildiriyor. İkinci add çağrısı hemen gönderilmiyor. Bu yöntem bazı siparişlerin daha geç görünmesine neden olabilir ama gereksiz çift tahsilatın ve çift teslimatın önüne geçmeyi hedefler.

Senaryo C: Cron işleyicisi dakikada bir çalışıyor; önceki görev hâlâ devam ederken sonraki görev başlıyor. İki süreç aynı siparişi görüyor. Atomik durum geçişi olan tasarımda yalnızca bir süreç sending hakkını kazanıyor. Diğeri kayıt güncellenmiş olduğu için iş üretmiyor. Bu örnek, cron aralığını değiştirmek yerine veritabanı düzeyinde tutarlılık sağlamanın niçin önemli olduğunu gösterir.

Sağlayıcı ID eşleştirmesi ve iade riski

Çift işlem oluşursa aynı yerel siparişe iki sağlayıcı numarası bağlanmış olabilir. Bu durum kısmi tamamlanma, iptal ve maliyet raporlarını hatalı gösterebilir. Bir sağlayıcı siparişi Completed, diğeri Partial olduğunda otomatik olarak tek bir doğru sonuç üretilemez. Operasyon kaydında her iki sağlayıcı işlemi ayrı tutulmalı, hangisinin mükerrer olduğu belgelendirilmeli ve uygun iş akışına göre düzeltme yapılmalıdır.

Müşteri hesabına ikinci kez kredi yansıtmak, mükerrer siparişi gizlemek için ayrı bir hata yaratabilir. Sipariş maliyetini ve müşteri ücretini ayrı defterlerde tutmak gerekir. Müşterinin tek onaylı talebi olduğuna dair kayıt varsa destek ekibi bunu esas almalıdır. Tüm işlem geçmişini değerlendirmeden tek tuşla iadeye veya ikinci sipariş göndermeye karar vermek sorunu büyütebilir.

Yayın öncesi kontrol listesi

Bir API entegrasyonunu canlıya almadan önce çift tıklama, aynı isteğin tekrar gönderilmesi, timeout, worker kapanması, servis değiştirilmesi ve iki cron görevinin eş zamanlı çalışması test edilmelidir. Test ortamında her senaryoda kaç yerel kayıt ve kaç sağlayıcı siparişi oluştuğu sayılmalı; bunların beklenen bire bir ilişkiyi koruyup korumadığı doğrulanmalıdır. Sağlayıcı maliyetinin ikinci kez yazılmadığı da test raporunda görünmelidir.

Testin başarılı olması her olası sağlayıcı davranışını garanti etmez. Özellikle sağlayıcının idempotency desteği yoksa “belirsiz yanıt” için manuel inceleme gereksinimi devam edebilir. Sistemi bu gerçeği saklayacak şekilde değil, açıkça gösterecek şekilde tasarlamak daha güvenlidir. Servis testi rehberimiz API’den sonraki gerçek teslimat performansını değerlendirirken kullanılabilir.

Operasyon ekibi için manuel mutabakat prosedürü

Belirsiz bir API gönderimiyle karşılaştığınızda destek ekibi için küçük bir kontrol akışı oluşturun. Önce yerel sipariş numarasını, gönderim saatini ve varsa sağlayıcıya giden işlem referansını bulun. Ardından sağlayıcının sipariş sorgulama yöntemlerini kullanarak gerçekten açılmış bir iş olup olmadığını kontrol edin. Böyle bir sorgu imkânı yoksa sağlayıcı desteğine, gizli anahtar paylaşmadan tarih ve uygun referans bilgileriyle başvurun. Sonuç doğrulanmadan müşteri hesabında ikinci bir ücretlendirme veya otomatik işlem başlatmayın.

Mutabakat tamamlandığında olayın nedenini ayrıca sınıflandırın: kullanıcı tekrar isteği, kuyruk yarış koşulu, ağ timeout’u, sağlayıcı yanıt biçimi veya manuel müdahale. Bir sonraki benzer olayda aynı hata kodu ve işlem akışı hızla bulunabilsin. Olay kayıtları yalnızca sorunu çözmek için değil, sistem tasarımındaki zayıf noktaları görmek için de işe yarar. Belirsiz bir sonuçla karşılaşmak doğal olabilir; asıl önemli olan bunun gizlenmemesi ve kontrolsüz tekrarlarla çoğalmamasıdır.

Hızlı karşılaştırma tablosu

Sık sorulan sorular

API timeout olursa sipariş kesin oluşmamış mıdır?

Hayır. Sağlayıcı işlemi kabul etmiş ve yanıt panele dönmemiş olabilir. Önce mutabakat kontrolü yapılmalıdır.

Idempotency key her SMM panel API’sinde var mı?

Hayır. Sağlayıcının dokümantasyonunu kontrol edin; destek yoksa yerel benzersizlik ve belirsiz durum yönetimi kurun.

Aynı müşterinin iki ayrı siparişi engellenmeli mi?

Hayır. Amaç gerçekten iki ayrı onayı değil, aynı mantıksal işlemin istemeden iki kez gönderilmesini engellemektir.

En önemli veritabanı önlemi hangisidir?

Benzersiz işlem anahtarı ve atomik durum geçişi birlikte uygulanmalıdır. Tek başına ön yüz kontrolü yeterli değildir.

Çift sipariş oluştuğunda ne yapılmalı?

Her sağlayıcı ID’si ayrı kaydedilir, maliyetler ve müşteri onayı karşılaştırılır, sonra destek ve düzeltme süreci işletilir.

Sonuç

SMM panel çift sipariş sorununda doğru yaklaşım; benzersiz müşteri işlemi, atomik kuyruk sahiplenme, temkinli yeniden deneme ve sağlayıcıyla mutabakat denetimini bir arada kullanmaktır. Müşterinin gördüğü bir siparişin arkasında kaç gerçek sağlayıcı işlemi olduğunu ölçebiliyorsanız, sorunu yalnızca fark etmekle kalmaz tekrarını da sistematik biçimde azaltabilirsiniz. Daha genel API kavramları için API rehberine ve diğer teknik araştırmalar için yazı arşivine göz atabilirsiniz.