API aracılığıyla takip numarası kaydetme: İstek alanları, taşıyıcı kodları ve yanıtlar
Bir takip numarasını API üzerinden kaydetmek için gönderinin takip numarasını ve gerektiğinde taşıyıcı tanımlayıcısını içeren kimliği doğrulanmış bir kayıt isteği gönderin. Ardından yalnızca HTTP durumunu değil, gönderilen her gönderinin yanıtını inceleyin ve kaydın başarılı, başarısız veya belirsiz olup olmadığını kaydedin. Kayıt işlemi takip iş akışını başlatır; taşıyıcının paketi taradığını veya takip etkinliklerinin zaten mevcut olduğunu kanıtlamaz.
Bu kılavuz, bir sipariş yönetim sistemini, depo uygulamasını veya e-ticaret platformunu bir takip API'sine bağlayan geliştiriciler içindir. Somut bir entegrasyon örneği olarak 17TRACK'i kullanır ve seçtiğiniz API sürümü için hangi ayrıntıların belgelere göre kontrol edilmesi gerektiğini açıklar.
Kayıt işlemi ne yapar, ne yapmaz
Kayıt isteği, bir takip hizmetine hangi gönderiyi takip etmek istediğinizi bildirir. Kargo etiketi satın almaktan, teslim alma randevusu oluşturmaktan veya taşıyıcıdan gönderi oluşturmasını istemekten farklıdır. Tipik bir entegrasyonda, gönderim iş akışı önce bir takip numarası üretir ve uygulamanız daha sonra bu numarayı kaydeder.
Uygulamanızda şu üç olayı birbirinden ayrı tutun:
- Gönderi oluşturuldu: gönderim sisteminiz bir takip numarası atadı.
- Kayıt kabul edildi: takip hizmeti gönderiyi takip edilmek üzere kabul etti.
- Takip bilgisi alındı: taşıyıcı etkinlikleri takip hizmeti üzerinden kullanılabilir hâle geldi.
Yalnızca kayıt başarılı oldu diye bir siparişin durumunu “taşımada” olarak güncellemeyin. Yeni oluşturulan bir etiket henüz fiziksel kabul taramasından geçmemiş olabilir. Müşteriye gösterilen gönderi durumu, kayıt yanıtından değil, durum eşleme kurallarınız üzerinden yorumlanan takip etkinliklerinden alınmalıdır.
17TRACK entegrasyonları için Tracking API overview ile başlayın ve uç noktalar, alan tanımları, kimlik doğrulama ve yanıt kodları için resmî API belgelerini esas alın. Aşağıdaki örnekler, sonuçları alma veya güncellemeleri alma gibi ayrı görevlerden ziyade kayıt işlemine odaklanır.
API çağrısını yazmadan önce istek alanlarını hazırlayın
En yararlı hazırlık, gönderim sisteminiz ile takip entegrasyonunuz arasında küçük bir alan sözleşmesi oluşturmaktır. Her değerin kaynağını, eksik olup olamayacağını ve nasıl doğrulanacağını belirleyin.
| Alan veya değer | Amaç | Uygulama kuralı |
|---|---|---|
| Takip numarası | Takip edilecek gönderiyi tanımlar. | Dize olarak saklayın ve iletin; baştaki sıfırları koruyun. |
| Taşıyıcı tanımlayıcısı | Taşıyıcıyı takip sağlayıcısının sistemi içinde tanımlar. | Dahili depo kodu yerine sağlayıcının belgelenmiş tanımlayıcısını kullanın. |
| Dahili referans | Kaydı gönderi kaydınıza bağlar. | Varsa desteklenen bir referans alanı kullanın; buna rağmen kendi veritabanınızdaki eşlemeyi koruyun. |
| Ek tanımlama verileri | Taşıyıcının takip numarasından daha fazlasını gerektirdiği durumlarda gönderinin tanımlanmasına yardımcı olabilir. | Yalnızca bu entegrasyon ve taşıyıcı için belgelenen alanları gönderin. |
| API kimlik bilgisi | Çağrıyı yapan hesabın kimliğini doğrular. | Sunucuda tutun ve uygulama günlüklerine eklemeyin. |
Takip numarasını tanımlayıcı olarak ele alın
Bir takip numarasını asla tam sayıya dönüştürmeyin. Sayısal dönüşüm baştaki sıfırları kaldırabilir ve bazı programlama ortamlarında büyük değerler kesinlik kaybedebilir. Kazara eklenmiş baştaki veya sondaki boşlukları kaldırın; ancak ilgili belgeler veya taşıyıcı biçimi bu normalleştirmeyi desteklemediği sürece noktalama işaretlerini silmeyin ya da harflerin büyük/küçük harf durumunu değiştirmeyin.
API'yi çağırmadan önce belirgin giriş hatalarını doğrulayın: boş dizeler, beklenmeyen satır sonları ve takip numarası alanına kopyalanmış sipariş numarası. Tüm taşıyıcılar için tek bir evrensel uzunluk veya karakter kuralı uygulamaktan kaçının. Bir taşıyıcıya uyan doğrulama kuralı, başka bir taşıyıcının geçerli numaralarını reddedebilir.
Sipariş referanslarını gönderi kimliklerinden ayrı tutun
Bir sipariş birden fazla paket içerebilir ve yenileme gönderisi başka bir takip numarası oluşturabilir. Her sipariş için tek bir takip numarası olduğunu varsaymak yerine kaydı gönderi veya paket düzeyinde modelleyin.
Sağlayıcı tarafından desteklenen bir etiket veya referans alanı kullanıyorsanız müşterinin e-posta adresi ya da sokak adresi yerine opak bir gönderi referansını tercih edin. Siparişler, gönderiler, takip numaraları ve taşıyıcı eşlemeleri arasındaki yetkili bağlantı kendi veritabanınız olmaya devam etmelidir.
Doğru taşıyıcı kodunu seçin
Taşıyıcı kodu mutlaka evrensel bir sektör tanımlayıcısı değildir. Bir takip platformu tarafından tanınan değer, gönderim yazılımınızda saklanan taşıyıcı adından farklı olabilir. Sayısal kodlar kullanan iki sistem bile aynı taşıyıcıya farklı numaralar atayabilir.
Gönderim hizmetinizden takip sağlayıcısının taşıyıcı tanımlayıcısına açık bir eşleme tutun. Gerektiğinde taşıyıcının bölgesel operasyonunu veya hizmetini daha geniş markasından ayırın. Yalnızca görünen ada dayalı bir eşleme, gönderim sistemleri takma adlar kullandığında belirsiz hâle gelebilir.
- Taşıyıcı biliniyorsa: özellikle takip numarası biçimlerinin çakıştığı durumlarda, desteklendiğinde belgelenmiş taşıyıcı tanımlayıcısını kullanın.
- Taşıyıcı bilinmiyorsa: otomatik algılamayı yalnızca belgelenmiş mekanizma üzerinden kullanın. Eksik bırakmanın, boş dizenin, sıfırın ve null değerinin aynı anlama geldiğini varsaymayın.
- Sonuç yanlış görünüyorsa: aynı numarayı tekrar tekrar kaydetmeden önce orijinal etiketi, gönderim hizmetini ve eşlemeyi doğrulayın.
Otomatik algılama yararlıdır; ancak belirli bir taşıyıcının gönderiyi fiziksel olarak elinde tuttuğunun kanıtı değildir. Benzer şekilde, geçerli bir taşıyıcı kodu sağlanan takip numarasının o taşıyıcıya ait olduğunu garanti etmez.
Taşıyıcı eşlemelerini uygulama kodunun farklı bölümlerine dağıtmak yerine yapılandırılabilir tutun. Bir eşlemenin en son ne zaman kontrol edildiğini kaydedin ve eşlemeyi her değiştirdiğinizde bilinen bir gönderiyi regresyon testlerine ekleyin.
Örnek: 17TRACK kayıt isteği gönderme
Aşağıdaki örnek 17TRACK v2.2 kayıt uç noktasını, 17token kimlik doğrulama başlığını ve bir takip numarası nesnesi içeren diziyi gösterir. Dağıtımdan önce bu sürümün ve istek gereksinimlerinin hesabınızla ve resmî belgelerle eşleştiğini doğrulayın. Takip numarası bir yer tutucudur ve gerçek bir gönderi tanımlayıcısıyla değiştirilmelidir.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Bu minimal örnek taşıyıcı seçimini veya taşıyıcıya özgü ek alanları göstermez. Taşıyıcı alanı atlandığında taşıyıcı algılamasının nasıl çalıştığını ve gönderinizin ek bilgi gerektirip gerektirmediğini belirlemek için kayıt belgelerini kontrol edin. Taşıyıcı sağlarsanız belgelenmiş carrier alanını ve ilgili API sürümünün beklediği tanımlayıcıyı kullanın.
Bu isteği sunucu tarafı bir ortamdan çalıştırın. Jetonu herkese açık bir mağazaya, tarayıcı betiğine veya müşterilere dağıtılan mobil uygulamaya yerleştirmeyin. Yerel bir örnek için ortam değişkeni kullanmak uygundur; üretim dağıtımları kuruluşunuzun gizli bilgi yönetimi denetimlerini kullanmalıdır.
Hacmi artırmadan önce bilinen bir gönderiyi test edin ve yanıtın tamamını inceleyin. Ardından geçersiz bir girişi ve hem geçerli hem de geçersiz öğeler içeren bir toplu işlemi test edin. Bu kontroller, entegrasyonunuzun yalnızca HTTP başarı yanıtını tanımak yerine öğe düzeyindeki sonuçları gerçekten işleyip işlemediğini ortaya çıkarır.
Yanıtı üç düzeyde okuyun
Güvenilir bir yanıt işleyici üç ayrı soruyu yanıtlar: istek hizmete ulaştı mı, hizmet işlemi kabul etti mi ve her gönderinin başına ne geldi?
1. HTTP ve aktarım sonucu
Bağlantı zaman aşımı, TLS hatası veya kesintiye uğramış yanıt, sunucunun isteği işleyip işlemediğini mutlaka göstermez. Bu sonucu mutabakat sağlayana kadar belirsiz olarak işaretleyin. HTTP başarı durumu başarılı bir HTTP alışverişini doğrular; ancak yine de uygulama yanıtını incelemeniz gerekir.
2. İstek düzeyindeki sonuç
API'nin belgelenmiş üst düzey sonuç ve hata alanlarını inceleyin. Kimlik doğrulama hataları, hatalı JSON ve hesap kısıtlamaları farklı işlemler gerektirir. Her hatayı “takip kullanılamıyor” şeklinde azaltmak yerine sağlayıcının özgün hata kodunu ve mesajını saklayın.
Sayısal bir uygulama kodunun HTTP durum koduyla aynı anlama geldiğini varsaymayın. Bunların anlamları farklı katmanlardan gelir ve ayrı ayrı yorumlanmalıdır.
3. Gönderi düzeyindeki sonuç
Toplu kayıt işleminde gönderilen her öğeyi hesaba katın. Bir yanıt kabul edilen ve reddedilen gönderileri ayırt edebilir; ayrıştırıcınız seçilen sürüm için belgelenen kesin şemayı izlemelidir. Bir öğe başarılı oldu diye tüm toplu işlemi kaydedilmiş olarak işaretlemeyin.
Sağlayıcı yanıtlarını kendi sabit uygulama durumlarınıza normalleştirin. Örneğin veritabanınızda accepted, rejected ve uncertain durumlarını kullanabilirsiniz. Bunlar önerilen dahili durumlardır; gerçek 17TRACK yanıt değerleri değildir. Geliştiricilerin farklılıkları araştırabilmesi için özgün sağlayıcı yanıtını uygun saklama ve erişim politikası kapsamında kullanılabilir durumda tutun.
Yararlı bir kayıt kaydı; dahili gönderi kimliğini, gönderilen numarayı, taşıyıcı seçimini, deneme zamanını, API sürümünü, sonucu ve sağlayıcının hata ayrıntılarını içerir. Kayıt durumunu teslimat durumundan ayrı tutun.
Sonsuz döngü oluşturmadan yeniden denemeleri yönetin
Yeniden deneme politikası, yalnızca bir istisna oluşup oluşmadığına değil, hatanın türüne bağlı olmalıdır.
- Geçersiz giriş: yeniden denemeden önce alanı düzeltin. Değiştirilmemiş hatalı bir isteği tekrarlamak muhtemelen yardımcı olmaz.
- Kimlik doğrulama hatası: kimlik bilgilerini ve hesap yapılandırmasını doğrulayın. Aynı başarısız toplu işlemi tekrar tekrar göndermekten kaçının.
- Hız sınırlaması: belgelenmiş limitlere ve geçerli yeniden deneme talimatlarına uyun. Anında paralel yeniden denemeler yerine sınırlı geri çekilme kullanın.
- Geçici hizmet hatası: tanımlanmış bir deneme ve zaman bütçesi içinde yeniden deneyin.
- Gönderimden sonra zaman aşımı: ilk denemenin başarısız olduğunu varsaymadan önce belgelenmiş API davranışını kullanarak gönderinin kayıt durumunu uzlaştırın.
- Yinelenen kayıtla ilgili yanıt: gönderinin zaten kaydedilip kaydedilmediğini ve uygulama kaydınızla doğru şekilde ilişkilendirilip ilişkilendirilmediğini kontrol edin.
Belgeler bu davranışı tanımlamadığı sürece kaydın idempotent olduğunu varsaymayın. Uygulama tarafında tekilleştirme, kazara yinelenen gönderimleri azaltır; ancak sağlayıcının yinelenen kayıtları nasıl ele aldığına ilişkin bir politika oluşturmaz.
Gönderi modelinize uygun bir dahili benzersizlik kuralı kullanın. Takip numarası tek başına taşıyıcılar ve uzun saklama süreleri arasında kalıcı bir anahtar olmak için yeterli olmayabilir. Taşıyıcı bağlamını ve kendi gönderi tanımlayıcınızı koruyun; yenilemelerin ve düzeltilmiş numaraların nasıl ele alınacağını belgeleyin.
Kayıt işlemini takip güncellemelerinden ayrı izleyin
API izleme, entegrasyon hatası ile gönderinin yalnızca yeni bir taşıyıcı etkinliğine sahip olmaması durumunu ayırt etmelidir. Bu koşullar farklı sorumlular ve farklı çözümler gerektirir.
Kayıt için kabul ve ret sayılarını, hata kategorilerini, belirsiz sonuçları, yeniden deneme kuyruğunu ve yanıt gecikmesini izleyin. Sonraki takip için güncelleme alma veya getirme hatalarını ayrıca izleyin. Normal trafiği ve sağlayıcının belgelenmiş işletim limitlerini anlayana kadar sayısal uyarı eşikleri belirlemekten kaçının.
Uygulamadaki pratik bir üretim kontrolü şu soruları yanıtlamalıdır:
- Takip bekleyen her gönderinin bir kayıt kaydı var mı?
- Kabul edilen her kayıt doğru pakete kadar izlenebiliyor mu?
- Reddedilen öğeler, temel verileri düzeltebilecek birine yönlendiriliyor mu?
- Belirsiz istekler terk edilmek veya süresiz yeniden denenmek yerine uzlaştırılıyor mu?
- Müşteriye gösterilen durumlar kayıt kabulünden değil, gönderi etkinliklerinden mi türetiliyor?
- Kimlik bilgileri ve gereksiz kişisel bilgiler günlüklerden çıkarılıyor mu?
E-ticaret operasyonlarında operasyonel devir, API çağrısı kadar önemlidir. Geliştiriciler aktarım ve ayrıştırma hatalarının sorumluluğunu üstlenmelidir; gönderim veya sipariş karşılama ekipleri yanlış etiketleri, taşıyıcı eşlemelerini ve eksik gönderi bilgilerini araştırabilmelidir.
SSS
İlk taşıyıcı taramasından önce bir takip numarasını kaydedebilir miyim?
Kayıt ve taşıyıcı taramaları ayrı olaylardır. Bir hizmet, doğrulama kurallarına bağlı olarak takip etkinlikleri kullanılabilir olmadan önce bir numarayı kabul edebilir. Kabulü, taşıyıcının paketi teslim aldığına dair kanıt olarak yorumlamayın.
Her zaman bir taşıyıcı kodu sağlamam gerekir mi?
Bu, API'nin belgelenmiş algılama davranışına ve ilgili gönderiye bağlıdır. Taşıyıcı biliniyorsa açık ve doğru şekilde eşlenmiş bir tanımlayıcı belirsizliği azaltabilir. Taşıyıcı bilinmiyorsa taşıyıcı değeri uydurmak yerine belgelenmiş otomatik algılama yöntemini kullanın.
Bir gönderi başarısız olurken API neden HTTP başarı durumu döndürdü?
HTTP isteği başarılı olurken uygulama tek tek bir öğeyi reddedebilir. Üst düzey uygulama sonucunu ve gönderi düzeyindeki sonuçları okuyun. Bu ayrım özellikle toplu istekler için önemlidir.
Bir kayıt isteği zaman aşımına uğradığında ne yapmalıyım?
Sonucu belirsiz olarak ele alın. Bağlantı kesilmeden önce sunucu isteği işlemiş olabilir. Sağlayıcının belgelenmiş yinelenen kayıt davranışını ve mevcut kayıt veya takip arama yöntemlerini kontrol edin; ardından sınırlı bir politika kapsamında uzlaştırın veya yeniden deneyin.
Kayıt işlemi takip bildirimlerini otomatik olarak yapılandırır mı?
Bunu yaptığını varsaymayın. Kayıt, takip alma ve webhook yapılandırması ayrı entegrasyon konularıdır. İlgili belgeleri doğrulayın ve müşteri bildirimleri için güvenmeden önce tüm güncelleme yolunu test edin.
Kaynaklar
- 17TRACK API documentation — kayıt uç noktaları, kimlik doğrulama, istek alanları, taşıyıcı tanımlayıcıları, yanıt şemaları ve hata işleme için referans. Uygulama ayrıntılarını dağıttığınız API sürümüyle eşleştirin.
- 17TRACK Tracking API overview — takip API ürünü ve geliştirici entegrasyonu kaynakları için resmî başlangıç noktası.


