Skip to main content
AnasayfaBlogKılavuzlarGeliştirme Ortamında Tracking API Entegrasyonunu Test Etme: Sandbox, Test Numaraları, Sahte Webhook'lar

Geliştirme Ortamında Tracking API Entegrasyonunu Test Etme: Sandbox, Test Numaraları, Sahte Webhook'lar

17TRACK

Geliştirme ortamında bir takip API'si entegrasyonunu test etmek için üç tamamlayıcı yöntem kullanın: API davranışı için sağlayıcı sandbox'ı veya belgelenmiş test numaraları, tekrarlanabilir gönderi senaryoları için yerel fixture'lar ve alıcı uç noktanız için sahte webhook'lar. Ardından, kimlik bilgileri, abonelik yapılandırması ve gerçek olay teslimi dahil olmak üzere simülasyonların kanıtlayamayacağı bölümleri doğrulamak için kontrollü bir canlı kontrol gerçekleştirin.

Geliştirme Sandbox Test Numaralarında Takip API Entegrasyonunu Test Etme

Bu kılavuz, gönderi takibini bir ecommerce platformuna, sipariş yönetim sistemine, ERP'ye veya müşteri bildirim hizmetine bağlayan geliştiriciler içindir. Amaç yalnızca başarılı bir API yanıtı almak değildir. Amaç, takip güncellemelerinin yinelenen mesajlar, kaybolan olaylar veya gerçek müşterilerle yanlışlıkla iletişim kurulması olmadan doğru sipariş durumunu oluşturduğunu kanıtlamaktır.

Sağlayıcı davranışını uygulama davranışından ayırın

Bir takip entegrasyonunun en az iki sınırı vardır: uygulamanızın sağlayıcıya gönderdiği istekler ve uygulamanızın daha sonra aldığı veya aldığı güncellemeler. İlk sınırdaki başarılı bir istek, ikinci sınırın çalıştığını göstermez.

Test planını, tek bir test takip numarasının tüm sistemi çalıştırmasını beklemek yerine bu sınırlar etrafında oluşturun.

Test yöntemiDoğrulayabileceği şeylerTek başına kanıtlayamayacağı şeyler
Sağlayıcı sandbox'ıSağlayıcı tarafından açıklanan desteklenen istek biçimleri, kimlik doğrulama ve simüle edilmiş davranışÜretim taşıyıcı verilerinin kullanılabilirliği veya üretim teslim davranışı
Belgelenmiş test numaralarıBu numaralara atanmış belirli senaryolarDiğer durumlar, taşıyıcılar veya webhook dizileri
Yerel fixture'lar ve API mock'larıAyrıştırıcınız, eşleme kurallarınız, kalıcılık ve hata işlemeGerçek sağlayıcının istekleri kabul edip etmediği veya aynı payload'ı gönderip göndermediği
Sahte webhook istekleriUç nokta işleme, doğrulama, yinelenenleri önleme ve sonraki etkilerSağlayıcı tarafındaki geri çağırma yapılandırması veya gerçek teslimat yeniden denemeleri
Kontrollü canlı testGerçek bağlantı ve gözlemlenen gönderi iş akışıHer nadir hata, istisna veya teslimat dizisi

Önerilen yaklaşım: yerel testleri deterministik hale getirin, mevcut olduğunda sağlayıcı destekli testleri kullanın ve canlı gönderileri sistemler arasındaki bağlantıyı doğrulamak için ayırın.

Fixture'lar yazmadan önce sağlayıcı sözleşmesini doğrulayın

Kullanmayı planladığınız API sürümünün resmi belgeleriyle başlayın. Temel URL'yi, kimlik doğrulama yöntemini, kayıt gereksinimlerini, yanıt şemasını, webhook kurulumunu ve belgelenmiş test olanaklarını doğrulayın. Sağlayıcının bir API sunması nedeniyle ayrı bir sandbox bulunduğunu varsaymayın.

17TRACK entegrasyonu için başlangıç noktası olarak 17TRACK Tracking API sayfasını ve resmi API belgelerini kullanın. Sağlayıcıya özgü örnekleri oluşturmadan önce geçerli istek ve geri çağırma özelliklerini burada doğrulayın. Aşağıdaki örnekler özellikle uygulamaya ait fixture'lardır; 17TRACK API şemasını temsil etmezler.

Geliştirme kodunu harici bir hesaba bağlamadan önce şu soruları yanıtlayın:

  • Geliştirme ve üretim kimlik bilgileri ayrı mı ve her kimlik bilgisi hangi ortama erişiyor?
  • Bir sandbox geri çağırmaları destekliyor mu, yoksa yalnızca istek-yanıt testini mi destekliyor?
  • Test numaraları belgelenmiş mi ve tam olarak hangi sonuçları üretiyorlar?
  • Kayıtlar veya diğer test istekleri hesap kotasını tüketebilir ya da kalıcı kayıtlar oluşturabilir mi?
  • Hangi geri çağırma kimlik doğrulama, onay, zaman aşımı ve yeniden deneme kuralları belgelenmiş?
  • Takip kaydını, gönderiyi, taşıyıcıyı ve geri çağırma olayını hangi tanımlayıcılar birbirine bağlıyor?

Test davranışı açıkça belgelenmemişse sağlayıcıdan bunu doğrulamasını isteyin. Bu sırada kendi işleme mantığınızı mock'larla test etmeye devam edin. Doğrulanmamış bir sandbox özelliği bir planlama belirsizliğidir; sağlayıcının bu özelliğe sahip olmadığının kanıtı değildir.

Yalıtılmış bir geliştirme ortamı oluşturun

Ayrı bir veritabanı veya yalıtılmış tenant, ayrı gizli bilgiler ve sentetik siparişler kullanın. E-postaları, SMS mesajlarını ve diğer bildirimleri test hedeflerine veya bir bildirim havuzuna yönlendirin. Fixture'da teslim edildi olarak işaretlenen bir gönderi gerçek bir alıcıya mesaj göndermemelidir.

Dahili kayıtlara ve günlüklere açık bir ortam işareti ekleyin. Sağlayıcı kimlik bilgilerini sunucuda, kaynak denetiminin dışında tutun ve istek yakalamalarındaki gizli bilgileri maskeleyin. Geri çağırmalar için geçici genel erişim gerekiyorsa yalnızca amaçlanan geliştirme rotasını açın ve kimlik doğrulama kontrollerini koruyun.

Olayları göndermeden önce bilinen duruma sahip küçük bir sipariş kümesi oluşturun. Bir siparişe bağlı iki gönderi ve uygulamanız destekliyorsa farklı taşıyıcı bağlamları altında aynı takip numarası dizesini içeren gönderiler ekleyin. Bu durumlar, yalnızca takip numarasının her zaman benzersiz bir iş kaydını tanımladığı varsayımını ortaya çıkarır.

Her testin beklenen etkisini önceden tanımlayın: gönderi durumu, sipariş ilişkisi, zaman çizelgesi kayıtları, bildirim sayısı ve denetim kaydı. Böylece bir gösterim, başarılı veya başarısız olabilen bir iddiaya dönüşür.

Test numaralarını yalnızca belgelenen amaçları için kullanın

Bir takip numarasının testte iki farklı rolü vardır. Kayıt işlemini doğrulamak için girdi olarak kullanılabilir ve takip olayları üreten bir gönderiyi tanımlayabilir. Biçim doğrulamasından geçen bir numara mutlaka yararlı bir olay geçmişi sağlamaz.

Resmi test numaraları mevcut olduğunda

Her numaranın yanında sağlayıcının belirttiği senaryoyu kaydedin. Teslim edilmiş bir gönderi için belgelenen bir numaranın istisna, iade veya başarısız teslimat girişimini simüle ettiği varsayılmamalıdır. Ayrıca sonucunun sabit olup olmadığını, zaman içinde değişip değişmediğini veya belirli bir taşıyıcı seçimi gerektirip gerektirmediğini kontrol edin.

Bu numaraları özel bir entegrasyon testi yapılandırmasında tutun. Harici davranışın değişmesi nedeniyle normalde deterministik olan testlerin güvenilmez hale gelebileceği birim testlerine bunları dağıtmayın.

Resmi test numaraları doğrulanmadığında

Kendi uygulamanız içinde sentetik tanımlayıcılar kullanın ve sağlayıcı sınırını mock'layın. Gerçek bir gönderiyle eşleşebileceğinden, makul görünen bir numara uydurup test için ayrıldığını varsaymayın.

Canlı doğrulama için kontrol ettiğiniz ve erişim yetkinizin bulunduğu gönderileri kullanın. Herkese açık ekran görüntülerinden veya müşteri görüşmelerinden takip numaralarını kopyalamaktan kaçının. Gönderi geçmişlerini potansiyel olarak hassas kabul edin; bunlar konumlar, zaman damgaları ve teslimat bilgileri içerebilir.

Daha eski bir teslim edilmiş gönderi ayrıştırmayı doğrulamaya yardımcı olabilir, ancak sürekli entegrasyon için kötü bir bağımlılıktır. Geçmiş verilerin kullanılabilirliği ve harici yanıt değişebilir. Tekrarlanabilir testler için temizlenmiş bir fixture saklayın ve canlı kontrolü ayrı tutun.

Fixture'ları anlamlı gönderi geçişleri etrafında oluşturun

Fixture'ları belgelenmiş şemadan ve mevcut olduğunda temizlenmiş gerçek yanıtlardan oluşturun. Sağlayıcı payload fixture'larını dahili normalleştirilmiş olay modelinizden ayrı tutun. Dahili bir mock'un bozuk bir sağlayıcı ayrıştırıcısını gizlememesi için aralarındaki adaptörü test edin.

Yararlı bir başlangıç kümesi şu senaryoları kapsar:

  • Henüz takip olayı yok: hareket veya teslimat iddiasında bulunmadan gönderiyi koruyun.
  • Taşımada: zaman çizelgesini güncelleyin ve doğru sipariş ilişkisini koruyun.
  • Dağıtıma çıktı: teslimatı tamamlanmış olarak ele almadan bildirim politikanızı uygulayın.
  • Teslim edildi: tamamlanmayı kaydedin ve amaçlanan iş aksiyonunu bir kez üretin.
  • İstisna veya teslimat girişimi: tamamlanmış teslimattan ayrımı koruyun.
  • İade hareketi: sonraki her taramayı ilk alıcıya doğru ilerleme olarak yorumlamaktan kaçının.
  • Bilinmeyen durum: durum eşlemesi uydurmadan tanı için yeterli bilgiyi koruyun.

Bu senaryolar için kendi normalleştirilmiş adlarınızı kullanın, ardından sağlayıcının belgelenmiş değerlerini bunlara açıkça eşleyin. Farklı API'lerin aynı durum etiketlerini kullandığını veya bir etiketin her yerde aynı iş anlamına geldiğini varsaymayın.

Veri biçimini de çeşitlendirin: boş olay listesi, eksik isteğe bağlı alanlar, ek bilinmeyen alanlar, Unicode konum adları, saat dilimi farkları içeren zaman damgaları ve hatalı zorunlu değerler. Ayrıştırıcınız uyumlu eklemelere tolerans göstermeli, güvenli şekilde işlenemeyen verileri ise reddetmelidir.

Sahte webhook'ları gerçek alıcı yolundan gönderin

Sahte bir webhook yalnızca son durum güncelleme işlevini çağırmamalı; alıcı rotasını, kimlik doğrulama ara yazılımını, doğrulamayı, depolamayı ve worker işlemesini çalıştırmalıdır.

Aşağıdaki payload sentetik bir dahili olayı temsil eder. Alan adları, olay kimliği ve durum örnek amaçlıdır; bunlar bir sağlayıcı geri çağırma sözleşmesi değildir.

{
  "event_id": "dev-event-001",
  "shipment_id": "dev-shipment-001",
  "tracking_number": "INTERNAL-TEST-001",
  "status": "in_transit",
  "occurred_at": "2025-01-15T10:00:00Z"
}

Dosyayı tracking-event.json olarak kaydedin ve yerel test alıcısına gönderin:

curl --request POST \
  http://localhost:3000/dev/tracking-events \
  --header 'Content-Type: application/json' \
  --data-binary @tracking-event.json

Bu komut yalnızca yerel yönlendirmeyi ve işlemeyi doğrular. Sağlayıcı kimlik doğrulamasını göstermez. Yalnızca geliştirmeye özel bir rotayı üretimde erişilemez tutun veya üretim alıcısını sağlayıcının belgelenmiş kimlik doğrulama yöntemi ve ayrı bir test gizli anahtarıyla test edin.

Üretim kontrollerini zayıflatmadan kimlik doğrulamayı test edin

Sağlayıcı imzalı geri çağırmalar belirtiyorsa, rastgele bir imza başlığı veya algoritması seçmek yerine tam olarak bu yöntemi uygulayın. İstek baytlarını imzalayan yöntemlerde doğrulama için özgün gövdeyi koruyun; JSON'u ayrıştırıp yeniden serileştirmek bu baytları değiştirebilir.

Uygun kimlik doğrulamayı, eksik kimlik bilgilerini, değiştirilmiş gövdeleri ve uygulanabiliyorsa hatalı imzaları test edin. Belgelenen yöntem zaman damgaları veya replay koruması içeriyorsa bu kuralları da test edin. HMAC standartlaştırılmış bir mesaj kimlik doğrulama yapısıdır, ancak varlığı belirli bir takip sağlayıcısının bunu kullandığını göstermez.

Yinelenenleri, sıralamayı ve kurtarmayı test edin

Aynı güncelleme tekrar tekrar geldiğinde veya olaylar beklenmeyen bir sırayla ulaştığında gönderi işleme doğru kalmalıdır. Bunlar belirli bir sağlayıcının teslimat garantisi hakkında iddia değil, savunmacı test senaryolarıdır.

TestBeklenen uygulama davranışı
Aynı olayı iki kez gönderinTek bir mantıksal olay tutun ve yinelenen müşteri bildirimlerinden kaçının.
Teslimattan sonra daha eski bir taşıma taraması gönderinYararlı geçmişi koruyun, ancak teslim edildi durumunu otomatik olarak geri çevirmeyin.
Eş zamanlı güncellemeler gönderinEş zamanlı worker'lara rağmen tutarlı durum geçişleri uygulayın.
Kalıcı alımdan sonra işlemeyi durdurunYeni bir geri çağırma gerektirmeden saklanan olayı kurtarın ve işleyin.
Alım kalıcı hale gelmeden önce depolamayı başarısız kılınBaşarılı kabulü yanlış biçimde onaylamayın.
Bilinmeyen bir gönderi gönderinTanımlı bir karantina veya reddetme politikasını izleyin; sipariş ilişkisini asla tahmin etmeyin.

Sağlandığında yinelenenleri önlemek için belgelenmiş ve sabit bir olay tanımlayıcısını tercih edin. Aksi halde ilgili alanlardan dikkatle sınırlandırılmış bir kimlik tanımlayın ve çakışmaları test edin. Tek bir gönderi birçok geçerli güncelleme üretebileceğinden, takip numarası tek başına olay kimliği değildir.

Olay geçmişini mevcut gönderi görünümünden ayırın. Geçmiş taramaları tutmak, geç gelen her taramanın görüntülenen durumu geçersiz kılmasına izin vermeyi gerektirmez. “En yeni zaman damgasını kullan” da eksiksiz bir kural değildir: düzeltmeler, iade akışları ve farklı zaman damgası anlamları açık işlem gerektirir.

Eşzamansız işlemede, mimarinize uygun olarak, olayın işlenmiş bir inbox kaydı veya kalıcı kuyruk gibi kalıcı bir devretme noktasına ulaşmasından sonra onay verin. Sağlayıcının belgelenmiş onay gereksinimlerini izleyin. HTTP durum kodu anlamlarını tanımlar, ancak belirli bir göndericinin yeniden deneme takvimi kendi sözleşmesinden gelmelidir.

Kontrollü bir canlı kontrol gerçekleştirin ve yayın kriterlerini belirleyin

Deterministik testler geçtikten sonra gerçek entegrasyon üzerinden yetkili bir gönderi kaydedin ve tüm yolu doğrulayın. Sağlayıcının amaçlanan kaydı kabul ettiğini, geri çağırma yapılandırmasının doğru ortama yöneldiğini ve gelen verilerin beklenen gönderiyle eşleştiğini kontrol edin.

Bu canlı kontrol sırasında her gönderi durumunun görünmesini beklemeyin. Gerçek gönderiler kontrol edilebilir fixture'lar değildir. Canlı çalıştırmayı bağlantıyı ve gözlemlenen sözleşme uyumluluğunu doğrulamak için kullanın; nadir veya yıkıcı senaryoları kapsamak için yeniden oynatılabilir fixture'ları kullanın.

Yayın öncesinde şu sonuçları zorunlu kılın:

  • API toplu işlemleri destekliyorsa öğe düzeyindeki hatalar dahil olmak üzere belgelenmiş başarı ve hata yanıtları işlenir.
  • İlk istek zaten başarılı olmuş olabileceğinde zaman aşımları körlemesine oluşturma yeniden denemelerini tetiklemez.
  • Yinelenen olaylar yinelenen iş aksiyonları oluşturamaz.
  • Geçersiz geri çağırmalar gönderi durumunu değiştiremez.
  • Worker hataları olayları sessizce kaybetmek yerine kurtarılabilir halde bırakır.
  • Geliştirme trafiği gerçek müşterilere bildirim gönderemez veya üretim siparişlerini değiştiremez.
  • Günlükler, gizli bilgileri açığa çıkarmadan istekleri, alınan olayları, işleme sonuçlarını ve bildirim girişimlerini birbirine bağlar.

Belirsiz bir istek, tekrarlanan geri çağırma veya kesintiye uğramış worker sonrasında sistemin nasıl kurtulduğunu ve normal iş akışını açıklayabildiğinizde yayın hazırdır. Tek bir başarılı takip sorgusu yeterli değildir.

SSS

Sandbox olmadan bir takip entegrasyonunu test edebilir miyim?

Evet. Giden API sınırını mock'layın, belgelenmiş geri çağırma fixture'larını yeniden oynatın ve normalleştirme ile iş kurallarınızı yerel olarak test edin. Ardından gerçek bağlantıyı doğrulamak için yetkili bir canlı gönderi kullanın. Bu önemli ölçüde kapsam sağlar, ancak belgelenmemiş sağlayıcı davranışını yeniden üretmez.

Takip isteğim neden başarılı oluyor ancak hiç olay döndürmüyor?

İstek kabulü ve takip verilerinin kullanılabilirliği farklı sonuçlardır. Sağlayıcının yanıt ayrıntılarını, kayıt gereksinimlerini, taşıyıcı tanımlama kurallarını ve olaysız gönderiler için belgelenmiş davranışı kontrol edin. Boş bir zaman çizelgesini doldurmak için hareket veya teslimat bilgisi uydurmayın.

Başarılı bir sahte webhook gerçek webhook'ların ulaşacağını kanıtlar mı?

Hayır. Yalnızca mock tarafından çalıştırılan yolu kanıtlar. Gerçek teslimat ayrıca sağlayıcı yapılandırmasına, genel erişilebilirliğe, TLS'ye, kimlik doğrulamaya ve gerçek geri çağırma sözleşmesine bağlıdır. Bunları sağlayıcı destekli bir test teslimatı veya yetkili bir canlı iş akışıyla doğrulayın.

İşleme tamamlanmadan önce HTTP 200 döndürmeli miyim?

Sağlayıcının belgelenmiş onay sözleşmesini izleyin. Eşzamansız bir tasarımda kalıcı kabulden sonra onay verin, ardından bir worker'da işleyin. Kalıcı kabulden önce başarı döndürmek, işlem hemen sonrasında başarısız olursa bir olayın kaybolmasına neden olabilir.

Müşteri bildirimlerini nasıl test etmeliyim?

Tüm geliştirme bildirimlerini kontrollü bir havuza gönderin. Hedefi, şablonu, tetikleyen geçişi ve gönderim sayısını doğrulayın. Tek bir gönderi güncellemesinin yinelenen müşteri mesajları oluşturmadığını doğrulamak için aynı olayı yeniden oynatın ve worker yeniden denemelerini simüle edin.

Kaynaklar

  • 17TRACK Tracking API — takip API ürünü için resmi başlangıç noktası.
  • 17TRACK API belgeleri — sağlayıcıya özgü entegrasyon sözleşmesi için referans; geçerli test ve geri çağırma gereksinimlerini burada doğrulayın.
  • RFC 9110: HTTP Semantics — HTTP yanıt anlamları ve isteklerin yeniden denenmesine ilişkin hususlar.
  • RFC 2104: HMAC — geri çağırma güvenliği rehberinde ele alınan standartlaştırılmış mesaj kimlik doğrulama yapısı.