Ticimax İade API Entegrasyonu Adım Adım Rehber

Bir Ticimax mağazası işletiyorsanız ve buna bir iade portalı eklemeye çalıştıysanız, acıyı zaten biliyorsunuzdur: Ticimax, Shopify değildir. Tek tıkla kurulabilecek bir Uygulama Mağazası listesi yoktur, OAuth yönlendirme akışı yoktur ve sipariş ile iade uç noktalarına ait dokümantasyon Batı platformlarının yayınladığından çok daha inceliklidir. Çoğu mağaza sahibi ya token her süresi dolduğunda bozulan kırılgan bir dahili script yazar ya da pes edip iadeleri e-posta ve WhatsApp üzerinden elle işlemeye devam eder. Sipariş hacmi ayda birkaç yüzü geçtiğinde ikisi de sürdürülebilir değildir. Bu rehber, iade otomasyonunu canlı bir Ticimax mağazasına tam olarak nasıl bağladığımızı belgeliyor: token doğrulama el sıkışması, sipariş sorgulama çağrıları ve mağaza önyüzüne geri yazılan iade senkronizasyonu, artı ilk seferinde bize gerçek hata ayıklama saatlerine mal olan tuzaklar.

Ticimax önemlidir çünkü Türkiye pazarında Shopify veya Magento'nun başka yerlerde hakim olduğu şekilde baskın yerel ticaret platformlarından biridir. Yerel platformlar, küresel oyuncular genişlese bile kendi bölgelerinde orantısız pazar payını korurlar; bu da genel bir küresel entegrasyon oyun kitabının Ticimax kurulumuna neden temiz bir şekilde uymadığını tam olarak açıklar (kaynak). Platformlar arasında mağazalara destek veren bir Çözüm Mühendisiyseniz, Ticimax'i farklı markalamaya sahip bir Shopify klonu değil, kendine özgü bir entegrasyon yüzeyi olarak ele alın. Bu otomasyonu sıfırdan kuran ekipler için, platformdan bağımsız mimariyi kapsayan iade API entegrasyon rehberimiz bu adım adım rehberin varsaydığı temeli oluşturur.

Adım 1: Token doğrulaması ve neden sürekli süresi doluyor

Ticimax'in REST katmanı (partner dokümantasyonunda genellikle rest1 olarak anılır), OAuth yerine token tabanlı bir kimlik doğrulama modeli kullanır. API kimlik bilgilerinizi bir bearer token ile değiştirirsiniz ve bu token süresi dolmadan önce kabaca bir gün geçerlidir. Bu, tüm entegrasyondaki en büyük tuzaktır: Shopify'ın uzun ömürlü erişim tokenlarının aksine, senkronizasyon sırasında süresi dolan bir Ticimax tokenı her kod yolunda belirgin bir hata fırlatmaz. Bazı uç noktalar genel bir hata döndürür, diğerleri ise 'token öldü' yerine 'sipariş bulunamadı' gibi görünen boş bir yük döndürür. İade otomasyonunuz tokenı 24 saatten daha kısa bir programda proaktif olarak yenilemiyorsa, sonunda yanlış-negatif bir sonuç göndereceksiniz: bir müşteri iade gönderir, sistem eşleşen sipariş bulunamadığını bildirir ve vaka her şeyi manuel olarak yeniden çalıştırması gereken bir insana yükseltilir.

Çözüm basit ama isteğe bağlı değildir: süre dolma penceresinin oldukça içinde çalışan bir token yenileme işi kurun, tokenı bir zaman damgasıyla önbelleğe alın ve her API çağrı grubundan önce saatler önce aldığınız bir tokena güvenmek yerine bu zaman damgasını kontrol edin. Token süre dolmasını izlemenizde uç bir durum değil, birinci sınıf bir hata modu olarak ele alın.

• Saat sapması ve yeniden deneme gecikmelerine pay bırakmak için her 24 saatte bir değil, her 6-8 saatte bir yeni bir token isteyin.
• Tokenı açık bir süre dolma zaman damgasıyla saklayın, dokümantasyondan sabit bir TTL varsaymayın.
• Her alt akış API çağrısını bir kontrolle sarın: önbelleğe alınmış token süresinin dolmasına 15 dakikadan az kaldıysa, devam etmeden önce yenileyin.
• Her kimlik doğrulama hatasını hata anındaki token yaşıyla birlikte kaydedin; sessizce çalışmayı durdurmuş bir yenileme işini yakalamanın en hızlı yolu budur.

Adım 2: order2 ve getOrders ile sipariş sorgulama

Geçerli bir token elinizde olduğunda, iade akışı müşterinin siparişini çözümlemeyle başlar. Ticimax, partner entegratörlerin tipik olarak order2 modülü olarak adlandırdığı yapı üzerinden sipariş verilerini sunar; birincil sorgulama yöntemi olarak getOrders çağrısı kullanılır. Pratikte bu, sipariş numarasına veya müşteri kimliğine göre sorgulama yapmak ve çoğu küresel platformun döndürdüğünden oldukça daha ayrıntılı bir yanıt yapısını ayrıştırmak anlamına gelir — iç içe geçmiş kalem nesneleri, Türkçe durum dizeleri ve indirim kodları veya kargo yöntemi gibi opsiyonel alanlarda tutarsız null işleme bekleyin.

Burada iki şey ekipleri takılmaya götürür. Birincisi, sipariş durum dizeleri Shopify'ın fulfillment_status numaralandırması gibi standartlaştırılmamıştır; Ticimax'in yerel durum kelime dağarcığından kendi dahili iade uygunluk durumlarınıza bir eşleme tablosu oluşturmanız ve sürdürmeniz gerekir. İkincisi, getOrders yanıtları iade pencerenizin çok dışındaki geçmiş siparişleri içerebilir, bu yüzden uygunluk filtrelemesi (30 gün, 14 gün, mağazanızın politikası ne belirtiyorsa) kendi mantık katmanınızda gerçekleşmelidir — Ticimax bunu sizin için filtrelemez. Bunu ilk kez uçtan uca yapılandırıyorsanız, Ticimax iade kurulumu kaynağımız bu API katmanıyla eşleşen mağaza tarafı yapılandırmayı adım adım anlatır.

Sipariş sorgulama adımı, çoğu Ticimax entegrasyonunun ya güvenilir bir şekilde çalıştığı ya da bir destek talebi üreticisi haline geldiği yerdir. Durum eşlemesini ve uygunluk filtrelemesini bir kez doğru yapın, sonrasında uygunluk kontrolleri, etiket oluşturma ve iade senkronizasyonu dahil her şey bu güvenilirliği devralır.

Adım 3: Mağazaya geri iade senkronizasyonu

Bir iade onaylandığında ve ürün teslim alındığında, sipariş kaydının, müşteriye görünen sipariş geçmişinin ve mağazanın muhasebe mutabakatının hepsinin birbirleriyle uyuşması için iadenin Ticimax'e geri yazılması gerekir. Bu bir yazma işlemidir ve salt okunur sipariş sorgulama adımına kıyasla riski önemli ölçüde artırır. Başarısız veya yinelenen bir iade yazma işlemi, başarısız bir sipariş sorgulamasından çok daha maliyetlidir çünkü doğrudan parayı ve müşteri güvenini etkiler.

İade senkronizasyonunu ilk günden itibaren idempotent bir işlem olarak kurun: her iade yazma işlemine kendi iade sisteminize ait bir referans kimliği ekleyin ve tekrar yazmadan önce bu referansı kontrol edin. Idempotency koruması olmadan bir ağ zaman aşımını yeniden denemek, mağazaların bir müşteriyi çift iade etmesine yol açan şeydir; bu hem finansal bir kayıp hem de çok garip bir destek görüşmesidir. Bunu iade API webhook'ları yazımızda anlatılan yeniden deneme ve teslimat garantileriyle eşleştirin, çünkü çoğu üretim ortamındaki Ticimax entegrasyonu iade-yazma çağrısını iade portalına giden bir dış webhook ile eşleştirir; böylece müşteri, yalnızca manuel bir senkronizasyon işi çalıştıktan sonra değil, neredeyse gerçek zamanlı olarak durum güncellemelerini görür.

Canlıya almadan önce test etmek

Ticimax'in API yüzeyi küresel platformlara göre dokümantasyon açısından daha inceliksiz olduğu için, kendi test paketinizi dokümantasyondan çok gerçek referans olarak ele alın. Herhangi bir Ticimax iade entegrasyonunu üretime almadan önce, yukarıdaki hata modlarını gerçek bir müşteriden önce yakalayan sabit bir kontrol listesinden geçiyoruz.

1. 1Oturum ortasında bir token süre dolmasını zorlayın ve yenileme mantığının devam eden isteği kaybetmeden kurtardığını doğrulayın.
2. 2Politika penceresinin tam içinde ve tam dışında olan bir sipariş için iade talebi gönderin ve uygunluk mantığının dışarıdaki durumu reddettiğini doğrulayın.
3. 3İade yazma sırasında bir ağ zaman aşımı simüle edin ve yeniden denemenin ikinci bir iade oluşturmadığını doğrulayın.
4. 4Mağazanızın gerçekten kullandığı her Ticimax sipariş durum dizesinin, varsayılan bir yedeğe değil dahili numaralandırmanızda tanımlı bir değere eşlendiğini doğrulayın.
5. 5Bir durum değişikliği için webhook teslimatını doğrulayın, ardından bilerek webhook'u düşürün ve polling yedeğinizin güncellemeyi kabul edilebilir bir süre içinde hâlâ yakaladığını doğrulayın.

Platforma özgü olmak neden göründüğünden daha önemli

Bir iade API entegrasyonunu, bir mağazanın kullanabileceği her platforma şablonlaştırabileceğiniz çözülmüş bir problem gibi ele almak cazip gelir. Ticimax bunun en net karşı örneğidir: kimlik doğrulama modeli, veri şekilleri ve operasyonel tuhaflıklar Shopify veya headless bir ticaret yığınından yeterince farklıdır, öyle ki kopyala-yapıştır bir entegrasyon, bir müşteri şikayet edene kadar tespit edilmesi zor şekillerde sessizce başarısız olur. Platforma özgü tuhaflıklar için gerçek mühendislik zamanı ayırmak — özellikle token süre dolma davranışı için — zamanında teslim edilen bir iade otomasyonu projesi ile üretimde keşfedilen hata düzeltmelerinin ikinci bir sprintine sürüklenen bir proje arasındaki farkı yaratır.