Wprowadzenie
FedEx Developer Portal oferuje zestaw interfejsów programowania aplikacji (API) umożliwiających integrację usług FedEx z Twoimi aplikacjami. Poniższe instrukcje pomogą Ci skonfigurować organizację, utworzyć projekt, przetestować integrację, przenieść projekt do środowiska produkcyjnego, a w niektórych przypadkach również zweryfikować interfejs API.
Typy użytkowników:
FedEx oferuje usługi integracji dla trzech typów użytkowników: nadawców FedEx, zweryfikowanych dostawców oprogramowania zwanych dostawcami FedEx Compatible oraz dostawców spoza programu FedEx Compatible.
Nadawca FedEx:
Firma korzystająca z usług wysyłkowych FedEx i potrzebująca integracji interfejsów API FedEx z własnym systemem.
Dostawca rozwiązań lub usług:
Firma potrzebująca integracji z interfejsami API FedEx w celu stworzenia rozwiązania, aplikacji lub wtyczki, która może zostać sprzedana i/lub przekazana zewnętrznej organizacji korzystającej z usług FedEx. Sprawdź, czy Twoja firma jest zweryfikowanym dostawcą FedEx, przeszukując nasz globalny katalog.
- Dostawca FedEx Compatible: zweryfikowana firma, która zawarła umowę w ramach programu FedEx Compatible.
- Dostawca spoza programu FedEx Compatible: rozwiązanie lub usługa niepoddana weryfikacji w ramach programu FedEx Compatible.
Spośród poniższych wybierz opcję, która najlepiej opisuje Twoją firmę. Niezależnie od typu użytkownika dostępna jest instrukcja wprowadzająca.
Wybierz, aby rozpocząć.
Which of the following best describes your business?
Select user
- Nadawca FedEx: Firma, która integruje interfejsy API FedEx ze swoimi własnymi aplikacjami.
- Dostawca FedEx Compatible: Firma zweryfikowana w programie FedEx Compatible, która dokonuje integracji z interfejsami API FedEx, aby zbudować rozwiązanie, aplikację lub wtyczkę, które można sprzedawać lub przekazywać organizacji zewnętrznej.
- Dostawca spoza programu Compatible: Firma, która dokonuje integracji z interfejsami API FedEx, aby zbudować rozwiązanie, aplikację lub wtyczkę, które można sprzedawać lub przekazywać organizacji zewnętrznej.
Wymaganie wstępne
Aby zalogować się do portalu FedEx Developer Portal i utworzyć organizację trzeba mieć identyfikator użytkownika FedEx.
Utwórz organizację, jeśli Twoja firma jej jeszcze nie ma, lub dołącz do istniejącej organizacji.
Tworzenie nowej organizacji
Aby utworzyć własną organizację, kliknij opcję Utwórz organizację w lewym panelu nawigacyjnym. W przypadku utworzenia nowej organizacji automatycznie zostajesz jej administratorem.
- Administrator może zapraszać użytkowników do dołączenia do organizacji, przypisywać im role (np. współautor lub przeglądający) i projekty oraz zarządzać kontami wysyłkowymi.
- Więcej na temat tych ról znajdziesz w wytycznych administrowania organizacją.
Informacje o organizacji
Wprowadź nazwę swojej firmy, adres URL strony internetowej i utwórz nazwę organizacji. Nadaj swojej organizacji nazwę, która będzie rozpoznawalna dla innych użytkowników. Nazwa ta może posłużyć do utworzenia bardziej określonych grup w Twojej firmie (np. dział, oddział, region, lokalizacja) lub może być taka sama jak nazwa Twojej firmy.
Po utworzeniu organizacji możesz, jako jej administrator, kliknąć opcję Zarządzaj organizacją w lewym panelu nawigacyjnym, aby wprowadzić więcej szczegółów.
Dodaj konto wysyłkowe
Otwórz kartę Konta wysyłkowe. Kliknij przycisk Dodaj konto.
- Wprowadź numer konta FedEx, nazwę skrótową konta oraz adres rozliczeniowy powiązany z kontem. Aby zapobiec nieuczciwym działaniom, adres rozliczeniowy zostanie zweryfikowany w celu upewnienia się, że jest zgodny z danymi konta. Jeśli nie masz jeszcze konta FedEx, załóż nowe konto lub skontaktuj się z przedstawicielem obsługi klienta FedEx.
- Zaakceptuj umowę licencyjną użytkownika końcowego lub prześlij ją do osoby upoważnionej do jej zaakceptowania w imieniu firmy.
Dodanie konta rozliczeniowego
Otwórz kartę Konta rozliczeniowe. Kliknij przycisk Dodaj konto rozliczeniowe do organizacji.
- Wprowadź numer konta FedEx, nazwę skrótową konta oraz adres rozliczeniowy na terenie Stanów Zjednoczonych powiązany z kontem. Aby zapobiec nieuczciwym działaniom, adres rozliczeniowy zostanie zweryfikowany w celu upewnienia się, że jest zgodny z danymi konta. Jeśli nie masz jeszcze konta FedEx, załóż nowe konto lub skontaktuj się z przedstawicielem obsługi klienta FedEx. Konta rozliczeniowe muszą być zarejestrowane w Stanach Zjednoczonych.
- Zaakceptuj umowę licencyjną użytkownika końcowego lub prześlij ją do osoby upoważnionej do jej zaakceptowania w imieniu firmy.
Zaproś użytkowników
Administrator może zapraszać użytkowników do organizacji oraz przypisywać im role i projekty. Otwórz kartę Użytkownicy. Kliknij przycisk Dodaj użytkowników.
- Wybierz rolę użytkownika: przeglądający, współautor lub administrator.
- Jeśli już masz utworzone projekty, przypisz projekt do użytkownika. Użytkowników możesz również przypisywać do projektów z poziomu dowolnej strony Przegląd projektu.
- Wprowadź adresy e-mail użytkowników, których chcesz dodać do swojej organizacji w ramach wybranej roli.
Dołączanie do istniejącej organizacji
Krok 1. Poproś administratora organizacji, aby przesłał Ci zaproszenie.
Jeśli dla Twojej firmy utworzono już organizację, poproś administratora tej organizacji, aby zaprosił Cię do niej. Będziesz mieć 24 godziny na zaakceptowanie zaproszenia. Jeśli przegapisz ten termin, zawsze możesz poprosić o ponowne wysłanie.
Krok 2. Zaakceptuj zaproszenie.
Aby zaakceptować zaproszenie, musisz zalogować się przy użyciu istniejącego identyfikatora użytkownika i hasła lub utworzyć nowy identyfikator, jeśli istniejący jest już powiązany z organizacją.
Utwórz projekt API
Na stronie Moje projekty otwórz kartę Interfejsy API. Kliknij przycisk Utwórz projekt API.
Krok 1. Wybierz interfejsy API, które chcesz dodać do projektu
Zapoznaj się z limitami i ograniczeniami interfejsu API oraz szczegółami weryfikacji interfejsów API.
Krok 2. Skonfiguruj szczegóły projektu
- Nadaj projektowi rozpoznawalną nazwę, która nie powtarza się w obrębie organizacji.
- Wybierz kraje, w granicach których zamierzasz dokonywać wysyłek, abyśmy mogli przypisać Ci testowe konto wysyłkowe. Aby przetestować krajową wysyłkę paczek w kraju europejskim, musisz mieć osobne konto testowe dla każdego kraju. Kraje możesz dodawać/usuwać później.
- Aby otrzymywać powiadomienia o najnowszych aktualizacjach dotyczących interfejsów API i informacje o przerwach w działaniu, ustaw preferencje dotyczące powiadomień.
Krok 3. Przeczytaj ze zrozumieniem i zaakceptuj umowę licencyjną FedEx Developer Portal
Po zaakceptowaniu warunków i kliknięciu przycisku Utwórz zobaczysz ekran potwierdzenia. Możesz teraz wyświetlić poświadczenia testowe dla nowego projektu.
Utwórz projekt elementu webhook
Wymagane składniki
- Przejrzyj wycenę: subskrybenci są obciążani miesięczną opłatą zależną od liczby numerów przesyłek. Zapoznaj się z Przewodnikiem po wycenie, aby dowiedzieć się więcej o wycenie.
- Konfigurowanie kont: element webhook Advanced Integrated Visibility wymaga konta rozliczeniowego w Stanach Zjednoczonych oraz co najmniej jednego konta wysyłkowego. Te dwa typy kont są wzajemnie rozłączne. Tylko administratorzy mogą dodawać konta rozliczeniowe i wysyłkowe na stronie Zarządzanie organizacją.
Utwórz prawidłowy adres URL (wywołania zwrotnego) w docelowej aplikacji lub platformie
Twój docelowy adres URL będzie używany do odbierania kodów uwierzytelniających i wiadomości, a także powiadomień dotyczących ładunku elementów webhook od firmy FedEx. W celu zapewnienia bezpieczeństwa adres URL musi wykorzystywać protokół HTTPS. Zostaną zablokowane następujące adresy URL:
- Wszystkie w przestrzeni adresowej IP RFC1918.
- Zawierające domenę fedex.com lub dowolne z jej subdomen
- Adresy IP w adresie URL (w tym localhost, 127.0.0.1).
Generowanie tokenu zabezpieczeń
Ten token zabezpieczeń można wykorzystywać jako tajny klucz do uwierzytelniania i weryfikowania informacji przesyłanych między Twoją organizacją a firmą FedEx. Token zabezpieczeń musi zawierać:
- Minimum 26 znaków i maksymalnie 100 znaków
- 1 wielka litera
- 1 mała litera
- 1 cyfra
Przykład: Y1F6OiVUQW2JPSElmRE9U0IY5
Po zdefiniowaniu adresu URL i tokenu zabezpieczeń możesz przystąpić do tworzenia projektu elementu webhook. Na stronie Moje projekty otwórz kartę Elementy webhook. Kliknij przycisk Utwórz projekt elementu webhook.
Wybór typu subskrypcji
Nadawcy FedEx mogą przypisać zdarzenia do numerów kont lub numerów monitorowania.
Krok 1. Potwierdź konto rozliczeniowe i wybierz funkcje
- Sprawdź domyślne konto rozliczeniowe, aby je potwierdzić, lub wybierz inne konto należące do Twojej organizacji.
- Skonfiguruj projekt poprzez wybór funkcji, takich jak opcje potwierdzenia doręczenia, opcje spodziewanego terminu doręczenia, zdarzenia monitorowania czy filtrowanie oparte na zdarzeniach.
Krok 2. Wprowadź szczegóły dotyczące projektu
- Nadaj projektowi rozpoznawalną nazwę, która nie powtarza się w obrębie organizacji.
- Podaj docelowy adres URL i szczegóły tokenu zabezpieczeń utworzone podczas uwierzytelniania przed konfiguracją (patrz kroki powyżej).
- Aby otrzymywać powiadomienia o najnowszych aktualizacjach dotyczących elementów webhook oraz informacje o przerwach w działaniu, ustaw adres e-mail oraz preferowany język.
Krok 3. Przeczytaj i zaakceptuj warunki
Po zaakceptowaniu warunków, w tym umowy licencyjnej FedEx Developer Portal i formularza zamówienia, oraz kliknięciu przycisku Utwórz zobaczysz ekran potwierdzenia.
W zależności od wybranego typu subskrypcji mogą być wymagane dodatkowe kroki. Zajrzyj do dokumentacji, aby dowiedzieć się więcej.
Na stronie Przegląd projektu API pobierz poświadczenia testowe — klucz API, klucz tajny i konta wysyłkowe — z karty Klucz testowy.
Krok 1. Poproś o token dostępu OAuth
Poproś o token dostępu OAuth, który musi być używany z każdą transakcją API. Token jest ważny tylko przez godzinę, więc kod aplikacji musi odświeżać token przed wygaśnięciem sesji. Więcej informacji znajdziesz w dokumentacji autoryzacji interfejsu API.
Krok 2. Przejrzyj dokumentację interfejsów API
Kliknij dokumentację każdego z Twoich interfejsów API, aby zapoznać się z kontekstem biznesowym i zrozumieć, jak korzystać z danego interfejsu API. Zaloguj się, aby pobrać kolekcję JSON API za pomocą przycisku znajdującego się u góry strony dokumentacji. Możesz także przejrzeć przykładowe żądania dla punktu końcowego, który jest zgodny z żądaną integracją.
Krok 3. Użyj piaskownicy do przetestowania przykładowych transakcji
Kliknij żądany punkt końcowy w lewym panelu nawigacyjnym, aby przejść do konkretnej piaskownicy. Zidentyfikuj przykładowe żądania, które odpowiadają Twojemu przypadkowi zastosowania, a następnie użyj swoich poświadczeń testowych oraz testowych adresów URL FedEx do realizacji wywołań do punktu końcowego zgodnie z podanym opisem. Upewnij się, że odebrane odpowiedzi na wywołania interfejsu API są zgodne z tymi podanymi w dokumentacji. Więcej na temat testowania znajdziesz w poradniku wirtualizacji piaskownicy.
Testowanie z elementami webhook
Testowanie może pomóc w ustaleniu, czy utworzony adres URL jest prawidłowy. W ten sposób FedEx może zidentyfikować Twój adres URL i ustanowić z nim połączenie w celu przesłania danych. Testowanie może również zapewnić przykładowe dane testowe, które będą pomocne w sprawdzeniu i potwierdzeniu, czy jesteś w stanie przetwarzać dane monitorowania przekazane w aplikacji. Testowanie nie jest jednak równoznaczne z uwierzytelnieniem adresu URL. Aby dowiedzieć się, w jaki sposób przetestować swój adres URL elementu webhook, zapoznaj się z dokumentacją elementów webhook.
Na stronie Przegląd projektu otwórz kartę Klucz produkcyjny. Projekty związane z subskrypcją opartą na numerze konta funkcji Advanced Integrated Visibility nie muszą być przenoszone do środowiska produkcyjnego.
Krok 1. Skonfiguruj projekt
- W razie potrzeby możesz zmienić nazwę swojego klucza.
- Można sprawdzić numer konta wybrany w kroku 1 procesu tworzenia projektu. Używa się go do przenoszenia projektu do środowiska produkcyjnego. Gdy projekt znajduje się już w środowisku produkcyjnym, można w razie potrzeby dodawać kolejne konta.
Krok 2. Pobierz klucze projektu
Skopiuj klucz produkcyjny interfejsu API i tajny klucz produkcyjny w bezpieczne miejsce. Ze względów bezpieczeństwa tajny klucz produkcyjny wyświetlamy tylko raz. Jeśli go zgubisz, możesz wygenerować nowy.
Po uzyskaniu kluczy projektu i kliknięciu Dalej szczegóły projektu zostaną wyświetlone w karcie Klucz produkcyjny.
- Aby dodać więcej kont wysyłkowych do projektu, kliknij opcję Edytuj u góry tabeli kont wysyłkowych.
Kroki weryfikacji różnią się w różnych regionach
Następujące kroki dotyczą tylko klientów w Stanach Zjednoczonych i Kanadzie. Jeśli mieszkasz w innym kraju, odwiedź stronę Weryfikacja interfejsu API w celu uzyskania wsparcia.
Niektóre interfejsy API wymagają weryfikacji etykiet wysyłkowych, aby można było używać ich w środowisku produkcyjnym. Sprawdź, czy Twój interfejs API wymaga weryfikacji.
Krok 1. Opracuj aplikację internetową i przetestuj ją z interfejsami API FedEx
Po opracowywaniu aplikacji internetowej sfinalizuj testowanie przy użyciu poświadczeń testowych (testowych kont wysyłkowych, klucza API i klucza tajnego). Testowy klucz API i klucz tajny zostaną wyświetlone na stronie Przegląd projektu i będą dostępne w dowolnym momencie.
Krok 2. Przenieś projekt do środowiska produkcyjnego
Po przetestowaniu z interfejsami API FedEx musisz rozpocząć proces weryfikacji, przenosząc projekt do środowiska produkcyjnego w portalu FedEx Developer Portal. Po pomyślnym zakończeniu tego procesu zostaną wyświetlone produkcyjny klucz API i klucz tajny. Produkcyjny klucz tajny zostanie wyświetlony tylko raz, ale będziesz w stanie wygenerować go ponownie później.
Krok 3. Wypełnij stronę tytułową etykiety
Wypełnij wszystkie pola na stronie tytułowej etykiety, podając odpowiednie dane kontaktowe oraz usługi, które planujesz wdrożyć. Podaj numer konta i klucz produkcyjny.
Krok 4. Wygeneruj i prześlij etykiety testowe do grupy ds. analizy kodów kreskowych
Wygeneruj etykiety testowe w środowisku testowym FedEx powiązanym z aplikacją, a następnie prześlij etykiety testowe do zespołów ds. oceny etykiet FedEx w celu zatwierdzenia. Grupa ds. analizy kodów kreskowych potrzebuje trzech dni roboczych na ocenę etykiety.
Aby uniknąć opóźnień w przetwarzaniu, przestrzegaj następujących dobrych praktyk:
- Etykiety muszą być drukowane i skanowane w rozdzielczości co najmniej 600 DPI. NIE WYSYŁAJ PLIKÓW WYGENEROWANYCH PRZEZ INTERFEJS API.
- W przypadku drukarek termicznych typ obrazu etykiety należy zamówić zgodnie z modelem drukarki. Przykład: ZPLII w przypadku drukarek Zebra.
- Podczas tworzenia przykładowych etykiet do oceny użyj informacji o adresie nadawcy/odbiorcy. Twórz przykładowe etykiety tylko dla konkretnych usług, do których będą stosowane.
- Etykieta płatności przy odbiorze FedEx® musi zawierać też odpowiednią etykietę zwrotną płatności przy odbiorze.
- Przesyłki FedEx International Express® muszą zawierać też dodatkową/pomocniczą etykietę lotniczego listu przewozowego.
- Przesyłki wieloczęściowe (MPS) muszą zawierać po jednej etykiecie dla każdej paczki w przesyłce.
- Wyślij plik PDF i stronę tytułową etykiety na adres: label@fedex.com.
- Etykiety fizyczne można wysyłać na poniższy adres:
FedEx Services
WTC-Business Solutions Testing
10 FedEx Parkway
2nd Floor Horizontal
Collierville, TN 38017, USA
Jeśli zeskanowane etykiety nie mają widocznych defektów (takich jak linie przechodzące przez kod kreskowy, plamy tuszu czy uszkodzenia fizyczne), przejdą kontrolę i uzyskają zatwierdzenie.
Wysyłając etykiety fizyczne, zwróć uwagę na jakość wydruku i przypadkowe powiększenie/skurczenie etykiet (tj. skalowanie). Są to dwa główne powody, dla których etykiety nie przechodzą pomyślnie procesu oceny.
Krok 5. Sprawdź ocenę etykiety
Grupa ds. analizy kodów kreskowych oceni przesłane etykiety testowe i zatwierdzi je lub odrzuci. Grupa ds. analizy kodów kreskowych skontaktuje się z Tobą w sprawie zatwierdzenia lub odrzucenia przesłanych etykiet. Jeśli etykiety zostały zatwierdzone, przejdź do następnego kroku. Jeśli etykiety zostały odrzucone, popraw je zgodnie z instrukcją i prześlij ponownie do zatwierdzenia.
Krok 6. Włącz aplikację
Po zatwierdzeniu etykiet testowych do statusu produkcyjnego grupa ds. analizy kodów kreskowych autoryzuje Twoje poświadczenia produkcyjne do przesyłania zidentyfikowanej transakcji etykiet wysyłkowych i powiadomi Cię za pomocą wiadomości e-mail o pomyślnej weryfikacji. Zatwierdzenia są udzielane dla poszczególnych projektów.
Krok 7. Zamień adres URL i poświadczenia
Zamień testowy adres URL i poświadczenia testowe na produkcyjny adres URL i poświadczenia produkcyjne. Ponownie przetestuj wdrożenie w środowisku produkcyjnym, używając przykładowych danych.
Wymaganie wstępne
Twoja firma musi być istniejącym dostawcą FedEx Compatible. Jeśli Twoja firma nie uczestniczy w programie Compatible, zmień powyższy wybór na „Dostawca spoza programu Compatible”.
Krok 1. Odbierz zaproszenie do dołączenia do organizacji
FedEx utworzy organizację, a następnie zaprosi jednego członka zespołu do dołączenia do niej. Ten użytkownik zostanie wyznaczony jako administrator w tej organizacji.
Krok 2. Zaakceptuj zaproszenie
Aby zaakceptować zaproszenie, musisz zalogować się przy użyciu istniejącego identyfikatora użytkownika i hasła lub utworzyć nowy identyfikator, jeśli istniejący jest już powiązany z organizacją.
Krok 3. Zaproś użytkowników
Administrator może zapraszać użytkowników do organizacji oraz przypisywać im role i projekty. Otwórz zakładkę Użytkownicy. Kliknij przycisk Dodaj użytkowników.
- Wybierz rolę użytkownika: przeglądający, współautor lub administrator. Więcej o tych rolach znajdziesz w wytycznych administrowania organizacją.
- Jeśli już masz utworzone projekty, przypisz projekt do użytkownika. Użytkowników możesz również przypisywać do projektów z poziomu dowolnej strony Przegląd projektu.
- Wprowadź adresy e-mail użytkowników, których chcesz dodać do swojej organizacji w ramach wybranej roli.
Przejdź do Katalogu interfejsów API, aby wybrać odpowiednie interfejsy API lub elementy webhook dla swojego rozwiązania. Twój doradca klienta ds. technologii FedEx (CTC) i kierownik ds. kanału Compatible mogą pomóc w wyborze odpowiednich interfejsów API dla rozwiązania zgodnie z potrzebami biznesowymi.
Krok 1. Wypełnij arkusz PIW
Wróć do społeczności dostawców FedEx Compatible (CPC), aby wypełnić arkusz informacji o produkcie (PIW).
Krok 2. Przejrzyj projekty utworzone przez FedEx
Po zatwierdzeniu arkusza PIW FedEx utworzy Twoje projekty. Każda wersja każdego z Twoich rozwiązań będzie mieć osobny projekt w ramach FedEx Developer Portal.
Krok 3. Weź udział w pokazie technicznym interfejsu API wraz ze swoim zespołem
Zespół FedEx Compatible wraz z zespołem FedEx CTC i zespołami ds. weryfikacji zorganizuje pokaz techniczny dotyczący interfejsów API we współpracy z Twoim zespołem. Zespół FedEx omówi procedurę weryfikacji programu FedEx Compatible, nowe funkcje i możliwości interfejsu API oraz odpowie na pytania.
Na stronie Przegląd projektu API pobierz poświadczenia testowe — klucz API i klucz tajny — z karty Klucz testowy.
Krok 1. Utwórz klucze klienta
Użyj interfejsu API rejestracji poświadczeń do utworzenia kluczy klienta. Jest to prywatny interfejs API, który można znaleźć wyłącznie w sekcji API na dole strony Przegląd projektu API.
Krok 2. Poproś o token dostępu OAuth
Poproś o token dostępu OAuth, który musi być używany z każdą transakcją API. Token jest ważny tylko przez godzinę, więc kod aplikacji musi odświeżać token przed wygaśnięciem sesji. Więcej informacji znajdziesz w dokumentacji autoryzacji interfejsu API. Przeglądając przykładowy kod, upewnij się, że z listy rozwijanej przykładów wybrano opcję „Reseller” (Sprzedawca).
Krok 3. Przejrzyj dokumentację interfejsu API
Kliknij dokumentację każdego z Twoich interfejsów API, aby zapoznać się z kontekstem biznesowym i zrozumieć, jak korzystać z danego interfejsu API. Zaloguj się, aby pobrać kolekcję JSON API za pomocą przycisku znajdującego się u góry strony dokumentacji. Możesz także przejrzeć przykładowe żądania dla punktu końcowego, który jest zgodny z żądaną integracją.
Krok 4. Użyj piaskownicy do przetestowania przykładowych transakcji
Kliknij żądany punkt końcowy w lewym panelu nawigacyjnym, aby przejść do konkretnej piaskownicy. Zidentyfikuj przykładowe żądania, które odpowiadają Twojemu przypadkowi zastosowania, a następnie użyj swoich poświadczeń testowych oraz testowych adresów URL FedEx do realizacji wywołań do punktu końcowego zgodnie z podanym opisem. Upewnij się, że odebrane odpowiedzi na wywołania interfejsu API są zgodne z tymi podanymi w dokumentacji. Więcej na temat testowania znajdziesz w poradniku wirtualizacji piaskownicy.
Krok 5. Sprawdź każde rozwiązanie
Po pełnym przetestowaniu rozwiązań prześlij przypadki testowe do zespołu ds. weryfikacji. FedEx w pełni sprawdzi wszystkie przesłane dane i poinformuje Cię o wyniku weryfikacji.
Testowanie z elementami webhook
Jeśli Twoja organizacja ma dostęp do elementów webhook, testowanie może pomóc w ustaleniu, czy utworzony adres URL jest prawidłowy. W ten sposób FedEx może zidentyfikować Twój adres URL i ustanowić z nim połączenie w celu przesłania danych. Testowanie może również zapewnić przykładowe dane testowe, które będą pomocne w sprawdzeniu i potwierdzeniu, czy jesteś w stanie przetwarzać dane monitorowania przekazane w aplikacji. Testowanie nie jest jednak równoznaczne z uwierzytelnieniem adresu URL. Aby dowiedzieć się, w jaki sposób przetestować swój adres URL elementu webhook, zapoznaj się z dokumentacją elementów webhook.
Następnie FedEx przeniesie projekty do środowiska produkcyjnego. Na stronie Przegląd projektu API otwórz kartę Klucz produkcyjny. Kliknij link Generuj klucz tajny w kolumnie Klucz tajny.
Możesz teraz ponownie przetestować wdrożenie w środowisku produkcyjnym, używając przykładowych danych.
Wymaganie wstępne
Aby zalogować się do portalu FedEx Developer Portal i utworzyć organizację trzeba mieć identyfikator użytkownika i konto FedEx.
Utwórz organizację, jeśli Twoja firma jej jeszcze nie ma, lub dołącz do istniejącej organizacji.
Tworzenie nowej organizacji
Aby utworzyć własną organizację, kliknij opcję Utwórz organizację w lewym panelu nawigacyjnym. W przypadku utworzenia nowej organizacji automatycznie zostajesz jej administratorem.
- Administrator może zapraszać użytkowników do dołączenia do organizacji oraz przypisywać im role (np. współautor lub przeglądający) i projekty.
- Więcej na temat tych ról znajdziesz w poradniku administrowania organizacją.
Krok 1. Wprowadź informacje o organizacji
- Podaj nazwę swojej firmy, adres URL strony oraz służbowy adres e-mail dla potrzeb weryfikacji.
- Stwórz nazwę organizacji. Nadaj swojej organizacji nazwę, która będzie rozpoznawalna dla innych użytkowników. Nazwa ta może posłużyć do utworzenia bardziej określonych grup w Twojej firmie (np. dział, oddział, region, lokalizacja) lub może być taka sama jak nazwa Twojej firmy.
- Podaj lokalizację siedziby firmy oraz miejsca, w których planujesz sprzedawać swoje rozwiązanie lub prowadzić jego dystrybucję.
Krok 2. Dodaj i uwierzytelnij konto
Wprowadź numer konta FedEx, nazwę skrótową konta oraz adres rozliczeniowy powiązany z kontem. Aby zapobiec nieuczciwym działaniom, adres rozliczeniowy zostanie zweryfikowany w celu upewnienia się, że jest zgodny z danymi konta. Jeśli nie masz jeszcze konta FedEx, załóż nowe konto lub skontaktuj się z przedstawicielem obsługi klienta FedEx.
- W przypadku dostawców zewnętrznych przystępujących do programu integratorów FedEx konto używane do pierwszej rejestracji musi być własnością integratora. Korzystanie z konta klienta końcowego jest niedozwolone.
- Konto to zostanie ustawione jako domyślne konto rozliczeniowe Twojej organizacji.
Krok 3. Przeczytaj i zaakceptuj warunki
Po zaakceptowaniu umowy programisty i instrukcji programu zostanie wyświetlony ekran potwierdzenia. Jako administrator nowej organizacji możesz kliknąć opcję Zarządzaj organizacją w menu po lewej stronie, aby wyświetlić lub edytować szczegóły.
Krok 4. Zaproś użytkowników
Administrator może zapraszać użytkowników do organizacji oraz przypisywać im role i projekty. Otwórz kartę Użytkownicy. Kliknij przycisk Dodaj użytkowników.
- Wybierz rolę użytkownika: przeglądający, współautor lub administrator.
- Jeśli już masz utworzone projekty, przypisz projekt do użytkownika. Użytkowników możesz również przypisywać do projektów z poziomu dowolnej strony Przegląd projektu.
- Wprowadź adresy e-mail użytkowników, których chcesz dodać do swojej organizacji w ramach wybranej roli.
Dołączanie do istniejącej organizacji
Krok 1. Poproś administratora organizacji, aby przesłał Ci zaproszenie.
Jeśli dla Twojej firmy utworzono już organizację, poproś administratora tej organizacji, aby zaprosił Cię do niej. Będziesz mieć 24 godziny na zaakceptowanie zaproszenia. Jeśli przegapisz ten termin, zawsze możesz poprosić o ponowne wysłanie.
Krok 2. Zaakceptuj zaproszenie.
Aby zaakceptować zaproszenie, musisz zalogować się przy użyciu istniejącego identyfikatora użytkownika i hasła lub utworzyć nowy identyfikator, jeśli istniejący jest już powiązany z organizacją.
Na stronie Moje projekty otwórz kartę interfejsy API. Kliknij przycisk Utwórz projekt API.
Krok 1. Wybierz interfejsy API, które chcesz dodać do projektu
Zapoznaj się z limitami w zakresie wysyłki i stawek oraz innymi ograniczeniami interfejsu API, a także szczegółami weryfikacji interfejsów API.
- W przypadku wyboru interfejsu API wysyłki lub Open Ship, interfejsy Service Availability API oraz Trade Documents Upload API zostaną wybrane automatycznie, ponieważ są to interfejsy niezbędne do korzystania z interfejsu API wysyłki lub Open Ship.
Krok 2. Skonfiguruj szczegóły projektu
Nadaj projektowi rozpoznawalną nazwę, która nie powtarza się w obrębie organizacji.
Krok 3. Przeczytaj ze zrozumieniem i zaakceptuj umowę licencyjną FedEx Developer Portal
Po zaakceptowaniu warunków i kliknięciu przycisku Utwórz zobaczysz ekran potwierdzenia. Możesz teraz wyświetlić poświadczenia testowe dla nowego projektu.
Utwórz projekt elementu webhook
Wymagane składniki
- Przejrzyj wycenę: subskrybenci są obciążani miesięczną opłatą zależną od liczby numerów przesyłek. Zapoznaj się z Przewodnikiem po wycenie, aby dowiedzieć się więcej o wycenie.
- Konfigurowanie kont: Advanced Integrated Visibility wymaga konta rozliczeniowego w Stanach Zjednoczonych oraz co najmniej jednego konta wysyłkowego. Te dwa typy kont są wzajemnie rozłączne. Tylko administratorzy mogą dodawać konta rozliczeniowe i wysyłkowe na stronie Zarządzanie organizacją.
Utwórz prawidłowy adres URL (wywołania zwrotnego) w docelowej aplikacji lub platformie
Twój docelowy adres URL będzie używany do odbierania kodów uwierzytelniających i wiadomości, a także powiadomień dotyczących ładunku elementów webhook od firmy FedEx. W celu zapewnienia bezpieczeństwa adres URL musi wykorzystywać protokół HTTPS. Zostaną zablokowane następujące adresy URL:
- Wszystkie w przestrzeni adresowej IP RFC1918.
- Zawierające domenę fedex.com lub dowolne z jej subdomen
- Adresy IP w adresie URL (w tym localhost, 127.0.0.1).
Generowanie tokenu zabezpieczeń
Ten token zabezpieczeń można wykorzystywać jako tajny klucz do uwierzytelniania i weryfikowania informacji przesyłanych między Twoją organizacją a firmą FedEx. Token zabezpieczeń musi zawierać:
- Minimum 26 znaków i maksymalnie 100 znaków
- 1 wielka litera
- 1 mała litera
- 1 cyfra
Przykład: Y1F6OiVUQW2JPSElmRE9U0IY5
Po zdefiniowaniu adresu URL i tokenu zabezpieczeń możesz przystąpić do tworzenia projektu elementu webhook. Na stronie Moje projekty otwórz kartę Elementy webhook. Kliknij przycisk Utwórz projekt elementu webhook.
Wybór typu subskrypcji
Nadawcy FedEx mogą przypisać zdarzenia do numerów kont lub numerów monitorowania.
Krok 1. Potwierdź konto rozliczeniowe i wybierz funkcje
- Sprawdź domyślne konto rozliczeniowe, aby je potwierdzić, lub wybierz inne konto należące do Twojej organizacji.
- Skonfiguruj projekt poprzez wybór funkcji, takich jak opcje potwierdzenia doręczenia, opcje spodziewanego terminu doręczenia, zdarzenia monitorowania czy filtrowanie oparte na zdarzeniach.
Krok 2. Wprowadź szczegóły dotyczące projektu
- Nadaj projektowi rozpoznawalną nazwę, która nie powtarza się w obrębie organizacji.
- Podaj docelowy adres URL i szczegóły tokenu zabezpieczeń utworzone podczas uwierzytelniania przed konfiguracją (patrz kroki powyżej).
- Aby otrzymywać powiadomienia o najnowszych aktualizacjach dotyczących elementów webhook oraz informacje o przerwach w działaniu, ustaw adres e-mail oraz preferowany język.
Krok 3. Przeczytaj i zaakceptuj warunki
Po zaakceptowaniu warunków, w tym umowy licencyjnej FedEx Developer Portal i formularza zamówienia, oraz kliknięciu przycisku Utwórz zobaczysz ekran potwierdzenia.
W zależności od wybranego typu subskrypcji mogą być wymagane dodatkowe kroki. Zajrzyj do dokumentacji, aby dowiedzieć się więcej.
Na stronie Przegląd projektu API pobierz poświadczenia testowe — klucz API i klucz tajny — z karty Klucz testowy.
Krok 1. Poproś o token dostępu OAuth
Poproś o token dostępu OAuth, który musi być używany z każdą transakcją API. Token jest ważny tylko przez godzinę, więc kod aplikacji musi odświeżać token przed wygaśnięciem sesji. Więcej informacji znajdziesz w dokumentacji autoryzacji interfejsu API.
Krok 2. Przejrzyj dokumentację interfejsów API
Kliknij dokumentację każdego z Twoich interfejsów API, aby zapoznać się z kontekstem biznesowym i zrozumieć, jak korzystać z danego interfejsu API. Zaloguj się, aby pobrać kolekcję JSON API za pomocą przycisku znajdującego się u góry strony dokumentacji. Możesz także przejrzeć przykładowe żądania dla punktu końcowego, który jest zgodny z żądaną integracją.
Krok 3. Użyj piaskownicy do przetestowania przykładowych transakcji
Kliknij żądany punkt końcowy w lewym panelu nawigacyjnym, aby przejść do konkretnej piaskownicy. Zidentyfikuj przykładowe żądania, które odpowiadają Twojemu przypadkowi zastosowania, a następnie użyj swoich poświadczeń testowych oraz testowych adresów URL FedEx do realizacji wywołań do punktu końcowego zgodnie z podanym opisem. Upewnij się, że odebrane odpowiedzi na wywołania interfejsu API są zgodne z tymi podanymi w dokumentacji. Więcej na temat testowania znajdziesz w poradniku wirtualizacji piaskownicy.
Testowanie z elementami webhook
Jeśli Twoja organizacja ma dostęp do elementów webhook, testowanie może pomóc w ustaleniu, czy utworzony adres URL jest prawidłowy. W ten sposób FedEx może zidentyfikować Twój adres URL i ustanowić z nim połączenie w celu przesłania danych. Testowanie może również zapewnić przykładowe dane testowe, które będą pomocne w sprawdzeniu i potwierdzeniu, czy jesteś w stanie przetwarzać dane monitorowania przekazane w aplikacji. Testowanie nie jest jednak równoznaczne z uwierzytelnieniem adresu URL. Aby dowiedzieć się, w jaki sposób przetestować swój adres URL elementu webhook, zapoznaj się z dokumentacją elementów webhook.
Na stronie Przegląd projektu otwórz kartę Klucz produkcyjny. Projekty związane z subskrypcją opartą na numerze konta funkcji Advanced Integrated Visibility nie muszą być przenoszone do środowiska produkcyjnego.
Krok 1. Skonfiguruj projekt
W razie potrzeby możesz zmienić nazwę swojego klucza.
Krok 2. Pobierz klucze projektu
Skopiuj klucz produkcyjny interfejsu API i tajny klucz produkcyjny w bezpieczne miejsce. Ze względów bezpieczeństwa tajny klucz produkcyjny wyświetlamy tylko raz. Jeśli go zgubisz, możesz wygenerować nowy.
Po uzyskaniu kluczy projektu i kliknięciu Dalej szczegóły projektu zostaną wyświetlone w karcie Klucz produkcyjny.
Kroki weryfikacji różnią się w różnych regionach
Następujące kroki dotyczą tylko klientów w Stanach Zjednoczonych i Kanadzie. Jeśli mieszkasz w innym kraju, odwiedź stronę Weryfikacja interfejsu API w celu uzyskania wsparcia.
Niektóre interfejsy API wymagają weryfikacji etykiet wysyłkowych, aby można było używać ich w środowisku produkcyjnym. Sprawdź, czy Twój interfejs API wymaga weryfikacji.
Krok 1. Opracuj aplikację internetową i przetestuj ją z interfejsami API FedEx
Po opracowaniu aplikacji internetowej sfinalizuj testowanie przy użyciu poświadczeń testowych (testowego klucza API i klucza tajnego). Testowy klucz API i klucz tajny zostaną wyświetlone na stronie Przegląd projektu i będą dostępne w dowolnym momencie.
- Zidentyfikuj wszystkie przypadki testowe dla regionów/terytoriów, w których rozwiązanie ma zostać zweryfikowane i wdrożone. Przypadki testowe znajdują się w dokumentacji bazowej przypadków testowych integratora.
- Przed uruchomieniem przypadków testowych konieczne będzie uruchomienie transakcji rejestracyjnych dla odpowiednich numerów kont testowych dostępnych w dokumentacji bazowej przypadków testowych.
- Następnie uruchom wszystkie przypadki testowe dla regionów/terytoriów, w których rozwiązanie ma zostać zweryfikowane i wdrożone.
Krok 2. Wypełnij arkusz PIW i formularz weryfikacji
Wypełnij w całości arkusz informacji o produkcie (PIW) i formularz weryfikacji integratora, podając odpowiednie dane kontaktowe, a także informacje o usługach i możliwościach, które planujesz oferować.
Krok 3. Wygeneruj i prześlij materiały do zespołu ds. weryfikacji
Zgromadź następujące materiały i skompresuj je w postaci pliku ZIP, a następnie prześlij drogą e-mailową na adres validationmtp@fedex.com. Zalecamy przesłanie plików w formacie ZIP, aby zmniejszyć ryzyko zablokowania przesyłki przez dostawcę poczty e-mail.
- Wypełnione arkusze PIW dla wszystkich wskazanych terytoriów/regionów (format PDF)
- Wypełniony formularz weryfikacji (format PDF)
- Zrzuty ekranu następujących elementów (format PDF):
- Rozwiązanie skierowane do klientów, prezentujące usługi FedEx/obsługę specjalną
- Oświadczenie o wyłączeniu odpowiedzialności
- Umowa licencyjna użytkownika końcowego
- Przepływ rejestracji klienta końcowego
- Transakcje rejestracji klienta końcowego — uwierzytelnianie wieloskładnikowe obejmujące fakturę i kod PIN, realizowane za pośrednictwem wiadomości SMS, połączeń telefonicznych lub wiadomości e-mail (format — pliki żądania/odpowiedzi JSON)
- Zeskanowane kopie rzeczywistych wydrukowanych etykiet dla wszystkich przypadków testowych uwzględnionych w dokumentacji bazowej przypadków testowych dla terytoriów, w których rozwiązanie ma zostać zweryfikowane (format PDF lub PNG)
- Transakcje wysyłki dla trzech przypadków testowych, po jednym dla każdego typu obrazu etykiety: PDF, PNG i ZPL. (format — pliki żądania/odpowiedzi JSON)
Aby uniknąć opóźnień w przetwarzaniu, przestrzegaj następujących dobrych praktyk:
- Etykiety muszą być drukowane i skanowane w rozdzielczości co najmniej 600 DPI.
- W przypadku drukarek termicznych typ obrazu etykiety należy zamówić zgodnie z modelem drukarki. Przykład: ZPLII w przypadku drukarek Zebra.
- Przesyłki FedEx International Express® muszą zawierać też dodatkową/pomocniczą etykietę lotniczego listu przewozowego.
- Przesyłki wieloczęściowe (MPS) muszą zawierać po jednej etykiecie dla każdej paczki w przesyłce.
Krok 4. Sprawdź ocenę etykiety
Grupa ds. weryfikacji oceni przesłane materiały i je zatwierdzi bądź odrzuci. Grupa ds. weryfikacji skontaktuje się z Tobą w kwestii zatwierdzenia bądź odrzucenia przesłanych materiałów. Jeśli materiały zostały zatwierdzone, przejdź do następnego kroku. Jeśli materiały zostały odrzucone, wprowadź poprawki do transakcji, zrzutów ekranu i/lub etykiet zgodnie z instrukcją i prześlij ponownie do zatwierdzenia.
Krok 5. Włącz aplikację
Po zatwierdzeniu materiałów do statusu produkcyjnego grupa ds. weryfikacji autoryzuje Twoje poświadczenia produkcyjne do przesyłania zidentyfikowanej transakcji etykiet wysyłkowych i powiadomi Cię za pomocą wiadomości e-mail o pomyślnej weryfikacji. Zatwierdzenia są udzielane dla poszczególnych projektów.
Krok 6: Postępuj zgodnie z instrukcją poweryfikacyjną
Przejrzyj instrukcje poweryfikacyjne i postępuj zgodnie z nimi, jeśli to konieczne.
