FedExin API-integrointien parhaat käytännöt

Tällä pikaoppaalla pyritään auttamaan API-käyttäjiä löytämään parhaat tavat FedEx-palvelujen integrointiin ja varmistamaan ratkaisujen laatu suunnittelun, nopeuden ja turvallisuuden osalta.

FedExin API-liittymiä käyttäessään kehittäjien on hyvä noudattaa näitä integrointien parhaita käytäntöjä:

URI-osoitteet

• Testille ja tuotannolle on omat URI-osoitteet. 
• Kehittäjien on hyvä käyttää testauksen URI-osoitteita kehitysvaiheessa sekä integrointitestauksessa ja tuotannon URI-osoitteita tuotantovaiheessa.

API-liittymien URI-osoitteet:

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

Tuotanto: https://apis.fedex.com/

Käyttäjätunnusten hallinta

• API-avain ja salainen avain

• API-avainta ja salaista avainta käytetään sovelluksen identifioimisessa ja OAuth-tunnuspyynnössä.

1. API-avain ja salainen avain on pidettävä salassa. Älä jaa API-avainta tai salaista avainta sähköpostissa äläkä jaa koodia, joka sisältää asiakaspään JavaScriptejä.
2. Sovellukset ovat vaarassa, jos API-avain tai salainen avain varastetaan. Jos epäilet, että käyttäjätunnukset on varastettu tai ne ovat paljastuneet, luo salainen avain uudelleen välittömästi.
3. Vältä kirjaamasta lokiin arkaluonteisia tietoja, kuten salaista avainta.

• Älä kirjoita API-avainta ja salaista avainta ohjelmakoodiin.
• Sovelluksen tulisi kyetä dynaamisesti päivittämään API-avain ja salainen avain.
• Asiakaspään käyttäjätunnukset tulee tallentaa säilöön tai turvalliseen paikkaan, jotta ne eivät joudu vääriin käsiin.

• OAuth-tunniste

• Käyttötunniste kannattaa tallettaa vain web-sovelluspalvelimeen, eikä se saa näkyä selaimessa.
• Älä koodaa tunnistetta sellaisenaan sovelluksiin.
• Säilytä käyttötunnisteita niin, että ne eivät päädy sivullisten haltuun.
• Vältä tekemästä useita kutsuja OAuth-tunnus-API:iin uuden käyttötunnuksen saamiseksi. On suositeltavaa siirtää käyttötunnus välimuistiin siihen saakka, kunnes palautuu HTTP-virhekoodi 401. Luo sitten OAuth-tunnus uudelleen.
• Älä paljasta tunnusta loppukäyttäjälle tai sovellukselle.
• Käytä HTTPS-yhteyttä kaikissa API-tapahtumissa.

Koodauskäytännöt

• Uusimpien ja turvallisimpien tietoliikenteen suojausmenetelmien noudattamiseksi on suositeltavaa käyttää TLS:n versiota 1.2 tai suurempaa.
• Älä unohda asettaa jokaiseen API-pyyntöön oikeita API-otsikoita. Otsikkotiedot löytyvät kunkin API:n dokumenttisivulta. 
• HTTP POST -kutsussa ’Content-Type’ pitää olla ‘application/json’.
• Tutustu esimerkkikoodiin, ennen kuin aloitat API-liittymän teon. Jokaisen API:n lopuksi on useita esimerkkejä, jotka auttavat ymmärtämään tarvittavat elementit, muodot ja muut yksityiskohdat.
• Jos käyttäjä tai kehittäjä lähettää arvon, jossa on useita desimaaleja, voi muodostua odottamattomia virheitä. Painossa ja valuutta-arvossa/-summassa saa olla vain kaksi desimaalia. Mitoissa – kuten pituus, leveys ja korkeus – ei tueta desimaaleja.

Esimerkki: Paino: 45.26, valuutta-arvo/-summa: 100.52, pituus: 10, leveys: 25, korkeus: 15.

• Vältä tyhjien elementtien lähettämistä.

Esimerkki: “Streetlines”:””

• Lähetä vain pyynnön käsittelyssä tarvittavat tiedot.

Esimerkiksi Yhdysvaltain sisäisissä lähetyksissä vältä lähettämästä kauppalaskua ja hyödyketietoja, joita tarvitaan vain kansainvälisissä lähetyksissä.

• Kun teet kehitystyötä, määritä tavat, joilla reagoidaan, jos tarpeetonta vastauselementtiä, kuten hintaa, ei palauteta. Arvioi tapahtuman vastaus puuttuvista elementeistä ennen tietojen käyttöä.

Esimerkiksi on mahdollista lähettää paketti, jos hinnoittelu ei toimi. Testaa tapahtuman vastaus puuttuvista elementeistä ennen tietojen käyttöä.

• Yleisesti ottaen vältä kovia riippuvuuksia FedExin API-integrointiin, jos se on mahdollista.
• Viiveen välttämiseksi ja tarkkojen tulosten saamiseksi käytä seuraavaa:
  
  • Suodatus - Käytä tätä tarkentamaan hakua käytettävillä parametreilla.
  • Lajittelu - Käytä tätä, kun haluat järjestää tulokset tietyn parametrin mukaan nousevaan tai laskevaan järjestykseen.
• Tarkista, että tarvittavat kentät – kuten vastaanottajan postinumero ja paketin paino – on annettu, ennen kuin lähetät tapahtuman. Varmista, että tieto kelpaa kyseiseen kenttään. Näin vältetään turhat tapahtumavirheet.
  

Esimeriksi, jos kyseessä on Yhdysvalloissa käytettävä postinumero, tarkista, että kenttä on kokonaan numeerinen ja se on joko 5-numeroinen postinumero tai postinumero + 4-numeroinen postikoodi.

• Jotta FedEx-järjestelmän käytettävyys ja luotettavuus eivät kärsi:
  
  • Älä aja suorituskykytestiä testi- tai tuotantoympäristössä.
  • Huolehdi koodin logiikassa, että sama tapahtuma ei epäonnistu toistuvasti.
• Rajaksi on asetettu 1400 tapahtumaa 10 sekunnin aikana. Jos tämä raja saavutetaan ensimmäisten sekuntien aikana, palautetaan HTTP-virhekoodi 429 Too many requests ja tapahtumat estetään, kunnes 10 sekuntia on kulunut. Sen jälkeen tapahtumat jatkuvat normaalisti.
  

Esimerkiksi, jos saadaan 1400 pyyntöä neljän ensimmäisen sekunnin aikana, palautuu HTTP-virhekoodi 429 Too many requests – ”We have received too many requests in a short duration. Please wait a while to try again.” Tapahtumia rajoitetaan seuraavan kuuden sekunnin ajan, jonka jälkeen ne jatkuvat.

• Älä koodaa lähettämisen business-sääntöjä, kuten palvelutyyppejä, pakettityyppejä, painorajoja jne., koska ne voivat muuttua.

Virheenhallinta

Jokainen API-vastaus sisältää HTTP-tilakoodin ja vastauksen tietosisällön. Osaan vastauksista liittyy virhe, varoitus tai huomautus tilanteen mukaan. Varoitukset ja huomautukset eivät ole merkkejä virheestä. Virhe- ja varoitusviestit pitää kuitenkin kirjata ja tutkia. Asianmukainen virheiden käsittely varmistaa, että integrointi FedEx-järjestelmään toimii sujuvasti eikä aiheuta tarpeettomia käyttökatkoja.

HTTP-tilakoodit

Hinta

• Hinta-arvion saamiseksi on kaksi tapaa:
  
  • serviceType-kohtainen hinta - Tulokset suodatetaan annetun serviceType-arvon mukaan. Tämä pienentää vastauksen kokoa ja lyhentää tapahtuman vastausaikaa.
    

    Esimerkki: STANDARD_OVERNIGHT
    

  • Hinnan haku – Jos serviceType on ilmoittamatta, järjestelmä palauttaa kaikki mahdolliset palvelut ja niiden hinnat.
• Palvelu saatavilla -API määrittää, mitkä palvelut, pakettivaihtoehdot ja erityispalvelut ovat saatavilla annetulle lähtöpisteen ja määränpään välille. Lisäksi se välittää serviceType-arvon ja pakettivaihtoehdon hintapyynnölle.
  

  Esimerkiksi STANDARD_OVERNIGHT (muiden muassa) ei ole saatavilla kaikille postinumeroille.

• Jos lähetykseen liittyy erityispalvelu, erityispalvelun tyyppi ja sen tiedot pitää sisällyttää mukaan. 
  
  • Huomautus: Kaikkiin erityispalveluihin ei liity tarkempia tietoja.
• Tutustu Hinta API:n dokumentaatioon.

Lähetä

• Palvelu saatavilla -API määrittää, mitkä palvelut ovat saatavilla annetulle lähtöpisteen ja määränpään välille, ja se välittää serviceType-arvon ja pakettivaihtoehdon lähetyspyynnölle.
• Jos lähetykseen liittyy erityispalvelu, erityispalvelun tyyppi ja sen tiedot pitää sisällyttää mukaan.
  
  • Huomautus: Kaikkiin erityispalveluihin ei liity tarkempia tietoja.
• Sulje FedEx Ground lähetyspäivän lopussa ennen kuin lähetys noudetaan.
  
• Tutustu Lähetys API:n dokumentaatioon.
  

Seuraa

• Rajoita seurantanumeroiden määrä yhdessä seurantapyynnössä 30:een. Tämä pienentää vastauksen kokoa ja lyhentää tapahtuman vastausaikaa.
• Rajoita paketin seurantakertojen määrä yrityksen kannalta tarpeelliselle tasolle.
• Eräseurannassa poista erästä kaikki paketit, jotka ovat palauttaneet seurantatilan "toimitettu".
• Tutustu Seuraa API:n dokumentaatiota.

Osoitteen vahvistus

• FedExin tarjoama osoitteen tarkistus on ehdotus eikä lopullinen valinta. Loppukäyttäjän pitää annettujen tietojen ja yritystarpeiden perusteella tehdä lopullinen valinta siitä, onko osoite kelvollinen. Niitä osoitteita varten, joita ei voi varmentaa, pitää sopia jokin prosessi, jotta tilaukset voidaan käsitellä.
• Jotta lähetyskokemus olisi sujuva, älä sido lähetysprosessia mihinkään erityispalveluun, kuten osoitteen vahvistukseen.

Esimerkiksi, jos osoitteen vahvistuksen API ei ole käytettävissä tilausta tehtäessä tai lähetettäessä, lähetyksen viimeistelyä varten pitää olla jokin mahdollisuus.

• Tutustu Osoitteen vahvistus API:n dokumentaatioon.
  

FedExin toimipistehaku

• Tarkenna hakua antamalla määrittäviä attribuutteja (esim. sijaintityyppi, tarjotut palvelut jne.), niin saat sopivat kohdevaihtoehdot nopeasti.
• Tutustu FedExin toimipistehaku-APIn dokumentaatioon.
  

Noutopyyntö

• Älä anna menneessä ajassa olevaa noutoaikaa tai päivämäärää äläkä päivämäärää, joka on liian kaukana tulevaisuudessa noudon sopimiseksi.
• Nimettömiä noutoja ei sallita.
  
• Tutustu Noutopyyntö API:n dokumentaatioon.
  

Palvelun saatavuus

• Jotta saat tuloksia useilta FedExiin kuuluvilta yrityksiltä, kuten FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) ja FedEx Ground® Economy, voit joko jättää pois carrierCodes-elementin tai lähettää erilliset palvelun saatavuuskyselyt, koska useita kuljetusliikekoodeja ei voida määrittää.
• Varmista, että olet ennalta hyväksyttänyt yksittäiset 151 paunan tai painavammat lavat ja yli 2 200 paunan lavat.
  
• Jos määrität SATURDAY_DELIVERY-arvon vaihteleville valinnoille, saat sekä lauantaitoimituksen vaihtoehdot että tavalliset vaihtoehdot kaikille palveluille, joissa on lauantaitoimituksen mahdollisuus. Älä määritä SATURDAY_DELIVERY-arvoa erityispalveluille, koska muutoin saat palautuksena vain soveltuvat lauantaitoimitusten vaihtoehdot.
• Tutustu Käytettävissä olevat palvelut API:n dokumentaatioon.

Asiakastuki

Jos sinulla on kysyttävää tai tarvitset opastusta, olemme täällä sinua varten. Siirry Tuki-sivulle, jos tarvitset lisätietoja resursseista ja yhteydenottotavoista.