Osvědčené postupy integrace rozhraní FedEx API

Jedná se o stručnou referenční příručku, která má uživatelům rozhraní API pomoci pochopit způsoby, jak zlepšit praxi integrace se službami FedEx a zajistit kvalitu integračního řešení z hlediska designu, rychlosti a bezpečnosti.

Aby se podařilo účinně integrovat rozhraní FedEx API, je třeba, aby se vývojáři řídili těmito osvědčenými postupy integrace:

Identifikátor URI rozhraní API

• Pro testování a vývoj existují samostatné identifikátory URI rozhraní API. 
• Je třeba, aby vývojáři používali tyto testovací identifikátory URI pro testování při vývoji a integraci a produkční identifikátory URI pro produkci.

Seznam identifikátorů URI rozhraní API naleznete níže:

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

Produkce: https://apis.fedex.com/

Správa pověření

• Klíč API a tajný klíč

• Klíč API a tajný klíč se používají k identifikaci vaší aplikace a je třeba je použít při požadavku na token OAuth.

1. S klíčem API a tajným klíčem byste měli zacházet velmi opatrně. Neposílejte klíč API ani tajný klíč prostřednictvím e-mailu nebo odesílaného zdrojového kódu, včetně JavaScriptu na straně klienta.
2. Pokud vám bude API klíč nebo tajný klíč ukraden, bude vaše aplikace ohrožena. Máte-li podezření, že byly vaše přihlašovací údaje ukradeny nebo ohroženy, okamžitě vytvořte tajný klíč znovu.
3. Citlivé informace, jako je například tajný klíč, si nezaznamenávejte.

• Nekóduje API klíč ani tajný klíč do zdrojového kódu.
• Vaše aplikace by měla být schopna API klíč a tajný klíč dynamicky aktualizovat.
• Přihlašovací údaje klienta by měly být uloženy do trezoru / na bezpečné místo, aby nemohlo dojít k jejich ohrožení.

• Token OAuth

• Token pro přístup by měl být uložen pouze na serveru webové aplikace a nesmí přijít do kontaktu s prohlížečem.
• Token nekódujte do svých aplikací.
• Přístupové tokeny zabezpečte tak, abyste zabránili jejich ohrožení.
• Neprovádějte více vyvolávání API OAuth tokenu za účelem získání nového tokenu. Přístupový kód se doporučuje uschovat do chvíle, kdy dojde k zaznamenání chybového kódu 401 protokolu HTTP. V tu chvíli token OAuth obnovte.
• Neodhalujte token koncovému uživateli nebo aplikaci.
• Pro veškeré transakce API použijte protokol HTTPS.

Způsoby kódování

• Pro zachování souladu s nejaktuálnějším a nejbezpečnějším komunikačním protokolem pro šifrování dat se doporučuje používat Transport Layer Security (TLS) verze 1.2 nebo vyšší.
• Nezapomeňte nastavit správná záhlaví API potřebná pro jednotlivé požadavky API. Informace o záhlaví naleznete na každé stránce dokumentace API. 
• Hlavička ‚Content-type‘ protokolu HTTP POST by měla být „application/json“.
• Když začínáte s jednotlivými rozhraními API, prohlédněte si ukázku zdrojového kódu. Každý koncový bod v rozhraní API je doprovázen několika ukázkami, které vám pomohou pochopit požadované prvky, formáty a další podrobnosti.
• Jestliže uživatelé nebo vývojáři odešlou hodnoty s mnoha desetinnými místy, může to mít za následek neobvyklé chyby. U hmotnosti a peněžní hodnoty / částky jsou povolena pouze dvě vyjádřená desetinná místa. U rozměrů (například délka, šířka a výška) nejsou podporována žádná desetinná místa.

Příklad: Hmotnost: 45,26, peněžní hodnota / částka: 100,52, délka: 10, šířka: 25, výška: 15.

• Neodesílejte prázdné prvky.

Příklad:„Streetlines“:„“

• Odesílejte pouze údaje nezbytné pro zpracování požadavku.

Například v případě zásilky v rámci Spojených států neodesílejte obchodní faktury a údaje o zboží, které mohou být vyžadovány pouze u mezinárodních zásilek.

• Při vývoji určete, jak reagovat, pokud je vrácen nepožadovaný prvek odpovědi, například cena. Před použitím dat vyhodnoťte odpověď transakce, zda u ní nechybí některé prvky.

Není například možné odeslat balík, jestliže není funkční stanovení ceny. Před použitím dat otestujte odpověď transakce, zda u ní nechybí některé prvky.

• Obecně se pokud možno vyhněte pevným závislostem na integraci FedEx API.
• Chcete-li zkrátit zpoždění a získat přesné výsledky, je třeba použít následující:
  
  • Filtrování – Slouží ke zúžení vyhledávání podle hledaných parametrů.
  • Řazení – Slouží k seřazení výsledků podle určitého parametru ve vzestupném nebo sestupném pořadí.
• Před odesláním transakce ověřte, že požadovaná pole (například poštovní směrovací číslo příjemce a hmotnost balíku) obsahují údaje. Ověřte, zda jsou údaje odpovídající pro dané pole. Tím se minimalizují chyby transakce.
  

Například v případě poštovních směrovacích čísel pro Spojené státy ověřte, zda je pole celé číselné a zda má podobu 5místného čísla nebo je ve tvaru ZIP+4.

• Chcete-li zabránit nepříznivým dopadům na dostupnost a spolehlivost systému FedEx:
  
  • V testovacím nebo produkčním prostředí neprovádějte testování výkonu.
  • Používejte logické kódování, aby se zabránilo opakovanému selhání stejné transakce.
• Limit pro omezení je nastaven na 750 transakcí za 10 sekund. Pokud je tohoto limitu dosaženo během několika prvních sekund, zobrazí se kód chyby HTTP 429 Příliš mnoho požadavků a po dobu 10 sekund budou transakce omezeny; poté budou znovu obnoveny.
  
  

Například pokud během prvních čtyř sekund obdržíme 750 požadavků, zobrazí se kód chyby HTTP 429 Příliš mnoho požadavků – „Během krátké doby jsme obdrželi příliš mnoho požadavků. Chvíli prosím počkejte a zkuste to znovu.“ a transakce budou po následujících šest sekund omezeny a poté se znovu obnoví.

• Nekódujte do zdrojového kódu obchodní podmínky pro zásilky, jako jsou například typy služeb, typy balíků, hmotnostní limity atd., protože u nich dochází ke změnám.

Zpracování chyb

Každá odezva rozhraní API bude obsahovat kód stavu dle protokolu HTTP a přenášený obsah odezvy. Některé odezvy budou případně doprovázeny chybou, varováním nebo poznámkou. Varování a poznámky nejsou známkou selhání; chybová nebo varovná zpráva by však měla být zaznamenána a prošetřena. Řádné vyřešení chyb zajistí, že bude vaše integrace se službami FedEx probíhat hladce a může vám pomoci zabránit poruše.

Stavové kódy protokolu HTTP

Cena

• Existují dva způsoby, jak můžete získat cenovou nabídku:
  
  • Cena za konkrétní typ služby – Výsledky budou filtrovány podle uvedené hodnoty parametru serviceType. Tím se zmenší rozsah odpovědi a zkrátí se doba odezvy transakce.
    

    Příklad: STANDARD_OVERNIGHT

  • Nabídka cen – Pokud není uveden žádný typ služby (parametr serviceType), budou vráceny všechny relevantní služby a odpovídající ceny.
• Pomocí rozhraní API Service Availability (Dostupnost služeb) určete, které služby, typy balíků a speciální služby jsou k dispozici pro daný pár místa odeslání a místa určení, a předejte parametr serviceType a typ balíku do požadavku API rozhraní Rate (Cena).
  

  Například (mimo jiné) STANDARD_OVERNIGHT (Standardní, přes noc) není k dispozici mezi všemi poštovními směrovacími čísly.

• Aby mohla být pro zásilku použita speciální služba, je nutné zařadit tento zvláštní typ služby a podrobnosti o ní. 
  
  • Poznámka: Některé speciální služby neobsahují podrobnosti.
• Prohlédněte si dokumentaci k API rozhraní Rate (Cena).

Odeslat

• Pomocí API rozhraní Service Availability (Dostupnost služeb) určete, které služby jsou k dispozici pro daný pár místa odeslání a místa určení, a předejte parametr serviceType a typ balíku do požadavku API rozhraní Ship (Zásilka).
• Aby mohla být pro zásilku použita speciální služba, je nutné zařadit tento zvláštní typ služby a podrobnosti o ní.
  
  • Poznámka: Některé speciální služby neobsahují podrobnosti.
• Na konci přepravního dne před vyzvednutím zásilky proveďte uzávěrku FedEx Ground.
  
• Prohlédněte si dokumentaci k API rozhraní Ship (Zásilka).
  

Sledování

• Omezte počet sledovacích čísel v požadavku na jedno sledování na 30. Tím se sníží rozsah odezvy a zkrátí se doba odezvy transakce.
• Omezte počet jednotlivých případů sledování balíku na takový počet, který je nezbytný z hlediska vašich firemních potřeb.
• Při hromadném sledování odeberte z dávky všechny balíky, u kterých byl oznámen stav sledování „doručeno“.
• Prohlédněte si dokumentaci k rozhraní API pro sledování.

Ověření adresy

• Společnost FedEx poskytuje ověření adresy jako podnět, nikoli jako konečné určení. Koncový uživatel musí na základě poskytnutých údajů a svých firemních potřeb učinit finální rozhodnutí, zda je adresa použitelná. Musí být zaveden proces pro zpracování adres, které nelze ověřit, aby bylo možné objednávky i přesto zpracovat.
• Chcete-li zajistit lepší praxi přepravy, nepodmiňujte proces přepravy volitelnými službami, jako je například ověření adresy.

Pokud například v okamžiku zadání objednávky nebo odeslání není k dispozici API rozhraní Address Validation (Ověření adresy), měl by být pro uskuteční přepravy použit pohotovostní plán.

• Prohlédněte si dokumentaci k API rozhraní Address Validation (Ověření adresy).
  

Vyhledání provozoven FedEx

• Zužte vyhledávání uvedením konkrétních atributů (tj. typ provozovny, nabízené služby atd.), abyste získali vhodné volby provozoven a rychlejší dobu odezvy.
• Prohlédněte si dokumentaci API rozhraní FedEx Locations Search (Vyhledání provozoven FedEx).

Požadavek na vyzvednutí

• Pro naplánování vyzvednutí nezadávejte čas v minulosti, datum v minulosti nebo datum, které je v příliš vzdálené budoucnosti.
• Anonymní vyzvednutí není povoleno.
  
• Prohlédněte si dokumentaci k API rozhraní Pickup Request (Požadavek na vyzvednutí).
  

Dostupnost služby

• Chcete-li získat výsledky pro více provozních společností, například FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) a FedEx Ground® Economy, vynechejte prvek carrierCodes nebo odešlete samostatné požadavky na dostupnost služby, protože není možné uvést více kódů přepravce.
• Ujistěte se, že máte předběžný souhlas pro jednotlivé palety o hmotnosti 68,5 kg nebo více a palety, jejichž hmotnost překračuje 1000 kg.
  
• Pokud v rámci nastavitelných možností zvolíte službu SATURDAY_DELIVERY (Dodání v sobotu), získáte jak možnost doručení v sobotu, tak i možnost standardního doručení pro všechny služby, kde je použita volba dodání v sobotu. Službu SATURDAY_DELIVERY (Dodání v sobotu) nezadávejte pro speciální služby, jinak budou v odezvě uvedeny pouze příslušné možnosti doručení v sobotu.
• Prohlédněte si dokumentaci k API rozhraní Service Availability (Dostupnost služby).

Zákaznická podpora

Pokud máte nějaké dotazy nebo potřebujete pomoci, jsme tu, abychom vám pomohli! Prostředky a informace o tom, jak nás můžete kontaktovat, naleznete na stránce Podpora.