Interfejs API subskrypcji opartej na numerze monitorowania w ramach usługi Advanced Integrated Visibility (AIV) umożliwia subskrybentom usługi Advanced Integrated Visibility powiązanie numerów monitorowania z projektem elementu webhook AIV przy użyciu punktów końcowych interfejsu API. Funkcja powiązania numerów monitorowania obejmuje dwa rodzaje przetwarzania:

• Opcja Tracking Number Association — Synchronous (Powiązanie numerów monitorowania — synchroniczne) umożliwia uzyskanie wyników przetwarzania w ramach tej samej odpowiedzi HTTP. Najlepiej sprawdza się przy mniejszej liczbie powiązanych numerów monitorowania, gdy wymagane jest natychmiastowe potwierdzenie.
• Opcja Tracking Number Association — Asynchronous (Powiązanie numerów monitorowania — asynchroniczne) umożliwia przesłanie żądania dotyczącego przetwarzania w tle i uzyskanie identyfikatora zadania. Identyfikator można następnie użyć, aby zapoznać się ze statusem przetwarzania oraz — w późniejszym czasie — z jego wynikami. Opcja ta najlepiej sprawdza się przy przetwarzaniu większych partii numerów monitorowania.

Wybierz rodzaj przetwarzania najbardziej odpowiadający wydajności Twojej aplikacji i wymaganiom w zakresie wolumenu.

Uwaga:

• Projekt Advanced Integrated Visibility wymaga uprawnień na poziomie administratora lub współautora.
• Więcej informacji o usłudze Advanced Integrated Visibility i jej funkcjach znajdziesz na stronie Dokumentacja usługi Advanced Integrated Visibility.

Interfejs API subskrypcji opartej na numerze monitorowania w ramach usługi Advanced Integrated Visibility zapewnia następujące korzyści:

• możliwość łatwego powiązania i aktualizowania numerów monitorowania oraz zarządzania nimi w ramach projektu elementu webhook Advanced Integrated Visibility przy użyciu punktów końcowych interfejsu API,
• możliwość powiązania wielu numerów monitorowania w ramach jednego żądania za pośrednictwem interfejsu API zamiast przetwarzania poszczególnych numerów monitorowania osobno,
• wybór między przetwarzaniem synchronicznym umożliwiającym natychmiastowe uzyskanie wyników a przetwarzaniem asynchronicznym przeznaczonym do operacji na większych partiach.

Projektem Advanced Integrated Visibility można zarządzać za pomocą następujących punktów końcowych:

• Opcja Tracking Number Association — Synchronous (Powiązanie numerów monitorowania — synchroniczne): umożliwia powiązanie numerów monitorowania z elementem webhook i uzyskanie wyniku końcowego przetwarzania w ramach tej samej odpowiedzi HTTP.
• Opcja Tracking Number Association — Asynchronous (Powiązanie numerów monitorowania — asynchroniczne): umożliwia powiązanie numerów monitorowania z elementem webhook i późniejsze użycie otrzymanego identyfikatora jobId w celu sprawdzenia statusu zadania asynchronicznego lub pobrania szczegółowych informacji przy użyciu odpowiednich punktów końcowych:
  • Numer monitorowania — status zadania
  • Numer monitorowania — szczegóły zadania

Te interfejsy API są dostępne w oknie podsumowania projektu Advanced Integrated Visibility.

Te interfejsy API są dostępne tylko w oknie podsumowania projektu, jak pokazano na zrzucie ekranu powyżej.

Poniższa tabela zawiera podsumowanie różnic między punktami końcowymi przetwarzania synchronicznego i asynchronicznego powiązanych numerów monitorowania.
 

Jeśli potrzebujesz natychmiastowego potwierdzenia i przetwarzasz mniejsze partie numerów monitorowania, użyj punktu końcowego przetwarzania synchronicznego. Jeśli przetwarzasz większe partie niewymagające natychmiastowej odpowiedzi, użyj punktu końcowego przetwarzania asynchronicznego.

Użyj tego punktu końcowego, aby powiązać jeden numer monitorowania lub więcej takich numerów z projektem elementu webhook Advanced Integrated Visibility i otrzymać wyniki przetwarzania w ramach tej samej odpowiedzi HTTP.

Ten punkt końcowy przeznaczony jest dla aplikacji wymagających natychmiastowego potwierdzenia. Obsługuje żądania obejmujące do 150 numerów monitorowania.

Wymagane elementy:

• subscriptionID
• trackingNumber

Korzyści

Punkt końcowy przetwarzania synchronicznego zapewnia następujące korzyści:

• natychmiastowe wyniki przetwarzania,
• szczegółowe informacje dotyczące pomyślnego lub nieudanego zakończenia przetwarzania w jednej odpowiedzi,
• obsługa do 150 numerów monitorowania na żądanie,
• weryfikacja żądania i zastosowanie reguł biznesowych przed przetworzeniem,
• opisowe komunikaty o błędach i kody błędu umożliwiające odczyt maszynowy,
• identyfikatory transakcji na potrzeby monitorowania żądań i rozwiązywania problemów.

W punkcie końcowym interfejsu Tracking Number Association — Synchronous (Powiązanie numerów monitorowania — synchroniczne) ma zastosowanie wiele reguł weryfikacji, w tym:

• żądanie poprawnego i aktywnego identyfikatora subscriptionId;
• obsługa tylko jednego identyfikatora subscriptionId na żądanie;
• żądanie elementu trackingNumber;
• weryfikacja zgodności numerów monitorowania z wymogami dotyczącymi formatowania firmy FedEx, w tym z wymogiem ograniczenia liczby znaków w numerze monitorowania do zakresu 6–22.

Odpowiedzi dotyczące błędów mają spójną strukturę. Sekcja „errors[]” zawiera kod i komunikat ułatwiający analizę.

"errors": [

{

"code": "ERROR.CODE",

"message": "Komunikat z opisem błędu"

}

Punkt końcowy interfejsu Tracking Number Association — Synchronous (Powiązanie numerów monitorowania — synchroniczne) zapewnia możliwość częściowego powodzenia. W przypadku niepomyślnego przetwarzania części numerów monitorowania interfejs API przetwarzania synchronicznego w dalszym ciągu zwróci komunikat 200 OK i wyświetli następujące elementy:

• failedTrackingNumbers
• komunikat z opisem

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "Poniższe numery monitorowania nie zostały przesłane z powodu błędów weryfikacji lub systemu"

      }

    }

Szczegółowe informacje i reguły można znaleźć w sekcji dotyczącej reguł biznesowych.

Użyj tego punktu końcowego, aby przesłać co najmniej jeden subskrybowany numer monitorowania do przetwarzania w tle.

Po wysłaniu żądania otrzymasz identyfikator zadania, którego możesz użyć w punkcie końcowym Tracking Number Job Status (Status zadania dotyczącego numerów monitorowania), aby monitorować postępy przetwarzania, oraz w punkcie końcowym Tracking Number Job Details (Szczegóły zadania dotyczącego numerów monitorowania), aby pobrać wyniki przetwarzania po zakończeniu zadania.

Wymagane dane:

• Czynność
• Szczegóły numeru monitorowania

W ramach jednego żądania można powiązać do 1000 numerów monitorowania.

Korzyści

Punkt końcowy przetwarzania asynchronicznego zapewnia następujące korzyści:

• obsługa dużych partii — do 1000 numerów monitorowania,
• możliwość przetwarzania w tle żądań zajmujących dużo czasu,
• możliwość monitorowania statusu zadania i pobrania raportów dotyczących przetwarzania,
• brak problemów z limitem czasu w przypadku dużych wolumenów.

Użyj tego punktu końcowego, aby sprawdzić status zadania asynchronicznego (jednego lub kilku kolejnych żądań w kolejce) albo status wszystkich przesłanych zadań.

Wymagane informacje wejściowe związane z tym żądaniem to:

• jobID — podaj identyfikator zadania, którego status chcesz sprawdzić.

Uwaga: Identyfikator zadania jest opcjonalnym parametrem dla tego punktu końcowego. Jeśli go nie podasz, pobrany zostanie status wszystkich przesłanych zadań.

Pomyślna odpowiedź na żądanie zwróci identyfikator zadania (jobID), bieżący status zadania oraz sygnatury czasowe utworzenia i zakończenia zadania. Odpowiedź będzie wskazywać aktualny status zadań. Odpowiedź będzie też zawierać komunikaty o sukcesie, błędy oraz ostrzeżenia. Użytkownicy mogą je przeglądać i w razie potrzeby rozwiązywać występujące problemy.

• Jeśli status zadania jest wyświetlany jako COMPLETED (Ukończone), oznacza to, że wszystkie numery monitorowania zostały zweryfikowane i przetworzone.
  • Status ten wskazuje, że numery monitorowania zostały zweryfikowane i przetworzone. Nie oznacza to jednak, że wszystkie numery monitorowania zostały pomyślnie dodane do projektu Advanced Integrated Visibility.
  • Zadania z wieloma numerami monitorowania otrzymają status COMPLETED (Ukończone), nawet jeśli pewnych numerów nie uda się powiązać z projektem. Aby sprawdzić status każdego numeru monitorowania w żądaniu powiązania, pobierz raport zbiorczy.

Uwaga: Jeśli zadanie ma status FAILED (Niepowodzenie), oznacza to, że z różnych powodów lub wskutek poważnych błędów żądanie nie mogło zostać przetworzone i użytkownik musi je ponowić.

Poniższa tabela zawiera statusy zadań i odpowiadające im opisy:

Ten punkt końcowy umożliwia pobranie raportu JSON dotyczącego zadania asynchronicznego mającego status COMPLETED.

Wymagane informacje wejściowe związane z tym żądaniem to:

• jobID — podaj identyfikator zadania, którego status chcesz sprawdzić. W przypadku tego punktu końcowego identyfikator zadania jest obowiązkowy.

Uwaga:

• Można pobrać tylko jeden raport dotyczący zadania asynchronicznego jednocześnie.
• Jeśli zadanie nie ma statusu COMPLETED i spróbujesz pobrać raport, pojawi się komunikat o błędzie.

Pomyślna odpowiedź na żądanie powoduje dostarczenie raportu dotyczącego zadania w formacie JSON.

Wspólne reguły biznesowe

• Nie ma ograniczeń co do maksymalnej liczby numerów monitorowania, które można powiązać z projektem Advanced Integrated Visibility.
• Numery monitorowania powiązane z projektem Advanced Integrated Visibility są oddzielane po 40 dniach od pomyślnego powiązania z elementem webhook.
• Chronione informacje związane z monitorowaniem, takie jak adres lub podpis odbiorcy oraz informacje poufne dotyczące doręczenia, nie są dostępne za pośrednictwem interfejsu Tracking Number Subscription API.

Reguły biznesowe dotyczące punktu końcowego w przypadku przetwarzania synchronicznego

• Maksymalnie 150 numerów monitorowania w ramach żądania.
• Wszystkie numery monitorowania muszą wykorzystywać ten sam identyfikator subscriptionId.
• Określona subskrypcja elementu webhook Advanced Integrated Visibility musi być prawidłowa i aktywna.
• Żądania są objęte 30-sekundowym limitem czasu.

Reguły biznesowe dotyczące punktu końcowego w przypadku przetwarzania asynchronicznego

• Maksymalnie 1000 numerów monitorowania w ramach żądania.
• Status i szczegóły zadania w przypadku żądań przetwarzania asynchronicznego są przechowywane przez 90 dni od pomyślnego powiązania numerów monitorowania z projektem elementu webhook Advanced Integrated Visibility.