Proaktif Teslimat Bildirimleri Göndermek İçin Gönderi Takip API'leri Nasıl Kullanılır
Bir gönderi takip API'siyle proaktif teslimat bildirimleri göndermek için her paketi siparişiyle ilişkilendirin, takip güncellemelerini alın, bu güncellemeleri müşterilerle ilgili olaylara dönüştürün ve e-posta, SMS veya uygulama bildirim hizmetiniz üzerinden mesajları tetikleyin. Gelen takip verileri ile giden mesajların arasına kalıcı bir kuyruk ve yinelenen kayıt kontrolleri ekleyin; böylece tekrarlanan veya gecikmiş güncellemeler kafa karıştırıcı uyarılar oluşturmaz.
Bu kılavuz, bu iş akışını oluşturan geliştiriciler ve e-ticaret operasyon ekipleri içindir. Amaç, her taşıyıcı taramasını iletmek değildir. Amaç, müşterilere anlamlı bir değişiklik olduğunda bunu, bu değişikliğin ne anlama geldiğini ve harekete geçmeleri gerekip gerekmediğini bildirmektir.
API'ye bağlanmadan önce bildirim iş akışını tasarlayın
Bir gönderi takip API'si takip bilgilerini sağlar; uygulamanız bu bilgileri nasıl kullanacağınıza karar verir. Seçtiğiniz hizmet her ikisini de sunsa bile gönderi görünürlüğünü ve müşteri iletişimini ayrı sorumluluklar olarak ele alın.
Pratik bir mimari altı aşamadan oluşur:
- Sipariş ilişkilendirme: gerektiğinde takip numarasını ve taşıyıcı tanımlayıcısını dahili bir gönderi kaydına bağlayın.
- Takip kaydı: gönderiyi sağlayıcının entegrasyon gereksinimlerine göre gönderin veya kaydedin.
- Güncelleme alma: webhook geri çağrılarını alın, API istekleriyle güncellemeleri çekin veya her iki yaklaşımı birleştirin.
- Olay işleme: gelen olayları doğrulayın, normalleştirin, yinelenenleri ayıklayın ve değerlendirin.
- Bildirim kararı: bildirim gönderip göndermeyeceğinizi, kiminle iletişime geçeceğinizi ve hangi kanal ile şablonu kullanacağınızı seçin.
- Mesaj teslimi: bildirimi gönderin ve mesajlaşma hizmetinin yanıtını kaydedin.
Entegrasyon gerçekten paylaşmayı gerektirmediği sürece müşteri iletişim bilgilerini kendi sipariş veya mesajlaşma sisteminizde tutun. Bir takip hizmetinin, uygulamanızın bir takip olayını siparişle ilişkilendirebilmesi için genellikle müşterinin e-posta adresine ihtiyacı yoktur.
1. Entegrasyon sözleşmesini doğrulayın
Alıcıyı yazmadan önce sağlayıcının belgelerinde kimlik doğrulama, gönderi kaydı, taşıyıcı tanımlama, desteklenen güncelleme yöntemleri, yanıt biçimleri, istek sınırları ve hata işleme bilgilerini kontrol edin. Webhook entegrasyonları için geri çağrıların nasıl doğrulandığını, hangi yanıtın alındıyı onayladığını ve başarısız teslimatların nasıl ele alındığını da kontrol edin.
17TRACK uygulaması için 17TRACK Tracking API sayfası ve resmi API belgeleri ile başlayın. Bu kılavuzdaki açıklayıcı alan adlarını 17TRACK istek veya yanıt alanları olarak ele almak yerine entegrasyonunuz için belgelenmiş sözleşmeyi kullanın. Uygulamadan önce geri çağrı kurulumunu, güvenlik gereksinimlerini ve hesaba özel sınırları doğrulayın.
Güncelleme yönteminizi entegrasyon sözleşmesine göre seçin:
- Webhook'lar: altyapınız için destekleniyor ve uygunsa geri çağrıları kullanın. Bunlar, sağlayıcı güncellemeleri gönderdiğinde uygulamanızın aynı gönderiyi tekrar tekrar istemeden işlemesine olanak tanır.
- Yoklama: geri çağrılar kullanılamadığında veya uygun olmadığında takip bilgilerini belirli aralıklarla alın. Zamanlamayı belgelenmiş istek sınırları içinde tutun.
- Birleşik yaklaşım: normal işleme için geri çağrıları, güncellemeleri eski görünen gönderileri uzlaştırmak içinse seçici API alımını kullanın; sağlayıcı bu iş akışını destekliyorsa.
Webhook kullandığınız için müşterilere anında bildirim sözü vermeyin. Yukarı akıştaki takip verileri kullanılabilir hale getirmeden uygulamanız bir taşıyıcı olayını bildiremez.
2. Gerçek siparişlere dayanıklı bir gönderi kaydı oluşturun
Birincil referans olarak yalnızca takip numarasını değil, dahili gönderi kimliğini kullanın. Bir sipariş birkaç paket içerebilir ve takip numaralarının sonsuza kadar küresel olarak benzersiz olduğu varsayılmamalıdır.
Yararlı bir dahili kayıt şunları içerir:
- Dahili sipariş kimliği ve gönderi kimliği.
- Biliniyorsa takip numarası ve taşıyıcı tanımlayıcısı.
- Sağlayıcının gönderi referansı, verildiyse.
- Mevcut normalleştirilmiş durum ve son anlamlı olay.
- Varsa saat dilimi veya farkıyla birlikte taşıyıcı olay zamanı.
- Sisteminizin güncellemeyi aldığı zaman.
- Müşterinin iletişim tercihlerine referans.
- Bildirim geçmişi ve etkin istisna iş akışı.
Olay zamanını alma zamanından ayrı saklayın. Daha önce gerçekleşen bir tarama, daha yeni bir taramadan sonra ulaşabilir. Uygulamanız yalnızca varış sırasına göre sıralama yaparsa teslim edilmiş bir gönderiyi yanlışlıkla yeniden yolda durumuna çevirebilir.
Bölünmüş siparişlerde bildirimleri etkilenen pakete bağlayın. Başka bir paket hâlâ hareket halindeyken “Siparişinizdeki bir paket ulaştı” ifadesi, “Siparişiniz ulaştı” ifadesinden daha doğrudur.
3. Takip olaylarını müşteri kararlarıyla eşleştirin
Taşıyıcı açıklamaları operasyonel verilerdir; kullanıma hazır müşteri mesajları değildir. Orijinal olayı korurken bildirim kurallarınızın anlayabileceği dahili bir kategori atayan bir normalleştirme katmanı oluşturun.
Aşağıdaki kategoriler önerilen uygulama kavramlarıdır; evrensel bir API durum sözlüğü değildir:
| Dahili kategori | Bildirim kararı | Mesajlaşma sınırı |
|---|---|---|
| Gönderi bilgileri alındı | Yalnızca yararlıysa hazırlık güncellemesi gönderin. | Yalnızca etiket oluşturulmasına dayanarak taşıyıcının fiziksel teslim aldığını ima etmeyin. |
| Yolda | İlk anlamlı hareket sırasında bildirim göndermeyi değerlendirin. | Müşterinin sonraki adımını değiştirmedikçe rutin tesis taramalarını bastırın. |
| Dağıtıma çıktı | Desteklenen bir olay bu durumu gösterdiğinde bildirim gönderin. | Durumu garantili teslimat saatine dönüştürmeyin. |
| Teslimat denemesi veya teslim alma gerekli | Eyleme geçirilebilir bir bildirim gönderin. | Son tarihleri veya teslim alma talimatlarını yalnızca doğrulanmışsa ekleyin. |
| Teslimat istisnası | Nedeni ve müşterinin harekete geçmesinin gerekip gerekmediğini değerlendirin. | Her istisnayı kayıp paket olarak tanımlamayın. |
| Teslim edildi | Paket düzeyinde bir onay gönderin. | Alıcıyı, teslimat yerini veya teslimat kanıtını uydurmayın. |
Belirsizliği koruyun. Tanınmayan bir olay, en yakın bilinen kategoriye zorla sokulmak yerine inceleme veya geri dönüş yoluna girmelidir. Sorun gidermeyi desteklemek için ham açıklamayı destek personeline sunun.
4. Güncellemeleri iş kaybetmeden veya yinelemeden alın
Webhook uç noktanız isteği doğrulamalı, kabul edilen güncellemeyi kalıcı olarak kaydetmeli ve sağlayıcının istediği alındı onayını döndürmelidir. Geri çağrı isteği sırasında e-posta veya SMS hizmetini beklemek yerine mesaj oluşturmayı asenkron olarak gerçekleştirin.
Sağlayıcının belgelenmiş geri çağrı doğrulama yöntemini uygulayın. Bir imza başlığı uydurmayın veya her sağlayıcının aynı kimlik doğrulama düzenini kullandığını varsaymayın. Ayrıca HTTPS'yi, istek boyutu sınırlarını, yük doğrulamasını ve uygun erişim kontrollerini zorunlu kılın.
Basitleştirilmiş bir işleme akışı şu şekildedir. Bunlar çalışan bir SDK örneği değil, uygulama düzeyindeki işlemlerdir:
receive callback
verify request using documented provider mechanism
validate payload
persist accepted payload and enqueue processing atomically
return documented acknowledgment
process queued update
find internal shipment
normalize relevant events
ignore already-processed events
evaluate chronology and state transition
create notification job if policy permits
commit state and job together
send notification job
check recipient preferences and suppression rules
submit message to messaging service
record result and retry only when appropriate
Atomik adımlar önemlidir. Uygulamanız bir durum değişikliğini kaydeder ancak bildirim işini oluşturmadan önce çökerse müşteri uyarıyı hiç almayabilir. İşlemsel bir outbox bir tasarım seçeneğidir: durum değişikliğini ve bekleyen işi aynı veritabanı işleminde kaydedin, ardından bir çalışanın işi göndermesine izin verin.
Bilinmeyen gönderi referanslarını açıkça ele alın. Hangi müşterinin bildirim alması gerektiğini tahmin etmek yerine bunları inceleme veya uzlaştırma için karantinaya alın.
5. Yinelenenleri önleme ve kronolojik kontroller ekleyin
Alıcıyı tekrarlanan geri çağrılara ve çalışan yeniden denemelerine tolerans gösterecek şekilde tasarlayın. Belgelenmişse kararlı bir sağlayıcı olay tanımlayıcısını tercih edin. Aksi takdirde dahili gönderi kimliği, olay kodu, olay zamanı ve konum gibi uygun alanlardan deterministik bir olay parmak izi oluşturun. Buna güvenmeden önce parmak izini gerçek yükler üzerinde test edin.
Olay yineleme ayıklama ve bildirim bastırma farklı sorunları çözer. Yineleme ayıklama aynı olayın iki kez işlenmesini durdurur. Bastırma ise birkaç farklı taramanın esasen aynı müşteri mesajını oluşturmasını önler.
Bildirim kimliğini iş olayı etrafında tanımlayın. Teslimat onayı, gönderi kimliği ve teslim edildi kilometre taşını kullanabilir. Teslimat denemesi, sonraki deneme gerçekten yeni bir olay olabileceği için denemeye özel bir kimlik gerektirebilir.
Sırası dışında gelen güncellemelerde olay zaman damgalarını karşılaştırın ve izin verilen durum geçişlerini değerlendirin. Bir geri çağrının yalnızca yeni bir tarama içerdiğini varsaymayın; belgelenmiş yapısının tek bir olayı, anlık görüntüyü veya geçmişi temsil edip etmediğini kontrol edin. Çelişkili güncellemeleri tüm düzeltmeleri sessizce silmek yerine uzlaştırmaya yönlendirin.
6. Bundan sonra ne olacağını açıklayan mesajlar yazın
Her bildirim ilgili paketi, doğrulanmış değişikliği ve müşterinin sonraki adımını belirtmelidir. Güvenli bir takip bağlantısı ve tanınabilir bir sipariş referansı ekleyin. SMS mesajlarında ve kilit ekranı önizlemelerinde tam adresleri veya gereksiz kişisel bilgileri göstermeyin.
Örneğin:
- Dağıtıma çıktı: “{order_reference} siparişinizin paketi dağıtıma çıktı. İlerlemesini buradan takip edin: {tracking_link}.”
- Teslimat denendi: “Taşıyıcı paketiniz için bir teslimat denemesi bildirildi. Kullanılabilir sonraki adımlar için takip sayfasını kontrol edin: {tracking_link}.”
- Teslim edildi: “Taşıyıcı, {order_reference} siparişinizin paketini teslim edildi olarak işaretledi. Mevcut teslimat ayrıntılarını görüntüleyin: {tracking_link}.”
Yer tutucuları yalnızca doğrulanmış verilerden oluşturun. Bir teslimat tahmini mevcutsa ve görüntülenmeye uygunsa bunu tahmin olarak etiketleyin. Eksikse tarih uydurmak yerine çıkarın.
İstisnalarda gönderi sorununu müşteri göreviyle ayırın. Bir aksaklık yalnızca açıklama gerektirebilir; doğrulanmış bir adres sorunu ise eylem gerektirebilir. Güvenilmeyen serbest metin takip içeriğine dayanarak müşterileri ödeme veya belge yükleme sayfasına yönlendirmeyin.
Kanalları müşteri tercihlerini, kanal izinlerini, aciliyeti ve geçerli kuralları kullanarak seçin. Kullandığınız yargı bölgeleri ve mesajlaşma kanalları için onay, abonelikten çıkma ve sessiz saat gereksinimlerini inceleyin. Teslimat hizmeti bildirimlerini promosyon kampanyalarından ayrı tutun; aynı izinlerin her ikisini de kapsadığını varsaymayın.
7. Takip sessiz kaldığında ne olacağını tanımlayın
Proaktif iletişim, yeni olayların yanı sıra ilerleme eksikliğini de kapsamalıdır; ancak tek başına sessizlik bir gönderinin geciktiğini veya kaybolduğunu kanıtlamaz.
Hizmet seviyesini, rotayı, son anlamlı olayı ve desteklenen teslimat tahminini kullanarak eski takip kuralı oluşturun. Eşikleri her gönderiye evrensel bir bekleme süresi uygulamak yerine operasyon verilerinizden ve destek sürecinizden belirleyin.
Bu kural tetiklendiğinde kaçırılan işlemleri kontrol edin, destekleniyorsa takip kaynağıyla uzlaştırın ve dahili bir destek görevi açıp açmayacağınıza karar verin. Müşteriye bildirim gönderirseniz bildiğiniz durumu yansıtan bir dil kullanın: “Yeni bir takip güncellemesi almadık” ifadesi, “Paketiniz kayboldu” ifadesinden farklıdır.
Çözülmemiş istisnalara bir sahip atayın. Bir sorunu çözüm yoluna yönlendirmeden tekrar tekrar duyuran bildirim sistemi müşteri memnuniyetsizliğini artırabilir.
8. Otomatik gönderimleri etkinleştirmeden önce tüm yolu test edin
Önce iş akışını gölge modunda çalıştırın: gerçek veya onaylanmış test olaylarını alın, önerilen bildirimleri oluşturun ve müşterilerle iletişime geçmeden sonuçları inceleyin.
- Aynı geri çağrıyı yeniden oynatın ve başka bir mesaj oluşturmadığını doğrulayın.
- Teslim edilmiş bir olaydan sonra daha eski bir yolda olayını işleyin ve ortaya çıkan durumu inceleyin.
- Eksik zaman damgalarını, bilinmeyen durumları ve hatalı yükleri test edin.
- Onaydan önce veritabanı hatasını ve kalıcılıktan sonra çalışan hatasını simüle edin.
- Hizmetin mesajı zaten kabul etmiş olabileceği belirsiz bir yanıt da dahil olmak üzere mesajlaşma zaman aşımlarını test edin.
- Bölünmüş gönderilerin pakete özel ifadeler oluşturduğunu doğrulayın.
- Abonelikten çıkmış alıcıları, geçersiz iletişim bilgilerini ve sessiz saat işlemlerini kontrol edin.
- Takip bağlantılarının başka bir müşterinin sipariş bilgilerini göstermediğini doğrulayın.
Kabul edilen geri çağrıları, işleme hatalarını, kuyruk yaşını, bildirim işlerini, yinelenen bastırmayı ve mesajlaşma sonuçlarını izleyin. İşleme gecikmesini sisteminizin alma zamanından ölçün ve taşıyıcı olayının yaşından ayrı değerlendirin. Bu ayrım, yavaş bir bildirimin yukarı akıştaki veri kullanılabilirliğinden mi yoksa kendi işlem hattınızdan mı kaynaklandığını belirlemeye yardımcı olur.
İyi anlaşılan küçük bir kilometre taşı grubuyla başlayın. Kuralları ancak destek ve operasyon ekipleri mesajların doğru, eyleme geçirilebilir ve alınmaya değer olduğu konusunda hemfikir olduktan sonra genişletin.
SSS
Bir gönderi takip API'si e-posta veya SMS mesajlarını otomatik olarak gönderir mi?
Her zaman değil. Takip verilerine erişim ve müşteri mesajlaşması ayrı yeteneklerdir. Hizmetin belgelenmiş kapsamını kontrol edin. Özel bir entegrasyonda uygulamanız takip güncellemelerini işleyebilir ve ayrı bir mesajlaşma hizmeti üzerinden bildirim gönderebilir.
Müşterilere her takip taraması hakkında bildirim göndermeli miyim?
Genellikle hayır. Anlamlı kilometre taşlarına ve eylem gerektiren olaylara öncelik verin. Birkaç tesis taraması, müşterinin bilmesi gerekenleri değiştirmeden normal taşıma sürecini temsil edebilir. Ayrıntılı geçmişi takip sayfasında tutun.
Gerçek zamanlı teslimat bildirimlerini garanti edebilir miyim?
Sisteminiz bir güncelleme aldıktan sonra bir işleme hedefi belirleyebilir ve bunu izleyebilirsiniz. Bir taşıyıcının taramayı ne zaman kaydedeceğini veya yayımlayacağını garanti edemezsiniz. Hizmeti bu bağımlılığı yansıtan ifadelerle tanımlayın.
Yinelenen teslimat mesajlarını nasıl önleyebilirim?
Kalıcı olay yineleme ayıklama, her iş kilometre taşı için ayrı bir bildirim kimliği ve işlemsel iş oluşturma kullanın. Mesajlaşma hizmetiniz idempotency'yi destekliyorsa bunu ek bir güvenlik önlemi olarak kullanın. Yalnızca bellekte tutulan bir yinelenen kayıt kontrolü yeniden başlatmalardan veya birden fazla çalışandan sağ çıkamaz.
Taşıyıcı teslim edildi durumunu düzeltirse ne olmalı?
Her iki olayı da koruyun ve gönderinin durumunu uzlaştırın. Düzeltme müşteriyi önemli ölçüde etkiliyorsa politikanıza göre açık bir düzeltme gönderin veya destek ekibine yönlendirin. Kodu basitleştirmek için teslim edildi durumunu kalıcı olarak geri döndürülemez hâle getirmeyin.
Kaynaklar
Aşağıdaki resmi kaynaklar, yukarıda ele alınan 17TRACK entegrasyonu için uygulama referanslarıdır. Bu kılavuzdaki dahili şema, bildirim kuralları ve işleme akışı, alıntılanmış API sözleşmeleri değil, mimari önerilerdir.
- 17TRACK Tracking API — API entegrasyonunu değerlendirmek için resmi başlangıç noktası.
- 17TRACK API belgeleri — sağlayıcıya özgü istek biçimleri, kimlik doğrulama, takip işlemleri ve entegrasyon gereksinimleri için referans.


