info-icon


MAIN MENU

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 1400 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 1400 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.
  • Kromě toho doporučujeme, abyste se v zájmu zajištění flexibility a budoucí bezproblémovosti vyhnuli pevnému kódování konkrétních výčtových hodnot v odpovědích rozhraní API, protože tyto hodnoty se mohou v průběhu času měnit. Místo toho implementujte dynamickou logiku, která dokáže zpracovat nové nebo neočekávané hodnoty, jakmile se objeví.

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

200 OK 
Váš požadavek byl úspěšně zpracován. Toto je standardní odpověď na úspěšný požadavek protokolu HTTP.

  • Poznámka: Odpověď rozhraní API může obsahovat poznámky a varování poskytující informativní obsah. Zprávy zaznamenejte a proveďte jejich analýzu.

400 Špatný požadavek
Obdrželi jsme špatný požadavek, který nejsme schopni zpracovat. Upravte svůj požadavek a zkuste to znovu.

  • Poznámka: Na základě kódu chyby a zprávy upravte požadavek a opakujte postup znovu. Do zdrojového kódu kódujte pouze kódy chyb, protože u zpráv dochází k dynamickým změnám.

401 Neautorizováno
Nepodařilo se nám potvrdit pravost vašich přihlašovacích údajů. Nezapomeňte zkontrolovat klíče API a zkuste to znovu.

403 Zakázáno
Nepodařilo se nám potvrdit pravost vašich přihlašovacích údajů. Zkontrolujte svá oprávnění a zkuste to znovu.

404 Nenalezeno
Zdroj, který požadujete, již není dostupný. Upravte svůj požadavek a zkuste to znovu.

405 Metoda není povolena
Obdrželi jsme požadavek na metodu, která není podporována. Smíte používat pouze metody poskytované pro každý koncový bod.

Chcete-li například vytvořit zásilku, musíte použít metodu POST, jak je popsáno v dokumentaci k rozhraní API.

409 Konflikt
{provide reason of conflict}. Upravte svůj požadavek a zkuste to znovu.

415 Nepodporovaný typ média
Nepodporujeme typ obsahu ve vašem požadavku. Upravte formát a zkuste to znovu.

422 Nezpracovatelná entita
Porozuměli jsme formátu vašeho požadavku, ale nebyli jsme schopni entitu zpracovat. Upravte svůj požadavek a zkuste to znovu.

429 Příliš mnoho požadavků
V krátkém čase jsme obdrželi jsme příliš mnoho požadavků. Zkontrolujte kvóty transakcí a limity sazeb.

500 Chyba
Objevili jsme neočekávanou chybu. Pracujeme na vyřešení tohoto problému. Omlouváme se za případné potíže. Vraťte se později a věnujte pozornost jakékoliv komunikaci ze strany společnosti FedEx.

503 Služba není dostupná
Služba není momentálně k dispozici. Pracujeme na vyřešení tohoto problému. Omlouváme se za případné potíže. Vraťte se později a věnujte pozornost jakékoliv komunikaci ze strany společnosti FedEx.

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“.
  • FedEx opakovaně používá sledovací čísla zásilek. Abyste se vyhnuli duplicitním výsledkům, zadejte rozsah dat.
  • Prohlédněte si dokumentaci k rozhraní API Basic Integrated Visibility.

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í

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.