FedEx API Entegrasyonu İçin En İyi Uygulamalar

Bu hızlı referans kılavuzu, API tüketicilerinin FedEx ile entegrasyon deneyimini iyileştirmelerini anlamalarına yardımcı olmayı ve tasarım, hız ve güvenlik yönünden entegrasyon çözümü kalitesini sağlamayı amaçlar.

FedEx API'leriyle etkin bir şekilde entegre olmak için geliştiricilerin entegrasyonla ilgili bu en iyi uygulamaları takip etmeleri gerekir:

API URI'leri

• Bunlar test ve üretim için ayrı API URI'leridir. 
• Geliştiriciler, geliştirme ve entegrasyon testi için test URI'lerini ve üretim için ise üretim URI'sini kullanmalıdır.

Aşağıda API URI'leri sıralanmıştır:

Test: https://apis-sandbox.fedex.com/

Üretim: https://apis.fedex.com/

Kimlik bilgisi yönetimi

• API Anahtarı ve Gizli Anahtar

• API Anahtarınız ve Gizli Anahtarınız, uygulamanızı tanımlamak için kullanılır ve OAuth belirteç isteğinde kullanılmalıdır.

1. API Anahtarınız ve Gizli Anahtarınız tamamen güvenilir bir şekilde işleme alınmalıdır. API Anahtarını veya Gizli Anahtarı e-posta veya istemci tarafındaki JavaScript dahil olmak üzere dağıtılmış kod üzerinden dağıtmayın.
2. API Anahtarınız veya Gizli Anahtarınız çalınırsa uygulamanızın güvenliği tehlikeye girecektir. Kimlik bilgilerinizin çalındığından veya güvenliğinin tehlikeye düştüğünden şüphelenirseniz lütfen Gizli Anahtarı derhal yeniden oluşturun.
3. Gizli Anahtar gibi hassas bilgileri günlüğe kaydetmekten kaçının.

• API Anahtarını ve Gizli Anahtarı kodunuza gömmeyin.
• Uygulamanız, API Anahtarını ve Gizli Anahtarı dinamik olarak güncelleyebilmelidir.
• İstemci kimlik bilgileri, kasada/güvenliğin tehlikeye giremeyeceği emniyetli bir yerde saklanmalıdır.

• OAuth belirteci

• Erişim belirteci sadece web uygulama sunucusunda saklanmalıdır ve tarayıcıya bırakılmamalıdır.
• Belirteci uygulamalarınıza gömmeyin.
• Erişim belirteçlerini güvene alarak güvenliğin tehlikeye düşmesini engelleyin.
• Yeni bir erişim belirteci için OAuth belirtecine birden fazla çağrı yapmaktan kaçının. HTTP hata kodu 401 gözleninceye kadar erişim belirtecinin önbelleğe alınması önerilir. O sürede OAuth belirtecini düzeltin.
• Belirteci son kullanıcıya ifşa etmeyin veya uygulamaya maruz bırakmayın.
• API işlemleri için HTTPS kullanın.

Kodlama uygulamaları

• En güncel ve en güvenli veri şifreleme iletişim protokolüyle uyumluluğu sağlamak için Taşıma Katmanı Güvenliği (TLS) 1.2 sürümü veya daha üst bir sürümünün kullanılması önerilir.
• Her API isteği için gereken doğru API başlıklarını ayarlamayı unutmayın. Başlık bilgilerini ilgili API belge sayfasında bulacaksınız. 
• HTTP POST'taki "Content-Type", "application/json" olmalıdır.
• Her API ile başlamak için lütfen örnek koduna başvurun. Her API uç noktası; gerekli ögeleri, biçimleri ve diğer ayrıntıları anlamanıza yardımcı olacak çeşitli örneklerle birlikte sunulur.
• Kullanıcılar veya geliştiriciler kendi değerlerinde birkaç ondalık sayı gönderdiklerinde bu durum garip hatalara neden olabilir. Ağırlık ve para birimi değeri/tutar için sadece iki adet açık ondalık basamağa izin verilir. Boyutlar (uzunluk, genişlik ve yükseklik gibi) ondalık sayıları desteklemez.

Örnek: Ağırlık: 45,26, para birimi değeri/miktar: 100,52, uzunluk: 10, genişlik: 25, yükseklik: 15.

• Boş öğeler göndermekten kaçının.

Örnek: "Sokak satırları":""

• Sadece isteği işleme almak için gerekli verileri gönderin.

Örneğin, bir ABD yurt içi gönderisinde sadece uluslararası gönderiler için gerekli olabilecek ticari fatura ve mal verilerini göndermekten kaçının.

• Geliştirme yaparken bir oran gibi gerekli olmayan bir yanıt ögesi geri dönmediği takdirde nasıl yanıt verileceğini belirleyin. Veri kullanmadan önce eksik ögeler için işlem yanıtını değerlendirin.

Örneğin, puanlandırma işlevsel değilse bir paket gönderilebilir. Veri kullanmadan önce eksik ögeler için işlem yanıtını test edin.

• Genel olarak, mümkünse FedEx API entegrasyonunda katı bağımlılıklardan kaçının.
• Gecikme süresini kısaltmak ve doğru sonuçlar almak için aşağıdaki kullanılmalıdır:
  
  • Filtreleme: Aramayı aradığınız parametrelerle daraltmak için bunu kullanın.
  • Sıralama: Sonuçları belirli bir parametreyi artan veya azalan sırada sıralamak için bunu kullanın.
• İşlemi göndermeden önce gerekli alanlarda (alıcı posta kodu ve paket ağırlığı gibi) verilerin bulunduğunu teyit edin. Verilerin söz konusu alan için uygun olduğunu teyit edin. Bu, işlem hatalarını en aza indirir.
  

Örneğin, ABD posta kodları için alanda yalnızca sayı bulunduğunu ve alanın 5 basamaklı veya ZIP+4 posta kodu biçiminde olduğunu teyit edin.

• FedEx sistem kullanılabilirliği ve güvenilirliği üzerinde olumsuz etkinin oluşmasını önlemek için:
  
  • Test veya üretim ortamında performans testi gerçekleştirmeyin.
  • Aynı işlemin sürekli başarısız olmasını engellemek için kodlama mantığını uygulayın.
• Kısıtlama sınırı, 10 saniye içinde 1400 işlemdir. Bu sınır ilk birkaç saniyede aşıldığı takdirde HTTP hata kodu 429 Çok fazla istek var uyarısı alınır ve işlemler 10 saniye geçinceye kadar kısıtlanır. İşlemler bu sürenin ardından tekrar devam eder.
  
  

Örneğin, ilk dört saniyede 1400 istek alırsak HTTP hata kodu 429 Çok fazla istek var - "Kısa sürede çok fazla istek aldık. Lütfen tekrar denemek için bir süre bekleyin." uyarısı alınır ve işlemler kalan altı saniye boyunca kısıtlanır ve bu sürenin ardından tekrar devam eder.

• Değişebileceğinden dolayı gönderiler için hizmet türleri, paket türleri, ağırlık sınırları gibi iş kurallarını gömmeyin.

Hata işleme alma

Her bir API yanıtında bir HTTP durum kodu ve hata yükü bulunur. Bazı yanıtlarla birlikte duruma göre bir hata, uyarı veya not bulunur. Uyarılar ve notlar arıza göstergeleri değildir. Ancak hata veya uyarı mesajı kaydedilmeli ve incelenmelidir. Uygun hata işleme, FedEx entegrasyonunuzun sorunsuz geçmesini sağlar ve kopmanın önlenmesine yardımcı olur.

HTTP durum kodları

Ücret

• Bir ücret teklifi almanın iki yolu vardır:
  
  • Belirli bir serviceType için ücret: Sonuçlar belirtilen serviceType değerine göre filtrelenecektir. Bu işlem, yanıt boyutunu küçültüp işlem yanıt süresini azaltacaktır.
    

    Örnek: STANDARD_OVERNIGHT
    

  • Ücret – Herhangi bir serviceType belirtilmediği takdirde tüm geçerli hizmetler ve ilgili ücretler geri dönecektir.
• Belirli bir çıkış/varış yeri ikilisi için hangi hizmetlerin, ambalaj seçeneklerinin ve özel hizmetlerin kullanılabileceğini belirlemek ve Ücret isteğinde serviceType ve paket seçeneğini geçirmek için Hizmet Kullanılabilirliği API'sini kullanın.
  

  Örneğin, STANDARD_OVERNIGHT (diğerlerinin yanı sıra) tüm posta kodları arasında mevcut değildir.

• Bir gönderiye özel bir hizmetin uygulanabilmesi için özel hizmet türü ve ayrıntıları dahil edilmelidir. 
  
  • Not: Bazı özel hizmetlerin ayrıntıları yoktur.
• Ücret API belgeleri'ni inceleyin.

Gönder

• Belirli bir çıkış/varış yeri ikilisi için hangi hizmetlerin kullanılabileceğini belirlemek ve Gönderi isteğinde serviceType ve paket seçeneğini geçirmek için Hizmet Kullanılabilirliği API'sini kullanın.
• Bir gönderiye belirli bir hizmetin uygulanabilmesi için özel hizmet türü ve bunun ayrıntıları eklenmelidir.
  
  • Not: Bazı özel hizmetlerin ayrıntıları yoktur.
• Gönderi teslim alınmadan önce gönderi gününün sonunda FedEx Ground için kapanışı gerçekleştirin.
  
• Gönderi API belgeleri'ni inceleyin.
  

Takip

• Tek bir takip isteğindeki takip numarası sayısını 30 ile sınırlandırın. Bu işlem, yanıt boyutunu küçültecek ve işlem yanıt süresini azaltacaktır.
  
• Bir paketin iş ihtiyaçları doğrultusunda gerekli olduğu ölçüde kaç kez takip edileceğini sınırlandırın.
• Toplu takip için "teslim edildi" takip durumuyla iade edilen tüm paketleri gruptan çıkarın.
• Takip API'si belgeleri'ni inceleyin.

Adres Doğrulama

• FedEx, son karar olarak değil, öneri olarak Adres Doğrulaması sunar. Son kullanıcının bir adresin sağlanan verilerden kullanılıp kullanılamayacağına ve bunların iş ihtiyaçlarına dair nihai bir karar vermesi gerekir. Siparişlerin işleme alınabilmesi amacıyla, doğrulanamayan adresleri işlemek için bir süreç yürürlükte olmalıdır.
• Daha iyi bir gönderi deneyimi sağlamak için gönderi sürecini Adres Doğrulama gibi isteğe bağlı hizmetlere bağlı duruma getirmeyin.

Örneğin, Adres Doğrulama API'si sipariş giriş veya gönderi tarihinde kullanılmadığı takdirde gönderiyi tamamlamak için bir acil eylem planı yürürlükte olmalıdır.

• Adres Doğrulama API belgeleri'ni inceleyin.
  

FedEx Şubesi Arama

• Uygun konum seçeneklerini ve daha hızlı yanıt süresi almak için belirli özellikleri (konum türü, sunulan hizmetler gibi) sağlayarak aramanızı daraltın.
• FedEx Şubeleri Arama API'si belgeleri'ni inceleyin.
  

Alım İsteği

• Bir teslim alım planlamak için geçmiş hazırlık saati, geçmiş tarih veya çok uzak gelecekte olan bir tarih girmeyin.
• İzinsiz teslim alımlara izin verilmez.
  
• Alım İsteği API Belgeleri'ni inceleyin.
  

Hizmet Kullanılabilirliği

• FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) ve FedEx Ground® Economy gibi farklı şirketlerle ilgili sonuç almak için farklı taşıyıcı kodları belirtilemeyeceğinden, carrierCodes ögesini çıkarın veya ayrı hizmet kullanılabilirliği istekleri gönderin.
• Lütfen 151 lb'lik müstakil kızaklar veya 2.200 lb boyutunu aşan kızaklar için önceden onay almayı unutmayın .
  
• Değişken seçenekler için SATURDAY_DELIVERY'yi belirtirseniz Cumartesi günü teslimatın seçenek olarak sunulduğu tüm hizmetler için hem Cumartesi günü teslimat seçeneklerini hem de normal seçenekleri alırsınız. Özel hizmetler için SATURDAY_DELIVERY'yi belirtmeyin. Aksi takdirde sadece geçerli Cumartesi günü teslimat seçenekleri alınır.
• Hizmet Kullanılabilirliği API belgeleri'ni inceleyin.

Müşteri desteği

Sorularınız varsa veya yardıma ihtiyacınız olursa size yardımcı olmaya hazırız! Kaynaklar ve bizimle iletişime geçme yolları hakkında bilgi almak için lütfen Destek sayfamızı ziyaret edin.