Ups Tracking Api Nasıl Kullanılır: Adım Adım Kurulum Kılavuzu

UPS Tracking API'yi kullanmak için bir UPS Developer hesabı oluşturun, bir uygulama kaydedin, OAuth 2.0 kimlik bilgilerini alın, bir erişim belirteci isteyin ve geçerli bir UPS takip numarasıyla kimlik doğrulamalı takip istekleri gönderin. Kesin portal etiketleri, onay adımları ve API gereksinimleri değişebilir; bu nedenle üretim entegrasyonunu kullanıma almadan önce güncel talimatları resmi UPS Developer Portal'da doğrulayın.

Bu kılavuz; çevrim içi mağaza, sipariş yönetim sistemi, depo iş akışı, müşteri hizmetleri aracı veya dahili gösterge paneli içinde gönderi durumuna ihtiyaç duyan geliştiriciler ve e-ticaret operasyon ekipleri içindir. Kılavuz; entegrasyon sırasına, güvenilirliği etkileyen kararlara ve yaygın takip hatalarını önleyen kontrollere odaklanır.

UPS Tracking API Ne İşe Yarar

Bir API entegrasyonu, bir çalışanın veya müşterinin taşıyıcının takip sayfasını manuel olarak açmasını gerektirmek yerine yazılımın UPS'ten gönderi bilgisi istemesine olanak tanır. Uygulamanız yanıtı en son bilinen durumu görüntülemek, teslimat olaylarını belirlemek, müşteri hizmetleri incelemelerini desteklemek veya dahili bir iş akışını tetiklemek için kullanabilir.

API, takip sayfasıyla aynı şey değildir. Takip sayfası bir kişinin okuyacağı şekilde tasarlanır. API yanıtı, yazılımın ayrıştırması, depolaması ve sunması gereken yapılandırılmış verilerdir. Kimlik doğrulama, hata yönetimi, yoklama veya olay toplama, veri saklama, kullanıcı arayüzü tasarımı ve teslimat olayları etrafında oluşturulan iş kuralları hâlâ sisteminizin sorumluluğundadır.

Başlamadan Önce

Geliştirici portalını açmadan önce aşağıdaki öğeleri hazırlayın:

• Bir UPS Developer hesabı veya mevcut UPS kayıt sürecinin gerektirdiği hesap türü.
• Kayıtlı bir uygulama ve bu uygulama için verilen kimlik bilgileri.
• Bir test takip numarası veya onaylanmış başka bir test yöntemi. UPS belgeleri ayrı bir test ortamı ya da test prosedürü sağlıyorsa canlı müşteri verileriyle başlamayın.
• Gönderi kayıtlarının, takip olaylarının ve müşteriye gösterilen durum mesajlarının hangi sisteme ait olacağına dair net bir karar.
• İstemci kimlik bilgilerini ve erişim belirteçlerini saklamak için güvenli bir yer. Gizli bilgileri asla tarayıcı koduna, herkese açık depolara, ekran görüntülerine veya kullanıcıların inceleyebileceği mobil uygulamalara koymayın.

Uygulamanızın yalnızca takibe mi yoksa daha kapsamlı bir UPS entegrasyonuna mı ihtiyaç duyduğuna da karar vermelisiniz. Takip, ücretlendirme, gönderim, adres doğrulama ve belge hizmetleri farklı ürünlere, izinlere, istek biçimlerine ve operasyonel gereksinimlere sahip olabilir.

1. Adım: UPS Developer Portal'ı Açın

resmi UPS Developer Portal üzerinden başlayın. Güncel API kataloğunu, kimlik doğrulama kılavuzunu, kayıt gereksinimlerini, şartları ve ortam bilgilerini inceleyin. Başka bir UPS hizmetine ait talimatların takip için de geçerli olduğunu varsaymak yerine özellikle Tracking API belgelerini bulun.

Portal; güncel istek alanları, yetkilendirme kapsamları, yanıt tanımları, hız sınırları, hata kodları ve ortam ayrıntıları için uygun kaynaktır. Bu ayrıntılar değişebilir ve üçüncü taraf bir kod örneği eski bir UPS arayüzünü veya güncel olmayan bir kimlik doğrulama yöntemini kullanıyor olabilir.

2. Adım: Bir Uygulama Kaydedin

Geliştirici portalında bir uygulama oluşturun ve uygulamanın gerçekten ihtiyaç duyduğu UPS API'lerini seçin. Yalnızca takip yapılan bir proje için iş akışınız ek hizmetler gerektirmedikçe sadece takip yeteneğini isteyin. İzinleri sınırlamak yapılandırma karmaşıklığını azaltır ve sonraki sorun gidermeyi kolaylaştırır.

Uygulama tanımlayıcısını ve gizli anahtarı sunucu tarafındaki bir gizli bilgi yöneticisinde veya korumalı bir ortam değişkeni sisteminde saklayın. Gizli anahtarı parola gibi değerlendirin. Açığa çıkarsa UPS tarafından sağlanan süreç üzerinden yenileyin ve yetkisiz kullanım için günlükleri inceleyin.

Portal hesap, faturalandırma, işletme veya uygulama bilgileri isterse doğru ayrıntıları sağlayın. Sadece bir testi tamamlamak için üretim kullanım senaryosu uydurmaktan veya başka birinin hesap bilgilerini kullanmaktan kaçının. Bir hizmete erişim, hesap yapılandırmasına ve mevcut UPS onay sürecine bağlı olabilir.

3. Adım: OAuth 2.0 Kimlik Doğrulamasını Uygulayın

Güncel UPS geliştirici belgeleri API'leri için OAuth tabanlı kimlik doğrulama kullanır. Sunucunuz normalde uygulama kimlik bilgilerini belgelenen belirteç akışıyla değiş tokuş eder ve bir erişim belirteci alır. Ardından bu belirteci bir API isteğinin yetkilendirme başlığına ekler.

Kimlik doğrulamayı takip mantığından ayrı tutun. Uygulanabilir bir tasarımda geçerli bir belirteç alan ve önbelleğe alan bir bileşen ile takip uç noktasını çağıran başka bir bileşen bulunur. Belirteç bileşeni şunları yapmalıdır:

• Kimlik bilgilerini yalnızca belgelenen UPS yetkilendirme uç noktasına göndermek.
• Güncel UPS belgelerinde belirtilen içerik türünü ve izin parametrelerini kullanmak.
• Belirteci geçici olarak saklamak ve her takip numarası için yeni bir belirteç istemek yerine süresi dolana kadar yeniden kullanmak.
• Belgelenen süre dolumu koşulu gerçekleştiğinde belirteci yenilemek veya yeniden almak.
• Kimlik bilgilerini ve belirteçleri uygulama günlüklerinden, hata raporlarından ve destek taleplerinden çıkarmak.

Bir tarayıcı oturumundaki belirteci kalıcı bir entegrasyona kopyalamayın. Gizli bilgileri herkese açık istemci kodundan uzak tuttuğu için kimlik bilgilerini yönetmek açısından arka uç hizmeti genellikle daha güvenli bir yerdir.

4. Adım: Takip İsteğini Oluşturun

Resmi Tracking API başvuru kaynağında gösterilen istek biçimini kullanın. Tipik bir istek; yol veya istek parametrelerinde bir takip numarası, yetkilendirme başlığında bir erişim belirteci ve UPS API'sinin gerektirdiği başlıkları içerir. Takip numarasının gereken tek değer olduğunu varsaymayın: güncel başvuru kaynağı sürüm, işlem, içerik türü veya ilişkilendirme başlıklarını belirtebilir.

Basitleştirilmiş bir istek kalıbı şöyledir:

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

Bu, kopyalanıp yapıştırılacak bir uç nokta değil, yapısal bir örnektir. Uygulamanız için UPS belgelerinde yayımlanan uç noktayı, sürümü, başlıkları ve parametre adlarını kullanın. Takip numarasını kendi sipariş verisi kurallarınıza göre standartlaştırın; ancak taşıyıcı belgeleri bunun güvenli olduğunu doğrulamadıkça karakterleri kaldırmayın.

5. Adım: Olayları Veri Modelinize Ayrıştırın

Taşıyıcı yanıtları genellikle tek bir durum etiketinden daha fazla bilgi içerir. Müşteriye gösterilen sayfayı kodlamadan önce yanıtı gönderi tanımlayıcısı, taşıyıcı, en son durum, olay kodu, olay açıklaması, olay zaman damgası, konum, tahmini teslimat bilgileri ve mevcutsa teslimat zaman damgası gibi dahili bir modele eşleyin.

Saklama ve gizlilik politikalarınız izin verdiğinde taşıyıcının orijinal yanıtını koruyun. Ham yanıt, bir eşleme hatasının teşhis edilmesine veya normalleştirilmiş durumunuzun taşıyıcının ifadesinden neden farklı olduğunun açıklanmasına yardımcı olabilir. Bununla birlikte, teknik olay kodlarını okunabilir bir açıklama olmadan müşterilere göstermeyin.

Her durumu nihai teslimat sonucu olarak değerlendirmeyin. Örneğin taşıma hâlindeki bir olay, istisna, teslimat girişimi ve teslim edilmiş olayı aynı müşteri mesajına indirgenmemelidir. Açık eşlemeler oluşturun ve UPS kodunuzun tanımadığı bir olay değeri eklediğinde ne olacağını belirleyin.

6. Adım: Yeniden Deneme, Doğrulama ve İzleme Ekleyin

Üretim entegrasyonu, geliştirme konsolunda başarılı bir istekten daha fazlasını gerektirir. Doğrulama ve operasyonel güvenlik önlemleri ekleyin:

• Girdi doğrulama: İstek göndermeden önce boş, hatalı biçimlendirilmiş veya açıkça eksik takip numaralarını reddedin.
• Zaman aşımları: Yavaş bir taşıyıcı yanıtının tüm ödeme, destek veya depo iş akışını engellemesini önleyin.
• Yeniden deneme kuralları: Geçici ağ veya hizmet hatalarını geri çekilmeli biçimde dikkatle yeniden deneyin. Kimlik doğrulama hatalarını veya geçersiz takip numaralarını tekrar tekrar denemeyin.
• Hız sınırlarının farkında olma: UPS belgelerindeki sınırları ve kullanım kurallarını izleyin. İş süreciniz izin verdiğinde son sonuçları önbelleğe alın.
• Bilinmeyen durumlar: Tanınmayan bir olayı yanlışlıkla teslim edildi veya kayıp olarak etiketlemek yerine inceleme için saklayın.
• Gözlemlenebilirlik: Gizli bilgileri veya gereksiz kişisel verileri günlüğe kaydetmeden istek zamanlamasını, yanıt kategorisini ve ilişkilendirme bilgilerini kaydedin.

Bir takip sistemi gönderiyi ne sıklıkta yenileyeceğini de tanımlamalıdır. Çok agresif yoklama gereksiz yük oluşturabilir ve yeni bilgi sağlamayabilir. Çok seyrek yoklama ise müşteriye gösterilen sayfanın güncel görünmemesine neden olabilir. Aralığı gönderi hacmine, operasyonel aciliyete, taşıyıcının kurallarına ve kullanıcılarınızın gerçekten ihtiyaç duyduğu güncelliğe göre seçin.

7. Adım: Gerçekçi Senaryolarla Test Edin

Yalnızca başarıyla teslim edilmiş bir gönderiyi test etmeyin. Bilinmeyen bir takip numarası, taşıma hâlindeki bir gönderi, bir istisna, birden fazla olaya sahip bir gönderi, süresi dolmuş bir belirteç, zaman aşımı, yetkilendirme hatası ve ayrıştırıcınızın beklemediği alanları içeren bir yanıt ekleyin. UPS ayrı bir test ortamı veya test kimlik bilgileri sağlıyorsa önce bu prosedürü izleyin.

İstekten kullanıcı arayüzüne kadar tüm yolu kontrol edin. Doğru siparişin doğru gönderiyi aldığını, zaman damgalarının amaçlanan saat diliminde görüntülendiğini, yinelenen olayların yinelenen müşteri mesajları oluşturmadığını ve taşıyıcı kesintisinin daha önce geçerli olan bir durumu yanıltıcı metinle geçersiz kılmadığını doğrulayın.

Çok Taşıyıcılı Bir Takip API'si Ne Zaman Daha Uygundur

Doğrudan UPS entegrasyonu, operasyonunuz çoğunlukla UPS ile gönderim yapıyor ve taşıyıcı iş akışı üzerinde yakın denetim gerektiriyorsa uygun olabilir. Siparişler birkaç taşıyıcı, pazaryeri, posta işletmesi veya bölgesel teslimat şirketi üzerinden ilerleyebildiğinde bu yaklaşım daha az kullanışlı hâle gelir. Bu durumda ayrı kimlik bilgileri, yanıt biçimleri, durum sözlükleri ve yeniden deneme kuralları bakım işini artırabilir.

17TRACK Tracking API gibi çok taşıyıcılı bir hizmet, birden fazla taşıyıcı üzerinden takip gerektiren uygulamalar için alternatif bir entegrasyon modeli sağlayabilir. Desteklenen taşıyıcılar, istek biçimleri, kimlik doğrulama, kullanım şartları ve mevcut yetenekler için geliştirici belgeleri doğrudan incelenmelidir. Bu, onu otomatik olarak doğrudan UPS bağlantısından daha iyi yapmaz: doğru seçim taşıyıcı karmasına, veri gereksinimlerine, entegrasyon üzerindeki denetime ve ticari veya uyumluluk kısıtlamalarına bağlıdır.

Geliştirici entegrasyonu yerine tüketiciye yönelik sorgulama gerekiyorsa 17TRACK takip sayfası bir API bağlantısı oluşturmaktan daha uygun olabilir. Markalı satın alma sonrası güncellemelere ihtiyaç duyan bir çevrim içi mağaza için mağazanın ihtiyaç duymadığı API çalışmalarını eklemek yerine ilgili platform entegrasyonunu ayrıca inceleyin.

Yaygın Uygulama Hataları

• Eski örnekleri kullanmak: Bir kod örneği kullanımdan kaldırılmış bir sürüme, eski bir kimlik doğrulama yöntemine veya farklı bir UPS hizmetine başvurabilir.
• Gizli bilgileri ön uç koduna koymak: Tarayıcıya gönderilen her şey incelenebilir kabul edilmelidir.
• Boş sonucun gönderi olmadığı anlamına geldiğini varsaymak: Bir iş sonucu çıkarmadan önce takip numarasını, hesap izinlerini, ortamı ve yanıt mesajını doğrulayın.
• Yalnızca metni eşlemek: Durum açıklamaları değişebilir. Belgelenmiş kodları kullanın ve bilinmeyen değerleri inceleme için saklayın.
• Hesap ve kullanım gereksinimlerini göz ardı etmek: Uygulama istenen hizmet için yapılandırılmamışken teknik kod doğru olabilir.
• Bir iş kuralı olmadan yenilemek: Gereksiz yoklama, müşteri deneyimini iyileştirmeden maliyeti, yükü ve operasyonel gürültüyü artırabilir.

Uygulamaya Alma İçin Pratik Kontrol Listesi

1. Uygulamanın güncel UPS belgelerini ve onaylanmış ortamı kullandığını doğrulayın.
2. Kimlik bilgilerinin sunucu tarafında saklandığını ve yenilenebildiğini doğrulayın.
3. Kimlik doğrulama hatasını, taşıyıcı hatalarını, hatalı girdiyi ve zaman aşımlarını test edin.
4. Temsili gönderiler için normalleştirilmiş durumları orijinal yanıtla karşılaştırın.
5. Bir yenileme politikası belirleyin ve istek hacmini izleyin.
6. Tanımlanamayan olayların, geciken güncellemelerin ve müşteri eskalasyonlarının sorumluluğunu belirleyin.
7. Başka bir geliştiricinin kimlik bilgilerini, uç nokta sürümlerini ve durum eşlemelerini güvenli biçimde güncelleyebilmesi için entegrasyonu belgeleyin.

SSS

Tracking API'yi kullanmak için UPS hesabına ihtiyacım var mı?

Güncel UPS kayıt ve erişim gereksinimlerini Developer Portal'da incelemelisiniz. API erişimi; uygulama kaydına, kimlik bilgilerine, hesap yapılandırmasına ve istenen belirli hizmete bağlı olabilir. Herkese açık takip sayfası girişinin geliştirici API erişimiyle aynı olduğunu varsaymayın.

UPS Tracking API ücretsiz mi?

API erişiminin ticari veya kullanım koşulları olmadığını varsaymayın. UPS güncel hizmet ve hesap bilgilerini resmi kanalları üzerinden yayımlar; bazı gereksinimler ürüne, hesaba veya anlaşmaya bağlı olabilir. Üretim bütçesi planlamadan önce geçerli şartları doğrudan doğrulayın.

UPS API'yi doğrudan bir tarayıcıdaki JavaScript'ten çağırabilir miyim?

Tarayıcı tabanlı bir çağrı, uygulama kimlik bilgilerini açığa çıkarabilir ve kaynaklar arası, güvenlik ve kullanım denetimi sorunları oluşturabilir. Gizli bilgileri saklamak, belirteçleri almak, yeniden deneme kurallarını uygulamak ve gönderi verilerine erişimi sınırlamak için sunucu taraflı entegrasyon genellikle daha güvenli bir yaklaşımdır.

Uygulamam takip güncellemelerini ne sıklıkta istemeli?

Yenileme politikasını taşıyıcının belgelenmiş sınırlarına, gönderi hacmine, operasyonel aciliyete ve kullanıcılarınızın ihtiyaç duyduğu güncelliğe göre belirleyin. Uygun olduğunda son sonuçları önbelleğe alın, geçici hatalardan sonra geri çekilme kullanın ve tekrarlanan yoklamayı belgelenmiş bir olay veya bildirim yeteneğinin yerine koymayın.

Doğrudan UPS entegrasyonu mu yoksa çok taşıyıcılı bir API mi kullanmalıyım?

Doğrudan UPS entegrasyonu, taşıyıcıya özgü denetim gerektiren UPS odaklı bir iş akışına uygun olabilir. Çok taşıyıcılı bir API, gönderileriniz birkaç taşıyıcı kullanıyorsa entegrasyon sayısını azaltabilir. Seçim yapmadan önce desteklenen taşıyıcıları, kimlik doğrulamayı, veri alanlarını, güvenilirlik gereksinimlerini, kullanım şartlarını ve uygulama çabasını karşılaştırın.

Kaynaklar

• UPS Developer Portal — resmi API kataloğu, uygulama erişimi, kimlik doğrulama ve geliştirici belgeleri.
• UPS Technology Integration — UPS teknolojisinin işletme sistemleriyle entegrasyonu hakkında resmi bilgiler.
• 17TRACK Tracking API — çok taşıyıcılı takip için resmi ürün ve geliştirici başlangıç noktası.
• 17TRACK API Documentation — kimlik doğrulama, istekler ve yanıt işleme için resmi API belgeleri.