Sprawdzone metody integracji interfejsów API FedEx

To jest skrócona instrukcja mająca na celu ułatwienie użytkownikom interfejsu API zrozumienie sposobu integracji z FedEx i zapewnienia jakości rozwiązania integracji pod względem projektu, szybkości i bezpieczeństwa.

W celu efektywnej integracji z interfejsami API FedEx programiści powinni stosować następujące sprawdzone metody integracji:

Identyfikatory URI interfejsów API

• Istnieją oddzielne identyfikatory URI interfejsów API do celów testowych i produkcyjnych. 
• Programiści powinni używać testowych identyfikatorów URI do programowania i testowania integracji, a produkcyjnych identyfikatorów URI w środowisku produkcyjnym.

Oto lista identyfikatorów URI interfejsów API:

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

Produkcja: https://apis.fedex.com/

Zarządzanie poświadczeniami

• Klucz interfejsu API i klucz tajny

• Klucz interfejsu API i klucz tajny służą do identyfikacji aplikacji użytkownika i muszą być używane w żądaniu tokena OAuth.

1. Należy zachować poufność klucza interfejsu API i klucza tajnego. Nie należy udostępniać klucza interfejsu API ani klucza tajnego pocztą e-mail ani w rozpowszechnianym kodzie, w tym w kodzie JavaScript wykonywanym po stronie klienta.
2. Kradzież klucza interfejsu API lub klucza tajnego będzie stanowić naruszenie bezpieczeństwa aplikacji. Jeśli podejrzewasz, że poświadczenia zostały skradzione lub ujawnione, niezwłocznie utwórz ponownie klucz tajny.
3. Unikaj rejestrowania w dziennikach poufnych informacji, takich jak klucz tajny.

• Nie umieszczaj w kodzie klucza interfejsu API ani klucza tajnego.
• Aplikacja powinna mieć możliwość dynamicznego aktualizowania klucza interfejsu API i klucza tajnego.
• Poświadczenia klienta powinny być przechowywane w magazynie/bezpiecznym miejscu, aby ich bezpieczeństwo nie zostało naruszone.

• Token OAuth

• Token dostępu powinien być przechowywany na serwerze aplikacji internetowej i nie może być ujawniony przeglądarce.
• Nie należy umieszczać tokena w kodzie aplikacji.
• Należy zabezpieczyć tokeny dostępu, aby zapobiec naruszeniu ich bezpieczeństwa.
• Należy unikać wykonywania wielu wywołań interfejsu API tokena OAuth w celu uzyskania nowego tokena dostępu. Zalecane jest przechowywanie tokena dostępu w pamięci podręcznej do czasu napotkania kodu błędu 401 protokołu HTTP. W takim przypadku należy ponownie wygenerować token OAuth.
• Nie należy ujawniać tokena użytkownikowi końcowemu ani aplikacji.
• Każda transakcja interfejsu API powinna być wykonywana za pośrednictwem protokołu HTTPS.

Metody programowania

• W celu zachowania zgodności z najnowszym i najbezpieczniejszym protokołem komunikacyjnym szyfrowania danych zalecane jest użycie protokołu TLS (Transport Layer Security) w wersji 1.2 lub wyższej.
• Należy ustawić prawidłowe nagłówki interfejsu API wymagane dla poszczególnych żądań interfejsu API. Informacje dotyczące nagłówka można znaleźć na stronie dokumentacji interfejsu API. 
• Dla właściwości „Content-Type” metody HTTP POST należy ustawić wartość „application/json”.
• Zapoznaj się z przykładowym kodem, aby rozpocząć korzystanie z poszczególnych interfejsów API. Dla każdego punktu końcowego interfejsu API przedstawiono kilka przykładów, które pomogą zrozumieć wymagane elementy, formaty i inne szczegóły.
• Wysyłanie wielu liczb dziesiętnych w wartościach przez użytkowników lub programistów może powodować nieoczekiwane błędy. W przypadku wagi i waluty/kwoty dozwolone są tylko dwa miejsca po przecinku. Liczby dziesiętne nie są obsługiwane w wartościach wymiarów, takich jak długość, szerokość i wysokość.

Przykład: waga: 45,26, waluta/kwota: 100,52, długość: 10, szerokość: 25, wysokość: 15.

• Należy unikać wysyłania pustych elementów.

Przykład: “Linie ulic”:””

• Należy wysyłać tylko dane niezbędne do przetworzenia żądania.

Na przykład w przypadku przesyłek krajowych na terenie USA należy unikać wysyłania danych faktur handlowych i towarów, które mogą być wymagane tylko w przypadku przesyłek międzynarodowych.

• Podczas programowania należy określić sposób reakcji w przypadku niezwrócenia niewymaganego elementu odpowiedzi, takiego jak stawka. Przed użyciem danych należy ocenić odpowiedź transakcji pod względem brakujących elementów.

Na przykład: czy możliwa jest wysyłka paczki bez prawidłowej stawki. Przed użyciem danych należy ocenić odpowiedź transakcji pod względem brakujących elementów.

• Ogólnie należy unikać sztywnych zależności od integracji interfejsu API FedEx, jeśli ma to zastosowanie.
• Aby ograniczyć opóźnienia i uzyskać dokładne wyniki, użyj poniższych technik:
  
  • Filtrowanie — należy zastosować filtrowanie w celu zawężenia wyszukiwania żądanych parametrów.
  • Sortowanie — należy użyć tej metody, aby sortować wyniki według określonego parametru w porządku rosnącym lub malejącym.
• Przed wysłaniem transakcji należy zweryfikować, czy wymagane pola, takie jak kod pocztowy odbiorcy i waga paczki, zawierają dane. Należy zweryfikować, czy dane są prawidłowe dla określonego pola. Ograniczy to liczbę błędów transakcji.
  

Na przykład w przypadku kodów pocztowych USA należy zweryfikować, czy pole zawiera jedynie cyfry, a kod pocztowy ma format 5-cyfrowy lub ZIP+4.

• Aby uniknąć negatywnego wpływu na dostępność i niezawodność systemu FedEx:
  
  • Nie należy uruchamiać testów wydajności w środowisku testowym ani produkcyjnym.
  • Należy zastosować logikę zapobiegającą wielokrotnemu uruchamianiu transakcji, które kończą się niepowodzeniem.
• Limit przepustowości ustawiono na 1400 transakcji w ciągu 10 sekund. W przypadku osiągnięcia tego limitu w ciągu kilku pierwszych sekund zostanie zwrócony kod błędu protokołu HTTP 429 Zbyt wiele żądań i transakcje zostaną ograniczone do upływu 10 sekund. Następnie transakcje zostaną wznowione.
  

Jeśli na przykład w pierwszych czterech sekundach otrzymamy 1400 żądań, zostanie zwrócony kod błędu protokołu HTTP 429 Zbyt wiele żądań — „Otrzymaliśmy zbyt wiele żądań w krótkim czasie. Zaczekaj chwilę i spróbuj ponownie.”, a transakcje będą ograniczone przez kolejne sześć sekund, po czym zostaną wznowione.

• Nie należy umieszczać w kodzie reguł biznesowych, takich jak rodzaje usług, rodzaje przesyłek, dopuszczalna waga itd. dla przesyłek, ponieważ mogą one ulegać zmianie.

Obsługa błędów

Każda odpowiedź interfejsu API będzie zawierać kod stanu HTTP i ładunek odpowiedzi. Niektóre odpowiedzi będą zawierać odpowiednio błąd, ostrzeżenie lub uwagę. Ostrzeżenia i uwagi nie oznaczają niepowodzenia, jednak komunikaty o błędach lub ostrzeżeniach należy rejestrować w dzienniku i analizować. Prawidłowa obsługa błędów zapewni bezproblemowe działanie integracji z systemem FedEx i może zapobiec awariom.

Kody stanu protokołu HTTP

Stawka

• Istnieją dwa sposoby pobierania ofert stawek:
  
  • Stawka dla określonej wartości rodzaju usługi (serviceType) — wyniki będą filtrowane według określonej wartości serviceType. Zmniejszy to rozmiar odpowiedzi i skróci czas odpowiedzi transakcji.
    

    Przykład: STANDARD_OVERNIGHT

  • Dostępne stawki — jeśli nie określono wartości serviceType, zostaną zwrócone wszystkie dostępne usługi i odpowiadające im stawki.
• Użyj interfejsu API dostępności usług, aby określić, które usługi, opcje przesyłek i usługi specjalne są dostępne dla danej pary miejsc pochodzenia i przeznaczenia, a następnie przekaż wartość serviceType i opcję przesyłki w żądaniu stawki.
  

  Na przykład usługa STANDARD_OVERNIGHT (między innymi) nie jest dostępna dla wszystkich kodów pocztowych.

• Aby zastosować usługę specjalną dla przesyłki, należy dołączyć rodzaj usługi specjalnej i jej szczegóły. 
  
  • Uwaga: niektóre usługi specjalne nie mają szczegółów.
• Wyświetl dokumentację interfejsu API stawki.

Wysyłka

• Użyj interfejsu API dostępności usług, aby określić, które usługi są dostępne dla danej pary miejsc pochodzenia i przeznaczenia, a następnie przekaż wartość serviceType i opcję przesyłki w żądaniu wysyłki.
• Aby zastosować usługę specjalną dla przesyłki, należy dołączyć rodzaj usługi specjalnej i jej szczegóły.
  
  • Uwaga: niektóre usługi specjalne nie mają szczegółów.
• Wykonaj zamknięcie FedEx Ground po zakończeniu dnia wysyłki przed odbiorem przesyłki.
  
• Wyświetl dokumentację interfejsu API wysyłki.
  

Śledzenie

• Ogranicz liczbę numerów śledzenia w pojedynczym żądaniu śledzenia do 30. Zmniejszy to rozmiar odpowiedzi i skróci czas odpowiedzi transakcji.
• Ogranicz liczbę żądań śledzenia do niezbędnej dla działania firmy.
• W przypadku śledzenia zbiorczego usuń z partii przesyłki, dla których zwrócono status „dostarczono”.
• Wyświetl dokumentację interfejsu API śledzenia.

Weryfikacja adresu

• FedEx zapewnia funkcję weryfikacji adresu jako sugestię, która nie stanowi ostatecznego ustalenia. Użytkownik końcowy musi ostatecznie ustalić, czy adres jest prawidłowy, na podstawie podanych danych i potrzeb biznesowych. Należy zastosować proces obsługi adresów, których nie można zweryfikować, aby umożliwić kontynuowanie przetwarzania zamówień.
• Aby zapewnić lepszą obsługę przesyłek, nie należy uzależniać procesu wysyłki od usług opcjonalnych, takich jak weryfikacja adresu.

Jeśli na przykład interfejs API weryfikacji adresów jest niedostępny podczas wprowadzania zamówienia lub wysyłki, należy zapewnić rozwiązanie awaryjne umożliwiające ukończenie wysyłki.

• Wyświetl dokumentację interfejsu API weryfikacji adresów.
  

Wyszukiwanie placówek FedEx

• Zawęź wyszukiwanie, podając określone atrybuty (tj. typ placówki, oferowane usługi itd.), aby uzyskać odpowiednie opcje placówki i krótszy czas odpowiedzi.
• Wyświetl dokumentację interfejsu API wyszukiwania placówek FedEx.
  

Żądanie odbioru

• Nie wprowadzaj przeszłego czasu gotowości, przeszłej daty ani daty w zbyt odległej przyszłości podczas planowania odbioru.
• Odbiór anonimowy jest niedozwolony.
  
• Wyświetl dokumentację interfejsu API żądania odbioru.
  

Dostępność usług

• Aby uzyskać wyniki z wielu jednostek biznesowych, takich jak FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) i FedEx Ground® Economy, pomiń element carrierCodes lub wyślij oddzielne żądania dostępności usług, ponieważ nie można określić wielu kodów przewoźników.
• Upewnij się, że masz wstępną zgodę na indywidualne palety o masie 151 funtów lub więcej oraz palety o masie większej niż 2200 funtów.
  
• W przypadku określenia parametru SATURDAY_DELIVERY dla różnych opcji, zostaną zwrócone opcje doręczenia w sobotę oraz opcje zwykły przesyłek dla usług, dla których doręczenie w sobotę jest dostępne jako opcja. Nie należy określać parametru SATURDAY_DELIVERY dla usług specjalnych, ponieważ spowoduje to zwrócenie tylko dostępnych opcji doręczenia w sobotę.
• Wyświetl dokumentację interfejsu API dostępności usług.

Obsługa klienta

Jeśli masz pytania lub potrzebujesz pomocy, skontaktuj się z nami. Odwiedź stronę Wsparcie, aby uzyskać informacje dotyczące metod kontaktu z nami.