API'niz aracılığıyla senkronize edilen en son taşıyıcı takip olaylarını doğrulamak için 6 kontrol
API'nizin en güncel taşıyıcı takip olaylarını senkronize ettiğini doğrulamak için gönderi kimliğini, olay zaman damgalarını, olay ayrıntılarını, teslimat rotasını, olay sıralamasını ve güncelliği bağımsız bir takip görünümüyle karşılaştırın. Başarılı bir API yanıtı veya webhook onayı bu zincirin yalnızca bir bölümünü doğrular; tek başına uygulamanızın taşıyıcının en yeni olayına sahip olduğunu kanıtlamaz.

Bu kılavuz, takip verilerini sipariş yönetim sistemine, müşteriye dönük sayfaya, destek aracına veya uyarı iş akışına aktarmaktan sorumlu geliştiriciler ve operasyon ekipleri içindir. Amaç, bir olayın nerede kaybolduğunu veya değiştiğini bulmak ve ardından işlemi yeniden denemeye, bir eşlemeyi düzeltmeye ya da taşıyıcıdan yeni bilgi gelmesini beklemeye karar vermektir.
Başlamadan önce: “en güncel” ifadesinin ne anlama geldiğini tanımlayın
Üç zamanı birbirinden ayrı tutun: taşıyıcının bir olayın gerçekleştiğini söylediği zaman, takip sağlayıcınızın olayı aldığı veya kullanıma sunduğu zaman ve uygulamanızın olayı kaydettiği zaman. Bu zamanlar farklı olabilir. Taşıyıcı, fiziksel olaydan sonra bir taramayı yayımlayabilir; entegrasyonunuz ise bunu daha sonra işleyebilir. Bu nedenle gerçekleşme zamanına göre en yeni olay, en son alınan kayıt olmak zorunda değildir.
Araştırmaya başlamadan önce bir karşılaştırma noktası seçin. İdeal olarak aynı gönderi için taşıyıcının takip sayfasını veya taşıyıcı tarafından sağlanan başka bir yetkili kaydı kullanın. Bu kullanılamıyorsa uygulamanızı, takip sağlayıcısının mevcut API yanıtıyla karşılaştırın. Bu daha dar karşılaştırma, uygulamanızın sağlayıcıyla eşleşip eşleşmediğini belirleyebilir; ancak sağlayıcının her taşıyıcı taramasına zaten sahip olduğunu kanıtlayamaz. Karşılaştırmayı ne zaman yaptığınızı kaydedin; böylece sonraki bir güncelleme önceki sonucu tutarsız göstermesin.
1. Her iki sistemin de aynı gönderiye atıfta bulunduğunu doğrulayın
Takip numarası, taşıyıcı ve entegrasyonunuz tarafından kullanılan hesap veya gönderi kimliğiyle başlayın. Sorun giderme için yalnızca takip numaraları yeterli olmayabilir: bir numara yazım hatasıyla girilmiş, yanlış taşıyıcıyla ilişkilendirilmiş veya bir sipariş düzenlendikten sonra dahili bir kayıtta yeniden kullanılmış olabilir. Sipariş numarası ile takip numarası da farklı amaçlara hizmet eder. Bir siparişte birden fazla paket bulunabilir; bu nedenle siparişin en güncel durumunu kontrol etmek, güncel olmayan bir paketi gizleyebilir.
- Takip API'sine gönderilen tam takip numarasını ve taşıyıcıyı bulun.
- Yanıtı hangi dahili gönderi veya paket kaydının aldığını doğrulayın.
- Gönderinin kayıttan sonra değiştirilip değiştirilmediğini, bölünüp bölünmediğini, iptal edilip edilmediğini veya yeniden ilişkilendirilip ilişkilendirilmediğini kontrol edin.
- Kaynak kayıtta gösterilen taşıyıcıyı ve numarayı uygulamanızda gösterilenlerle karşılaştırın.
Kimlikler eşleşmiyorsa farkı bir senkronizasyon gecikmesi olarak değerlendirmeyi bırakın. Önce ilişkilendirmeyi düzeltin, ardından olay karşılaştırmasını tekrarlayın. Hassas hesap kimlik bilgilerini bu kayıtlara koymadan bir gönderiyi izleyebilmek için tanılama günlüklerinde yeterli kimliği saklayın.
2. Anlamlarını kaybetmeden olay zamanlarını karşılaştırın
Aday en güncel olayların her biri için taşıyıcının bildirdiği gerçekleşme zamanını, sağlanmışsa belirtilen saat dilimini veya uzaklığını ve uygulamanızın alma ve kaydetme zamanlarını kaydedin. Karşılaştırma için zaman damgalarını ortak bir zaman temeline dönüştürün, ancak orijinal değeri koruyun. RFC 3339, açık uzaklık bilgisine sahip bir internet zaman damgası biçimi tanımlar; kendi zaman damgası alanlarınızı tasarlarken yararlı bir başvuru kaynağıdır. Ancak taşıyıcının veya sağlayıcının her olay için bir saat dilimi sunacağını garanti etmez.
Yalnızca saat gösterimi, varsayılan yerel saat dilimi veya uzaklığı sessizce atan bir ayrıştırıcı, bir olayı başka bir takvim gününe taşıyabilir ya da yanlış sıraya yerleştirebilir. Kaynak belirsiz bir yerel saat veriyorsa, kesin bir UTC anı uydurmak yerine karşılaştırmayı belirsiz olarak işaretleyin. Ayrıca bir olayın gerçekleşme zamanını API yanıt zamanından ayırın: şimdi alınan bir yanıtın daha önce gerçekleşmiş bir olayı içermesi normaldir.
Taşıyıcı veya sağlayıcı görünümünü kontrol ettiğiniz zamanı not edin. Kaynak, API isteğinizden sonra yeni bir tarama yayımladıysa iki görünüm arasındaki fark, önceki isteğin başarısız olduğunu göstermez.
3. Yalnızca başlık durumunu değil, olay yükünü de kontrol edin
En son olayın açıklamasını, konumunu, taşıyıcı durumunu veya kodunu ve ilgili teslimat alanlarını üst kayıttakilerle karşılaştırın. “Transit halinde” gibi normalleştirilmiş bir durum, birbirinden farklı birkaç taramayı özetleyebilir. Uygulamanız yalnızca özeti saklıyorsa yeni bir olay gelmiş olsa bile değişmemiş gibi görünebilir.
Veri işleme kurallarınız izin veriyorsa ham API yanıtını veya saklanan webhook gövdesini inceleyin. Ardından olayı ayrıştırma, alan eşleme, kalıcı depolama ve sunum aşamalarında takip edin. Null alanların varsayılanlarla üzerine yazılmasına, beklenmeyen durum kodlarının genel bir kategoriye düşmesine, metnin kesilmesine veya kullanıcı arayüzünün yalnızca seçili olay türlerini göstermesine dikkat edin. Durum etiketi uyuşmazlığı, eksik olaydan farklıdır: teslimattan çok dönüştürme veya görüntüleme mantığına işaret eder.
Bir konumun veya durumun kesin görünmesine dayanarak teslimat sonucunu varsaymayın. İş akışınızın dayandığı belirli olayı ve alanları doğrulayın. Buna karşılık, üst düzey durumun değişmemesi senkronizasyonun durduğunun kanıtı değildir; yeni alınan bir tarama aynı kategoriye eşlenebilir. Tanılama kaydınız hem üst kaynaktaki olayı hem de kullanıcılara gösterilen değeri korumalıdır.
4. Olayın uygulamanıza nasıl ulaştığını izleyin
Webhook kullanıyorsanız ilgili gönderi ve olay için alım günlüğünü kontrol edin. Uç noktanızın isteği kabul ettiğini, mesajın doğrulamadan geçtiğini ve sonraki işlemenin tamamlandığını doğrulayın. Uç noktanızdan gelen HTTP başarı yanıtı, daha sonra çalışan bir kuyruk işçisinin olayı kaydettiğini kanıtlamaz. İşleme eşzamansızsa hem gelen isteği hem de iş sonucunu inceleyin.
Bir API'yi yokluyorsanız son tamamlanan isteği, bu istekteki gönderi kimliğini, yanıtını ve entegrasyonunuzun kullandığı sayfalama veya alma mantığını kontrol edin. Başarılı bir isteğin ardından veritabanı yazma işlemi başarısız olabilir veya eski bir önbellek okunabilir. Her takip API'sinin aynı sözleşmeyi izlediğini varsaymak yerine entegrasyonunuz için gerçek yanıt alanlarını, kimlik doğrulama gereksinimlerini ve teslimat davranışını doğrulamak üzere sağlayıcının ilgili belgelerini kullanın. 17TRACK entegrasyonu için ilgili başlangıç noktaları Tracking API sayfası ve API documentation'dır; kullandığınız uç nokta ve yöntem için belgelenen davranışı doğrulayın.
Olay işlemesini yeniden çalıştırmaya güvenli hâle getirin. Bir yeniden deneme yinelenen taramalar oluşturmamalı, aynı müşteri bildirimini tekrar tekrar göndermemeli veya daha yeni kaydedilmiş durumu daha eski bir yükle değiştirmemelidir. Uygun yinelenen kayıt anahtarı, sağlayıcınızın gerçekten sunduğu alanlara bağlıdır. Seçtiğiniz anahtarı, aynı durumu veya zaman damgasını paylaşan farklı olaylar üzerinde test edin; yalnızca benzer göründükleri için bu olaylar birleştirilmemelidir.
5. Sıralama ve durum geçişi kurallarını doğrulayın
Kaydedilen olayları açıkça tanımlanmış bir kurala göre sıralayın ve sonucu inceleyin. Birçok uygulamanın “gerçekleşen en son olay” ile “aldığımız en son olay” arasında ayrım yapması gerekir. Gecikmiş eski bir tarama, daha yeni bir taramadan sonra gelebilir. Veritabanınız en son işlenen mesajı doğrudan mevcut gönderi durumu yapıyorsa bu gecikmiş tarama, görüntülenen durumu geriye taşıyabilir.
Saklanan geçmişinizi yalnızca tek durum alanıyla değil, üst kaynak geçmişiyle karşılaştırın. Yeni alınan bir kaydın eklendiğini mi, yinelenen olarak atıldığını mı veya mevcut durumu güncellemesine izin verildiğini mi sorun. Bazı olaylara diğerlerinden öncelik veren kuralları kontrol edin. Böyle bir kural kasıtlı olabilir; ancak altta yatan olayı gizlememeli veya uygulamanın eski bir taramayı geç alması, taşıyıcının bir kilometre taşını geri aldığı izlenimini oluşturmamalıdır.
Uygulamalı bir test için birden fazla olaya sahip bir gönderiyi alın ve mesajlarını üretim dışı bir ortamda farklı bir geliş sırasıyla yeniden oynatın. Olay geçmişinin bütünlüğünü koruduğunu ve müşteriye dönük durumun belgelenmiş kuralınızı izlediğini doğrulayın. Bu, normal ve sıralı bir testin ortaya çıkaramayacağı sıralama hatalarını açığa çıkarır.
6. Güncelliği ölçün ve istisnaları uzlaştırın
Son olarak her katmanın aynı gözlem anında bildiklerini karşılaştırın: taşıyıcı görünümü, takip sağlayıcısı yanıtı, gelen webhook veya yoklama sonucu, veritabanı kaydı ve müşteriye dönük çıktı. Beklenen olayın ilk kaybolduğu katmanı işaretleyin. Bu sınır, genel bir “takip gecikiyor” raporundan daha kullanışlıdır.
Hem taşıyıcının bildirdiği en son olayın yaşını hem de entegrasyonunuzun verileri en son başarıyla kontrol etmesinden veya almasından bu yana geçen süreyi ölçün. Bunlar farklı soruları yanıtlar. Entegrasyonunuz sağlıklı olsa bile bir paketin yeni taşıyıcı taraması olmayabilir; alternatif olarak taşıyıcı yeni bir tarama gösterirken son başarılı isteğiniz eski olabilir. Kendi operasyonel gereksinimlerinizi ve gözlemlediğiniz davranışı yansıtan uyarı eşikleri kullanın. Taşıyıcı ve sağlayıcı düzenlemeleriniz bunu desteklemiyorsa müşterilere sabit bir güncelleme aralığı vaat etmeyin.
Kayıtları seçilen karşılaştırma kaynağından farklı olan gönderiler için küçük bir uzlaştırma kuyruğu oluşturun. Kimlikleri, eksik veya uyuşmayan olayı, ilgili zaman damgalarını, ilk başarısız katmanı ve sonraki eylemi ekleyin. Örneğin sağlayıcı yanıtında bulunup veritabanınızda bulunmayan bir olay, entegrasyon incelemesi gerektirir. Veritabanınızda bulunup takip sayfasında bulunmayan bir olay, görüntüleme veya önbellek kontrolü gerektirir. Taşıyıcının kendisi yeni bir tarama göstermiyorsa başka bir API isteği bunu üretemez.
Operasyonel test basittir: aynı gönderiyi tanımlayabiliyor, bilinen en son üst kaynak olayını bulabiliyor ve anlamını değiştirmeden bu olayı kullanıcıya dönük görünüme kadar takip edebiliyor musunuz? Eğer edemiyorsanız, altı kontrol sorunu belirli bir sınıra indirger ve ekibinize savunulabilir bir sonraki adım sağlar.
SSS
Başarılı bir webhook yanıtı en son olayın senkronize edildiği anlamına mı gelir?
Hayır. Bu yalnızca uç noktanızın bir isteğe başarılı yanıt verdiğini gösterir. Doğrulama, kuyruk işleme, veritabanı kaydı ve görüntüleme işlemlerinin de başarılı olduğunu doğrulayın. İsteğin hangi olayı içerdiğini belirlemek için yükü kontrol edin.
Taşıyıcı sayfası neden API yanıtımdan daha yeni bir tarama gösteriyor?
Öncelikle aynı paketi görüntülediğinizi ve her iki gözlemin karşılaştırılabilir zamanlarda yapıldığını doğrulayın. Taşıyıcının bir olayı yayımlaması ile takip sağlayıcısının bu olayı alması veya kullanıma sunması farklı zamanlarda gerçekleşebilir. Fark devam ederse bir güncelleme garantisi varsaymak yerine belirli gönderiyi araştırmak için sağlayıcının belgelerini ve destek sürecini kullanın.
En güncel durumu seçmek için olay zaman damgasını mı yoksa sistemimin aldığı zamanı mı kullanmalıyım?
İş akışınıza uygun, belgelenmiş bir kural kullanın ve her iki değeri de koruyun. Olay zaman damgası bildirilen etkinliğin ne zaman gerçekleştiğini, alma zamanı ise sisteminizin bunu ne zaman öğrendiğini belirtir. Özellikle kaynak zamanları belirsiz olduğunda veya eski taramalar geç geldiğinde, iki alandan hiçbiri her durumu tek başına çözmez.
API durumu değişmiyor ancak olay listesinde yeni bir giriş varsa ne olur?
Birden fazla taşıyıcı olayı tek bir normalleştirilmiş duruma eşleniyorsa bu beklenen bir durum olabilir. Olay ayrıntılarını karşılaştırın ve uygulamanızın yeni girişi uygun şekilde kaydedip gösterdiğini doğrulayın. Eksik olay ile değişmeyen özet etiketini farklı sorunlar olarak ele alın.
Kaynaklar
- 17TRACK Tracking API — takip API entegrasyonları için ürün referansı.
- 17TRACK API documentation — geçerli entegrasyon sözleşmesini kontrol etmek için referans noktası.
- RFC 3339: Date and Time on the Internet: Timestamps — zaman damgası ve UTC uzaklığı biçimi referansı.


