WooCommerce 11.3 İade API Tutarı Nasıl Doğrulanır?

WooCommerce iade API isteği neden artık hata verebilir?

WooCommerce 11.3 beta sürümünde, sipariş iadesi oluşturan REST API çağrısında açıkça gönderilen satır tutarları daha sıkı doğrulanıyor. Entegrasyonunuz POST /wp-json/wc/v3/orders/{order_id}/refunds isteğine line_items ekliyorsa, satırların toplamı üst düzey iade tutarını veya satırın kalan iade edilebilir miktarını aştığında isteğin 400 ya da 422 ile reddedilmesi beklenebilir. 26 Ekim 2026 geliştirici duyurusu bu davranışı yaklaşan 11.3 sürümü için anlatıyor. 28 Ekim itibarıyla 11.3 beta test aşamasındadır; bunu tüm canlı mağazalarda gerçekleşmiş bir değişiklik gibi değerlendirmeyin.

Önce mağazanın sürümünü, iade oluşturan bileşeni ve gönderilen alanları kaydedin. Yönetim panelinden elle yapılan iade ile harici ERP, müşteri hizmetleri aracı veya özel web uygulamasından gelen API isteği aynı yol değildir. Sorun yalnızca API ile açık tutar gönderen akışta görünüyorsa, müşteri arayüzünü değiştirmeden önce istek hesabını ve hata yanıtını inceleyin. Yanıtın alınmış olması iadenin yapıldığı anlamına gelmez.

Hangi tutarlar birlikte kontrol edilmeli?

Bir iade isteğinde siparişin kalan iade edilebilir tutarı, her ürün veya ücret satırının kalan tutarı, vergi payı ve üst düzey amount ayrı kavramlardır. Entegrasyon satır bazında refund_total ve refund_tax veriyorsa toplamı yalnızca ekrandaki ürün fiyatına bakarak hesaplamasın. İndirim, kargo ve kısmi iade geçmişi nedeniyle bir satırın bugün iade edilebilen kısmı ilk satın alma tutarından küçük olabilir.

WooCommerce REST API belgesi iade oluşturma isteğinde amount ile line_items alanlarını ve hesaplanan tutar seçeneğini tanımlar. Güncel 11.3 duyurusu ise özellikle açıkça verilen satır tutarının doğrulama sınırını değiştirir. Eski örnek isteği körlemesine kopyalamak yerine mağazanın yüklü sürümüne uygun davranışı test edin. Aynı siparişe daha önce iade yapılmışsa kalan sınırı işlem anında yeniden okuyun.

Bir kontrol tablosunda sipariş kimliği, satır kimliği, orijinal miktar, önceki iadeler, istenen miktar, satır tutarı, vergi tutarı ve toplam tutar yer alsın. Bunlar müşteri destek personelinin göreceği ekranda kişisel bilgiyle birlikte gereksizce gösterilmemelidir. Teknik günlükte de ödeme kartı verisi veya müşterinin açıklama metni yerine istek kimliği, satır sayısı ve sonuç kodu yeterli olabilir.

400 ve 422 yanıtları nasıl ayrılır?

11.3 ön duyurusu, tutarsız açık iade tahsislerinin woocommerce_rest_* hata koduyla 400 veya 422 dönebileceğini belirtir. Örneğin üst düzey amount değeri satırda iade edilmek istenen tutardan küçükse bir doğrulama hatası oluşabilir. Bir satırın kalan iade edilebilir miktarı aşılırsa farklı bir hata sınıfı dönebilir. Bu örnekleri bütün kurulumlar için tek ve sabit hata mesajı olarak kodlamayın; API cevabındaki kodu ve ilgili alanı saklayın.

Özellikle ödeme hizmeti tarafında iki durum ayrılmalı: WooCommerce iade kaydı oluşmadı mı, yoksa ödeme sağlayıcısına para iadesi ayrıca gönderildi mi? Entegrasyonun hangi adımı yönettiği açık değilse kullanıcıya “iade tamamlandı” mesajı vermeyin. Hatalı API isteği için aynı yükü otomatik tekrar göndermek, iş kuralındaki tutarsızlığı çözmez. Önce satır dağılımını düzeltin, sonra siparişin güncel iade durumunu kontrol ederek yeniden deneyin.

Beta ortamında hangi senaryolar sınanmalı?

Canlı sipariş üzerinde test iadesi oluşturmak yerine kopya veya test mağazasında örnek siparişler hazırlayın. Tam iade, tek ürünün kısmi iadesi, vergi içeren satır, kargo satırı, indirimli ürün ve daha önce kısmen iade edilmiş sipariş için ayrı senaryolar kurun. Her senaryoda beklenen sipariş kaydı ile API durum kodunu karşılaştırın. İstek başarısız olduğunda muhasebe ve müşteri panelinde iade varmış gibi görünmediğini de doğrulayın.

Kısa bir tablo yeterlidir: örnek sipariş, mevcut kalan tutar, istek amount, satır toplamı, beklenen sonuç, gerçek HTTP kodu ve takip aksiyonu. Başarılı sonuçta yalnızca 2xx koduna değil, dönen iade kimliğine ve siparişteki son duruma bakın. Başarısız sonuçta kullanıcıya ham teknik hata göstermek yerine hangi alanın yeniden hesaplanması gerektiğini operatöre anlatan bir açıklama sunun.

WooCommerce 11.3 henüz beta olduğundan yayına çıkış takvimi veya son ayrıntılar değişebilir. Duyuruda planlanan sürüm haftası belirtilse de mağaza güncellemesini o gün otomatik olmuş saymayın. Sürüm yayınlandığında son sürüm notunu ve kurulu eklentilerin uyumunu yeniden inceleyin. Özellikle muhasebe veya ERP eklentisi iade isteğini oluşturuyorsa eklenti sağlayıcısının test sonucunu ayrıca isteyin.

Ödeme ve müşteri iletişimi nasıl tasarlanmalı?

Müşteri bir iade talebi açtığında “talep alındı”, “işlem inceleniyor” ve “ödeme iadesi tamamlandı” aşamaları ayrı yazılmalıdır. API doğrulama hatası, müşterinin talebinin reddedildiği anlamına gelmez; iç operasyonun tutarı düzelterek işlemi tekrar değerlendirmesi gerekebilir. Destek ekibi siparişin güncel durumunu görmeden kesin ödeme tarihi söylememelidir.

İade talebinin müşteri tarafından nasıl açılacağını planlıyorsanız e-ticarette iade ve değişim talep portalı yazısı başvuru ve onay akışını açıklar. Buradaki problem, portalın görünümü değil, onay sonrası WooCommerce REST isteğinin doğru tutarı taşımasıdır. Portalda doğru görünen bir talep bile entegrasyonun satır hesabı hatalıysa API’de başarısız olabilir.

Sürüm geçişi için karar kaydı

Geliştirici ve operasyon ekibi, hangi sistemin iade tutarını hesapladığını tek cümleyle belgelemeli. Birden çok sistem aynı tutarı yeniden hesaplıyorsa yuvarlama ve vergi farkları ortaya çıkabilir. Entegrasyonun kaynak sistemi, yetkili kişi, test ortamı, geri dönüş planı ve canlıya alma koşulları yazılı olsun. Mümkünse iade yaratmadan önce mevcut sipariş ve kalan tutar yeniden okunmalı; eşzamanlı iki çalışan aynı siparişe işlem yapıyorsa ikinci isteğin sonucuna ayrıca bakılmalıdır.

Webinle’nin web yazılım hizmeti kapsamında WooCommerce ile ERP veya özel panel arasındaki iade akışı gözden geçirilebilir. Görüşmeye örnek anonimleştirilmiş istek, hata kodu, mağaza sürümü ve sipariş durumunun nasıl eşlendiğini getirin. Böylece hangi hesap kuralının düzeltilmesi, hangi testin eklenmesi ve müşteriye hangi aşamada bildirim gönderilmesi gerektiği somutlaşır.

Yayın öncesi son kontrolde aynı örnek isteği eski ve hedef sürümde karşılaştırın. Farklı sonuç varsa bunu sürüm notuyla birlikte kaydedin; tahmini bir başarı varsayımıyla canlı iadeleri otomatik işlemeye başlamayın.