Bir Takip API'si hangi verileri döndürmeli? Mevcut durumun ötesinde 12 alan?
A tracking API, “Transit halinde” gibi yalnızca bir etiketten fazlasını döndürmelidir. Mevcut durumun ötesinde gönderi tanımlayıcılarını, taşıyıcı kimliğini, ayrıntılı durum bilgilerini, orijinal taşıyıcı mesajlarını, olay geçmişini, olay zaman damgalarını, konumları, tahmini teslimat bilgilerini, istisnaları, taşıyıcı devirlerini, teslimat ayrıntılarını ve verilerin güncelliğine ilişkin meta verileri arayın. Bu 12 veri grubu birlikte, geliştiricilerin güvenilir iş akışları oluşturmasına ve operasyon ekiplerinin harekete geçmek için yeterli bağlama sahip olmasına yardımcı olur.

Bu, geliştiriciler, teknik satın alma ekipleri ve e-ticaret operasyon ekipleri için önerilen bir yanıt sözleşmesidir; her taşıyıcının veya API’nin her alanı sağladığı iddiası değildir. Bazı değerlerin kullanılamaması normaldir. Daha iyi tasarım, bu boşlukları varsayımlarla doldurmak yerine açıkça belirtir.
Takip verilerini kullanışlı kılan nedir?
Güncel durum tek ve dar bir soruyu yanıtlar: gönderinin özetlenmiş durumu nedir? Bu bilgi, ne olduğunu, ne zaman olduğunu, bilginin güncel olup olmadığını veya sırada ne yapılması gerektiğini açıklamayabilir.
Örneğin, iki gönderinin ikisi de “Transit halinde” görünebilir ancak farklı yanıtlar gerektirebilir. Birinde yakın zamanda yapılmış bir tesis taraması olabilir ve bildirilen herhangi bir sorun bulunmayabilir. Diğerinde ise olay geçmişinde çözülmemiş bir adres sorunu kaydedilmiş olabilir. Yalnızca başlık durumunu okuyan bir uygulama bu farkı gözden kaçırabilir.
Yanıtı üç pratik göreve göre değerlendirin: gönderiyi doğru siparişle eşleştirmek, ilerlemesini doğru şekilde açıklamak ve bir eylemin gerekli olup olmadığına karar vermek. Aşağıdaki alanlar bu görevleri destekler. Alan adları örnek niteliğindedir; evrensel bir standart veya belirli bir sağlayıcının şeması değildir.
Mevcut durumun ötesinde değerlendirilecek 12 alan
1. Gönderi ve takip tanımlayıcıları
Yanıt, açıklanan gönderiyi tanımlamalıdır. Yararlı değerler arasında gönderilen takip numarası, API’nin takip kaydı tanımlayıcısı ve sisteminizin bir teslimat veya paket kaydıyla eşleştirebileceği müşteri referansı bulunur.
Bir siparişin tek bir gönderiye eşit olduğunu varsaymayın. Bir sipariş paketlere bölünebilir ve bir değiştirme işlemi başka bir gönderi oluşturabilir. Takip kayıtlarını paket veya teslimat düzeyinde saklayın, ardından bunları siparişle ilişkilendirin. Biçimlendirme ve baştaki sıfırların kaybolmaması için takip numaralarını dize olarak koruyun.
2. Taşıyıcı kimliği
Okunabilir taşıyıcı adının yanında sabit bir taşıyıcı tanımlayıcısı arayın. Kullanılabiliyorsa yanıt, uygulamanız tarafından açıkça sağlanan taşıyıcı ile otomatik algılama yoluyla seçilen taşıyıcıyı ayırt etmelidir.
Taşıyıcı bağlamı, bir takip numarasını ve olaylarını yorumlarken önemlidir. Algılama belirsizse entegrasyonunuz, belirsiz bir eşleşmeyi sessizce doğrulanmış olarak sunmak yerine bunu çözmenin bir yoluna sahip olmalıdır. Hizmet düzeyi bilgilerini ayrı tutun: yalnızca taşıyıcı adı, bir gönderinin ekspres, posta veya başka bir hizmet kullanıp kullanmadığını göstermez.
3. Normalleştirilmiş durum ayrıntısı
Ana durumun yanında belgelenmiş bir ayrıntı kodu veya alt durum isteyin. Genel bir kategori gönderiyi istisna olarak tanımlayabilirken ayrıntı, teslimat denemesini, adres sorununu veya gümrükle ilgili bekletmeyi belirtebilir.
İş mantığı için sabit kodlar, sunum için okunabilir etiketler kullanın. Sağlayıcının taşıyıcı olaylarını bu kodlara nasıl eşlediğini ve bilinmeyen veya eşlenmemiş olayları nasıl ele aldığını doğrulayın. Normalleştirilmiş bir etiket, farklı taşıyıcı akışlarını kullanmayı kolaylaştırır; ancak destek ekibinizin ihtiyaç duyduğu ayrımları ortadan kaldırmamalıdır.
4. Orijinal taşıyıcı mesajları ve kodları
Sağlandığında orijinal olay açıklamasını ve taşıyıcı olay kodunu saklayın. Bu değerler, özellikle taşıyıcının belirli bir operasyonel ifade kullandığı durumlarda, normalleştirilmiş bir durumda bulunmayabilecek bağlamı destek görevlilerine sunar.
Orijinal metni çevrilmiş veya yeniden yazılmış açıklamalardan ayrı tutun. Aksi halde müşteriye yönelik bir açıklama, taşıyıcının tam ifadesi sanılabilir. Taşıyıcı metnini görüntülerken güvenilmeyen girdi olarak ele alın: uygun şekilde kaçışlayın ve çalıştırılabilir HTML olarak oluşturmaktan kaçının.
5. Takip olay geçmişi
Kullanışlı bir yanıt yalnızca son olayı değil, gönderi zaman çizelgesini de sunmalıdır. Her olay ideal olarak bir tanımlayıcı, durum veya kod, açıklama, zaman damgası ve mevcut konum bilgilerini içermelidir.
API’nin tüm geçmişi mi, sınırlı bir aralığı mı yoksa sayfalandırılmış sonuçları mı döndürdüğünü kontrol edin. Düzeltmelerin ve yinelenen gözlemlerin nasıl temsil edildiğini de belirleyin. Yanıt sözleşmesi sıralamayı açıkça garanti etmedikçe uygulamanız ilk öğenin her zaman en yeni öğe olduğunu varsaymamalıdır.
6. Olay zaman damgaları ve saat dilimi bilgileri
Bir olayın gerçekleşme zamanı, API’nin onu aldığı veya döndürdüğü zamandan farklıdır. Kullanılabiliyorsa her ikisini de koruyun. Bu ayrım, yeni alınan bir güncellemenin daha önce gerçekleşmiş bir olayı neden açıkladığını anlamaya yardımcı olur.
Zaman damgalarını açık UTC farkları veya UTC gösterimiyle isteyin. RFC 3339, sayısal saat farkları da dahil olmak üzere internet protokollerine uygun bir zaman damgası biçimi tanımlar. Kaynak yalnızca bilinen bir fark olmadan yerel saat sağlıyorsa, bunu sessizce UTC olarak değerlendirmek yerine bu belirsizliği koruyun. Temel kaynak yalnızca tarih sağlıyorsa saniye düzeyinde kesinlik ima etmeyin.
7. Olay konumları ve gönderi coğrafyası
Sağlandığında şehir, bölge, ülke ve posta kodu gibi yapılandırılmış konum bileşenlerini arayın. Yapılandırılmış alanlara dönüştürmek anlam kaybına yol açabilecekse ham konum dizesini de koruyun.
Bir tarama konumu, paketin canlı konumu olmak zorunda değildir. Aynı şekilde son bildirilen tesis, paketin hâlâ orada olduğunun kanıtı değildir. Müşteriye yönelik sayfalar bunu son bildirilen konum olarak açıklamalıdır. Eksik tarama metninden koordinat veya kesin teslimat adresi çıkarmaktan kaçının.
8. Tahmini teslimat tarihi veya aralığı
Tahmini teslimat alanı, tek bir tarih mi yoksa bir aralık mı içerdiğini, bunu kimin oluşturduğunu ve en son ne zaman güncellendiğini belirtmelidir. Taşıyıcı tarafından sağlanan tahmin ile ayrıca hesaplanan tahmin ayırt edilebilir olmalıdır.
Yalnızca tarih içeren bir tahmini kesin varış saatine dönüştürmeyin. Entegrasyonunuz, güncellenen veya geri çekilen tahminleri de ele almalı ve takip sayfasında güncelliğini yitirmiş bir taahhüdü tutmamalıdır. Tahmin yoksa desteklenmeyen bir varsayımla hesaplamak yerine kullanılamadığını gösterin.
9. İstisna nedeni ve gerekli eylem
İstisna bilgileri sorunu açıklamalı ve kaynağın desteklediği durumlarda bir eylemi, sorumlu tarafı veya son tarihi belirtmelidir. Genel bir gecikme bildirimi, alıcı bilgilerinin istenmesinden operasyonel olarak farklıdır.
Bildirilen gerçekleri kendi iş akışı kararlarınızdan ayrı tutun. Örneğin işletmeniz, belirli bir süre güncelleme gelmediğinde bir destek görevi açabilir. Bu bir iç eskalasyon kuralıdır; taşıyıcının paketi kayıp ilan ettiğine dair kanıt değildir. Belirsiz takip metninden ödeme talimatları veya hassas bilgi istekleri oluşturmayın.
10. Taşıyıcı devirleri ve ilişkili takip numaraları
Bir gönderi operatörler arasında hareket ettiğinde yararlı veriler arasında sonraki taşıyıcı, ilişkili takip numarası ve orijinal kayıtlarla sonraki kayıtlar arasındaki ilişki bulunur. Teslimat aşamasında farklı bir tanımlayıcı kullanıldığında bu bilgiler sürekliliğin korunmasına yardımcı olabilir.
Bildirilen devri, orijinal taşıyıcının üzerine yazmak yerine bir ilişki olarak ele alın. Hedefleri veya takip numaraları benzer görünüyor diye kayıtları birleştirmeyin. İlişki sağlanmamış veya başka şekilde doğrulanmamışsa sürekli bir yolculuk uydurmak yerine çözülmemiş olarak bırakın.
11. Teslimat sonucu ve kanıt referansları
Teslimat bildirildiğinde yanıt, kaydedilen teslimat zamanını ve güvenli bırakma yeri açıklaması veya alıcı kategorisi gibi mevcut teslimat ayrıntılarını sunmalıdır. Taşıyıcı ve hizmet bunu sağlıyorsa teslimat kanıtı referansı da yararlı olabilir.
Teslim edildi durumu, paketin hedeflenen alıcı tarafından şahsen kabul edildiğinin kanıtı olarak değerlendirilmemelidir. İmzalar, fotoğraflar, adlar ve kesin konumlar kişisel bilgiler içerebilir. Erişimi sınırlandırın, bu ayrıntıları herkese açık takip sayfalarında göstermeyin ve kanıt bağlantıları için yetkilendirme veya son kullanma gerekliliklerini doğrulayın.
12. Güncellik, alma durumu ve yanıt meta verileri
En son gönderi olayı ile son başarılı veri alma işlemini ayırt etmek için yeterli meta veri isteyin. Yararlı değerler arasında son başarılı kontrol, son başarısız deneme, yanıt oluşturma zamanı ve döndürülen verilerin önbelleğe alınmış veya kısmi olup olmadığı bulunur.
Başarılı bir API isteği tek başına taşıyıcının yeni bir tarama yayınladığını göstermez. HTTP yanıt semantiği isteğin sonucunu açıklar; gönderi ilerlemesi uygulama verilerine aittir. Geçici bir bağlantı sorununun yanlış bir teslimat uyarısına dönüşmemesi için alma hatalarını gönderi istisnalarından ayrı tutun.
Eksik verilerin tanımlı bir anlamı olmalıdır
Alanların mevcut olması sözleşmenin yalnızca bir parçasıdır. Ekibiniz ayrıca eksik bir değerin ne anlama geldiğini de bilmelidir. Bir teslimat tahmini kaynaktan kullanılamıyor olabilir, henüz alınmamış olabilir veya teslimattan sonra geçerli olmayabilir. Bu durumlar otomatik olarak aynı müşteri mesajını üretmemelidir.
- Bilinmiyor: Değer henüz belirlenmemiştir.
- Sağlanmadı: Kaynak, alınan verilerde değeri sunmamıştır.
- Uygulanamaz: Alan bu kayıt veya durum için geçerli değildir.
- Alma başarısız: Sistem ilgili sorguyu tamamlayamamıştır.
Bunlar önerilen ayrımlardır; zorunlu gerçek değerler değildir. Hangi gösterimi seçerseniz seçin bunu belgeleyin. Yer tutucu tarihlerden, geçerli kayıtlara benzeyen boş nesnelerden ve gerçek konum sanılabilecek varsayılan koordinatlardan kaçının.
Entegrasyondan önce yanıt nasıl test edilir?
İşletmenizin kullandığı taşıyıcılardan, hizmetlerden ve gönderim rotalarından gerçek yükleri değerlendirin. Bir şema isteğe bağlı bir alanı listeleyebilir ancak her temel kaynağın bu alanı dolduracağını garanti etmeyebilir. 17TRACK entegrasyonu için, bu kılavuzdaki kavramsal alan adlarını doğrudan kullanılabilir parametreler olarak değerlendirmek yerine yanıt sözleşmesini kontrol etmek üzere resmi Tracking API belgelerini kullanın.
- Temsili bir örnek oluşturun. Yeni kaydedilmiş gönderileri, aktif gönderileri, teslimat denemelerini, tamamlanmış teslimatları ve mevcut devir durumlarını dahil edin.
- Alanları olaylara kadar izleyin. Görüntülenen durumun, son olayın ve teslimat ayrıntılarının tutarlı bir kaydı açıkladığını doğrulayın. Tutarsızlıkları gizlemek yerine araştırın.
- Gecikmiş ve tekrarlanan güncellemeleri test edin. Aynı yükü yeniden işleyin ve daha yeni bir olaydan sonra daha eski bir olay alın. Her iki durumun da yinelenen bildirimler oluşturmadığını veya görüntülenen durumu yanlışlıkla geri almadığını doğrulayın.
- Eksik ve hatalı biçimlendirilmiş değerleri test edin. Eksik tahminleri, bilinmeyen konumları, tanınmayan durum kodlarını ve tamamlanmamış zaman damgalarını dahil edin. Uygulama yerine bir şey uydurmadan kullanılabilir kalmalıdır.
- Taşıma hatalarını takip sonuçlarından ayırın. Kimlik doğrulama hatası, zaman aşımı veya hatalı biçimlendirilmiş yanıt bir entegrasyon hata yoluna girmeli, gönderi istisnası iş akışına girmemelidir.
- Müşteri görünümünü doğrulayın. Dahili referansların, ham tanılama ayrıntılarının ve kişisel bilgilerin herkese açık sayfalara veya bildirimlere sızmadığını kontrol edin.
Webhook tabanlı güncellemelerde sağlayıcının belgelerinde teslimat tanımlayıcılarını, kimlik doğrulamayı, yeniden deneme davranışını ve yeniden oynatma yönetimini de kontrol edin. Bunlar gönderi gerçeklerinden ziyade entegrasyon gereklilikleridir. Alıcınız tekrarlanan teslimatları güvenli şekilde işlemeli ve geliş sırasının olay sırasına eşit olduğunu varsaymamalıdır.
Kabul kriteri pratik olmalıdır: Uygulamanız desteklenmeyen iddialarda bulunmadan gönderiyi açıklayabiliyor mu ve operasyon ekibiniz bir sonraki haklı eylemi belirleyebiliyor mu? Daha küçük ve iyi tanımlanmış bir yük, açıklanmamış isteğe bağlı değerlerle dolu daha büyük bir yanıttan daha kullanışlı olabilir.
SSS
Her gönderinin 12 veri grubunun tamamını doldurması gerekir mi?
Hayır. Teslimat kanıtı, sonraki takip numaraları ve tahmini teslimat tarihleri kullanılamayabilir veya uygulanamayabilir. Evrensel doluluk yerine açık alan tanımları ve öngörülebilir eksik değer davranışı talep edin. En önemli alanları gerçek gönderi karışımınıza göre kontrol edin.
Ham yanıtı mı yoksa yalnızca normalleştirilmiş alanları mı saklamalıyız?
Uygulama mantığı için normalleştirilmiş alanları saklayın. İlgili kaynak yüklerini korumak, gizlilik, güvenlik, sözleşme ve saklama gerekliliklerinize tabi olmak üzere hata ayıklama ve eşleme değişiklikleri konusunda da yardımcı olabilir. Erişimi sınırlandırın ve bir yanıtta göründüğü için hassas içeriği saklamayın.
En son olayı hangi zaman damgası belirlemelidir?
Saat dilimlerini ve düzeltmeleri dikkate alarak belgelenmiş olay kronolojisini ve sağlayıcının sıralama kurallarını kullanın. Alma zamanı, sisteminizin bir olayı ne zaman öğrendiğini gösterir; olayın ne zaman gerçekleştiğini zorunlu olarak göstermez. Zaman damgaları eksik veya çelişkiliyse kesin bir sıra iddia etmek yerine belirsizliği koruyun.
Bir tracking API paketin kayıp olduğunu doğrulayabilir mi?
Kaybı yalnızca kaynak bu yorumu açıkça desteklediğinde taşıyıcı tarafından bildirilmiş olarak kabul edin. Uzun süre tarama yapılmaması, operasyon kurallarınız kapsamında soruşturmayı haklı çıkarabilir; ancak tek başına sessizlik kaybı kanıtlamaz. “Eski takip” ile “kayıp bildirildi” kavramlarını ayrı tutun.
Teslim edildi durumu müşteri şikâyetini kapatmak için yeterli midir?
Otomatik olarak hayır. Bildirilen takip sonucunu ortaya koyar ancak alıcının itirazını çözmeyebilir. Mevcut teslimat ayrıntılarını, müşterinin hesabını ve destek sürecinizi inceleyin. Bir durum etiketini çelişkili bilgileri araştırmanın yerine kullanmaktan kaçının.
Kaynaklar
- 17TRACK Tracking API belgeleri — bir entegrasyonun belgelenmiş alanlarını ve davranışını kontrol etmek için ürüne özgü referans; yukarıdaki 12 grup editoryal önerilerdir ve şemanın birebir kopyası değildir.
- RFC 3339: İnternette Tarih ve Saat: Zaman Damgaları — zaman damgası gösterimi ve saat farkı kuralları.
- RFC 9110: HTTP Semantiği — gönderi düzeyindeki iş durumundan farklı olan HTTP yanıt semantiği.


