Kargo API Teslimat Durumu: Durum Kodları, Webhook'lar ve İstisna Uyarıları
Bir gönderim API'sindeki teslimat durumu, bir paketin ilerlemesini açıklar; bir API isteğinin başarılı olup olmadığını değil. Güvenilir takip oluşturmak için HTTP yanıt kodlarını gönderi durumlarından ayrı tutun, web kancalarını bir kez veya sıralı olarak geldiklerini varsaymadan işleyin ve uygulanabilir istisnaları, sorumluları net olan uyarılara dönüştürün. Mühendislik ve e-ticaret operasyon ekipleri için amaç, taşıyıcı güncellemeleri geciktiğinde, yinelendiğinde veya düzeltildiğinde güvenilirliğini koruyan bir gönderi kaydıdır.
Bu kılavuzda bu kaydın nasıl yapılandırılacağı, gelen takip olaylarının nasıl işleneceği ve bir teslimat sorununun takip entegrasyonu sorunundan nasıl ayırt edileceği açıklanmaktadır.
HTTP kodlarını, API sonuçlarını ve gönderi durumlarını ayırın
“Durum kodu” ifadesi üç farklı katmana atıfta bulunabilir. Bunların karıştırılması yanıltıcı panolara ve gereksiz müşteri bildirimlerine yol açar.
| Katman | Size ne anlatır? | Örnek yorum |
|---|---|---|
| HTTP yanıtı | HTTP isteğinin sonucu | 200 yanıtı HTTP düzeyinde başarıyı gösterir; paketin teslim edildiği anlamına gelmez. |
| API iş sonucu | İstenen işlemin sağlayıcının uygulama kuralları kapsamında başarılı olup olmadığı | API bu tasarımı kullanıyorsa, başarılı bir HTTP yanıtı içinde bile yanıt gövdesi bir takip kaydının reddedildiğini bildirebilir. |
| Gönderi durumu | Paketin bildirilen fiziksel veya operasyonel durumu | Taşımada, teslim alınmayı bekliyor veya teslim edildi. |
HTTP anlamları standardı, HTTP yanıtlarının anlamlarını tanımlar. Örneğin 202 Accepted, bir isteğin işlenmek üzere kabul edildiği, ancak işlemenin henüz tamamlanmamış olabileceği anlamına gelir. Bu, taşıyıcının bir paketi kabul ettiğinin kanıtı değildir.
Benzer şekilde, başarısız bir takip isteği gönderinin hareket etmeyi durdurduğunu kanıtlamaz. Fiziksel teslimat normal şekilde devam ederken uygulamanız geçici olarak görünürlüğünü kaybedebilir. Bu katmanları birbirinden bağımsız olarak izleyin.
Taşıyıcı ayrıntılarını kaybetmeden bir durum modeli oluşturun
Her gönderim API'si ve taşıyıcı tarafından paylaşılan evrensel bir sayısal teslimat durumu kodu yoktur. Bir entegrasyondan gelen değer, başka bir sağlayıcının eşlemesine göre yorumlanmamalıdır. Uyguladığınız belirli API sürümünün belgelerini kullanın.
Uygulanabilir bir dahili model, az sayıda standartlaştırılmış durumu orijinal taşıyıcı olayıyla birleştirir. Standartlaştırma tutarlı raporlamayı destekler; orijinal olay ise inceleme için gereken ayrıntıyı korur.
| Örnek dahili durum | Anlamı | Operasyonel uyarı |
|---|---|---|
| Bilgi alındı | Elektronik gönderi bilgileri mevcut. | Etiket oluşturulmasını fiziksel teslimin onaylandığı şeklinde değerlendirmeyin. |
| Taşımada | Takip kaydı, teslimat ağı içinde hareket olduğunu gösteriyor. | Bu geniş kategori farklı taşıma aşamalarını içerebilir. |
| Dağıtıma çıktı | Paketin bir teslimat rotasında olduğu bildiriliyor. | Bunu koşulsuz bir teslimat garantisine dönüştürmeyin. |
| Teslim alınmayı bekliyor | Alıcının paketi teslim alması bekleniyor. | Teslim alma talimatlarını veya son tarihleri yalnızca kaynak tarafından desteklendiğinde ekleyin. |
| Teslim edildi | Takip kaynağı teslimatı bildiriyor. | Teslimat taraması tek başına müşterinin teslim almadığı yönündeki iddiasını çözmez. |
| İstisna | Bir olay, dikkat gerektirebilir veya normal ilerlemeyi kesintiye uğratabilir. | Her istisnayı kayıp olarak değerlendirmek yerine nedeni koruyun. |
| İade sürüyor veya iade edildi | Paket geri dönüyor veya iadenin tamamlandığı bildiriliyor. | İade sürecini asıl alıcıya yapılan teslimattan ayrı tutun. |
| Bilinmiyor | Mevcut bilgiler güvenle eşleştirilemiyor. | Bir teslimat durumu uydurmak yerine eşleme veya veri eksikliğini araştırın. |
Bu etiketler resmi bir 17TRACK kod listesi değil, önerilen bir uygulama modelidir. Sağlayıcının durum kodunu, alt durumunu, açıklamasını, olay zamanını, saat dilimi bilgilerini, konumunu ve mevcutsa teslim alınma zamanını koruyun. Daha sonraki eşleme değişikliklerinin denetlenebilmesi için eşleme sürümünü de saklayın.
Çok taşıyıcılı bir uygulama için 17TRACK Tracking API uygun bir entegrasyon seçeneğidir. Sağlayıcıya özgü alanlara örnek etiketleri kopyalamak yerine uygulama sözleşmesini oluşturmak için resmi API belgelerini kullanın. Adaptörü oluşturmadan önce geçerli durum tanımlarını, web kancası yapılandırmasını, kimlik doğrulama gereksinimlerini ve yanıt anlamlarını doğrulayın.
Web kancası işlemeyi kalıcı alım etrafında oluşturun
Web kancası, bir olayı bildirmek için uç noktanıza gönderilen bir HTTP isteğidir. Tekrarlanan yoklama ihtiyacını azaltabilir, ancak anında, sıralı veya tam olarak bir kez teslimat garantisi olarak değerlendirilmemelidir. Sağlayıcı açıkça aksi yönde garanti vermedikçe alıcıyı yeniden denemelere, kesintilere ve beklenmeyen yük içeriklerine dayanacak şekilde tasarlayın.
- İsteğin kimliğini doğrulayın. Sağlayıcının belgelenmiş doğrulama yöntemini uygulayın. İmzalar destekleniyorsa belirtilen algoritmayı ve ham istek baytlarını kullanarak doğrulayın. Bir imza başlığı uydurmayın veya her hizmetin HMAC kullandığını varsaymayın.
- Yük içeriğini doğrulayın. Gerekli alanları, türleri, yük boyutunu ve gönderinin hesabınız tarafından yönetilen bir gönderiyle ilişkisini kontrol edin. İleriye dönük uyumluluğu gereksiz yere bozmadan bilinmeyen isteğe bağlı alanları işleyin.
- Onaylamadan önce kalıcı olarak kaydedin. Belgelenmiş başarı yanıtını göndermeden önce kabul edilen olayı saklayın veya kalıcı bir kuyruğa yerleştirin. Kalıcı kayıt başarısız olursa olayı güvenle alındı olarak onaylamayın.
- Eşzamansız olarak işleyin. Uygun olduğunda durum eşleme, sipariş güncellemeleri ve bildirim kararlarını istek işleyicisinin dışında gerçekleştirin.
- Yan etkileri idempotent hâle getirin. Yinelenen bir olay başka bir destek talebi oluşturmamalı veya aynı müşteri mesajının başka bir kopyasını göndermemelidir.
Kesin onay kodu, zaman aşımı, yeniden deneme takvimi ve yeniden oynatma davranışı sağlayıcıya bağlıdır. Bu ayrıntıları açıkça kontrol edin. Genel bir “200 döndürün” talimatı, web kancası sözleşmesinin yerini tutmaz.
HTTPS kullanın ve kimlik bilgilerini URL'lerden ve rutin günlüklerden uzak tutun. Takip verileri kişisel bilgiler içerebileceği için saklanan yük içeriklerine erişim kontrolleri uygulayın. OWASP REST Güvenlik Kontrol Listesi, aktarım koruması, girdi doğrulama ve uç nokta güvenliği hakkında ilgili yönergeler sunar.
Gerçek güncellemeleri bastırmadan olayları tekilleştirin
Mevcut olduğunda belgelenmiş ve kararlı bir olay tanımlayıcısını tercih edin. Aksi takdirde gönderi kimliği, olay zaman damgası, olay kodu ve konumun dikkatle seçilmiş bir birleşiminden tekilleştirme anahtarı türetin. Bu yaklaşımı gerçek yük içerileriyle test edin: iki meşru olay aynı zaman damgasını paylaşabilir ve aynı olay biraz farklı açıklayıcı metinlerle gelebilir.
Olay alımı ve sonraki işlemler için ayrı tekilleştirme kontrolleri kullanın. Bir durum güncellemesinin düzeltme olarak yeniden saklanması gerekebilirken müşteri bildirimi bastırılmaya devam etmelidir. Her bildirim veya talep işlemi için kendine ait kalıcı bir kimlik verin.
Olay zamanını alım zamanından ayrı tutun
Taşımada olan bir olayın, dağıtıma çıktı olayından sonra sisteminize ulaştığını, ancak taşıyıcının zaman damgasının daha eski olduğunu varsayalım. Geçmişe kaydedin, ancak mevcut durumu otomatik olarak yeniden taşımada durumuna çevirmeyin.
Tek başına zaman damgası sıralaması her durum için yeterli değildir. Eksik saat dilimleri, düzeltilmiş taramalar ve çelişkili kaynaklar açık kurallar gerektirir. Zaman damgası hassasiyetini ve farklarını koruyun, sisteminizin her olayı ne zaman aldığını kaydedin ve mevcut olduğunda belgelenmiş sağlayıcı sıra bilgilerini kullanın. Katı, yalnızca ileri giden bir durum sıralaması dayatmayın: teslimat denemeleri, yönlendirmeler, iadeler ve düzeltmeler geriye doğru ilerliyor gibi görünen meşru geçişler oluşturabilir.
İstisnaları sorumluluğu belirlenmiş eylemlere dönüştürün
Bir istisna uyarısı ne olduğunu, hangi işlemin gerektiğini ve sonraki adımdan kimin sorumlu olduğunu açıklamalıdır. Genel bir “gönderi istisnası” mesajı, operasyon personelini aynı incelemeyi tekrarlamak zorunda bırakır ve müşterileri yardımcı olmadan endişelendirebilir.
Küçük bir yönlendirme politikasıyla başlayın:
- Adres veya erişim sorunu: Sorunu doğrulaması ve taşıyıcının mevcut düzeltme sürecini kontrol etmesi için müşteri desteğine yönlendirin. Mümkün olduğunu doğrulamadan adres değişikliği sözü vermeyin.
- Teslim alma gerekli: Kaynak kullanılabilir bir teslim alma talimatı sağladığında alıcıyı bilgilendirin. Doğrulanmış son tarihi koruyun.
- Gümrük işlemi gerekli: Talep edilen belgeleri veya bilgileri kimin sağlaması gerektiğine göre vakayı atayın. Tek başına gümrükle ilgili bir olay, ödeme yapılması gerektiğini göstermez.
- Başarısız teslimat denemesi: Yeniden teslimat veya teslim alma önerisinde bulunmadan önce bildirilen sonraki adımı kontrol edin.
- Gönderene iade: Operasyon incelemesi başlatın. Politikanız açıkça izin vermedikçe yalnızca genel bir takip etiketine dayanarak otomatik olarak geri ödeme yapmayın.
- Taşıyıcı tarafından bildirilen kayıp veya hasar: Vakayı talep sorumlusuna yönlendirin ve olay kanıtlarını koruyun. Talep kararlarını genel gecikme tespitinden ayrı tutun.
Her uyarı bir gönderi tanımlayıcısı, sipariş referansı, olay nedeni, kaynak zaman damgası, bilinen en son durum, atanmış sorumlu ve sonraki eylemi içermelidir. Paylaşılan mesajlaşma kanallarında gereksiz müşteri ayrıntılarını açığa çıkarmak yerine ilgili dahili kayda bağlantı ekleyin.
“Güncelleme yok” durumunu ayrı bir koşul olarak ele alın
Yakın zamanda taranmamış bir gönderi otomatik olarak kayıp değildir. Kontrol noktaları arasında olabilir, ilk fiziksel taramasını bekliyor olabilir veya görünürlük açığından etkilenmiş olabilir.
Tek bir evrensel zamanlayıcı uygulamak yerine hareketsizlik eşiklerini hizmete, rotaya, gönderim aşamasına ve ticari taahhüde göre tanımlayın. Hiç kabul taraması yapılmamış bir paket ile ağa girdikten sonra güncellenmeyi durduran bir paketi birbirinden ayırın. Geçmiş kanıtlar sınırlıysa eşiği kayıp ilan etmek için değil, inceleme başlatmak için kullanın.
Değişmemiş bir vaka açık kaldığı sürece yinelenen uyarıları bastırın. Yeni kanıt ortaya çıktığında, kararlaştırılan takip kaçırıldığında veya müşteri teslimat taahhüdü müdahale gerektirdiğinde durumu yükseltin.
Entegrasyon sağlığını teslimat performansından ayrı izleyin
API izleme, takip entegrasyonunuzun çalışıp çalışmadığını yanıtlar. Teslimat izleme, gönderilere ne olduğunu yanıtlar. Sağlıklı bir uç nokta güncel olmayan taşıyıcı verilerini alabilirken, kullanılamayan bir uç nokta normal şekilde hareket eden paketlerin güncellemelerini kaçırabilir.
- İstek sağlığı: Kimlik doğrulama hatalarını, zaman aşımlarını, hız sınırı yanıtlarını, sunucu hatalarını ve uygulama düzeyindeki retleri izleyin.
- Web kancası sağlığı: Doğrulama hatalarını, onay gecikmesini, kalıcı kayıt hatalarını, yinelenen teslimatları ve işleme hatalarını izleyin.
- İşleme sağlığı: Kuyruk yaşını, işlenmemiş olayları, eşleme hatalarını ve bildirim hatalarını izleyin.
- Takip güncelliği: Son kaynak olayından bu yana geçen süreyi, son başarılı alımdan bu yana geçen süreden ayrı ölçün.
- Operasyonel sonuçlar: Çözülmemiş istisnaları, sorumlu atanmasına kadar geçen süreyi ve gecikmiş takipleri izleyin.
İstek yeniden denemeleri için sağlayıcının hız sınırı ve yeniden deneme yönergelerini izleyin. Yinelenen kayıtlar veya başka yan etkiler oluşturabilecek işlemleri düşünmeden tekrarlamaktan kaçının; mevcut olduğunda belgelenmiş idempotency mekanizmalarını kullanın.
Desteklendiğinde, kesintilerden veya kaçırılmış olay şüphelerinden sonra en güncel takip kaydını almak için bir mutabakat süreci kullanın. Sıklığını sözleşme ve hız sınırları içinde belirleyin. Web kancaları ve mutabakat farklı amaçlara hizmet eder: biri değişiklikleri iletir, diğeri boşlukların tespit edilmesine ve giderilmesine yardımcı olur.
Müşteri bildirimlerini etkinleştirmeden önce hata durumlarını test edin
Durum değişikliklerinin müşteri mesajları göndermesine izin vermeden önce yalnızca dahili işlemeyle başlayın ve temsili gönderileri inceleyin. Taşımada durumundan teslim edildi durumuna normal ilerlemeden fazlasını test edin.
- Yinelenen bir web kancası, amaçlanan tek bir müşteri bildirimi oluşturur.
- Daha eski bir olayın geç gelmesi mevcut durumu yanlışlıkla değiştirmez.
- Bilinmeyen bir durum korunur ve sessizce teslim edildi olarak eşlenmek yerine işaretlenir.
- Başarısız bir kalıcı yazma işlemi başarılı bir onay üretmez.
- Geçici bir sonraki sistem kesintisi, olayları yeniden deneme için erişilebilir bırakır.
- Teslim edildi olayının ardından gelen bir düzeltme denetlenebilirliğini korur.
- Çok paketli bir sipariş, yalnızca bir paket teslim edildiğinde tamamen teslim edilmiş hâle gelmez.
- Bir API kesintisi, müşterilere paketlerinin geciktiğini otomatik olarak bildirmeden mühendislik ekibine uyarı gönderir.
Yayınlama ölçütü operasyonel tutarlılık olmalıdır: gönderi kaydı, müşteri mesajı ve destek işlemi aynı temel kanıtla uyumlu olmalıdır. Tek başına başarılı bir web kancası yanıtı, teslimat deneyiminin çalıştığını göstermez.
SSS
HTTP 200 paketin teslim edildiği anlamına mı gelir?
Hayır. İstek için HTTP düzeyinde başarıyı gösterir. API'nin iş sonucunu ve gönderi durumu alanlarını ayrı ayrı okuyun. Bir web kancası için başarılı onay, fiziksel paket teslimatıyla değil bildirimin alınmasıyla ilgilidir.
Takip güncellemeleri için web kancalarını mı yoksa yoklamayı mı kullanmalıyım?
Sağlayıcı desteklediğinde olay odaklı güncellemeler için web kancalarını kullanın. Desteklendiğinde ve operasyonel olarak gerekli olduğunda, boşlukları gidermek için sınırlı bir mutabakat yoklaması ekleyin. Web kancaları kullanılamadığında yalnızca yoklama uygun olabilir, ancak sıklığı sağlayıcının sınırlarına ve güncellik gereksinimlerinize uymalıdır.
Takip durumu “teslim edildi” sonrasında neden değişebilir?
Bir kaynak bir olayı düzeltebilir veya entegrasyonunuz gecikmiş ya da çelişkili bilgiler alabilir. Geçmişi koruyun ve teslim edildi durumunu teknik olarak değişmez kabul etmek yerine daha yeni kanıtı değerlendirin. Bildirilen teslimat ile müşterinin teslim aldığını onaylaması da farklı olgulardır.
Bir istisna uyarısı ne kadar hızlı gönderilmelidir?
Aciliyeti gereken eyleme ve doğrulanmış son tarihe göre belirleyin. Alıcının eylemini gerektiren bir sorun, bilgilendirme amaçlı bir gecikmeden farklı şekilde ele alınmalıdır. Geç yayımlanan bir taşıyıcı olayını işlem hızı telafi edemez; bu nedenle hem kaynak hem de alım zaman damgalarını koruyun.
Müşteriler ham taşıyıcı durumunu görmeli mi?
Genellikle müşteriler açıklanmamış bir kod yerine net bir açıklamadan ve desteklenen sonraki adımdan yararlanır. Ham ayrıntıları destek ve denetim amaçlarıyla koruyun. Bir durumu, temel olayın desteklediğinden daha güçlü bir vaade asla dönüştürmeyin.
Kaynaklar
- RFC 9110: HTTP Semantics — 200 ve 202 dahil HTTP durum kodlarının anlamları için referans.
- OWASP REST Security Cheat Sheet — API ve web kancası uç noktalarıyla ilgili güvenlik yönergeleri.
- 17TRACK Tracking API — ele alınan takip entegrasyonu seçeneği için resmi ürün referansı.
- 17TRACK API Documentation — sağlayıcıya özgü entegrasyon gereksinimleri için resmi referans; bu kılavuzdaki örnek şemalar ve iş akışı önerileri bu sözleşmenin yerine geçmez.
