Webhook Beklemeden API Üzerinden En Son Gönderi Durumu Nasıl Alınır
Bir webhook beklemeden kullanılabilir en güncel gönderi durumunu almak için takip sağlayıcınızın gönderi sorgulama API'sine kimlik doğrulamalı bir istek gönderin. Uygulamanızı hemen güncellemek için yanıtı kullanın, ardından sonraki değişiklikler için webhook'ları etkin tutun. Önemli ayrım şudur: Bir sorgu genellikle sağlayıcının depoladığı en son takip bilgilerini alır; mutlaka taşıyıcıya yeni bir kontrol yaptırmaz.

Bu yaklaşım, bir müşteri sipariş sayfasını açtığında, bir destek temsilcisinin güncellemeye ihtiyaç duyduğunda veya sisteminizin kaçırılmış bir bildirimi telafi etmesi gerektiğinde kullanışlıdır. Güvenilir bir uygulama; isteğe bağlı sorguları, net güncellik göstergelerini ve yinelenen ya da sırası dışında gelen güncellemelere karşı korumaları bir araya getirir.
“En güncel gönderi durumu”nun ne anlama geldiğine karar verin
Bir uç nokta seçmeden önce kulağa benzer gelebilen ancak farklı sonuçlar üreten üç işlemi birbirinden ayırın.
| İşlem | Yaptığı şey | Belirlemediği şey |
|---|---|---|
| Kendi veritabanınızı okuyun | Uygulamanızın zaten tuttuğu takip bilgilerini döndürür. | Sağlayıcının daha yeni bir güncelleme alıp almadığını. |
| Takip API'sini sorgulayın | Sağlayıcının sorgulama işlemi aracılığıyla kullanılabilen bilgileri alır. | Bu istek sırasında yeni bir taşıyıcı sorgusunun yapılıp yapılmadığını. |
| Takip yenilemesi isteyin | Sağlayıcı bu işlemi sunuyorsa, üst sistemde başka bir kontrol yapılmasını ister. | Taşıyıcının yeni bir tarama yaptığı veya yenilemenin eşzamanlı olarak tamamlandığı varsayımını. |
Şimdi bir yanıta ihtiyacınız olduğunda sorgu kullanın. Sağlayıcının başka bir üst sistem kontrolü yapmasını istediğinizde yenileme işlemini araştırın. Önbellek bozucu bir parametre eklemenin, bir isteği tekrarlamanın veya HTTP cache-control başlığı göndermenin taşıyıcıyı yeni bilgi sağlamaya zorlayacağını varsaymayın.
Gönderi görünürlüğünün birkaç aşaması vardır: taşıyıcı bir olayı kaydeder, takip sağlayıcısı bunu alır ve uygulamanız olayı alır veya getirir. Doğrudan API isteği, bildirim teslimini bekleme ihtiyacını ortadan kaldırabilir; ancak bu zincirin önceki aşamalarındaki gecikmeleri ortadan kaldıramaz.
Kod yazmadan önce sorgu sözleşmesini kontrol edin
Takip hizmetini entegre eden geliştirici bu iş akışından sorumludur. Eski bir entegrasyon örneğinden kopyalanmış bir uç nokta yerine sağlayıcının güncel belgeleriyle başlayın. Şu ayrıntıları doğrulayın:
- Gönderi kimliği: Sorgu bir takip numarasını, dahili gönderi kimliğini veya taşıyıcı tanımlayıcısıyla birlikte bir takip numarasını kabul ediyor mu?
- Kayıt gereksinimleri: Sorgulanabilmesi için gönderinin önceden kaydedilmesi gerekiyor mu?
- Kimlik doğrulama: Hangi başlık veya kimlik doğrulama mekanizması gerekiyor?
- Yanıtın anlamı: İşlem depolanmış bilgileri mi döndürüyor, veri toplamayı mı başlatıyor yoksa daha sonra kontrol edilecek bir iş mi döndürüyor?
- Sonuç işleme: Başarılı bir HTTP yanıtı gönderi düzeyinde bir hata veya bekleyen bir sonuç içerebilir mi?
- Kullanım kısıtlamaları: Hangi hız sınırları, toplu işlem sınırları ve hesaba özel kısıtlamalar geçerli?
- Güncellik alanları: Hangi zaman damgaları taşıyıcı olaylarını, sağlayıcı güncellemelerini ve yanıt oluşturma zamanını temsil ediyor?
17TRACK entegrasyonu için tüketici takip sayfası veya mağaza takip arayüzü yerine ilgili ürün Tracking API'sidir. Entegrasyonunuz için takip bilgisi sorgulama işlemini, kimlik doğrulamayı, istek alanlarını ve yanıt yapısını doğrulamak üzere resmi API belgelerini kullanın. Sorgulama ile webhook işleme süreçlerini aynı gönderi kaydını güncelleyen ayrı uygulama yolları olarak ele alın.
Yenileme davranışı veya sorgu sıklığı hakkında varsayımları koda sabitlemekten kaçının. Bu ayrıntılar kullandığınız işlem ve hizmet koşullarıyla uyumlu olmalıdır.
Arka ucunuz üzerinden isteğe bağlı arama oluşturun
Uygulamanızda kimlik doğrulamalı bir uç nokta sunmak pratik bir tasarımdır. Tarayıcı bu uç noktadan bir gönderi güncellemesi ister; sunucunuz yetkilendirmeyi kontrol eder, sağlayıcı sorgusunun gerekli olup olmadığına karar verir ve normalleştirilmiş bir sonuç döndürür.
Aşağıdaki rota, uygulamanızda oluşturacağınız bir uç nokta örneğidir. Bu, bir 17TRACK uç noktası veya sağlayıcı istek belirtimi değildir.
GET /api/orders/{order_id}/shipment-statusGönderiyi sunucuda aramak için sipariş tanımlayıcısını kullanın. Bir çağrının istekteki takip numarasını değiştirerek başka bir müşterinin takip geçmişini almasına izin vermeyin. Sağlayıcı API kimlik bilgilerini tarayıcı JavaScript'i veya mobil uygulama paketi yerine arka ucunuzda tutun.
Uygulayabileceğiniz bir istek akışı
- Erişimi yetkilendirin. Müşterinin veya çalışanının siparişi görüntüleme yetkisi olduğunu doğrulayın.
- Gönderiyi belirleyin. Uygun olduğunda depolanan takip tanımlayıcısını ve taşıyıcı bilgilerini okuyun.
- Yerel güncelliği kontrol edin. Yakın zamanda başarılı bir sorgu mevcutsa, uygulamanızın güncellik politikasına göre bunu yeniden kullanın.
- Gerektiğinde sağlayıcıyı sorgulayın. Belgelenmiş işlemi ve sınırlı bir istek zaman aşımını kullanın.
- Sonucu doğrulayın. Hem HTTP sonucunu hem de gönderi düzeyindeki sonucu kontrol edin.
- Bilgileri birleştirin. Webhook olayları için kullanılan normalleştirme ve uzlaştırma kurallarının aynısını uygulayın.
- Durumu ve güncelliği döndürün. Kullanılabiliyorsa en son olay zamanını ve sağlayıcıya yapılan son başarılı kontrol zamanını ekleyin.
Yerel güncellik politikası bir mühendislik kararıdır; taşıyıcı güncelleme sıklığı hakkında bir ifade değildir. Bu politikayı arayüz gereksinimlerinize, sağlayıcı sınırlarına, gönderi hacmine ve gözlemlenen sorgu faydasına göre seçin. Bir müşterinin güncelleme düğmesine art arda tıklaması, sınırsız bir üst sistem istek akışı oluşturmamalıdır.
Güncellik icat etmeden yanıtı normalleştirin
Sağlayıcı yanıt yapıları farklı olsa bile uygulamanız kararlı bir dahili biçim döndürebilir. Bu örnek nesne, gerçek bir sağlayıcı yükü değil, kendi uygulama sözleşmenizdir:
{
"shipment_id": "internal-shipment-id",
"status": "in_transit",
"latest_event_at": null,
"provider_updated_at": null,
"last_successful_query_at": null,
"retrieval_state": "success",
"source": "provider_query"
}Her zaman damgasını yalnızca anlamı bilindiğinde doldurun. Sunucunuzun yanıt aldığı zaman sorgu meta verilerine aittir; paketin hareket ettiği zaman olarak sunulmamalıdır. Sağlayıcı bir sağlayıcı-güncelleme zaman damgası sunmuyorsa, başka bir zaman damgasını yerine koymak yerine bu alanı eksik veya null bırakın.
Müşteri arayüzünde mesajları ayırın: “En son taşıyıcı olayı” gönderi hareketini, “Takip kontrol edildi” ise uygulamanızın alma etkinliğini açıklar. Bu ayrım, değişmemiş bir taramanın yeni kaydedilmiş gibi görünmesini engeller.
API sorgularının ve webhook'ların birbirinin üzerine yazmasını önleyin
Her iki mekanizma da etkin olduğunda aynı olay bir sorgu ve webhook aracılığıyla gelebilir. Ayrıca başladıkları sıradan farklı bir sırayla tamamlanabilirler. Önce başlatılan bir sorgu, webhook daha yeni bilgileri sağladıktan sonra tamamlanabilir.
Son yanıt kazanır mantığını kullanmayın. En son alınan yük, mutlaka en güncel gönderi durumu değildir.
- Tek bir güncelleme hattı paylaşın. Sorgu sonuçlarını ve webhook yüklerini aynı doğrulama, normalleştirme ve kalıcılaştırma işlevlerinden geçirin.
- Olayları tekilleştirin. Belgelenmiş bir olay tanımlayıcısını tercih edin. Yoksa olay zamanı, durum, konum ve açıklama gibi kullanılabilir alanlardan dikkatle tanımlanmış bir parmak izi oluşturun.
- Anlamı bilinen sıralama alanlarını kullanın. Belgelenmiş bir revizyon veya sıra, varış zamanının olay sırasını temsil ettiğini varsaymaktan daha kullanışlıdır.
- Geçmişi koruyun. Yeni alınan bir olay, mevcut gönderi özetini değiştirmeden geçmişteki bir boşluğu doldurabilir.
- Düzeltmelere izin verin. Durumlar evrensel, doğrusal bir merdiven değildir. Görünürdeki her geriye dönüşü kalıcı olarak reddetmek yerine belgelenmiş düzeltme davranışını izleyin.
Olay sırası belirsiz olduğunda, özgün yükü ve kaynağını inceleme amacıyla saklayın. Bir olay zaman damgası uydurarak veya tüm taşıyıcı zaman damgalarının aynı saat dilimini kullandığını varsayarak belirsizliği çözmeye çalışmayın.
Eksik verileri ve başarısız istekleri farklı ele alın
Boş bir sonuç, değişmemiş bir sonuç ve başarısız bir istek müşteriye aynı mesajı göstermemelidir.
Sorgu başarılı ancak durum değişmedi
Mevcut gönderi durumunu koruyun ve son başarılı sorgu zamanını güncelleyin. Başka bir aramanın tamamlanmış olması nedeniyle yeni bir gönderi olayı oluşturmayın. Müşterinin daha fazla ayrıntıya ihtiyacı varsa mevcut olay geçmişini gösterin ve daha yeni bir takip olayının döndürülmediğini açıklayın.
Gönderinin henüz takip bilgisi yok
Kayıt gerekip gerekmediğini, tanımlayıcı ve taşıyıcının doğru olup olmadığını ve sağlayıcının bekleyen veri toplamayı nasıl temsil ettiğini kontrol edin. Olayların bulunmaması tek başına takip numarasının geçersiz olduğunu veya paketin kaybolduğunu kanıtlamaz. Sağlayıcının bilinmeyen tanımlayıcı, bilgi bekleyen kayıtlı gönderi ve işlenemeyen istek arasındaki ayrımını koruyun.
Sağlayıcı isteği zaman aşımına uğruyor veya başarısız oluyor
Önceki geçerli bir durumunuz varsa, en son kontrolün başarılı olmadığına dair açık bir belirtiyle bunu döndürün. Önceki başarılı sorgu zaman damgasını değiştirmeyin. Ağ hatası bir teslimat istisnası değildir ve paketin iş durumunu değiştirmemelidir.
Uygun geçici hatalar için geri çekilme ve rastgelelik içeren sınırlı yeniden denemeler kullanın. Geçersiz kimlik bilgilerini veya hatalı istekleri tekrar tekrar denemeyin. Bir yanıt Retry-After sağladığında, bunu sağlayıcının sözleşmesine ve HTTP anlamlarına göre yorumlayın. HTTP belirtimi bu değerin saniye cinsinden gecikme veya HTTP tarihi olarak ifade edilmesine izin verir.
Aynı gönderi için birden fazla istek geliyor
Eşzamanlı aramaları birleştirerek tek bir üst sistem isteğini paylaşmalarını sağlayın. Hesap ve gönderi bazında sınırlar uygulayın ve otomatik yeniden denemenin birkaç uygulama katmanında çoğalmasını önleyin. Toplu işlem destekleniyorsa, HTTP isteği tamamlandığı için tüm grubu başarılı kabul etmek yerine her gönderinin sonucunu inceleyin.
Yoklamayı kontrollü bir yedek yöntem olarak kullanın
Webhook'lar olmadan zamanlanmış yoklama veritabanınızı güncel tutabilir; ancak açık bir işletim politikası gerektirir. Hangi gönderilerin uygun kalacağını, hataların zamanlamayı nasıl etkileyeceğini ve rutin yoklamanın ne zaman duracağını belirleyin.
Çoğu entegrasyon için hibrit tasarım mantıklı bir başlangıçtır: webhook'lar arka plan değişikliklerini ele alır, isteğe bağlı sorgular etkileşimli isteklere hizmet eder ve uzlaştırma işleri ilgilenilmesi gereken kayıtları kontrol eder. Bu, her hesap için maliyeti en aza indireceğine dair bir garanti değil, mimari bir öneridir.
- Etkin gönderilere ve çözülmemiş alma hataları bulunan kayıtlara öncelik verin.
- Her zamanlanmış çalıştırmada tüm geçmiş gönderileri sorgulamaktan kaçının.
- İşletmenizin gerektirdiği düzeltme penceresi de dahil olmak üzere tamamlanmış gönderilerin nasıl ele alınacağını tanımlayın.
- Sorguların ne sıklıkta gerçekten yeni bilgi bulduğunu izleyin.
- Giderek daha sık yoklamayla gizlemek yerine webhook teslimat sorunlarını araştırın.
Sağlayıcı istek gecikmesini, başarısız sorguları, hız sınırı yanıtlarını ve sorgulanan verilerle webhook üzerinden gelen kayıtlar arasındaki farkları izleyin. En son taşıyıcı olayının yaşını ayrıca izleyin. Başarılı API yanıtları, değişmemiş takip bilgileriyle birlikte bulunabilir.
Yayınlamadan önce iş akışını test edin
Başarılı bir istek yalnızca ilk testtir. Aksi hâlde yanıltıcı durum güncellemeleri oluşturabilecek durumları doğrulayın:
- İsteğe bağlı sorgu hâlâ çalışırken bir webhook gelir.
- İki müşteri veya çalışan oturumu aynı gönderiyi eşzamanlı olarak ister.
- Sağlayıcı HTTP başarısı döndürür ancak gönderi düzeyinde hata bildirir.
- Uygulamanız geçerli takip bilgilerini zaten tutarken bir istek başarısız olur.
- Bir olayda saat dilimi yoktur veya bilinmeyen bir durum kodu bulunur.
- Bir taşıyıcı düzeltmesi daha önce gösterilen sonucu değiştirir.
- Bir kullanıcı başka bir hesaba ait gönderiye erişmeye çalışır.
Yayınlama ölçütünüz; uygulamanın bilinen en iyi gönderi bilgisini döndürmesi, güncelliğini doğru açıklaması ve istekler başarısız olduğunda veya sıra dışında geldiğinde bu bilgiyi bozmamasıdır.
SSS
API'yi sorgulamak taşıyıcıyı paketi taramaya veya güncellemeye zorlar mı?
Hayır. Takip bilgilerinin alınması fiziksel bir taramaya neden olamaz. Bir isteğin üst sistem sorgusunu tetikleyip tetiklemediği belgelenmiş işleme bağlıdır. Desteklenen bir yenileme bile taşıyıcının daha yeni bir olayı yoksa değişmemiş bilgiler döndürebilir.
Webhook'ları yapılandırmadan API sorgularını kullanabilir miyim?
Sağlayıcı gerekli sorgu iş akışını destekliyorsa entegrasyonu isteğe bağlı istekler veya yoklama etrafında oluşturabilirsiniz. Önce kayıt ve sorgu gereksinimlerini doğrulayın. Ardından ne zaman kontrol edileceğine karar vermek, istek hacmini kontrol etmek ve değişiklikleri tespit etmek uygulamanızın sorumluluğunda olur.
Gönderi durumunu ne sıklıkta yoklamalıyım?
Evrensel bir aralık yoktur. Sağlayıcınızın sınırlarına, gönderi hacminize ve güncellemeleri daha erken bulmanın ticari değerine uygun bir zamanlama seçin. Yoklamanın ne sıklıkta yeni olaylar döndürdüğünü ölçün; sık isteklerin daha güncel taşıyıcı verisi sağlayacağını varsaymak yerine buna göre ayarlayın.
API neden webhook aracılığıyla zaten aldığım bilgileri döndürüyor?
Her iki yol da aynı temel gönderi kaydını sunabilir. Webhook bir bildirim iletirken sorgu bilgileri isteğe bağlı olarak alır. Aynı olayın her iki yoldan alınması mutlaka bir hata değildir; uygulamanız bunu tekilleştirmelidir.
Güncelleme düğmesinde “Takibi yenile” mi yazmalı?
Yalnızca bu ifade işlemi doğru tanımlıyorsa. Düğme depolanmış sağlayıcı verilerini alıyorsa “Güncellemeleri kontrol et” daha açıktır. Son taşıyıcı olayını, uygulamanızın son başarılı kontrolü tamamladığı zamandan ayrı gösterin.
Kaynaklar
- 17TRACK Tracking API — bu kılavuzda ele alınan takip API'si entegrasyonu için resmi ürün referansı.
- 17TRACK API belgeleri — sağlayıcıya özgü işlemler, kimlik doğrulama, istek alanları ve yanıt işleme için referans.
- RFC 9110, Bölüm 10.2.3: Retry-After — HTTP başlığının delay-seconds ve HTTP-date biçimlerini tanımlar.


