Skip to main content
AnasayfaBlogKılavuzlarAPI Gönderiminden Önce Takip Numaraları Nasıl Doğrulanır: Uyulması Gereken 7 Kural

API Gönderiminden Önce Takip Numaraları Nasıl Doğrulanır: Uyulması Gereken 7 Kural

17TRACK

Bir takip API'sine göndermeden önce bir takip numarasını katmanlar halinde doğrulayın: girdiyi normalleştirin, temel yapısını kontrol edin, taşıyıcı bağlamını doğrulayın, sağladığı belgelerde bir sağlama toplamı belirtilmişse yalnızca o zaman uygulayın ve açıkça güvensiz veya eksik değerleri reddedin. Tek bir evrensel düzenli ifadeye güvenmeyin. Takip numarası biçimleri taşıyıcıya, hizmete, ülkeye ve gönderi türüne göre değişir. Bu nedenle etkili bir doğrulayıcı, kötü istekleri önlerken alışılmadık bir biçim kullanan geçerli numaraları engellememelidir.

API Gönderiminden Önce Takip Numaraları Nasıl Doğrulanır: 7 Kural

Bu kılavuz; sipariş yönetim sistemine, depo iş akışına, müşteri portalına veya e-ticaret uygulamasına gönderi takibini entegre eden geliştiriciler ve operasyon ekipleri için hazırlanmıştır. Amaç, gönderimden önce bir paketin var olduğunu kanıtlamak değildir. Sözdizimsel doğrulama ile gönderi durumu doğrulaması ayrı adımlardır.

Doğrulama neleri doğrulayabilir ve neleri doğrulayamaz?

Gönderim öncesi bir doğrulayıcı; boş değer, yanlışlıkla eklenmiş boşluklar, desteklenmeyen karakterler, aşırı uzunluk veya yanlış alana girilmiş takip numarası gibi yaygın giriş sorunlarını tespit edebilir. Taşıyıcı biliniyor ve biçim belgelenmişse olası taşıyıcıyı da belirleyebilir.

Normalde bir numaranın gerçek bir gönderiye ait olduğunu, paketin bir taşıyıcı tarafından kabul edildiğini veya numaranın şu anda takip edilebilir olduğunu doğrulayamaz. Bu sorular için taşıyıcı ya da takip platformu sorgulaması gerekir. Bir numara biçim kontrolünü geçse bile kullanılmamış, küçük bir yazım hatası içeren, süresi dolmuş veya farklı bir hizmetle ilişkilendirilmiş olabilir.

Yedi kural

1. Anlamını değiştirmeden değeri normalleştirin

Kullanıcılar ve üst sistemler sıklıkla başta veya sonda boşluklar, satır sonları, bölünemez boşluklar ya da biçimlendirme karakterleri ekler. Doğrulamadan önce bunları güvenli biçimde normalleştirin. Yaygın bir ilk adım, çevredeki boşlukları kırpmak ve yazdırılmayan boşlukları normal boşluklara dönüştürmektir. Taşıyıcının belgelenmiş biçimi dahili boşluklara veya tirelere izin veriyorsa bunları API isteği için kaldırmaya mı yoksa görüntüleme ve denetim amacıyla özgün değeri korumaya mı karar verin.

Mümkün olduğunda iki değer tutun: özgün girdi ve kurallı değer. Özgün değer, destek ekiplerinin veri kalitesi sorunlarını incelemesine yardımcı olur; kurallı değer ise doğrulama ve gönderim için kullanılır. Tanımlayıcıları değiştirebilecek dönüşümlerden kaçının. İlgili taşıyıcı veya API belgeleri bunu açıkça desteklemiyorsa harfleri otomatik olarak sayılara dönüştürmeyin, belirsiz karakterleri değiştirmeyin veya tüm noktalama işaretlerini kaldırmayın.

Unicode işleme dikkat gerektirir. Başka bir alfabeden alınmış görsel olarak benzer bir karakter, ASCII harfi veya rakamı gibi görünse bile API tarafından kabul edilmeyebilir. Kurallı değeri seçilen entegrasyonun izin verdiği karakter kümesiyle sınırlamak, kafa karıştırıcı sonraki hataları önleyebilir.

2. Temel yapısal kontrolleri geçemeyen değerleri reddedin

Taşıyıcıya özgü mantığı uygulamadan önce değerin mevcut ve makul olup olmadığını kontrol edin. Yararlı kontroller arasında minimum ve maksimum uzunluk, izin verilen karakter sınıfları ve değerin yalnızca boşluklardan veya “N/A”, “TBD” ya da “test” gibi bir yer tutucudan oluşup oluşmadığı bulunur. Kesin sınırlar API sözleşmesinden veya taşıyıcı belgelerinden alınmalıdır. Örneklerin çoğu kısa diye evrensel bir maksimum uzunluk uydurmayın.

Yapısal kontrol bilinçli olarak ihtiyatlı olmalıdır. Örneğin yalnızca rakamlara izin veren bir kural, geçerli alfasayısal tanımlayıcıları reddeder. Sabit bir uzunluk gerektiren bir kural, hizmet varyantlarını veya uluslararası biçimleri reddedebilir. Genel kontrolleri açık hataları yakalamak için kullanın; daha özel kontrolleri yalnızca taşıyıcı ve hizmet bilindiğinde uygulayın.

Ayrıca uygulama sınırında veri türünü doğrulayın. Takip numarası genellikle tam sayı olarak değil, dize olarak ele alınmalıdır. Sayısal dönüşüm baştaki sıfırları kaldırabilir ve sabit genişlikte sayısal türler kullanan sistemlerde hassasiyet sorunları oluşturabilir. Onaylanmış normalleştirmeden sonra değeri tam olarak dize biçiminde koruyun.

3. Yalnızca numaradan tahmin etmek yerine taşıyıcı bağlamını kullanın

Taşıyıcısı olmayan bir takip numarası belirsiz bir girdidir. Farklı taşıyıcılar örtüşen uzunluklar, ön ekler veya karakter kümeleri kullanabilir ve bir taşıyıcı için makul görünen biçim başka bir taşıyıcı için geçersiz olabilir. Sipariş, etiket, depo sistemi veya satıcı hesabı taşıyıcıyı zaten belirliyorsa API desteklediği sürece bu bağlamı takip numarasıyla birlikte gönderin.

Taşıyıcı bağlamı hem doğrulamayı hem de yönlendirmeyi iyileştirir. Uygulamanızın ilgili biçim kurallarını seçmesini, yanlış eşleşmeleri azaltmasını ve hata mesajlarını daha kullanışlı hale getirmesini sağlar. Ayrıca birden fazla taşıyıcının benzer görünen bir değeri kabul edebileceği durumlarda otomatik algılama sonucunun gerçekmiş gibi değerlendirilmesini önler.

Taşıyıcı bilinmiyorsa iki aşamalı bir yaklaşım kullanın. Önce genel güvenlik kontrollerini çalıştırın. Ardından değeri yalnızca taşıyıcı algılamayı açıkça destekleyen bir API akışı üzerinden gönderin veya iş süreci doğrulanmış bir taşıyıcı gerektiriyorsa inceleme kuyruğuna alın. Bu eşleme korunmuyor ve belgelenmiyorsa yalnızca bir ön eke dayanarak taşıyıcı atamayın.

4. Sağlama toplamlarını yalnızca kural belgelenmişse uygulayın

Bazı tanımlayıcı sistemleri kontrol basamakları kullanır, ancak takip numaraları tek bir evrensel sağlama toplamı standardına tabi değildir. Sağlama toplamı belirli aktarım hatalarını tespit edebilir, ancak bir gönderinin var olduğunu kanıtlamaz. Daha da önemlisi, yanlış sağlama toplamı algoritmasını uygulamak geçerli numaraları reddedebilir.

Sağlama toplamını yalnızca ilgili taşıyıcı, hizmet, etiket spesifikasyonu veya API belgeleri algoritmayı ve kapsadığı girdi bölümünü tanımlıyorsa uygulayın. Kuralın sürümünü kaydedin ve resmi örneklerle test edin. Yetkili bir kural yoksa küçük bir örnekte gözlemlenen kalıplardan tahmin yürütmek yerine sağlama toplamını atlayın.

Sağlama toplamı sonucunu tam bir doğrulama kararı olarak değil, sinyallerden biri olarak değerlendirin. Kural yetkiliyse başarısız kontrol gönderimi engellemeyi haklı çıkarabilir. Başarılı kontrol ise değeri sonraki aşamaya taşımalı, onu canlı bir gönderi olarak işaretlememelidir.

5. Biçim doğrulamasını API uygunluğundan ayırın

Bir değer doğru biçimlendirilmiş olabilir ancak çağırdığınız uç nokta için yine de uygun olmayabilir. Gönderimden önce API belgelerinde zorunlu alanları, kabul edilen taşıyıcı tanımlayıcılarını, kimlik doğrulama gerekliliklerini, istek sınırlarını, yinelenen istek işleme davranışını ve hizmet türleri ya da hedeflerle ilgili kısıtlamaları kontrol edin. Bunlar takip numarası kuralları değil, entegrasyon kurallarıdır; ancak geçerli bir tanımlayıcının başarıyla işlenip işlenemeyeceğini belirler.

17TRACK Tracking API belgeleri bu ayrımın neden önemli olduğuna örnektir: geliştiricilerin, takip numarasının görünümünden bir istek uydurmak yerine platformun istek modelini ve desteklenen entegrasyon davranışını izlemesi gerekir. Uç nokta gereklilikleri ve yanıt işleme için güncel belgelere 17TRACK API belgelerinden başvurun.

Doğrulama hatalarını aktarım ve kimlik doğrulama hatalarından ayrı tutun. “Geçersiz takip numarası biçimi”, “bilinmeyen taşıyıcı”, “hız sınırına ulaşıldı” ve “yetkilendirme başarısız” farklı eylemler gerektirir. Tek ve genel bir “gönderim başarısız” mesajı, yeniden denemeleri ve operasyonel raporlamayı daha az güvenilir hale getirir.

6. Sınırlandırılmış girdiler, tekilleştirme ve güvenli yeniden denemelerle API''yi koruyun

Doğrulama aynı zamanda operasyonel bir güvenlik önlemidir. Ayrıştırmadan veya günlüğe kaydetmeden önce giriş uzunluğunu sınırlandırın. Kontrol karakterlerini ve beklenmeyen yük yapılarını reddedin. Hatalı bir içe aktarmanın kontrolsüz bir istek patlaması oluşturamaması için kendi uygulama sınırınızda hız sınırları uygulayın.

İş süreci tekrarlanan kaydı gerektirmiyorsa gönderimden önce tekilleştirme yapın. Yararlı bir tekilleştirme anahtarı; kurallı takip numarasını, taşıyıcıyı, hesabı ve gönderi bağlamını içerebilir. Doğru anahtar iş akışınıza bağlıdır; aynı tanımlayıcı bazen farklı hizmetler veya iş kayıtları arasında yeniden kullanılabilir. Bu nedenle yalnızca numaranın her zaman küresel olarak benzersiz olduğunu varsaymayın.

Geçici hatalar için geri çekilmeli ve sınırlandırılmış yeniden denemeler kullanın; kalıcı doğrulama hatalarını yeniden denemekten kaçının. API ve mimariniz destekliyorsa bir idempotency veya gönderim kaydı saklayın. İsteği gidermek için yeterli bilgiyi günlüğe kaydedin, ancak kimlik bilgilerini, müşteri verilerini ve hassas gönderi ayrıntılarını koruyun. Doğrulayıcı tekrarlanan hataları azaltmalı, aşırı günlük kaydıyla ikinci bir güvenlik sorunu oluşturmamalıdır.

7. Gönderimden sonra sonucu doğrulayın ve yanlış pozitifleri izleyin

Son kural, gönderim öncesi doğrulamayı bir hüküm değil, geçiş kapısı olarak değerlendirmektir. İstek kabul edildikten sonra API yanıtını inceleyin ve durumunu, istek tanımlayıcısını, taşıyıcı ilişkisini ve belgelenmiş hata kodlarını kaydedin. Platform isteği kabul ediyor ancak henüz hareket olaylarını döndüremiyorsa bu, geçersiz bir numaradan çok işleme gecikmesine işaret edebilir.

Çözülmeden kalan numaralar için bir takip politikası tanımlayın. Süre aralığı taşıyıcıyı, hizmeti, gönderim kaynağını ve müşteri hizmetleri politikanızı yansıtmalıdır; bir numaranın geçersiz olduğunu kanıtlayan evrensel bir süre yoktur. Eksik taşıyıcısı, tekrarlanan sağlayıcı hataları, çelişkili taşıyıcı sonuçları veya sipariş kaydıyla eşleşmeyen durumu olan kayıtları üst seviyeye aktarın.

Yanlış retleri ve yanlış kabulleri ölçün. Katı bir düzenli ifade hatalı gönderimleri azaltırken geçerli gönderileri yanlışlıkla engelleyebilir. İzin verici bir doğrulayıcı daha fazla isteği kabul edebilir, ancak sonraki süreçte gürültü oluşturabilir. Başarısız örnekleri taşıyıcı ve hizmet bazında inceleyin, belgelenmiş kuralları sürüm denetimiyle güncelleyin ve değişiklikleri temsili, gizlilik açısından güvenli bir test veri kümesine karşı test edin.

Pratik bir doğrulama sıralaması

Sürdürülebilir bir uygulama aşağıdaki sıralamayı kullanabilir:

  1. İsteğin bir dize değeri ve geçerli bir iş kaydı içerdiğini kontrol edin.
  2. Özgün girdiyi kaydedin, ardından belgelenmiş bir kurallı biçim oluşturun.
  3. Boş değerleri, yer tutucuları, güvensiz karakterleri ve belgelenmiş uzunluk aralığının dışındaki değerleri reddedin.
  4. Taşıyıcıyı güvenilir sipariş verilerinden çözümleyin veya açıkça desteklenen bir algılama akışı kullanın.
  5. Taşıyıcıya özgü sözdizimi ve sağlama toplamı kurallarını yalnızca yetkili belgeler destekliyorsa uygulayın.
  6. Uç nokta gerekliliklerini, yinelenen kayıt durumunu ve yeniden deneme uygunluğunu kontrol edin.
  7. Gönderin, yanıtı sınıflandırın, sonucu saklayın ve çözümlenmemiş kayıtlar için takip planlayın.

Bu sıralama, her kararın farklı bir nedeni olduğu için doğrulayıcının test edilmesini kolaylaştırır. Ayrıca operasyon ekiplerine tek ve anlaşılmaz bir hata yerine uygulanabilir hata kategorileri sunar.

Uygulama kontrol listesi

  • Baştaki sıfırların korunması için takip numaralarını dize olarak saklayın.
  • Denetlenebilirlik önemli olduğunda özgün ve kurallı değerleri ayrı tutun.
  • Taşıyıcı kurallarını dağınık sabit kodlu koşullar yerine sürümlendirilmiş yapılandırma olarak yönetin.
  • Harfleri, rakamları, tireleri, boşlukları, Unicode benzer karakterlerini, yer tutucuları ve sınır uzunluklarını test edin.
  • Mevcut olduğunda güvenilir taşıyıcı bağlamını kullanın.
  • Başarılı bir düzenli ifade eşleşmesinden gönderinin var olduğu sonucunu çıkarmayın.
  • Kalıcı doğrulama hatalarını geçici API veya ağ hatalarından ayrı sınıflandırın.
  • Biçim kurallarını veya istek mantığını değiştirmeden önce sağlayıcı belgelerini inceleyin.

SSS

Düzenli ifade bir takip numarasını doğrulayabilir mi?

Taşıyıcı ve hizmet biçimi biliniyorsa sınırlı bir kalıbı doğrulayabilir. Numaranın var olduğunu, belirli bir gönderiye ait olduğunu veya hâlâ etkin olduğunu kanıtlayamaz. Evrensel bir ifade büyük olasılıkla yanlış retler veya yanlış eşleşmeler oluşturur.

Geçersiz görünümlü bir numara API''ye gönderilmeli mi?

Açıkça boş, güvensiz veya yapısal olarak imkânsız değerler normalde gönderimden önce durdurulmalıdır. Aksi halde güvenli olan ancak alışılmadık bir biçim, yalnızca dahili bir tahminle eşleşmediği için reddedilmemelidir. Önce taşıyıcı belgelerini kontrol edin veya desteklenen bir algılama süreci kullanın.

Bir gönderiyi doğrulamak için sağlama toplamı yeterli midir?

Hayır. Uygulanabildiğinde sağlama toplamı yalnızca değerin matematiksel bir kuralı karşılayıp karşılamadığını test eder. Taşıyıcının numarayı verdiğini veya paketin ağa girdiğini doğrulamaz.

Taşıyıcı bilinmiyorsa ne yapılmalı?

Genel güvenlik kontrollerini çalıştırın ve varsa taşıyıcı algılamayı açıkça destekleyen bir API iş akışı kullanın. Aksi halde taşıyıcıyı sessizce tahmin etmek yerine kaydı zenginleştirme veya manuel inceleme için saklayın.

API hataları nasıl ele alınmalı?

Hataları nedenlerine göre sınıflandırın. Hatalı girdileri ve desteklenmeyen taşıyıcı değerlerini düzeltin; geçici ağ veya sağlayıcı hatalarını sınırlı ve geri çekilmeli yeniden denemelerle tekrarlayın; kimlik doğrulama veya kota hatalarını entegrasyon sorumlusuna yönlendirin. Sırları açığa çıkarmadan tanılama için gereken yanıt ayrıntılarını saklayın.

Kaynaklar