Gönderi Takip API İş Akışı: Bir Gönderiyi Kaydetmekten Takip Ayrıntılarını Almaya Kadar
Bir gönderi takip API'si iş akışı, bir takip numarası ve gerekli taşıyıcı bilgileri göndererek, kaydın başarılı olup olmadığını kontrol ederek, takip verilerinin kullanılabilir hâle gelmesini bekleyerek ve gönderinin durumunu ve olay geçmişini alarak başlar. Üretim ortamındaki bir entegrasyon için geliştiricilerin ayrıca her takip kaydını bir siparişle ilişkilendirmesi, kısmi hataları yönetmesi, güncellemeleri güvenli şekilde işlemesi ve kabul edilmiş bir kayıt ile gerçek bir taşıyıcı taramasını birbirinden ayırması gerekir.
Bu kılavuz, bir e-ticaret platformunu, sipariş yönetim sistemini, depo uygulamasını veya müşteri hizmetleri aracını bağlayan geliştiriciler için bu iş akışını açıklar. Uygulama tasarımı önerilerini sağlayıcıya özgü API gereksinimlerinden ayırır. Bir 17TRACK entegrasyonu için aşağıdaki örnekleri uygulamadan önce istek şemasını, kimlik doğrulamayı, desteklenen işlemleri ve yanıt alanlarını doğrulamak üzere resmî API belgelerini kullanın.
Kaydın ne yaptığını ve ne yapmadığını anlayın
Bir gönderiyi takip hizmetine kaydetmek, hizmetin API sözleşmesine göre gönderiyi takip edebilmesi veya yönetebilmesi için bir tanımlayıcı göndermek anlamına gelir. Bu işlem, posta ücreti satın almak, gönderi etiketi oluşturmak, teslim alma rezervasyonu yapmak veya bir paketi taşıyıcıya teslim etmekle aynı değildir.
Uygulamanızda şu üç sonucu birbirinden ayrı tutun:
- İstek alındı: API, HTTP isteğinize bir yanıt döndürdü.
- Kayıt kabul edildi: Hizmet, ilgili takip kaydını işleme almak üzere kabul etti.
- Takip bilgileri kullanılabilir: Hizmet, uygulamanızın alabileceği veya alması gereken gönderi bilgilerine sahip.
Bu sonuçlar tek bir “başarı” bayrağında birleştirilmemelidir. Kabul edilmiş bir takip numarası henüz taşıyıcı olaylarına sahip olmayabilir. Aynı şekilde, bir toplu istek için başarılı bir HTTP yanıtı, toplu işlemdeki her öğenin kabul edildiği anlamına gelmez; sağlayıcı tarafından tanımlanan uygulama düzeyindeki sonuç yapısını inceleyin.
1. Gönderi kimliğinizi ve API yapılandırmanızı hazırlayın
Bir kayıt isteği göndermeden önce, gönderinin kendi sisteminiz içinde nasıl tanımlanacağına karar verin. Tek başına bir sipariş tanımlayıcısı genellikle yeterli değildir; çünkü bir sipariş birkaç pakete bölünebilir. Her gönderi veya paket için ayrı bir dahili kayıt oluşturun ve bu kaydı ilgili siparişle ilişkilendirin.
Yararlı bir dahili kayıt aşağıdaki bilgileri içerir. Bunlar önerilen uygulama alanlarıdır; 17TRACK istek şeması değildir.
- Dahili gönderi kimliği: Paket için kullandığınız sabit tanımlayıcı.
- Sipariş referansı: Gönderinin ait olduğu sipariş veya gönderim kaydı.
- Takip numarası: Taşıyıcı tarafından verilen tanımlayıcı; baştaki sıfırları korumak için metin olarak saklanmalıdır.
- Taşıyıcı bilgileri: Biliniyorsa, gönderim sisteminiz tarafından sağlanan taşıyıcı kimliği.
- Sağlayıcı referansı: Daha sonraki işlemler için gereken ve takip hizmeti tarafından döndürülen herhangi bir tanımlayıcı.
- Kayıt durumu: Gönderimin beklemede, kabul edilmiş, reddedilmiş veya mutabakat bekliyor olup olmadığına dair kaydınız.
- Takip durumu: Kayıt durumundan ayrı olarak tutulan en son gönderi durumu.
Göndermeden önce girdiyi doğrulayın. Yanlışlıkla eklenmiş baştaki ve sondaki boşlukları kaldırın; ancak taşıyıcının biçimiyle ilgili varsayımlara dayanarak takip numarasını yeniden yazmayın. Sorun giderme için özgün değeri koruyun. Bir taşıyıcı biliniyorsa, gayriresmî görünen adını göndermek yerine sağlayıcının belgelenmiş taşıyıcı tanımlayıcısıyla eşleyin.
Kimlik doğrulamayı sunucu tarafında yapılandırın. Kimlik bilgilerini kaynak kodu denetiminin dışında tutun, geliştirme ve üretim yapılandırmalarını ayırın ve gizli bilgileri günlüklerden maskeleyin. İlgisiz bir entegrasyondan değerleri kopyalamak yerine belgelenmiş API sürümünü, istek sınırlarını, toplu işlem sınırlarını ve hesap gereksinimlerini doğrulayın.
2. Gönderiyi kaydedin ve öğe düzeyindeki sonucu kaydedin
Takip kaydını, sağlayıcınızın belgelerinde açıklanan kayıt işlemini kullanarak gönderin. Yalnızca gerekli alanları ve belirli bir amaca hizmet eden isteğe bağlı bilgileri ekleyin. Sipariş veritabanınızda mevcut oldukları için müşteri adlarını, adreslerini veya diğer kişisel verileri göndermekten kaçının.
Aşağıdaki sözde kod uygulama sırasını gösterir. İşlev adları örnek amaçlıdır; API uç noktaları veya SDK yöntemleri değildir.
shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)
result = tracking_adapter.register(shipment)
if result.item_accepted:
save_registration_result(shipment_id, result)
elif result.outcome_unknown:
schedule_registration_reconciliation(shipment_id)
else:
save_registration_error(shipment_id, result)
route_for_retry_or_correction(result)
Ne olduğunu açıklamak için yeterli bilgiyi kalıcı olarak saklayın: dahili gönderi kimliği, gönderim zamanı, deneme numarası, öğe düzeyindeki sonuç ve sağlayıcının istek referansı. Yalnızca geçici bir çalışan günlüğüne güvenmeyin. Müşteri hizmetleri ve operasyon ekipleriniz, bir gönderinin başarıyla kaydedilip kaydedilmediğine dair kalıcı bir yanıta ihtiyaç duyar.
Toplu gönderimleri ayrı ayrı ele alın
API toplu kayıt işlemini destekliyorsa, döndürülen her öğeyi özgün gönderisiyle ilişkilendirin. HTTP isteği başarıyla tamamlandı diye tüm toplu işlemi kabul edilmiş olarak işaretlemeyin. Kabul edilen öğeleri kaydedin, reddedilenleri ayırın ve belirsiz sonuçları ayrı olarak inceleyin.
Bu yaklaşım, hatalı tek bir takip numarasının zaten başarılı olmuş kayıtlar için gereksiz yeniden denemelere yol açmasını önler. Ayrıca operasyon personeline düzeltilmesi gereken kayıtların uygulanabilir bir listesini sunar.
Zaman aşımını bilinmeyen sonuç olarak ele alın
Zaman aşımı, kaydın başarısız olduğunu kanıtlamaz. Bağlantınız kesilmeden önce sağlayıcı isteği kabul etmiş olabilir. Körlemesine yeniden göndermeden önce sonucu mutabakatla doğrulamak için belgelenmiş idempotensi davranışını, yinelenen istek işleme yöntemini veya sorgulama işlemlerini kullanın.
Sağlayıcının yinelenen isteklere davranışı belirsizse, otomatik yeniden denemeleri etkinleştirmeden önce kontrollü kayıtlarla test edin ve sözleşmeyi doğrulayın. Kayıt işleri için dahili tekilleştirme hâlâ yararlıdır; ancak uzak hizmetin tekrarlanan istekleri nasıl ele aldığını anlamanın yerini tutmaz.
3. İlk takip bilgilerinin gelmesi için zaman tanıyın
Kayıt kabul edildikten sonra takip ayrıntıları hemen kullanılabilir olmayabilir. Taşıyıcı fiziksel bir işlem olayını kaydetmeden önce bir etiket mevcut olabilir. Eksik bilgiler, takip numarasının, taşıyıcı seçiminin veya gönderiye özgü sorgulama gereksinimlerinin kontrol edilmesini de gerektirebilir.
Bu durumu açıkça gösterin. “Kaydedildi; takip bilgileri bekleniyor” ifadesi, “Taşınıyor” veya “Kayıt başarısız” ifadelerinden daha doğrudur. Boş bir arayüzü doldurmak için teslimat tahmini veya hareket olayı uydurmayın.
Bir kayıt boş kaldığında şu pratik sırayla inceleyin:
- Bireysel kaydın kabul edildiğini doğrulayın.
- Gönderilen takip numarasını gönderim kaydıyla karşılaştırın.
- Taşıyıcı eşlemesini ve belgelenmiş ek sorgulama gereksinimlerini kontrol edin.
- Aynı gönderi için taşıyıcının kendi takip sayfasını kontrol edin.
- Taşıyıcının olayları varsa ancak entegrasyonunuzda görünmüyorsa alma yanıtlarını inceleyin ve API sağlayıcısıyla maskelenmiş tanılama bilgilerini paylaşarak iletişime geçin.
Kanıt olmadan evrensel bir bekleme süresi benimsemekten kaçının. Eskalasyon kuralları gönderim hizmetini, beklenen teslim sürecini ve kendi operasyonel taahhütlerinizi yansıtmalıdır.
4. Takip ayrıntılarını alın ve doğru yorumlayın
Kayıt kullanılabilir olduğunda, gerekli tanımlayıcıları kullanarak belgelenmiş takip ayrıntıları işlemini çağırın. Kayıt ve alma işlemlerinin aynı alanları kabul ettiğini varsaymayın. Bazı API sözleşmeleri takip numaraları, taşıyıcı tanımlayıcıları ve sağlayıcı tarafından oluşturulan kayıt referansları arasında ayrım yapar.
Uygulamanız üç bilgi katmanını birbirinden ayırmalıdır:
- Gönderi özeti: Panolarda, sipariş sayfalarında ve operasyonel filtrelerde kullanılan genel durum.
- Olay geçmişi: Sağlandığında olay açıklamalarını, zaman damgalarını ve konumları içeren bireysel gözlemler.
- Alma meta verileri: Uygulamanızın bilgiyi aldığı veya getirdiği zaman ve isteğin başarıyla tamamlanıp tamamlanmadığı.
Başarılı bir sorgulama, alma işleminin başarılı olduğu anlamına gelir. Paketin önceki sorgulamadan bu yana hareket ettiği anlamına gelmez. Bildirim veya sonraki iş akışını oluşturmadan önce döndürülen takip bilgilerini saklanan kaydınızla karşılaştırın.
Olay zamanını alma zamanından ayrı tutun
Bir taşıyıcı olayına ait zamanı, sisteminizin olayı aldığı zamandan ayrı saklayın. Bu öğleden sonra alınan bir olay daha önce gerçekleşmiş bir taramayı açıklıyor olabilir. Olay zamanını alma zamanıyla değiştirmek, eski bir güncellemeyi yeni bir fiziksel hareket gibi gösterir.
Özgün zaman damgasını ve sağlanan zaman dilimi farkını koruyun. Zaman damgalarını karşılaştırma amacıyla yalnızca saat dilimi biliniyorsa normalleştirin. Bir olayda saat dilimi bilgisi yoksa, bu belirsizliği koruyun ve sunucunuzun saat dilimini sessizce atamayın.
Ham anlamı normalleştirilmiş durumla birlikte koruyun
Normalleştirilmiş bir durum, taşıyıcılar arasındaki gönderileri gruplamak için yararlıdır; ancak özgün olay açıklaması operasyonel bir sorunu daha kesin biçimde açıklayabilir. Kullanılabilir olduğunda her ikisini de saklayın. Tek başına geniş bir istisna kategorisi, destek temsilcisine sonraki adımın adresi kontrol etmek, alıcıyla iletişime geçmek veya başka bir güncellemeyi beklemek olup olmadığını söylemeyebilir.
Belirsiz bir durumdan teslimat garantisi, doğrulanmış kayıp veya belirli bir gümrük sonucu çıkarmayın. Temel bilgilere ve işletim politikanıza göre eskalasyon yapın.
5. Yoklama veya web kancalarıyla kayıtları güncel tutun
Ayrıntıları bir kez almak bağlantıyı test etmek için yeterlidir; ancak gönderi görünürlüğünü korumak için yeterli değildir. Üretim tasarımınızın bir güncelleme mekanizmasına ihtiyacı vardır. Seçtiğiniz sağlayıcının desteklediği mekanizmaları ve bunlara bağlı koşulları doğrulayın.
Yoklama ile uygulamanız belirli bir programa göre takip ayrıntılarını ister. İstekleri belgelenmiş sınırlar içinde planlayın, değişmemiş kayıtları bir neden olmadan tekrar tekrar sorgulamaktan kaçının ve yeniden denenebilir hatalar için geri çekilme kullanın. Bir müşterinin sipariş sayfasını açması, sınırsız bir üst akış isteğini otomatik olarak tetiklememelidir; sayfaya saklanan takip görünümü sunulabilir ve kontrollü bir arka plan işlemi bu görünümü yenileyebilir.
Web kancaları kullanıyorsanız gelen istekleri sağlayıcının belgelenmiş doğrulama mekanizmasıyla doğrulayın. Kabul edilen mesajları, web kancası sözleşmesine göre onaylamadan önce kalıcı olarak saklayın veya dayanıklı bir kuyruğa alın; ardından olayları eşzamansız olarak işleyin.
Belgelenmiş teslimat sözleşmesi aksini garanti etmiyorsa alıcıyı yinelenen mesajlara ve beklenmedik varış sırasına dayanıklı olacak şekilde tasarlayın. Kullanılabilir olduğunda tekilleştirme için sağlayıcı olay tanımlayıcısını kullanın. Aksi takdirde uygun olay alanlarına dayalı bir parmak izi tanımlayın ve test edin; bu parmak izinin verileriniz için ayarlanması gerekebileceğini unutmayın.
Web kancası odaklı bir entegrasyon, mutabakat için kontrollü almayı da kullanabilir. Örneğin bir kurtarma işi, alıcı kesintisinden etkilenen kayıtları kontrol edebilir. Bu bir dayanıklılık modelidir; hız sınırlarını veya sağlayıcıya özgü yönergeleri göz ardı etme izni değildir.
6. Takip bilgilerini güvenli iş eylemlerine dönüştürün
Müşteriye yönelik eylemleri tetiklemeden önce dahili gönderi kaydınızı güncelleyin. Yinelenen bir olayın tekrarlanan mesajlar oluşturmasını önlemek için bildirimlerin ve iş akışı geçişlerinin kalıcı kaydını tutun.
İş eylemlerini her API yanıtına değil, anlamlı değişikliklere bağlayın. Yeni gözlemlenen bir teslimat olayı, teslim edildi bildirimi göndermeyi gerektirebilir. Aynı olayı içeren tekrarlanmış bir yanıt gerektirmemelidir. Bir istisna, dahili incelemeyi gerektirebilir; ancak müşteri mesajı olayın gerçekte söylediğini yansıtmalıdır.
Bir gönderi tamamlanmış kabul edildikten sonra alınan olayları nasıl ele alacağınızı tanımlayın. Bir özet son duruma ulaştı diye olay geçmişini silmeyin veya sonraki tüm güncellemeleri kalıcı olarak engellemeyin. Saklama, mutabakat ve bildirim kurallarınız, tamamlanmış iş akışlarını tekrar tekrar açmadan meşru düzeltmeleri hesaba katmalıdır.
İş akışını 17TRACK entegrasyonuna uygulama
Özel bir takip entegrasyonu için ilgili başlangıç noktaları 17TRACK Tracking API sayfası ve geliştirici belgeleridir. Sunulan hizmeti değerlendirmek için ürün sayfasını, gerçek entegrasyon sözleşmesini oluşturmak için belgeleri kullanın. Tüketici takip sayfaları API özelliklerinin yerine geçmez.
Adaptörünüzü yazmadan önce kimlik doğrulama biçimini, kayıt ve alma işlemlerini, taşıyıcı tanımlama kurallarını, öğe düzeyindeki yanıt işlemeyi ve geçerli istek sınırlarını doğrulayın. Web kancası tabanlı işleme için yük şemasını, doğrulama sürecini, onay gereksinimlerini ve yeniden deneme davranışını da doğrulayın.
Bu sağlayıcıya özgü ayrıntıları, yanıt alanı varsayımlarını sipariş sisteminizin her yerine yaymak yerine bir adaptörün içinde tutun. Böylece uygulamanızın geri kalanı kayıt sonucu, gönderi durumu, olay geçmişi ve son başarılı senkronizasyon gibi dahili kavramlarla çalışabilir.
Pahalı hataları yakalayan lansman öncesi kontroller
- Kabul edildi ancak kayıt boş: Arayüz, paketin hareket ettiğini değil, takip bilgilerinin beklemede olduğunu gösterir.
- Karışık toplu sonuç: Her gönderi kendi kalıcı sonucunu alır.
- Gönderimden sonra zaman aşımı: Çalışan, başarısız olduğunu varsaymak yerine belirsiz sonucu mutabakatla doğrular.
- Yinelenen olay: Gönderi zaman çizelgesi ve müşteri bildirimi tekilleştirilmiş kalır.
- Daha eski olay daha sonra alındı: Olay, daha yeni özeti körü körüne değiştirmeden korunur.
- Üst akış hizmeti kullanılamıyor: Müşteri sayfası uygun bir güncellik göstergesiyle son saklanan sonucu gösterebilir.
- Yanlış taşıyıcı eşlemesi: Kayıt, belgelenmiş bir kurtarma yoluyla düzeltilebilir.
- Bölünmüş sipariş: Her paket kendi takip durumunu ve olay geçmişini korur.
- Kimlik bilgileri veya yük açığa çıkıyor: Günlükler, gizli bilgileri veya gereksiz kişisel bilgileri sızdırmadan tanılama referanslarını içerir.
Pratik tamamlanma ölçütü yalnızca başarılı bir kayıt yanıtı almak değildir. Bir paketi gönderimden güncellemelere kadar izleyebilmek, boş veya başarısız bir sonucu açıklayabilmek ve olayları kaybetmeden ya da müşteri eylemlerini yinelemeden kesintiye uğramış işlemeden kurtulabilmektir.
SSS
Bir takip numarasını kaydetmek gönderi oluşturur mu?
Bu kılavuzda açıklanan iş akışında hayır. Takip kaydı, mevcut bir tanımlayıcıyı takip hizmetine gönderir. Belirli bir API bunları açıkça birleştirmediği sürece etiket oluşturma, posta ücreti satın alma ve taşıyıcı rezervasyonu ayrı işlemlerdir.
Kayıt başarılı olduktan sonra takip ayrıntıları neden boş?
Kayıt kabulü ile takip verilerinin kullanılabilirliği farklı koşullardır. Taşıyıcı henüz bir olay kaydetmemiş olabilir veya takip numarasının, taşıyıcı eşlemesinin ya da ek sorgulama bilgilerinin kontrol edilmesi gerekebilir. Kaydı başarıyla yapılmış kabul etmeden önce öğe düzeyindeki sonucu inceleyin.
Durumunu her aldığımda gönderiyi kaydetmeli miyim?
Tekrarlanan kaydı varsayılan yenileme mekanizmanız olarak kullanmayın. Kabul edilmiş kayıt durumunu saklayın ve belgelenmiş alma veya güncelleme mekanizmasını kullanın. Düzeltmeler, yeniden etkinleştirme veya yinelenen gönderimler için sağlayıcının açık kurallarına uyun.
Yoklama mı yoksa web kancaları mı kullanmalıyım?
Belgelenmiş API sözleşmenize ve işletim gereksinimlerinize uygun mekanizmayı kullanın. Yoklama kontrollü bir istek programı gerektirir. Web kancaları güvenli, kalıcı bir alıcı ve yinelenen mesajlara dayanıklı işleme gerektirir. Desteklendiğinde, hedefli mutabakatla birlikte web kancası güncellemeleri pratik bir kurtarma yolu sağlayabilir.
Takip numarasını veritabanımdaki tek gönderi tanımlayıcısı olarak kullanabilir miyim?
Bunun yerine dahili bir gönderi tanımlayıcısı kullanın. Takip numarasını ve ilgili taşıyıcı bağlamını bu kaydın öznitelikleri olarak saklayın. Böylece dahili gönderinizin kimliğini değiştirmeden bölünmüş siparişleri, düzeltilmiş takip numaralarını ve sağlayıcıya özgü referansları daha kolay yönetebilirsiniz.
Kaynaklar
- 17TRACK Tracking API — 17TRACK API entegrasyonunu değerlendirmek için resmî ürün başlangıç noktası.
- 17TRACK API belgeleri — uygulamaya özgü istek biçimleri, işlemler, yanıtlar ve entegrasyon gereksinimleri için resmî referans. Bu kılavuzdaki sözde kod ve dahili alan önerileri uygulama tasarımı örnekleridir; bu API sözleşmesinden alıntı değildir.


