Kargo Takip API'si E-Ticaret Mağazanıza Nasıl Entegre Edilir
Bir gönderi takip API'sini e-ticaret mağazanıza entegre etmek için sipariş sisteminizi takip sağlayıcısına bağlayın, gönderi ve taşıyıcı verilerini güvenli bir sunucu tarafı isteği üzerinden gönderin, normalleştirilmiş takip olaylarını kaydedin ve elde edilen durumu müşteri ve destek arayüzlerinde görüntüleyin. Güvenilir bir uygulama, yalnızca bir takip numarası alanı eklemekten daha fazlasıdır: taşıyıcı seçimini, durum güncellemelerini, teslimat istisnalarını, yeniden denemeleri, gizliliği ve müşterilerin satın alma sonrası bilgileri gerçekte nasıl kullandığını ele almalıdır.
Bu kılavuz, mağaza sahipleri, geliştiriciler ve operasyon ekipleri için pratik bir entegrasyon yaklaşımını açıklar. Referans noktası olarak 17TRACK'in resmi Tracking API belgelerini kullanır; ancak aynı planlama ilkeleri başka bir çok taşıyıcılı sağlayıcı değerlendirilirken de geçerlidir.
Entegrasyonun neyi başarması gerektiğine karar verin
API uç noktasından ziyade iş sonucuyla başlayın. Çoğu mağaza, “Siparişim nerede?” sorularını azaltmak, alıcılara net bir teslimat görünümü sunmak ve bir müşteri şikâyet etmeden önce operasyonların geciken gönderileri belirlemesine yardımcı olmak ister. Bu hedefler farklı veri ve iş akışları gerektirir.
- Müşteri görünürlüğü: mevcut gönderi durumunu, mevcut olduğunda tahmini teslimat bilgilerini, taşıyıcı ayrıntılarını ve anlamlı en son olayı gösterin.
- Operasyonel görünürlük: personelin taşıyıcılar genelinde geciken, takılan, iade edilen veya istisna durumundaki gönderileri bulmasını sağlayın.
- Otomatik iletişim: bir gönderi tanımlanmış bir duruma ulaştığında onaylanmış e-posta, SMS veya diğer bildirimleri tetikleyin.
- Veri tutarlılığı: farklı taşıyıcı olay etiketlerini mağazanızın güvenilir şekilde kullanabileceği daha küçük bir durum kümesine dönüştürün.
Bir uygulama yöntemi seçmeden önce bu sonuçları tanımlayın. Bir takip API'si gönderi verileri sağlayabilir; ancak hangi olayların müşteri bildirimini hak ettiğine veya mağazanızın bir adres sorununu nasıl ele alması gerektiğine otomatik olarak karar vermez.
Doğru entegrasyon mimarisini seçin
Tipik bir mimari dört katmana sahiptir: ticaret platformu, entegrasyon hizmeti, takip sağlayıcısı ve müşteriye yönelik deneyim. Entegrasyon hizmeti bir backend uygulaması, sipariş yönetim sistemi veya sunucusuz iş akışı olabilir. Bu mantığı sunucuda tutmak, API kimlik bilgilerini tarayıcı koduna yerleştirmekten genellikle daha güvenlidir.
Temel akış şu şekildedir:
- Ödemesi alınmış bir sipariş karşılanır ve bir takip numarası ile taşıyıcı alır.
- Backend'iniz gönderi ayrıntılarını takip sağlayıcısına gönderir.
- Sağlayıcı, API tasarımına göre bir takip tanımlayıcısı veya takip verileri döndürür.
- Sisteminiz sağlayıcı referansını kaydeder ve gönderi olaylarını dahili durumlarla eşleştirir.
- Zamanlanmış bir güncelleme işlemi veya desteklenen olay bildirimi gönderiyi yeniler.
- Mağazanız, sipariş sayfanız, destek araçlarınız ve bildirim hizmetiniz kendi normalleştirilmiş verilerinizden okur.
Her sayfa görüntülemesinde taşıyıcıya veya takip API'sine çağrı yaptırmayın. Bu tasarım yavaş müşteri deneyimlerine, yinelenen isteklere, hız sınırı sorunlarına ve tutarsız sonuçlara yol açabilir. En son kabul edilen takip durumunu veritabanınızda saklayın ve kontrollü arka plan görevleri veya sağlayıcının desteklenen güncelleme mekanizması aracılığıyla yenileyin.
Kodlamadan önce sağlayıcının belgelerini doğrulayın
Uygulamadan önce sağlayıcının resmi API belgelerini kimlik doğrulama, istek biçimleri, yanıt alanları, desteklenen taşıyıcılar, hata davranışı, güncelleme mekanizmaları ve hesap gereksinimleri açısından inceleyin. 17TRACK, özel bir Tracking API ürün sayfası ve geliştirici belgeleri sunar. Güncel API davranışı için forumlardan veya eski entegrasyon eğitimlerinden kopyalanan örneklere güvenmek yerine bu sayfaları yetkili kaynak olarak kabul edin.
Belgelerden kısa bir gereksinim kontrol listesi oluşturun:
- API kimlik bilgileri nasıl verilir, saklanır, yenilenir ve iptal edilir?
- İstek bir taşıyıcı kodu gerektiriyor mu, yoksa hizmet taşıyıcıyı takip numarasından tanımlayabilir mi?
- Hangi yanıt alanları gönderiyi, durumu, konumu, zaman damgalarını ve istisna mesajını tanımlar?
- Hesap bunları destekliyorsa asenkron güncellemeler nasıl iletilir?
- Belgelenmiş istek sınırları, faturalandırma kuralları, zaman aşımı beklentileri ve hata kodları nelerdir?
- Yinelenen takip numaraları, geçersiz numaralar, bilinmeyen taşıyıcılar ve teslim edilmiş gönderiler nasıl ele alınmalıdır?
Bir özelliği ürün adından çıkarsamayın. Örneğin “gerçek zamanlı” ifadesi, her taşıyıcı olayının hemen görüneceğine dair bir garanti yerine ürün konumlandırma ifadesi olabilir. Uygulamanız, taşıyıcı taramalarının gecikebileceğini ve bir API'nin taşıyıcının bildirmediği bir taramayı oluşturamayacağını açıklamalıdır.
Sipariş ve gönderi verilerini hazırlayın
Takibi oluşturmak için genellikle en uygun an sipariş oluşturma değil, gönderinin karşılanmasıdır. Bir sipariş ödenmiş olabilir ancak henüz paketlenmemiş olabilir ve taşıyıcı paketi kabul etmeden önce bir takip numarası oluşturulabilir. Karşılama iş akışınızda hangi olayın takip kaydını oluşturması gerektiğine karar verin.
En azından dahili gönderi kaydınız aşağıdaki değerleri birbirinden ayırmalıdır:
- Dahili sipariş kimliği ve karşılama kimliği
- Takip numarası
- Taşıyıcı adı veya taşıyıcı kodu
- Operasyonel olarak gerekli olduğunda varış ülkesi veya bölgesi
- Döndürülmüşse sağlayıcı takip kimliği veya abonelik referansı
- Mevcut normalleştirilmiş durum
- Son olay zaman damgası ve son senkronizasyon zaman damgası
- Ham sağlayıcı yanıtı veya kontrollü bir denetim referansı
Sipariş verilerini ve gönderi verilerini ayrı tutun. Bir sipariş birden fazla paket, bölünmüş gönderiler veya farklı taşıyıcılar içerebilir. Tek siparişin tek takip numarasına sahip olduğu varsayımı, bir deponun ürünleri ayrı ayrı göndermesi durumunda genellikle başarısız olur.
İdempotent bir işlem kullanın. Karşılama sistemi aynı isteği yeniden denerse entegrasyon, yinelenen abonelikler veya yinelenen müşteri mesajları oluşturmak yerine mevcut gönderiyi güncellemelidir. Pratik bir idempotensi anahtarı, sağlayıcının kendi gereksinimlerine tabi olmak üzere dahili karşılama kimliğinizi, taşıyıcı tanımlayıcınızı ve takip numaranızı birleştirebilir.
Müşteriler için taşıyıcı durumlarını normalleştirin
Taşıyıcılar farklı etiketler ve olay dizileri kullanır. Mağazanız Bilgi alındı, Transit halinde, Dağıtıma çıktı, Teslim edildi, İstisna ve İade edildi gibi küçük bir dahili durum modeli tutmalıdır. Destek personeli için orijinal taşıyıcı olayını koruyun, ancak mağaza mantığı için normalleştirilmiş durumu kullanın.
Normalleştirme kuralları açık olmalıdır. “Etiket oluşturuldu” olayı, paketin hareket ettiğinin kanıtı olarak sunulmamalıdır. “Teslim edildi”, müşterinin paketi fiziksel olarak bulduğuna dair bir garanti olarak değil, taşıyıcı tarafından bildirilen bir olay olarak ele alınmalıdır. Bir istisna, gönderi daha sonra devam edebilecek olsa bile sessizce “transit halinde” durumuna dönüştürülmemelidir.
Ayrıca durum önceliğini ve gerileme işlemlerini tanımlayın. Gecikmiş bir taşıyıcı beslemesi olayları sıra dışı getirebilir. Mevcut olduğunda olay zaman damgalarını karşılaştırın, ham olayı kaydedin ve daha yeni bir teslim edildi durumunu daha eski bir transit halinde durumuyla değiştirmekten kaçının. Zaman damgaları eksik veya belirsizse, bir sıra uydurmak yerine kaydı ihtiyatlı bir güncelleme için işaretleyin.
Sunucu tarafı istek akışını oluşturun
Backend'iniz takip sağlayıcısını çağırmadan önce gelen karşılama verilerini doğrulamalıdır. Takip numarasının mevcut olduğunu kontrol edin, yanlışlıkla eklenmiş boşlukları temizleyin, uygun olduğunda beklenen biçimi doğrulayın ve taşıyıcı değerinin kabul edilebilir olduğunu onaylayın. Olağandışı ancak geçerli takip numaralarını yalnızca dar bir yerel kalıpla eşleşmedikleri için reddetmeyin.
Sağlayıcıdan bağımsız bir istek akışı şu şekilde gösterilebilir:
karşılama olayını al
sipariş ve gönderi alanlarını doğrula
mevcut bir idempotensi anahtarı olup olmadığını kontrol et
belgelenmiş takip isteğini sunucudan gönder
sağlayıcı yanıtını ve dahili gönderi kaydını sakla
yenileme işlemini sıraya al veya desteklenen güncelleme olayını işle
yalnızca onaylanmış alanları mağazaya yayınlaGeçici hatalar için kısa zaman aşımları, sınırlı sayıda yeniden deneme ve üstel geri çekilme kullanın. Her hatayı yeniden denemeyin. Kimlik doğrulama hatası, geçersiz istek veya desteklenmeyen taşıyıcı genellikle tekrarlanan çağrılar yerine düzeltme gerektirir. Bir korelasyon kimliği, istek sonucunu ve sağlayıcı hata kategorisini günlüğe kaydedin; ancak API anahtarlarını, müşterilerin tam adreslerini veya gereksiz kişisel bilgileri uygulama günlüklerine yazmaktan kaçının.
Sağlayıcı yanıtını müşteriye yönelik modelden ayrı tutun. Bu, sağlayıcıları değiştirmeyi, bir eşleme kuralını düzeltmeyi ve herkese açık sipariş sayfası üzerinden gösterilen bilgileri sınırlamayı kolaylaştırır.
Müşteri takip deneyimini tasarlayın
Bir takip sayfası üç soruyu hızlıca yanıtlamalıdır: mevcut durum nedir, en son ne oldu ve müşteri bundan sonra ne yapmalı? Sipariş referansını, gizliliğe duyarlı biçimde gösterilen gönderi numarasını, taşıyıcı adını, en son olay zamanını ve istisnalar için net bir açıklamayı gösterin.
Boş bir zaman çizelgesini teknik bir arıza gibi göstermeyin. İlk taşıyıcı taramasından önce, gönderi bilgilerinin alındığını ve hareketin henüz görünür olmayabileceğini açıklayın. Bir istisna için yalnızca kaynak veriler bunu desteklediğinde sade bir açıklama sunun. Taşıyıcı bir adres sorunu bildirirse, işletmenizin gerçekten sağlayabileceği destek sürecine veya müşteri hizmetleri işlemine bağlantı verin.
Shopify veya başka bir ticaret platformu üzerinde oluşturulan mağazalar için platformun karşılama olaylarını, müşteri hesaplarını, sipariş durum sayfalarını ve bildirim şablonlarını nasıl sunduğunu kontrol edin. Shopify'ın resmi geliştirici belgeleri webhook'lar ve karşılama verileri için kaynaklar içerir. Platform API'leri ve sürümlendirilmiş belgeler değişebilir; bu nedenle üretim çalışmasından önce uygulamanızın kullandığı sürümü doğrulayın.
Bildirimleri dikkatli kullanın
Gönderi olayları faydalı tetikleyicilerdir, ancak her taşıyıcı taraması için mesaj göndermek bildirim yorgunluğuna yol açabilir. Gönderi oluşturma, anlamlı transit ilerlemesi, dağıtıma çıkma, teslimat ve seçilmiş istisnalar için bildirim gönderme gibi iş kuralları tanımlayın. Yinelenenleri bastırın ve tekrarlanan gecikme mesajları için minimum bir aralık ekleyin.
Operasyonel uyarıları müşteri bildirimlerinden ayırın. Bir destek ekibinin bir gönderinin birkaç gün boyunca değişmediğini bilmesi gerekebilirken müşterinin yalnızca taşıyıcı somut bir istisna bildirdiğinde mesaj alması gerekebilir. Zaman eşiği, operasyonel temeli olmayan evrensel bir sayı yerine hizmet seviyesini, varış yerini, taşıyıcıyı ve gönderim yöntemini yansıtmalıdır.
Gerçek teslimat senaryolarıyla test edin
Bir takip numarası için alınan başarılı yanıt, üretime geçiş için yeterli değildir. Birden fazla taşıyıcıyı, ülkeyi, gönderi türünü ve olay durumunu içeren bir test matrisi oluşturun. En azından şunları test edin:
- Taşıyıcı taraması olmayan yeni oluşturulmuş bir gönderi
- Normal transit halindeki bir gönderi
- Dağıtıma çıkmış bir gönderi
- Teslim edilmiş bir gönderi
- Bir istisna veya adresle ilgili olay
- İade edilmiş bir gönderi
- Geçersiz bir takip numarası
- Yinelenen bir karşılama olayı
- Gecikmiş bir sağlayıcı yanıtı veya zaman aşımı
- Sırası dışında gelen bir olay
API kullanılabilirliğinden fazlasını ölçün. Doğru siparişin güncellenip güncellenmediğini, müşterinin anlaşılır bir dil görüp görmediğini, yinelenen bildirimlerin bastırılıp bastırılmadığını ve destek personelinin orijinal taşıyıcı olayını belirleyip belirleyemediğini kontrol edin. Önce sınırlı bir kullanıma sunum gerçekleştirin, operasyonel bir geri dönüş seçeneğini koruyun ve sürümden sonra hata kategorilerini izleyin.
Güvenlik, gizlilik ve bakım
Kimlik bilgilerini tema kodunda, mobil kodda, kaynak denetiminde veya tarayıcı isteklerinde değil, bir gizli bilgi yöneticisinde ya da korumalı bir ortam değişkeninde saklayın. Gönderi verilerine erişimi role göre kısıtlayın, HTTPS kullanın ve ham yanıtların ve müşteriyle ilgili alanların ne kadar süreyle saklandığını gözden geçirin.
Sağlayıcının belgelerini ve ticaret platformunuzun API sürümünü düzenli olarak gözden geçirin. Taşıyıcı desteği, olay adları, kimlik doğrulama gereksinimleri ve platform webhook davranışı değişebilir. Durum eşleme kurallarını yapılandırılabilir tutun, bunların arkasındaki varsayımları belgeleyin ve başka bir müşteri mesajı göndermeden bir gönderiyi yeniden oynatmayı veya uzlaştırmayı mümkün kılın.
Mağazanız taşıyıcılar arasında özel bir takip entegrasyonuna ihtiyaç duyduğunda 17TRACK'in API'si değerlendirmeye değer bir seçenektir. Yine de uygun seçim kullandığınız taşıyıcılara, hizmet verdiğiniz ülkelere, hesabınız için belgelenmiş güncelleme davranışına, beklenen istek hacminize ve ekibinizin gerektirdiği operasyonel kontrollere bağlıdır. Üretim tasarımına karar vermeden önce bu noktaları resmi belgelerde ve kontrollü bir kavram kanıtında doğrulayın.
SSS
Takip, sipariş verildiğinde mi oluşturulmalıdır?
Genellikle hayır. Gönderi kaydını, karşılama iş akışınızda taşıyıcı ve takip numarası bulunduğunda oluşturun veya etkinleştirin. Ödeme sırasında oluşturmak, daha sonra iptal edilen, karşılanmayan veya bölünen siparişler için kayıtlar oluşturabilir.
Bir takip API'si gerçek zamanlı teslimat bilgilerini garanti edebilir mi?
Hiçbir API, her taşıyıcı taramasının hemen görünür olacağını garanti edemez. Sağlayıcı taşıyıcı verilerine bağlıdır ve taşıyıcı sistemleri olayları gecikmeli veya eksik bildirebilir. Zaman damgalarını ve durum dilini doğru şekilde sunun ve ilgili belgeler ile hizmet sözleşmesi bu vaadi desteklemediği sürece kesin bir yenileme zamanı vaat etmekten kaçının.
Tarayıcı doğrudan takip API'sini çağırmalı mı?
Çoğu uygulamada hayır. Kimlik bilgilerinin korunması, yanıtların normalleştirilebilmesi, yeniden denemelerin kontrol edilebilmesi ve müşteriye yönelik verilerin filtrelenebilmesi için sunucu tarafı bir entegrasyon kullanın. Mağaza genellikle uygulamanızdan onaylanmış bir gönderi görünümünü okumalıdır.
Bir mağaza tek siparişteki birden fazla paketi nasıl ele almalıdır?
Üst sipariş kimliğini korurken her karşılamayı veya paketi ayrı bir gönderi olarak modelleyin. Sipariş sayfası genel bir özet ve her paket için ayrı zaman çizelgeleri gösterebilir. Bu, başka bir paketin teslim edildi durumunun arkasında geciken bir paketin gizlenmesini önler.
İzlenecek ilk üretim metriği nedir?
Karşılama oluşturulmasından doğru ve müşterinin görebileceği güncellemeye kadar tüm akışı izleyin. Tek başına API başarısı yeterli değildir. Yinelenen kayıtları, güncel olmayan gönderileri, eşlenmemiş olayları, bildirim hatalarını ve manuel düzeltme gerektiren gönderilerin yüzdesini takip edin.
