Üretime Geçmeden Önce Bir Tracking API Sağlayıcısına Sorulacak 15 Soru
Bir takip API'sini üretime almadan önce, gerçek taşıyıcılarınızı ve gönderi türlerinizi nasıl işlediğini, etkinliklerinin ne anlama geldiğini, güncellemelerin nasıl ulaştığını ve veriler ya da entegrasyon başarısız olduğunda ne olduğunu sorun. Aşağıdaki 15 soru, müşteriler, destek temsilcileri veya otomatik iş akışları bu API'lere güvenmeden önce mühendislik ve operasyon ekiplerine bu yanıtları test etmek için pratik bir yol sunar.

Başarılı bir demo, üretim testi değildir. Gecikmiş, iade edilmiş ve tanımlanması zor paketler de dahil olmak üzere temsili bir gönderi örneği kullanın. Her yanıt için dokümantasyon, örnek payload veya test sonucu isteyin. Çözülmemiş her öğeyi, lansmandan sonra ele alınacağını varsaymak yerine bir sorumlu ve karar tarihiyle kaydedin.
Gönderi uyumluluğu ve veri anlamıyla başlayın
1. Gerçek gönderilerimizden hangilerini takip edebilirsiniz ve kapsam ne anlama geliyor?
Sağlayıcıya taşıyıcılarınızdan, hizmetlerinizden, çıkış ve varış noktası çiftlerinden ve takip numarası formatlarından bir örnek verin. Hangi gönderileri kabul edebildiğini, hangi taşıyıcıları otomatik olarak tanımlayabildiğini ve nerede bir taşıyıcı kodu sağlamanız gerektiğini belirlemesini isteyin. Bir taşıyıcının listede yer alması, her hizmetin, aktarmanın veya gönderi türünün uygulamanızın ihtiyaç duyduğu etkinlikleri üreteceği anlamına gelmez.
Yüksek hacimli rotalardan ve operasyonel istisna durumlarından gerçek örnekleri test edin. İşletmenizde gerçekleşiyorsa, taşıyıcıların taşıma sırasında değiştiği bir gönderiyi de dahil edin. API'nin bir gönderiyi reddedip reddetmediğini, etkinlik bulamadan kabul edip etmediğini veya sınırlı ayrıntıyla etkinlik döndürüp döndürmediğini kaydedin. Bu sonuçlar, bir sipariş yönetim sisteminde farklı işlemler gerektirir.
2. Bir gönderiyi kaydetmek için neler gerekir ve yinelenen kayıtları nasıl önlersiniz?
Gerekli tanımlayıcıları, taşıyıcı seçimi kurallarını, kayıt zamanlamasını ve geçersiz ya da henüz etkin olmayan bir takip numarasına verilen yanıtı netleştirin. Kullanım senaryonuz için yalnızca bir takip numarasının yeterli olup olmadığını veya ek bilgi gerekip gerekmediğini sorun. Aynı gönderi aynı sistem ya da ayrı hizmetler tarafından iki kez gönderilirse ne olduğunu doğrulayın.
Açık sorumluluklara sahip tek bir kayıt akışı oluşturun: gönderileri hangi sistem gönderiyor, sağlayıcının tanımlayıcısını hangisi saklıyor ve belirsiz bir gönderimi hangisi yeniden deniyor? Sağlayıcı isteği işledikten sonra zaman aşımı yaşanırsa, körlemesine yapılan yeniden deneme sessizce ikinci bir kayıt veya yinelenen alt akış bildirimleri oluşturmamalıdır.
3. Durumlarınız ne anlama geliyor ve temel taşıyıcı etkinliklerini inceleyebilir miyiz?
Bir durum sözlüğü ve temsili ham etkinlikler isteyin. Taşıma halinde, dağıtıma çıktı, istisna, teslim edildi ve iade edildi gibi terimler yararlı özetlerdir; ancak iş kurallarınız daha fazla ayrıntıya ihtiyaç duyabilir. Sağlayıcının standartlaştırılmış durumların yanında orijinal taşıyıcı açıklamalarını sunup sunmadığını ve net biçimde eşleştirilemeyen bir etkinliği nasıl ele aldığını belirleyin.
Lansmandan önce kendi dahili durum modeliniz üzerinde anlaşın. Özellikle hangi etkinliğin bir gönderiyi kapatacağına, teslimat mesajını tetikleyeceğine veya bir istisna iş akışını başlatacağına karar verin. Temel veriler bu yorumu desteklemediği sürece, geniş bir durum etiketini belirli bir fiziksel etkinliğin kanıtı olarak değerlendirmeyin.
4. Hangi zaman damgaları ve konumlar sağlanıyor ve bunları nasıl yorumlamalıyız?
Her etkinlik için taşıyıcının gerçekleştiğini söylediği zamanı, sağlayıcının etkinliği aldığı veya yayımladığı zamandan ayırın. Saat dilimlerini, eksik fark bilgilerini, konum kesinliğini ve daha sonraki etkinliklerden sonra gelen güncellemeleri sorun. Yakın zamanda alınan bir etkinlik daha eski bir taramayı açıklayabilir; yalnızca alım zamanına göre sıralama yanıltıcı bir zaman çizelgesi oluşturabilir.
Payload'ı veritabanı şemanıza ve müşteriye gösterilen ekrana göre test edin. Yerel saat dilimi belirsiz olduğunda bir etkinliğin nasıl gösterileceğine karar verin ve kaynak sağlamıyorsa kesin bir teslimat zamanı veya konumu göstermeyin.
5. İstisnalar, iadeler ve teslimat kanıtı nasıl temsil ediliyor?
Başarısız teslimat girişimleri, gümrük bekletmeleri, adres sorunları, göndericiye iade hareketleri ve teslim edilmiş gönderiler için örnekler isteyin. Hangi ayrıntıların standartlaştırıldığını, hangilerinin taşıyıcıya özgü kaldığını ve teslimat onayının önem verdiğiniz durumlarda destekleyici kanıt içerip içermediğini sorun. Teslim edildi durumunun alıcı adı, imza, fotoğraf veya başka bir kanıt içerdiğini varsaymayın.
Her istisnayı bir işlem sorumlusuyla eşleştirin. Bazı etkinlikler destek incelemesini gerektirir; diğerleri daha fazla bilgi gelene kadar müşteriye mesaj gönderilmesini gerektirmez. Bir itiraz iş akışı için teslimat kanıtı gerekiyorsa, kullanılabilirliğini ve formatını takip kapsamının ima edilen bir parçası olarak değil, ayrı bir kabul kriteri olarak belirleyin.
Güncellemelerin sistemlerinize nasıl ulaştığını test edin
6. Güncellemeleri webhook, polling veya her ikisiyle mi iletiyorsunuz ve her birini ne zaman kullanmalıyız?
Belgelenmiş teslimat modelini, payload örneklerini, abonelik kurulumunu ve kaçırılan güncellemeleri kurtarma talimatlarını sorun. Webhook sunuluyorsa bunun değişen bir gönderiyi duyurup duyurmadığını, eksiksiz bir anlık görüntü sağlayıp sağlamadığını veya tek bir etkinlik taşıyıp taşımadığını belirleyin. Polling gerekiyorsa ya da yedek olarak kullanılıyorsa, uygun istek modelini ve değişen kayıtların nasıl belirleneceğini netleştirin.
Modeli iş akışına göre seçin. Müşteriye gösterilen bir zaman çizelgesi, bir istisna kuyruğundan farklı bir güncelleme gecikmesine tolerans gösterebilir. Entegrasyon webhook kullanıyor diye mimariniz anında uyarı sözü vermemelidir: önce taşıyıcı etkinliği kullanılabilir hale getirmeli, ardından her sistem bunu işleyebilmelidir.
7. Bildirimler yinelendiğinde, geciktiğinde veya sıra dışı geldiğinde ne olur?
Sağlayıcının başarısız teslimatları yeniden deneyip denemediğini, ne kadar süreyle denediğini ve uç noktanızdan hangi yanıtı beklediğini sorun. Varsa kararlı bir etkinlik veya gönderi tanımlayıcısı isteyin. Ardından aynı bildirimi iki kez test edin, daha yeni bir etkinlikten sonra daha eski bir etkinlik gönderin ve uç noktanızdan geçici olarak hata döndürün.
Alıcınız yalnızca güvenli biçimde kabul ettiği şeyi onaylayacak, müşteri mesajlarını tekrarlamadan yeniden denemeleri işleyecek ve etkinlikler sıra dışı geldiğinde doğru bir zaman çizelgesi oluşturacak şekilde tasarlanmalıdır. Önerilen tasarım her bildirimin tam olarak bir kez teslim edilmesine dayanıyorsa, yayına almadan önce bu varsayımı sorgulayın.
8. Veri güncelliğini nasıl ölçeceğiz ve bunu neler etkiler?
Sağlayıcının her aşamada neleri ölçebildiğini sorun: taşıyıcı etkinlik zamanı, sağlayıcının alım zamanı ve sisteminize teslim zamanı. Bu ölçümleri yaptığı herhangi bir taahhütten ayırın. Fiziksel hareket ile uygulamanızdaki güncelleme arasındaki uzun boşluk, üst sistemden, sağlayıcının işleme sürecinden veya kendi kuyunuzdan kaynaklanabilir.
Pilot sırasında temsili gönderiler için bu boşlukları ölçün ve aykırı değerleri araştırın. Uyarı eşiklerini iş akışınızın gerçek gereksinimlerine göre belirleyin. Gecikmiş bir tarama zararlı bir müşteri mesajına veya kaçırılmış bir eskalasyona yol açacaksa, eski veri etiketi ya da manuel inceleme gibi bir yedek tanımlayın.
9. API kimlik bilgileri ve webhook istekleri nasıl korunuyor?
Kimlik doğrulama ve kimlik bilgisi yönetimi dokümantasyonunu isteyin. Kimlik bilgilerinin nasıl verildiğini, kapsamlandırıldığını, döndürüldüğünü ve iptal edildiğini; test ve üretim kimlik bilgilerinin ayrı olup olmadığını ve bir webhook alıcısının isteğin gerçek olduğunu nasıl doğrulayabileceğini teyit edin. Ayrıca yeniden oynatılan webhook isteklerine karşı hangi korumaların bulunduğunu sorun.
Yalnızca sağlayıcının özellik listesini değil, önerilen uygulamayı da güvenlik ekibinize inceletin. Gizli bilgileri istemci tarafı kodundan ve günlüklerden uzak tutun, üretim kimlik bilgilerine erişimi kısıtlayın ve kimlik bilgisi döndürme işlemini prova edin. Uygulamanız gelen bildirimi belgelenen mekanizmayla doğrulayamıyorsa bu, webhook tabanlı bir iş akışı için yayına çıkmayı engelleyen bir sorundur.
10. Hangi gönderi ve müşteri verilerini saklıyorsunuz ve bunlar nereye gidiyor?
Takip numaraları, sipariş referansları, adresler, iletişim bilgileri ve özel meta veriler dahil olmak üzere entegrasyonunuzun göndereceği her alanı listeleyin. Hangi alanların zorunlu olduğunu, verilerin ve günlüklerin ne kadar süre saklandığını, silme taleplerinin nasıl işlendiğini ve kuruluşunuzun gereksinimleri açısından hangi bölgelerin veya alt işleyenlerin ilgili olduğunu sorun. İncelemeniz gerektiriyorsa sözleşme veya güvenlik dokümantasyonu alın.
Aktardığınız verileri en aza indirin. Bir takip entegrasyonu, tüm sipariş nesnesini göndermek kolay olduğu için müşteri bilgilerini almamalıdır. Gizlilik, hukuk ve güvenlik ekipleriniz, sağlayıcının belgelenmiş veri işleme yönteminin faaliyet gösterdiğiniz pazarlara uygun olup olmadığına karar vermelidir.
Arızalara ve operasyonel değişikliklere hazırlanın
11. Hız sınırları nelerdir ve istemciler hatalara nasıl yanıt vermelidir?
Her uç nokta, kimlik bilgisi ve ortam için sınırları; eşzamanlılık kurallarını ve önerilen yeniden deneme davranışını sorun. Geçersiz bir isteği geçici bir hizmet sorunundan ve hız sınırına takılmış bir istekten ayırın. HTTP API'leri için durum kodlarının anlamı önemlidir: RFC 6585, çok fazla istek için 429'u tanımlarken RFC 9110, sunucu hataları dahil HTTP semantiğini açıklar.
Normal günler ve ani yoğunluklar için beklenen trafiği hesaplayın; ardından geri çekilme uygulayan, işleri kuyruğa alan ve devam eden arızalarda uyarı veren bir istemciyi test edin. Belirsiz bir yazma işleminin güvenle yeniden denenip denenemeyeceğini doğrulayın. Bir kesinti sırasında trafiği katlayan yeniden deneme politikası kurtarmayı zorlaştırabilir.
12. Şema, durum ve taşıyıcı entegrasyonu değişiklikleri nasıl duyuruluyor?
API sürümleme, kullanımdan kaldırma bildirimleri, değişiklik günlükleri ve etkinlik alanlarının sürüm değişikliği olmadan eklenip eklenemeyeceğini sorun. Taşıyıcı tarafından sağlanan açıklamalar ve takip davranışı da değişebilir. Tüm API yerine tek bir taşıyıcıyı veya rotayı etkileyen bir değişikliğin nasıl duyurulduğunu belirleyin.
İsteğe bağlı alanlar ve bilinmeyen durum değerleri için toleranslı ayrıştırıcılar yazın; ancak tanımadığınız bir değeri sessizce teslim edildi veya başarısız olarak dönüştürmeyin. Değişen bir eşleştirmeyi teşhis etmek için yeterli kaynak ayrıntısını saklayın. Sağlayıcı bildirimlerini incelemesi ve değişiklik müşterilere ulaşmadan önce entegrasyon testlerinizi güncellemesi için birini görevlendirin.
13. Üretimden önce neleri test edebiliriz ve test ortamı canlı davranışla ne kadar örtüşüyor?
Dokümantasyona, sunuluyorsa bir test ortamına, örnek yanıtlara ve hata yollarını çalıştırma yöntemine erişim isteyin. Hangi senaryoların simüle edildiğini, hangilerinin canlı gönderiler gerektirdiğini sorun. Bir sandbox kodunuzun bir payload'ı işleyebildiğini gösterebilir; ancak taşıyıcı etkinliklerinin eksiksizliği, güncelleme zamanlaması veya bölgesel uygunluk hakkında çok az şey söyleyebilir.
İki tür test yürütün: ayrıştırma, yeniden denemeler ve güvenlik için deterministik entegrasyon testleri; operasyonel davranış için sınırlı bir canlı gönderi pilotu. Yinelenen gönderimleri, sağlayıcı zaman aşımını, gecikmiş taramayı, iadeyi ve bilinmeyen durumu dahil edin. Hem mühendislik ekibinin hem de istisnalarla ilgilenecek ekibin sonuçları onaylamasını zorunlu tutun.
14. Takip güncellenmeyi durdurduğunda hangi destek ve olay taahhütleri geçerlidir?
Hesabınız için hangi destek kanallarının mevcut olduğunu, olayların nasıl bildirildiğini ve varsa API veya bildirim teslimatı için hangi sözleşmesel hizmet taahhütlerinin geçerli olduğunu sorun. Çalışma süresi taahhüdünün API uç noktasını mı, takip güncellemelerinin teslimini mi yoksa her ikisini mi kapsadığını netleştirin. Bunlar aynı operasyonel sonuç değildir.
Kendi runbook'unuzu oluşturun: arızayı kim tespit ediyor, sağlayıcıyla kim iletişime geçiyor, polling veya başka bir yedek ne zaman kullanılıyor ve güncellemeler gecikirken müşteriler ne görüyor? Gönderiye özgü bir veri sorununun yanı sıra platform genelindeki kesintiyi çözme sürecini de isteyin. İhtiyaç duymadan önce eskalasyon yolunuzu test edin.
15. Kullanım ve maliyetler nasıl hesaplanıyor ve ayrılırsak ne olur?
Gönderimler, takip edilen gönderiler, istekler, bildirimler veya başka bir birim olmak üzere hangi işlemlerin faturalandırma ya da kullanım sınırlarına dahil olduğunu sorun. Önerilen anlaşma kapsamında yinelenen kayıtların, yeniden denemelerin, etkin olmayan gönderilerin, aşımın ve test trafiğinin nasıl ele alındığını doğrulayın. Maliyetleri bir API demosundan tahmin etmek yerine geçerli koşulları yazılı olarak alın.
Fesih için de plan yapın. Gönderi geçmişlerini nasıl dışa aktarabileceğinizi, erişimin ne kadar süre devam edeceğini ve etkin takip kayıtlarına ne olacağını belirleyin. Uygulanabilir bir çıkış planı, sağlayıcı değiştireceğinizin tahmini değildir; hâlihazırda hareket halindeki gönderilerin görünürlüğünü kaybetmekten kaçınmanın bir yoludur.
Yanıtları üretim kararına dönüştürün
Yararlı bir yayına alma incelemesinin üç çıktısı vardır:
- Gönderi uyumluluğu sonucu: Hangi takip kayıtlarının kabul edildiğini ve etkinliklerinin amaçlanan müşteri ve operasyon iş akışlarını destekleyip desteklemediğini gösteren test edilmiş bir örnek.
- Entegrasyon sonucu: Kimlik doğrulama, yinelenen kayıtlar, yeniden denemeler, gecikmiş etkinlikler, şema farklılıkları ve kaçırılan güncellemelerden kurtarma işlemlerinin gösterilmiş biçimde ele alınması.
- Operasyon anlaşması: Belgelenmiş sınırlar, veri işleme koşulları, destek iletişim bilgileri, maliyet varsayımları ve çözülmemiş riskler için sorumlular.
Çok taşıyıcılı bir takip API'si kullanımınıza uyuyorsa 17TRACK değerlendirilecek sağlayıcılardan biridir; Tracking API sayfası ve API dokümantasyonu, entegrasyonu bu sorulara göre kontrol etmek için başlangıç noktalarıdır. Aynı standart her sağlayıcıya uygulanmalıdır: dokümantasyon bir arayüzün nasıl çalışmasının amaçlandığını ortaya koyar; kendi temsili gönderi testleriniz ise üretim iş akışınız için çalışıp çalışmadığını gösterir. Tetikleyen etkinlikler doğrulanmadan müşteri bildirimi veya istisna otomasyonu yayınlamayın.
SSS
Bir takip API'sini üretim için onaylamak için sandbox testi yeterli mi?
Hayır. Bir sandbox istek formatlarını ve bazı hata işleme davranışlarını doğrulayabilir; ancak gerçek rotalarınızda taşıyıcıya özgü etkinlikleri, zamanlamayı ve istisna verilerinin yararlılığını değerlendirmek için canlı gönderiler gerekir. Her ikisini de ayrı kabul kriterleriyle kullanın.
Takip güncellemeleri için webhook mu kullanmalı, yoksa polling mi yapmalıyız?
Karar vermek için sağlayıcının belgelenmiş teslimat seçeneklerini ve iş akışınızın gecikme toleransını kullanın. Desteklendiğinde webhook'lar tekrarlı kontrolleri azaltabilir; ancak alıcınızın yine de yeniden deneme ve yinelenen bildirimleri işleme yeteneğine ihtiyacı vardır. Belgelenmiş sınırlara tabi olmak üzere polling, birincil yöntem veya kurtarma yolu olarak uygun olabilir.
Takip durumlarını eşleştirirken en yaygın hata nedir?
Daha özel bir iş iddiası için tek bir geniş durumu tetikleyici olarak kullanmak. Örneğin yalnızca teslim edildi etiketi, bir anlaşmazlığı çözmek için gereken kanıtı sağlamayabilir. Tetikleyicileri, sağlayıcınızın gerçekten sunduğu temel etkinlik ayrıntılarını kullanarak tanımlayın.
Lansmandan önce entegrasyonu kim onaylamalıdır?
Mühendislik ekibi güvenilirlik ve güvenliği; operasyon veya destek ekibi etkinliklerin ve istisna iş akışlarının yararlılığını; uygun gizlilik, hukuk ve satın alma sorumluları ise veri işleme ve ticari koşulları onaylamalıdır. Açık kalan her boşluk için adı belirli bir sorumlu atayın.


