UPS Tracking API: Başlangıç İçin Yeni Başlayanlar Rehberi

UPS Tracking API, bir işletmenin gönderi durumunu almasına ve teslimat güncellemelerini kendi web sitesi, uygulaması, sipariş yönetim sistemi veya müşteri hizmetleri araçları içinde göstermesine olanak tanır. Başlamak genellikle bir UPS geliştirici hesabı oluşturmayı, bir uygulama kaydetmeyi, kimlik doğrulama bilgilerini almayı, bir takip isteği göndermeyi ve yanıtı müşteriye sunulabilecek yararlı olaylara dönüştürmeyi içerir. Bu kılavuz, daha önce API deneyimi olduğunu varsaymadan süreci açıklar.

Örnekler etiket oluşturma, ücret hesaplama veya adres doğrulama yerine takip işlemlerine odaklanır. UPS ayrı API ürünleri ve belgeleri sunar; bu nedenle üretim iş akışlarını oluşturmadan önce kaydettiğiniz uygulamanın ihtiyaç duyduğunuz takip özelliğine erişimi olduğunu doğrulayın.

UPS Tracking API Ne İşe Yarar?

API, bir yazılım sisteminin başka bir sistemden bilgi istemesini sağlayan yapılandırılmış bir yöntemdir. Bir takip iş akışında sisteminiz, takip numarası gibi bir gönderi tanımlayıcısını taşıyıcıya veya takip platformuna gönderir. Hizmet; hizmete, gönderiye ve istek sırasında kullanılabilen yanıt alanlarına bağlı olarak mevcut durumu, durum açıklamasını, konum bilgilerini, tarihleri ve paket aşamalarını içerebilen gönderi verilerini döndürür.

Bu veriler çeşitli pratik özellikleri destekleyebilir:

• Bir e-ticaret mağazasına yerleştirilmiş takip sayfası.
• Sipariş yönetimi veya kurumsal kaynak planlama sistemi içinde gönderi görünürlüğü.
• Taşıyıcının web sitesini manuel olarak kontrol etme ihtiyacını azaltan müşteri hizmetleri ekranları.
• Teslimat istisnaları, gecikmeler veya tamamlanan teslimatlar için dahili uyarılar.
• Gönderi olaylarına dayalı satın alma sonrası mesajlar.

API, uygulama mantığınızın yerini almaz. Güncellemeleri ne sıklıkta isteyeceğinize, yanıtları nasıl depolayacağınıza, eksik verileri nasıl işleyeceğinize ve taşıyıcı durumlarını müşterilere nasıl açıklayacağınıza yine sizin karar vermeniz gerekir.

UPS Tracking API ve UPS Web Sitesi Karşılaştırması

UPS web sitesi, bir kişinin takip numarası girip sonucu okuması için tasarlanmıştır. API ise yazılımlar için tasarlanır. Takip bilgilerinin başka bir sistemde otomatik olarak görünmesi veya dahili bir süreci tetiklemesi gerektiğinde kullanışlıdır.

Bu ayrım önemlidir; çünkü API entegrasyonu, manuel sorgulamanın gerektirmediği sorumlulukları beraberinde getirir. Ekibiniz kimlik bilgilerini korumalı, kullanıcı girdilerini doğrulamalı, istekleri ve yanıtları uygun şekilde kaydetmeli, geçici hatalarla başa çıkmalı ve taşıyıcı platformundaki değişikliklerden sonra entegrasyonun çalışmaya devam edip etmediğini izlemelidir.

UPS geliştirici platformu, güncel kayıt ve teknik gereksinimler için uygun başlangıç noktasıdır. Kimlik doğrulama yöntemleri, API sürümleri, gerekli üst bilgiler ve ürün erişim kuralları değişebileceğinden, belgeleri eski eğitimlerin, kod örneklerinin veya forum gönderilerinin önünde tutmalısınız.

İstek Göndermeden Önce İhtiyacınız Olanlar

Entegrasyonu yazmadan önce aşağıdaki öğeleri hazırlayın:

1. Bir UPS geliştirici hesabı. Kullanılabilir API'leri incelemek ve bir uygulama oluşturmak için resmi UPS Developer Portal'ı kullanın.
2. Uygulama kimlik bilgileri. Kesin kimlik bilgisi adları ve kimlik doğrulama akışı güncel UPS belgelerinden alınmalıdır. İstemci sırlarını tarayıcı koduna, mobil uygulamalara, herkese açık depolara veya müşterilerin görebileceği sayfalara koymayın.
3. Test için geçerli bir takip numarası. Kuruluşunuzun erişim yetkisi bulunan gönderilerle test yapın ve kişisel veya ticari gönderi verilerini günlüklerde açığa çıkarmaktan kaçının.
4. Sunucu tarafı bir entegrasyon noktası. Kimlik bilgilerini gizli tutabildiği ve istek hacmini kontrol edebildiği için bir arka uç hizmeti, taşıyıcıyı doğrudan herkese açık bir web sayfasından çağırmaktan genellikle daha güvenlidir.
5. Yanıt depolama planı. Hangi alanlara ihtiyacınız olduğuna, bunları ne kadar süre saklayacağınıza ve bir taşıyıcı olayını dahili bir siparişle nasıl ilişkilendireceğinize karar verin.

Yeni Başlayanlar İçin Uygun Entegrasyon İş Akışı

1. İş gereksinimini doğrulayın

Öncelikle ürününüzde “takip” ifadesinin ne anlama geldiğini tanımlayın. Müşteriye yönelik bir sayfada yalnızca mevcut durum ve tahmini teslimat bilgileri gerekebilir. Bir depo veya destek panosunda tarama geçmişi, zaman damgaları, istisna açıklamaları ve orijinal takip numarası da gerekebilir.

Bir neden olmadan mevcut her alanı istemekten kaçının. Daha küçük bir veri modelinin bakımı daha kolaydır ve kullanıcılarınızın ihtiyaç duymadığı bilgilerin açığa çıkma olasılığı daha düşüktür.

2. Uygulamayı kaydedin

UPS geliştirici ortamında bir uygulama oluşturun ve güncel portal talimatlarına göre ilgili takip ürününü seçin. Uygulama tanımlayıcısını güvenli biçimde kaydedin. UPS üretim erişimi için onay, hesap ilişkilendirmesi veya ek kurulum gerektiriyorsa, canlıya geçiş tarihi vermeden önce bu adımları tamamlayın.

Platform bu modeli destekliyorsa test ve üretim için ayrı kimlik bilgileri ve yapılandırmalar kullanın. Bu, bir test komut dosyasının canlı iş akışını etkileme ihtimalini azaltır.

3. Kimlik doğrulamayı uygulayın

Kimlik doğrulama, uygulamanızın hizmeti çağırmaya yetkili olduğunu kanıtlar. Güncel UPS belgelerinde gösterilen kimlik doğrulama yöntemini, belirteç uç noktasını, kapsam gereksinimlerini ve üst bilgi biçimini izleyin. Erişim belirteçlerini geçici sırlar olarak değerlendirin ve uygulama günlüklerine yazmayın.

Mantıklı bir uygulama, belirteci yalnızca gerektiğinde ister, izin verilen ömrü boyunca yeniden kullanır ve süresi dolduktan sonra yenisini alır. Kodunuz ayrıca kimlik doğrulama hatası ile takip numarası hatasını ayırt etmelidir. Çözüm farklıdır: biri kimlik bilgileri veya yapılandırmanın incelenmesini, diğeri ise girdi doğrulamasını gerektirebilir.

4. Bir takip isteği gönderin

Kimlik doğrulamasından sonra UPS tarafından belirtilen takip işlemini ve tanımlayıcı biçimini kullanarak bir istek gönderin. Kesin URL, HTTP yöntemi, üst bilgiler ve yanıt şeması, seçtiğiniz API sürümüne ait resmi belgelerde yer alır.

Kavramsal bir istek şu şekildedir:

POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "trackingNumber": "YOUR_TRACKING_NUMBER"
}

Bu, öğrenme amaçlı bir örnektir; üretimde kopyalayıp yapıştırılacak bir istek değildir. İşlem adını, uç noktayı, üst bilgileri ve gövdeyi güncel UPS API referansındaki değerlerle değiştirin. Bazı API'ler bir yol parametresi veya farklı bir istek yapısı kullanır.

5. Yanıtı normalleştirin

Taşıyıcı yanıtları her zaman müşterilerinizin beklediği dilde yazılmaz. Aşağıdakiler gibi sabit alanlara sahip dahili bir olay modeli oluşturun:

• Dahili sipariş veya gönderi kimliği.
• Taşıyıcı adı ve takip numarası.
• En son taşıyıcı durum kodu ve ham açıklama.
• Uygulamanız tarafından kullanılan normalleştirilmiş durum.
• Olay zaman damgası ve sağlanmışsa konum.
• Son başarılı güncelleme zamanı.

Mümkün olduğunda orijinal taşıyıcı durumunu koruyun. “Taşınıyor” gibi normalleştirilmiş bir etiket müşteri arayüzü için yararlıdır; ancak ham açıklama, destek personelinin olağan dışı bir olayı araştırmasına yardımcı olabilir.

6. Güncellemelerin nasıl alınacağına karar verin

Bazı sistemler zamanlanmış yoklama kullanır: bir arka uç, uygun gönderileri belirli aralıklarla kontrol eder ve değişiklikleri depolar. Diğerleri, ilgili platform desteklediğinde olay bildirimlerini kullanır. Her UPS takip ürününün aynı bildirim mekanizmasını sunduğunu varsaymayın. Webhook tabanlı bir iş akışı tasarlamadan önce güncel belgeleri ve ticari koşulları doğrulayın.

Yoklama seçici olmalıdır. Yeni gönderilmiş veya aktif olarak hareket eden paketler, teslim edilmiş veya iptal edilmiş gönderilerden daha sık kontrol edilmeyi gerektirebilir. Geçici hatalar için geri çekilmeli yeniden denemeler uygulayın, belgelenen sınırlara uyun ve iş süreciniz daha sonra doğrulama gerektirmediği sürece son duruma ulaşıldıktan sonra gereksiz istekleri durdurun.

Yaygın Hatalar ve Bunların Ele Alınması

En önemli kullanıcı deneyimi kuralı, eksik verileri kesin bir sonuca dönüştürmemektir. “Yeni tarama yok” otomatik olarak “kayıp” anlamına gelmez ve “etiket oluşturuldu” mutlaka “taşınıyor” demek değildir. Durumları dikkatle eşleyin ve istisna yönetimini destek ekipleri için görünür tutun.

Çoklu Taşıyıcı API'si Ne Zaman Daha Uygundur?

Gönderileriniz çoğunlukla UPS tarafından taşınıyorsa ve ekibiniz taşıyıcı bağlantısı üzerinde doğrudan kontrol istiyorsa, doğrudan UPS entegrasyonu mantıklı bir seçim olabilir. Bunun karşılığında her ek taşıyıcı başka bir kimlik doğrulama modeli, veri şeması, hata politikası ve bakım süreci gerektirebilir.

Operasyonunuz birden fazla taşıyıcı kullanıyorsa, çoklu taşıyıcı hizmeti ayrı entegrasyonların sayısını azaltabilir. 17TRACK's Tracking API uygulama tabanlı gönderi takibi için tasarlanmıştır ve resmi geliştirici belgeleri kullanılabilir entegrasyon modelini açıklar. Gerçek gereksinim yalnızca UPS takibi değil, taşıyıcılar arasında tutarlı bir takip katmanı olduğunda değerlendirmeye değer olabilir.

Bu, doğrudan UPS bağlantısını otomatik olarak değiştirmek için bir neden değildir. İhtiyaç duyduğunuz taşıyıcı kapsamını, olay ayrıntılarını, veri saklama gereksinimlerini, kimlik doğrulama modelini, operasyonel sınırları, destek sürecini ve toplam uygulama çabasını karşılaştırın. Bir sağlayıcının herkese açık belgeleri, kendi gönderi modellerinizi test etmenin yerine değil, teknik bir kavram kanıtı için başlangıç noktası olarak değerlendirilmelidir.

Üretime Hazırlık Kontrol Listesi

• Kimlik bilgileri bir sır yöneticisinde saklanıyor ve tarayıcıya hiçbir zaman açığa çıkarılmıyor.
• Test ve üretim ortamları açıkça ayrılmış.
• İsteklerde zaman aşımı, kontrollü yeniden denemeler ve yararlı hata günlükleri bulunuyor.
• Takip numaraları gönderilmeden önce doğrulanıyor.
• Sistem son başarılı güncellemeyi saklıyor ve boş bir yanıtla üzerine yazılmasını önlüyor.
• Ham taşıyıcı mesajları ve müşteriye yönelik etiketler ayrı şekilde işleniyor.
• Yoklama sıklığı sağlayıcının yayımlanmış sınırlarına ve operasyonel ihtiyacınıza uyuyor.
• İzleme sistemi kimlik doğrulama hatalarını, artan hata oranlarını ve güncelliğini yitirmiş gönderileri tespit edebiliyor.
• Destek personeli, müşteri sorusunu araştırmak için yeterli ayrıntıyı görebiliyor.
• UPS belgeleri, kimlik bilgileri, uç noktaları veya yanıt alanlarını değiştirdiğinde entegrasyon yeniden test ediliyor.

Tek bir eksiksiz yol ile başlayın: kimlik doğrulaması yapın, bir test gönderisini takip edin, yanıtı saklayın, basit bir durum gösterin ve hatayı yönetin. Bu yol güvenilir hale geldikten sonra genişletin. Bu yaklaşım, temel veriler ve hata davranışı anlaşılmadan önce büyük bir müşteriye yönelik takip deneyimi oluşturmaktan genellikle daha güvenlidir.

SSS

Yalnızca birkaç paketi takip ediyorsam API'ye ihtiyacım var mı?

Genellikle hayır. Ara sıra yapılan sorgulamalar için taşıyıcının web sitesinde manuel takip daha pratik olabilir. Takip, tekrarlanabilir bir iş akışının parçası olduğunda veya başka bir uygulama içinde görünmesi gerektiğinde API daha değerli hale gelir.

UPS Tracking API'yi bir Shopify teması veya tarayıcıdan çağırabilir miyim?

Doğrudan tarayıcı çağrısı kimlik bilgilerini açığa çıkarabilir ve istek kontrolünü zorlaştırabilir. Sunucu tarafı bir hizmet veya yerleşik bir takip entegrasyonu genellikle daha güvenlidir. Güncel UPS belgelerinde teknik gereksinimleri ve izin verilen mimariyi doğrulayın.

Bir takip API'si kargo etiketleri oluşturur mu?

Şart değil. Takip, etiket oluşturma, ücret hesaplama, adres doğrulama ve diğer lojistik işlevler ayrı API ürünleri olabilir. İhtiyacınız olan işleme uygun ürünü seçin.

Geçerli bir takip numarası neden az bilgi döndürebilir?

Bir paket ilk taramasını almamış olabilir, veriler henüz kullanıma sunulmamış olabilir veya istek API'nin gerekli biçimi ya da erişim izinleriyle eşleşmiyor olabilir. Boş veya sınırlı bir yanıtı gönderinin kaybolduğunun kanıtı olarak değil, araştırılması gereken bir durum olarak değerlendirin.

Doğrudan UPS'i mi yoksa çoklu taşıyıcılı bir takip API'sini mi seçmeliyim?

UPS ana taşıyıcıysa ve odaklanmış bir entegrasyon istiyorsanız doğrudan bağlantıyı seçin. Operasyonel hedefiniz birkaç taşıyıcı arasında tek bir takip iş akışı oluşturmaksa çoklu taşıyıcı hizmetini değerlendirin. Nihai kararınızı vermeden önce gereken taşıyıcıları ve olay senaryolarını test edin.

Kaynaklar

• UPS Developer Portal
• UPS Tracking API belgeleri ve ürün kaynakları
• 17TRACK Tracking API
• 17TRACK API belgeleri