FedEx API-k integrációja – bevált gyakorlat

Ennek a rövid hivatkozási útmutatónak az a célja, hogy segítsen megérteni az API-kat használó fejlesztőknek, miként szerezhetnek jobb tapasztalatokat a FedEx-szel való integráció során, és hogy biztosítsa az integrációs megoldások minőségét a tervezés, a sebesség és a biztonság vonatkozásában.

Hogy hatékony lehessen a FedEx API-kkal való integráció, a fejlesztőknek követniük kell az alábbi bevált gyakorlatokat:

API URI-k

• Külön API URI-k állnak rendelkezésre a tesztelési és a termelési környezethez.
• A fejlesztőknek a tesztelési URI-kat kell használniuk fejlesztéshez és integrációs teszteléshez, a termelési URI-k a termelési környezetben történő használatra valók.

Az API URI-k listája itt található:

Tesztelési: https://apis-sandbox.fedex.com/

Termelési: https://apis.fedex.com/

Hitelesítési adatok kezelése

• API-kulcs és titkos kulcs

• Az Ön API-kulcsa és titkos kulcsa alkalmazásának azonosítására szolgál, és az OAuth lexikális elem (token) lekérésekor kell használni őket.

1. Az API-kulcsot és a titkos kulcsot szigorúan titokban kell tartani. Ne terjessze az API-kulcsot vagy a titkos kulcsot e-mailben vagy elosztott kódban, ideértve az ügyfél oldali JavaScriptet is!
2. Veszélybe kerülhet az alkalmazása, ha ellopják az API-kulcsát vagy a titkos kulcsát. Ha azt gyanítja, hogy hitelesítési adatait ellopták vagy veszélyeztetik, azonnal hozza létre újra a titkos kulcsot!
3. Ne naplózza az érzékeny adatokat, például a titkos kulcsot!

• Ne írja bele közvetlenül se az API-kulcsot, se a titkos kulcsot a kódjába!
• Alkalmazásának képesnek kell lennie arra, hogy dinamikusan frissítse az API-kulcsot és a titkos kulcsot.
• Az ügyfélhitelesítő adatokat széfben vagy biztonságos helyen kell tárolni úgy, hogy ne kerülhessenek veszélybe.

• Az OAuth lexikális elem (token)

• A hozzáférési lexikális elem csak a webalkalmazás-kiszolgálón tárolandó, a böngésző számára nem szabad elérhetővé tenni.
• Ne írja bele közvetlenül a lexikális elemet az alkalmazásaiba!
• Védje a hozzáférési lexikális elemeket, hogy ne kerülhessenek veszélybe, ne sérülhessenek meg!
• Ne hívja meg többször az OAuth lexikális elem API-t, hogy új hozzáférési lexikális elemet kapjon! Javasolt a hozzáférési lexikális elemet gyorsítótárazni, amíg elő nem fordul a 401-es HTTP-hiba. Ekkor állítsa elő újra az OAuth lexikális elemet!
• Ne tegye a lexikális elemet elérhetővé a végfelhasználó vagy az alkalmazás számára!
• Minden API-tranzakció esetén HTTPS protokollt használjon!

Kódolási gyakorlatok

• Hogy megfeleljen a legújabb és legbiztonságosabb adattitkosítási kommunikációs protokollnak, javasoljuk, hogy a TLS (Transport Layer Security) 1.2-es vagy újabb verzióját használja.
• Ne feledje el beállítani az egyes API-kérésekhez szükséges megfelelő API-fejléceket! A fejlécekre vonatkozó információkat az egyes API-k dokumentációs oldalán találja.
• A HTTP POST-ban a „Content-Type”-nak „application/json”-nak kell lennie.
• Amikor használni kezd egy-egy API-t, nézze meg a mintakódot. Minden API végponthoz több olyan minta tartozik, amelynek segítségével megértheti a szükséges elemeket, formátumokat és egyéb részleteket.
• Szokatlan hibák fordulhatnak elő, amikor a felhasználók vagy a fejlesztők túl sok tizedes jegyet használnak az értékekben. A tömeg és a pénznem értékénél csak két kifejezett tizedes jegy megengedett. A méretek – így a hosszúság, a szélesség és a magasság – nem támogatják a tizedes jegyeket.

Példa: Tömeg: 45,26, pénznem értéke/összege: 100,52, hosszúság: 10, szélesség: 25, magasság: 15.

• Ne küldjön el üres elemeket!

Példa: „Streetlines”:„”

• Csak a kérés feldolgozásához szükséges adatokat küldjön!

USA-beli belföldi küldemények esetében például ne küldje el a kereskedelmi számlát, és ne küldjön árucikkekre vonatkozó olyan adatokat, amelyekre csak nemzetközi küldemények esetében van szükség!

• Fejlesztéskor adja meg, hogyan kell reagálni, ha egy nem kötelező válaszelemet, például egy tarifaértéket nem kap vissza! Az adatok felhasználása előtt elemezze ki a tranzakció válaszát, és állapítsa meg, nem hiányoznak-e belőle elemek!

Egy csomagot például fel lehet adni, ha nem működik a tarifamegállapítás. Az adatok felhasználása előtt tesztelje a tranzakció válaszát, hogy megállapíthassa, nem hiányoznak-e belőle elemek!

• Általában kerülje a FedEx API integrációtól való erős függőséget!
• A késés csökkentése és a pontosabb eredmények érdekében a következőket kell használni:
  
  • Szűrés – Akkor használja, ha a keresett paraméterek segítségével le kívánja szűkíteni a keresést.
  • Rendezés – Akkor használja, ha a találatokat bizonyos paraméter szerint növekvő vagy csökkenő sorrendbe szeretné állítani.
• A tranzakció elküldése előtt ellenőrizze, hogy a kötelezően kitöltendő mezőkben van-e adat – például meg van-e adva a címzett irányítószáma vagy a csomag tömege! Ellenőrizze, hogy a megadott adat megfelelő-e a kérdéses mező esetén! Ezzel minimalizálhatja a tranzakciók hibáit.
  

Az USA-beli irányítószámok esetén például ellenőrizze, hogy a mezőben csak számjegyek vannak-e, és hogy 5 számjegyű vagy ZIP+4 irányítószám-formátumú-e!

• A FedEx rendszerének elérhetőségére és megbízhatóságára gyakorolt nemkívánatos hatás elkerülése érdekében:
  
  • Ne végezzen teljesítménytesztelést se a tesztelési, se a termelési környezetben!
  • Alkalmazzon olyan kódolási logikát, amely nem engedi meg, hogy ugyanaz a tranzakció ismételten sikertelen legyen!
• A szabályozásra vonatkozó korlát: 1400 tranzakció 10 másodpercenként. Amennyiben a tranzakciók száma már az első néhány másodpercben eléri ezt a korlátot, akkor a rendszer 429 Too many requests (Túl sok kérés) HTTP-hibakódot küld, és nem hajt végre tranzakciókat a 10 másodperces időintervallum fennmaradó részében, majd folytatja a tranzakciók végrehajtását.
  

Ha például az első négy másodpercben 1400 kérés érkezik, akkor megjelenik a 429 Too many requests (Túl sok kérés) – „Rövid idő alatt túl sok kérés érkezett. Várjon egy kicsit, és próbálja meg újra.” HTTP-hibakód, és a következő hat másodpercre a rendszer felfüggeszti a tranzakciók végrehajtását, majd annak letelte után folytatja.

• Ne írja bele közvetlenül a kódba a küldeményekre vonatkozó üzleti szabályokat, például a szolgáltatásfajtákat, csomagolásfajtákat, tömegre vonatkozó korlátokat stb., mert az ilyen szabályok változhatnak.

Hibakezelés

Minden API-válasz tartalmaz egy HTTP állapotkódot és választerhelést. Egyes válaszokhoz hiba, figyelmeztetés, illetve megjegyzés társul. A figyelmeztetések és a megjegyzések nem utalnak hibára, a hiba- vagy figyelmeztető üzeneteket azonban naplózni kell és meg kell vizsgálni. A megfelelő hibakezelés biztosítja, hogy a FedEx-szel való integrációja zökkenőmentesen haladjon, és segíthet elkerülni a leállást is.

HTTP állapotkódok

Tarifa

• Árajánlat kétféleképp kérhető:
  
  • Tarifa egy konkrét serviceType szolgáltatásfajtára – A találatokat a rendszer a serviceType jelzett értéke szerint szűri. Ezzel csökkenti a válasz méretét és a tranzakció válaszidejét.
    

    Példa: STANDARD_OVERNIGHT

  • Minden tarifa – Ha nincs megjelölve serviceType szolgáltatásfajta, akkor a rendszer az összes vonatkozó szolgáltatást és a hozzá tartozó tarifát visszaadja.
• A Szolgáltatás elérhetősége API segítségével határozható meg, hogy mely szolgáltatások, csomagolási lehetőségek és különleges szolgáltatások érhetőek el egy adott származási hely–rendeltetési hely pár esetén, és ennek segítségével adható át a serviceType szolgáltatásfajta és a csomagolási lehetőség az árajánlatkérésben.
  

  A STANDARD_OVERNIGHT (többek között) például nem érhető el miden irányítószám-kombináció esetén.

• Ha különleges szolgáltatást szeretne alkalmazni egy küldeményre, akkor a különleges szolgáltatás típusát és részletes adatait is meg kell adnia.
  
  • Megjegyzés: Egyes különleges szolgáltatások nem rendelkeznek részletes adatokkal.
• Nézze meg a Tarifa API dokumentációját!

Feladás

• A Szolgáltatás elérhetősége API segítségével határozható meg, hogy mely szolgáltatások érhetőek el egy adott származási hely–rendeltetési hely pár esetén, és ennek segítségével adható át a serviceType szolgáltatásfajta a szállítási kérésben.
• Ha különleges szolgáltatást szeretne alkalmazni egy küldeményre, akkor a különleges szolgáltatás típusát és részletes adatait is meg kell adnia.
  
  • Megjegyzés: Egyes különleges szolgáltatások nem rendelkeznek részletes adatokkal.
• FedEx Ground szolgáltatások esetén a szállítási nap végén hajtsa végre a zárást, még mielőtt felvennék a küldeményt!
  
• Nézze meg a Szállítási API dokumentációját!

Nyomon követés

• Egyedi nyomon követési kérésbe ne foglaljon bele 30-nál több fuvarlevélszámot! Ezzel csökkenti a válasz méretét és a tranzakció válaszidejét.
• Egy csomagot csak annyiszor kövessen nyomon, ahányszor az üzleti szempontból szükséges!
• Kötegelt nyomon követés esetén a kötegből távolítson el minden olyan csomagot, amely már „kézbesítve” nyomon követési státuszt adott vissza.
• Nézze meg a Nyomon követési API dokumentációját!

Címellenőrzés

• A FedEx a címellenőrző eszközt javasolt, nem pedig végleges döntést meghozó eszközként biztosítja. A végfelhasználónak kell meghoznia a végső döntést arról, hogy egy, a megadott adatok között található cím használható-e, és megfelel-e üzleti igényeinek. A nem ellenőrizhető címek kezelésére is kell lennie eljárásnak, hogy a megrendelések ilyen esetben is feldolgozhatóak legyenek.
• Hogy zökkenőmentesebb legyen a szállítás, ügyeljen arra, hogy a szállítási folyamat ne függjön olyan nem kötelező szolgáltatástól, mint a címellenőrzés.

Ha például a Címellenőrzési API nem áll rendelkezésre a rendelés vagy a küldemény feladásánál, kell lennie egy olyan „B tervnek”, amellyel befejezhető a küldeményfeladás.

• Nézze meg a Címellenőrzési API dokumentációját!

FedEx kirendeltségek keresése

• Konkrét attribútumok (például a kirendeltség fajtája, a kínált szolgáltatások stb.) megadásával szűkítse le a keresést, hogy a kirendeltségek használható kínálatát kapja, és hogy rövidebb legyen a válaszidő!
• Nézze meg a FedEx kirendeltség-kereső API dokumentációját.
  

Küldeményfelvételi kérés

• Küldeményfelvétel beütemezésekor ne adjon meg múltbeli elkészülési időpontot, múltbeli vagy a távoli jövőbeli dátumot!
• Név nélküli küldeményfelvétel nem megengedett.
  
• Nézze meg a Küldeményfelvételi kérés API dokumentációját!

A szolgáltatások elérhetősége

• Ahhoz, hogy több szolgáltató vállalatra, például a FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) és FedEx Ground® Economy vállalatra vonatkozóan kapjon találatokat, vagy hagyja ki a carrierCodes elemet, vagy küldjön a szolgáltatások elérhetőségére vonatkozó különálló kéréseket, mert több szállítókód nem adható meg.
• Figyeljen arra, hogy legyen előzetes jóváhagyása az egyenként legalább 151 fontos raklapokra és a 2200 fontnál nehezebb raklapokra!
  
• Ha változó lehetőségek esetén a SATURDAY_DELIVERY értéket adja meg, akkor a szombati kézbesítési lehetőségeket és a normál lehetőségeket is megkapja minden olyan szolgáltatás esetében, amelynél lehetőség van szombati kézbesítésre. Különleges szolgáltatások esetén ne adja meg a SATURDAY_DELIVERY értéket, mert ha megadja, akkor csak a használható szombati kézbesítési lehetőségeket fogja visszaadni a rendszer.
• Nézze meg a Szolgáltatás elérhetősége API dokumentációját!

Ügyféltámogatás

Ha kérdése merül fel, vagy ha segítségre van szüksége, forduljon hozzánk bizalommal! Azt, hogy miként léphet velünk kapcsolatba, a Támogatás oldalon ismerheti meg. Ezen az oldalon különféle erőforrásokat is találhat.