Die API für erweiterte integrierte Sichtbarkeit Sendungsnummer Abonnement ermöglicht Nutzer*innen der erweiterten integrierten Sichtbarkeit, Sendungsnummern mithilfe von API-Endpunkten mit einem Webhook-Projekt zu zuordnen. Die Funktion zur Zuordnung von Sendungsnummern unterstützt zwei Verarbeitungsmethoden:

• Zuordnung der Sendungsnummer – synchron gibt die Verarbeitungsergebnisse innerhalb derselben HTTP-Antwort zurück. Diese Option eignet sich am besten für Anwendungen, die eine sofortige Bestätigung für eine kleinere Anzahl von Sendungsnummern benötigen. 
• Zuordnung der Sendungsnummer – asynchron sendet die Anfrage zur Hintergrundverarbeitung ab und gibt eine Job-ID zurück, mit der später der Verarbeitungsstatus und die Ergebnisse abgerufen werden können. Diese Option eignet sich am besten für die Verarbeitung einer größeren Anzahl von Sendungsnummern. 

Wählen Sie die Verarbeitungsmethode, die den Leistungs- und Workload-Anforderungen Ihrer Anwendung am besten entspricht.

Hinweis:

• Sie benötigen Administrator- oder Mitwirkendenzugriff für Ihr Advanced Integrated Visibility-Projekt
• Weitere Informationen zu Advanced Integrated Visibility und seinen Funktionen finden Sie auf der Seite Advanced Integrated Visibility – Dokumentation.

Die Advanced Integrated Visibility Tracking Number Subscription API bietet folgende Vorteile:

• Sie können die Sendungsnummern Ihres Advanced Integrated Visibility-Webhook-Projekts ganz einfach über die API-Endpunkte verknüpfen, aktualisieren und verwalten.
• Verknüpfen Sie mehrere Sendungsnummern in einer einzigen API-Anfrage, anstatt jede Sendungsnummer einzeln zu verarbeiten.
• Wählen Sie zwischen synchroner Verarbeitung für sofortige Ergebnisse oder asynchroner Verarbeitung für größere Batch-Operationen.

Verwenden Sie die folgenden Endpunkte, um Ihr Advanced Integrated Visibility-Projekt zu verwalten:

• Zuordnung der Sendungsnummer – synchron ermöglicht Ihnen, Sendungsnummern mit einem Webhook zu verknüpfen und den endgültigen Verarbeitungsstatus innerhalb derselben HTTP-Antwort zu empfangen.
• Zuordnung der Sendungsnummer – asynchron ermöglicht Ihnen, Sendungsnummern mit einem Webhook zu verknüpfen und die zurückgegebene jobId später zu verwenden, um den Status des asynchronen Jobs zu überprüfen oder Details mit verwandten Endpunkten herunterzuladen:    
  • Sendungsverfolgungsnummer —Jobstatus
  • Sendungsverfolgungsnummer —Jobdetails

Diese APIs sind über Ihre Advanced Integrated Visibility-Projektübersicht verfügbar.

Der Zugriff auf diese API ist nur über Ihre Projektübersicht möglich, wie im obigen Screenshot dargestellt.

In der folgenden Tabelle sind die Unterschiede zwischen den Endpunkten für die synchrone und asynchrone Zuordnung von Sendungsnummern zusammengefasst.
 

Verwenden Sie den synchronen Endpunkt, wenn Sie eine sofortige Bestätigung für eine kleinere Anzahl an Sendungsnummern benötigen. Verwenden Sie den asynchronen Endpunkt bei der Verarbeitung größerer Mengen, die keine sofortige Antwort erfordern.

Verwenden Sie diesen Endpunkt, um eine oder mehrere Sendungsnummern mit einem Advanced Integrated Visibility-Webhook-Projekt zu verknüpfen und die Verarbeitungsergebnisse in derselben HTTP-Antwort zu erhalten.

Dieser Endpunkt ist für Anwendungen vorgesehen, die eine sofortige Bestätigung erfordern, und unterstützt Anfragen mit bis zu 150 Sendungsnummern.

Erforderliche Eingabe: 

• subscriptionID
• trackingNumber

Vorteile

Der synchrone Endpunkt bietet folgende Vorteile:

• Sofortige Verarbeitungsergebnisse
• Detaillierte Erfolgs- und Fehlerinformationen in einer Antwort
• Unterstützung für bis zu 150 Sendungsnummern pro Anfrage
• Anfragevalidierung und Durchsetzung von Geschäftsregeln vor der Verarbeitung
• Maschinenlesbare Fehlercodes und beschreibende Fehlermeldungen
• Transaktions-IDs für Anfragenachverfolgung und Problembehandlung

Der Endpunkt „Zuordnung der Sendungsnummer – synchron“ setzt mehrere Validierungsregeln durch, darunter:

• Gültige und aktive subscriptionId erforderlich
• Nur eine subscriptionId pro Anfrage
• trackingNumber ist erforderlich
• Sendungsnummern müssen Formatvorgaben von FedEx entsprechen, einschließlich der maximalen Länge von 6 bis 22 Ziffern

Fehlerantworten haben eine einheitliche Struktur, wobei errors[] einen Code und eine Mitteilung zur einfachen Auswertung enthält.

"errors": [

{

"Code": "ERROR.CODE",

"message": "Fehlerbeschreibung"

}

Der Endpunkt „Zuordnung der Sendungsnummer – synchron“ lässt teilweise erfolgreiche Anfragen zu. Wenn einige Sendungsnummern fehlschlagen, gibt die synchrone API trotzdem 200 OK zurück und zeigt Folgendes an:

• failedTrackingNumbers
• Eine Beschreibung

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "Die folgenden Sendungsnummern konnten aufgrund von Validierungs- oder Systemfehlern nicht hochgeladen werden"

      }

    }

Weitere Einzelheiten und Regeln finden Sie in den Abschnitten zu den Geschäftsregeln.

Nutzen Sie diesen Endpunkt, um eine oder mehrere abonnierte Sendungsnummern für die Hintergrundverarbeitung zu übermitteln.

Die Anfrage gibt eine Job-ID zurück, die Sie mit dem Endpunkt Sendungsnummer – Jobstatus verwenden können, um die Verarbeitung zu überwachen, und mit dem Endpunkt Sendungsnummer – Jobdetails, um die Verarbeitungsergebnisse nach Abschluss des Jobs herunterzuladen.

Erforderliche Eingabe:

• Aktion
• Details zur Sendungsnummer

Sie können bis zu 1000 Sendungsnummern in einer Anfrage zusammenfassen.

Vorteile

Der asynchrone Endpunkt bietet folgende Vorteile:

• Unterstützung für Batch-Einreichungen mit bis zu 1000 Sendungsnummern
• Verarbeitung länger dauernder Anfragen im Hintergrund
• Überwachung des Jobstatus und herunterladbare Verarbeitungsberichte
• Keine Zeitüberschreitung bei großen Workloads

Verwenden Sie diesen Endpunkt, um den Status eines asynchronen Jobs (eine oder mehrere aufeinanderfolgende Anfragen in der Warteschlange) oder den Status aller übermittelten Jobs abzurufen.

Die für diese Anfrage erforderlichen Eingabedaten sind:

• jobID – Geben Sie die Job-ID an, für die Sie den Status abrufen möchten.

Hinweis: Die Job-ID ist eine optionale Eingabe für diesen Endpunkt. Wenn Sie die Job-ID nicht angeben, erhalten Sie den Status aller übermittelten Jobs.

Die erfolgreiche Antwort auf diese Anfrage gibt die Job-ID, den aktuellen Jobstatus sowie den Zeitstempel für die Erstellung und Fertigstellung des Jobs zurück. Die Antwort zeigt den aktuellen Status der Jobs an. Darüber hinaus enthält die Antwort auch Erfolgsmeldungen, Fehler oder Warnungen, die Benutzer anzeigen und gegebenenfalls beheben können.

• Wenn der Jobstatus als „ABGESCHLOSSEN“ angezeigt wird, bedeutet dies, dass alle Sendungsverfolgungsnummern validiert und erfolgreich verarbeitet wurden.
  • Der Status „ABGESCHLOSSEN“ bedeutet, dass die Sendungsverfolgungsnummern validiert und erfolgreich verarbeitet wurden. Dies bedeutet nicht, dass alle Sendungsverfolgungsnummern erfolgreich zum Advanced Integrated Visibility-Projekt hinzugefügt wurden.
  • Bei Anfragen mit mehreren Sendungsnummern kann der Status als ABGESCHLOSSEN angesehen werden, auch wenn die Verknüpfung einiger Nummern mit dem Projekt fehlschlägt, andere jedoch erfolgreich sind. Um den Status der einzelnen Sendungsnummern in der ursprünglichen Anfrage zu prüfen, müssen Sie den Batch-Bericht herunterladen.

Hinweis: Wenn der Jobstatus als „FEHLGESCHLAGEN” angezeigt wird, bedeutet dies, dass die Anfrage aus verschiedenen Gründen/aufgrund schwerwiegender Fehler nicht verarbeitet werden konnte und erneut gestartet werden muss.

Die folgende Tabelle zeigt die Jobstatus und ihre jeweiligen Beschreibungen:

Verwenden Sie diesen Endpunkt, um einen JSON-Bericht für einen asynchronen Job im Status „ABGESCHLOSSEN“ herunterzuladen.

Die für diese Anfrage erforderlichen Eingabedaten sind:

• jobID – Geben Sie die Job-ID an, für die Sie den Status abrufen möchten. Für diesen Endpunkt ist eine Job-ID erforderlich.

Hinweis:

• Sie können für asynchrone Jobs jeweils nur einen Bericht herunterladen.
• Wenn der Job nicht ABGESCHLOSSEN ist und Sie versuchen, den Bericht herunterzuladen, wird eine Fehlermeldung angezeigt.

Die erfolgreiche Antwort auf diese Anfrage liefert Ihnen den Bericht des Jobs im JSON-Format.

Allgemeine Geschäftsregeln

• Die Anzahl der Sendungsnummern, die Sie einem Advanced Integrated Visibility-Projekt zuordnen können, ist unbegrenzt.
• Die Verknüpfung der mit einem Advanced Integrated Visibility-Projekt verknüpften Sendungsnummern wird 40 Tage, nachdem sie erfolgreich mit dem Webhook verknüpft wurden, aufgehoben.
• Geschützte Sendungsverfolgungsdaten, wie Empfängeradresse, Unterschrift des Empfängers und sensible Lieferdaten, sind über die Sendungsnummer-Abonnement-API nicht verfügbar.

Geschäftsregeln für den synchronen Endpunkt

• Maximal 150 Sendungsnummern pro Anfrage.
• Alle Sendungsnummern müssen dieselbe subscriptionId haben.
• Das angegebene Advanced Integrated Visibility-Webhook-Abonnement muss gültig und aktiv sein.
• Für Anfragen gilt ein Zeitlimit von 30 Sekunden.

Geschäftsregeln für den asynchronen Endpunkt

• Maximal 1000 Sendungsnummern pro Anfrage.
• Bei asynchronen Anfragen werden Jobstatus und Jobdetails nach erfolgreicher Verknüpfung der Sendungsnummern mit dem Advanced Integrated-Visibility-Webhook 90 Tage lang gespeichert.