Tek Bir API İsteğinde Birden Fazla Takip Numarası Nasıl Gönderilir (Toplu İşlem Sınırları ve Kısmi Başarısızlıklar)
Bir API isteğinde birden fazla takip numarası göndermek için açıkça toplu işlemleri kabul eden bir Tracking API uç noktası kullanın, her gönderiyi kendi istek şemasına göre biçimlendirin ve daha uzun listeleri belgelenmiş sınırlar içindeki gruplara bölün. Ardından hem HTTP yanıtını hem de her gönderinin sonucunu inceleyin: başarılı bir HTTP isteği, her takip numarasının kabul edildiği anlamına gelmez. Yalnızca uygun hataları yeniden deneyin ve tüm grubu yeniden göndermeden önce belirsiz sonuçları uzlaştırın.

Bu kılavuz; gönderi takibini bir sipariş yönetim sistemine, depo platformuna, e-ticaret uygulamasına veya dahili panele bağlayan geliştiriciler içindir. Amaç yalnızca daha az istek göndermek değildir. Amaç, yinelenen işler oluşturmadan veya başarısız kayıtları kaybetmeden her gönderiyi hesaba katmaktır.
Öncelikle toplu işlem uç noktasının gerçekte ne yaptığını belirleyin
Bir takip entegrasyonu birkaç farklı işlem içerebilir. Gönderileri kaydetmek, en güncel takip bilgilerini almak ve sonraki güncellemeleri almak birbirinin yerine geçmez.
- Kayıt: Hizmetin gönderileri izlemeye başlaması veya izlemeyi sürdürmesi için gönderileri gönderin.
- Sorgulama: Uç noktanın alma kurallarına tabi olarak gönderiler için takip bilgisi isteyin.
- Teslimat güncellemesi: Web kancaları gibi desteklenen bir mekanizma aracılığıyla sonraki değişiklikleri alın veya bunları planlanmış isteklerle alın.
İhtiyacınız olan kesin işlem için belgeleri kontrol edin. Birden fazla kaydı kabul eden bir kayıt uç noktası, bir sorgulama uç noktasının aynı sayıyı kabul ettiğini, aynı şemayı kullandığını veya aynı hız sınırını paylaştığını göstermez.
17TRACK entegrasyonu için Tracking API ürün sayfası ile başlayın ve işlemi, kimlik doğrulama yöntemini, istek biçimini ve yanıt alanlarını doğrulamak için resmî API belgelerini kullanın. Aşağıdaki örnekleri bu API sözleşmesinin yerine geçmeyen uygulama kalıpları olarak değerlendirin.
Toplu işlem sınırları, gönderi sayısı için bir üst sınırdan fazlasıdır
Bir Tracking API için evrensel bir toplu işlem sınırı yoktur. Sınırlar sağlayıcıya, uç noktaya, API sürümüne ve hesap yapılandırmasına göre değişebilir. Toplu işlem uygulamadan önce bu kısıtları ayrı ayrı kaydedin.
| Kısıtlama | Doğrulanacak konu | Uygulama sonucu |
|---|---|---|
| İstek başına öğe sayısı | Belirli işlem için maksimum kayıt sayısı | Göndermeden önce giriş listesini bölün |
| İstek gövdesi boyutu | Belgelenmiş bir bayt sınırı olup olmadığı | İsteğe bağlı alanları ve serileştirme boyutunu hesaba katın |
| İstek hızı | Belirli bir aralıkta izin verilen istek sayısı | İstekleri ortak bir sınırlayıcı üzerinden hızlandırın |
| Eşzamanlılık | Eşzamanlı isteklerle ilgili herhangi bir kısıtlama | Aktif çalışan sayısını sınırlandırın |
| Kullanım hesaplama | Kullanımın istek, gönderi veya başka bir birime göre sayılıp sayılmadığı | Tüketimi istek hacminden ayrı tahmin edin |
Örneğin, varsayımsal bir uç nokta istek başına 25 kayda izin veriyorsa, 63 kayıt için 25, 25 ve 13 kayıt içeren üç istek gerekir. Bu sayılar yalnızca gruplamayı açıklar; 17TRACK sınırları olarak belirtilmemiştir.
Toplu işlemenin faturalandırılabilir kullanımı azalttığını varsaymayın. HTTP istek ek yükünü azaltabilir, ancak ücretler üzerindeki etkisi sağlayıcının gerçek hesaplama kurallarına bağlıdır. Benzer şekilde, geçerli bir grup boyutu sınırsız paralel isteğe izin vermez.
İsteği oluşturmadan önce kayıtları hazırlayın
Önlenebilir toplu işlem hatalarının çoğu giriş hazırlığından kaynaklanır. Her gönderiyi bir gruba eklemeden önce doğrulayın, ancak farklı taşıyıcılara ait geçerli takip numaralarını yanlışlıkla reddeden kurallardan kaçının.
- Takip numaralarını dize olarak koruyun. Bunları sayıya dönüştürmek baştaki sıfırları kaldırabilir veya uzun tanımlayıcıları değiştirebilir.
- Yanlışlıkla eklenen çevresel boşlukları kaldırın. İlgili belirtim bu normalleştirmeye izin vermedikçe iç karakterleri kaldırmayın veya büyük/küçük harf durumunu değiştirmeyin.
- Gerekli alanları doğrulayın. Bazı iş akışları taşıyıcı tanımlayıcısı veya ek gönderi bilgileri gerektirebilir. Yalnızca belgelenmiş alan adlarını ve değerlerini kullanın.
- Açık bir tekilleştirme kapsamı seçin. Tekrarlanan bir takip numarası, her taşıyıcı, satıcı veya geçmiş gönderi genelinde otomatik olarak yinelenen kayıt değildir.
- Yerel bir gönderi tanımlayıcısı tutun. API özel referans alanlarını kabul etmese bile giden öğe ile sipariş veya gönderi kaydınız arasındaki ilişkiyi saklayın.
Birden fazla ağda Carrier Tracking kullanırken, bu çıkarım kendi iş akışınız için güvenilir olmadıkça taşıyıcıyı yalnızca takip numarasının uzunluğuna veya ön ekine göre belirlemeyin. API taşıyıcı tanımlamayı destekliyorsa belgelenmiş belirsizlik işleme davranışını izleyin.
Örnek istek yapısı
Aşağıdaki JSON, toplu işlem yükü kavramını gösterir. Kapsayıcı, özellik adları ve tanımlayıcılar örnek niteliğindedir; 17TRACK istek şeması değildir. Bazı API'ler dizi içeren bir nesne yerine üst düzey bir dizi bekler.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Yükü dizeleri birleştirmek yerine JSON serileştirici aracılığıyla oluşturun. Kimlik doğrulama bilgilerini belgelenmiş mekanizma üzerinden gönderin ve bunları kaynak denetiminden, tarayıcıya gönderilen koddan ve rutin günlüklerden uzak tutun.
Yanıtı iki düzeyde işleyin
Bir toplu işlem isteğinin aktarım düzeyinde ve uygulama düzeyinde bir sonucu vardır. Entegrasyonunuz her ikisini de değerlendirmelidir.
Düzey 1: İstek kullanılabilir bir yanıt aldı mı?
HTTP durumuyla, yanıt başlıklarıyla ve yanıt gövdesiyle başlayın. Kimlik doğrulama hataları, hatalı biçimlendirilmiş istekler, hız sınırlaması ve sunucu hataları normal öğe işlemeyi engelleyebilir. Ağ zaman aşımı farklıdır: istemci, sunucunun isteği alıp almadığını veya işleyip işlemediğini bilemeyebilir.
HTTP semantiği RFC 9110 ile tanımlanır. Ancak uygulama düzeyindeki sonuç alanlarının gerçek gönderi sonuçlarına nasıl eşlendiğini sağlayıcının belgeleri belirler.
Düzey 2: Her gönderiye ne oldu?
Yanıt öğe düzeyinde sonuçları destekliyorsa gönderilen her kaydı sınıflandırın. HTTP 200'ün her kaydın başarılı olduğu anlamına geldiğini veya sözleşme açıkça garanti etmedikçe sonuç listesinin istek sırasını koruduğunu varsaymayın.
- Kabul edildi: İşlem, uç noktanın belgelenmiş tanımına göre başarılı oldu.
- Kalıcı giriş hatası: Başka bir denemeden önce kaydı düzeltin veya inceleyin.
- Yeniden denenebilir hata: Sağlayıcının yeniden deneme yönergelerine göre başka bir deneme planlayın.
- Bilinmeyen sonuç: Yanıt eksik, tamamlanmamış veya gönderilen kayıtla güvenli biçimde eşleştirilemiyor.
“Zaten kaydedildi” veya benzer yinelenen kayıtla ilgili yanıtları belgelenmiş anlamlarını anlayana kadar ayrı tutun. Bunlar istenen durumun zaten mevcut olduğunu gösterebilir, ancak otomatik olarak başarılı sahiplik, yapılandırma veya abonelik onayı olarak değerlendirilmemelidir.
Bir yanıtı işledikten sonra her giriş kaydının tam olarak bir yerel sonucu olmalıdır. Yararlı bir uzlaştırma kontrolü şudur: gönderilen kayıtlar = kabul edilen kayıtlar + kalıcı hatalar + yeniden denenebilir hatalar + bilinmeyen sonuçlar. Bu, yerel bir muhasebe kuralıdır; gerekli bir API yanıt biçimi değildir.
Başarılı kayıtları yeniden oynatmadan kısmi hataları yönetin
Örnek bir grubun on gönderi içerdiğini varsayalım: yedisi kabul edilmiş, ikisinin gerekli alanları geçersiz ve birinde belgelenmiş geçici bir hata oluşmuş olsun. Yedi başarılı sonucu kaydedin, iki geçersiz kaydı düzeltme için yönlendirin ve yalnızca geçici hatayı yeniden deneyin.
On kaydın tamamını yeniden oynatmak gereksiz trafik oluşturur ve yinelenen kayıtların işlenmesini zorlaştırabilir. Ayrıca ilk reddi sonraki yinelenen kayıtla ilgili yanıttan ayırt etmeyi zorlaştırır.
| Sonuç | Önerilen işlem |
|---|---|
| Geçersiz alan veya desteklenmeyen değer | Girişi düzeltin; değiştirmeden yeniden denemeyin |
| Kimlik doğrulama veya izin hatası | Etkilenen çalışmayı duraklatın ve kimlik bilgilerini veya erişimi düzeltin |
| Hız sınırı yanıtı | Belgelenmiş yönergelere ve geçerli yanıt başlıklarına göre geciktirin |
| Geçici öğe düzeyinde hata | Bu öğeyi sınırlı deneme ve bekleme süresiyle yeniden deneyin |
| Gönderimden sonra zaman aşımı | Belirsiz olarak işaretleyin; uzlaştırın veya belgelenmiş yeniden deneme güvenliği garantilerini kullanın |
| Tanınmayan veya tamamlanmamış sonuç | Başarı varsaymak yerine kanıtı saklayın ve inceleyin |
HTTP 429 çok fazla isteği belirtir ve yanıt, RFC 6585'te açıklandığı üzere Retry-After başlığını içerebilir. Bu başlığın her zaman bulunduğunu varsaymayın. Açık bir yeniden deneme gecikmesi sağlanmadığında API belgeleriyle uyumlu sınırlı bir bekleme politikası kullanın.
Birden fazla çalışanın yeniden denemelerini yaymak için rastgele gecikme ekleyin, maksimum deneme sayısı veya yeniden deneme yaşı belirleyin ve tükenen kayıtları inceleme kuyruğuna gönderin. Sınırsız yeniden deneme, kalıcı bir yapılandırma sorununu gizleyebilir.
Zaman aşımları neden özel işlem gerektirir?
Zaman aşımı reddedilmeyi kanıtlamaz. Bağlantı kesilmeden önce sunucu grubu kabul etmiş olabilir. Bu nedenle durum değiştiren bir isteği otomatik olarak yeniden oynatmak işi tekrarlayabilir.
Uç nokta belgelenmiş idempotency anahtarlarını destekliyorsa anahtar kapsamı ve saklama süresi dâhil olmak üzere kurallarını izleyin. Bir idempotency başlığı uydurup sunucunun bunu dikkate aldığını varsaymayın. Aksi takdirde yeniden göndermeden önce istenen durumun mevcut olup olmadığını belirlemek için desteklenen bir sorgulama veya uzlaştırma iş akışı kullanın. Yerel tekilleştirme kendi çalışanlarınızı koordine etmeye yardımcı olur, ancak sunucu tarafında idempotency garantisi vermez.
Uygulanabilir bir toplu işlem iş akışı
Sağlayıcıya özgü ayrıntıları bir adaptörde tutun; böylece kuyruk, yeniden deneme zamanlayıcısı ve izleme mantığı ham yanıt alan adlarına bağlı olmaz.
kayıtları doğrula ve yerel gönderi kimliklerini koru
tasarlanan iş kapsamındaki yinelenen kayıtları çözümle
belgelenmiş öğe ve yük sınırlarını kullanarak kayıtları böl
sınırlı bir çalışan havuzu üzerinden her grup için:
göndermeden önce bir deneme kaydı kalıcı olarak sakla
ortak hız sınırlayıcıyı bekle
sağlayıcıya özgü adaptörü kullanarak gönder
sonuç belirsizse:
uzlaştırma kuyruğuna ekle
devam et
istek düzeyindeki ve öğe düzeyindeki sonuçları sınıflandır
gönderilen her kayıt için bir sonuç kalıcı olarak sakla
yalnızca uygun hataları yeniden denemeye planla
geçersiz veya tükenmiş kayıtları incelemeye yönlendir
Sonuçların kalıcı olarak saklanmasını ve yeniden deneme planlamasını kurtarılabilir hâle getirin. Örneğin kalıcı bir iş kaydı veya işlemsel kuyruklama düzeni, işlem çökmesinin yeniden deneme kararının kaybolmasını önleyebilir. Çalışanlar yeniden başlatıldığında gönderilmemiş işleri, uzak sonucu hâlâ belirsiz olan işlerden ayırt edebilmelidir.
Grup boyutunu kod tabanına dağılmış bir sabit olarak değil, ilgili uç noktaya bağlı yapılandırılabilir bir ayar olarak kullanın. Sorun giderirken veya sorunlu kayıtları izole ederken daha küçük bir grup yararlı olabilir; izin verilen en büyük grup otomatik olarak en iyi çalışma boyutu değildir.
Yalnızca HTTP çalışma süresini değil, gönderi sonuçlarını izleyin
API Monitoring, gönderilerin amaçlanan duruma ulaşıp ulaşmadığını göstermelidir. Yalnızca HTTP başarı oranlarını bildiren bir panel, başarılı görünen yanıtların içindeki kısmi hataları gözden kaçırabilir.
- Öğe kabul oranı: Yeniden denemelerin nasıl ele alındığı açıkça tanımlanarak kabul edilen kayıtların gönderilen kayıtlara oranı.
- Hata dağılımı: Uç noktaya, belgelenmiş hata koduna ve ilgili taşıyıcı bağlamına göre sayılar.
- Bilinmeyen sonuçlar: Uzlaştırılmamış kayıtlar ve ne kadar süredir çözümsüz kaldıkları.
- Yeniden deneme birikimi: Bekleyen yeniden denemeler, en eski yeniden denemenin yaşı ve tükenen denemeler.
- İstek sağlığı: Gecikme, zaman aşımları, hız sınırlaması ve sunucu hataları.
- Takip güncelliği: Kabul edilen gönderilerin daha sonra kullanılabilir takip bilgisi alıp almadığı.
Kayıt kabulü, yeni bir taşıyıcı taramasının kanıtı değildir. Entegrasyon olayının teslimat gecikmesiyle karıştırılmaması için API işleme durumunu gönderi hareketinden ve veri güncelliğinden ayrı tutun.
Yerel grup kimliklerini, gönderi referanslarını, deneme sayılarını, belgelenmiş hata kodlarını ve mevcut olduğunda sağlayıcı istek kimliklerini günlüğe kaydedin. Kimlik bilgilerini ve gereksiz kişisel bilgileri maskeleyin. Takip tanımlayıcılarını yalnızca operasyonel olarak gerekli olduğunda kullanın ve ham gönderi tanımlayıcılarını yüksek kardinaliteli metrik etiketlerine koymaktan kaçının.
Üretimden önce bu durumları test edin
Mevcut olduğunda belgelenmiş bir sanal alan veya kontrollü test ortamı kullanın. Uydurma takip numaralarının üretimde öngörülebilir yanıtlar vereceğini varsaymayın.
- Belgelenmiş öğe sınırında geçerli bir grup gönderin, ardından istemcinizin aşırı büyük bir grubu nasıl önlediğini test edin.
- Baştaki sıfırları içeren takip numaralarının serileştirme ve depolama sonrasında korunduğunu doğrulayın.
- Başarılı kayıtları yeniden denemeden kabul edilen ve reddedilen öğelerin karışımını test edin.
- Hız sınırlamasını simüle edin ve birden fazla çalışanın aynı sınıra uyduğunu doğrulayın.
- Gönderimden sonra zaman aşımını simüle edin ve uzlaştırma yolunu doğrulayın.
- Yanıtın alınması ile yerel kalıcılık arasında bir çalışanı yeniden başlatın.
- Eksik, bilinmeyen veya eşleştirilemeyen öğe sonuçlarını test edin.
- Geçersiz kayıtların sonsuza kadar yeniden denenmek yerine görünür bir düzeltme kuyruğuna ulaştığını doğrulayın.
Üretime hazır bir entegrasyon, sonucu geçici olarak bilinmeyenler de dâhil olmak üzere gönderilen her gönderinin durumunu açıklayabilir. İstek sayısını azaltmak yararlıdır; ancak bu hesap verebilirliği korumak daha önemli tasarım hedefidir.
SSS
Tek bir istekte kaç takip numarası gönderebilirim?
Tam uç nokta ve API sürümü için belgelenmiş sınırı kullanın. Ayrıca istek boyutunu, hız sınırlarını ve hesaba özgü kısıtlamaları kontrol edin. Tracking API'leri arasında veya tek bir API içindeki farklı işlemler arasında uygulanabilecek güvenli ve evrensel bir sayı yoktur.
Bir geçersiz takip numarası tüm grubun başarısız olmasına neden olabilir mi?
Evet, uç noktanın doğrulama kurallarına bağlı olarak olabilir. Bazı API'ler tek tek reddetmeler döndürürken bazıları öğe işlemesinden önce isteği reddedebilir. Hem istek düzeyindeki hataları hem de öğe düzeyindeki sonuçları kontrol edin; her toplu işlem uç noktasının kısmi kabulü desteklediğini varsaymayın.
HTTP yanıtı başarılı olduğunda bir grubu yeniden denemeli miyim?
Otomatik olarak değil. Önce belgelenmiş uygulama düzeyindeki durumu ve öğe sonuçlarını ayrıştırın. Başarılı kayıtları kalıcı olarak saklayın ve yalnızca uygun hataları yeniden deneyin. Sonuç güvenli biçimde yorumlanamıyorsa bunu belirsiz olarak sınıflandırın ve inceleyin.
Aynı grupta taşıyıcıları karıştırabilir miyim?
Yalnızca uç nokta bu istek yapısını destekliyorsa. Taşıyıcı bilgilerinin gönderi başına sağlanıp sağlanmadığını, otomatik tanımlamanın desteklenip desteklenmediğini ve tanımlama belirsiz olduğunda ne olduğunu doğrulayın. Çok taşıyıcılı bir hizmet, tek başına her uç noktanın toplu işlem kurallarını belirlemez.
Toplu işlem takip güncellemelerinin daha hızlı gelmesini sağlar mı?
Toplu işlem uygulamanızın gönderdiği istek sayısını azaltabilir, ancak taşıyıcı olaylarının daha erken görünmesini tek başına sağlamaz. Kayıt, veri alma, taşıyıcı taramasının kullanılabilirliği ve güncelleme teslimi iş akışının ayrı bölümleridir.
Kaynaklar
- 17TRACK Tracking API — takip entegrasyonunu değerlendiren geliştiriciler için resmî ürün giriş noktası.
- 17TRACK API belgeleri — sağlayıcıya özgü uç nokta sözleşmesi, sınırlar, kimlik doğrulama ve yanıt işleme için referans.
- RFC 9110: HTTP Semantiği — HTTP durum semantiği, idempotency, otomatik yeniden denemeler ve Retry-After.
- RFC 6585: Ek HTTP Durum Kodları — HTTP 429 Too Many Requests tanımı ve isteğe bağlı Retry-After başlığı.


