Anmelden
nShift Help Center

Erste Schritte mit der Delivery Cloud API

Avatar
Malene Tidemann
Aktualisiert

Suchen Sie nach einer Möglichkeit, alle Ihre Versanddaten zentral an einem Ort zu bündeln, auch wenn Sie mit mehreren verschiedenen Book- und Print-Produkten arbeiten? Mit der Delivery Cloud API von nShift können Sie alle Ihre Sendungen in das nShift Portal integrieren. So können Sie Ihre Sendungen einfach verwalten und verfolgen und gleichzeitig von umfassenden Berichten und erweiterten Tracking-Tools profitieren, was für eine bessere Transparenz Ihres gesamten Versandprozesses sorgt.

 

Inhalt dieses Artikels:

 

Wichtigste Anwendungsfälle

Unsere Kunden verfügen über viele unterschiedliche Setups und Lösungen, wodurch verschiedene Anwendungsfälle für die Delivery Cloud API entstehen. Hier sind einige Beispiele für die wichtigsten Anwendungsfälle:

 

Anwendungsfall 1: Mehrere Versandabläufe

Der Kunde verwendet möglicherweise eine nShift Book- und Print-Lösung zusammen mit nShift Track, hat aber zusätzlich einen Dropshipping-Ablauf, der eine andere Book- und Print-Lösung verwendet. Mit der Delivery Cloud API kann der Kunde Sendungen aus dem Dropshipping-Ablauf an das nShift Portal senden und Track für alle Sendungen nutzen.

 

Anwendungsfall 2: Emissions Tracker

Der Kunde möchte den nShift Emissions Tracker nutzen, aber nicht alle Sendungen werden mit einem nShift Book- und Print-Produkt erstellt. Mithilfe der Delivery Cloud API können alle Sendungen übertragen und Emissionsberechnungen durchgeführt werden.

 

Anwendungsfall 3: Nutzung einer Nicht-nShift Book- und Print-Lösung

Der Kunde nutzt eine Nicht-nShift Book- und Print-Lösung, möchte jedoch nShift Track erwerben. Mit der Delivery Cloud API können alle in einem anderen System gebuchten Sendungen übertragen und die Vorteile von nShift Track genutzt werden.

 

 

Erstellen einer Delivery Cloud-Organisation

Beginnen Sie mit dem Erstellen einer Organization und eines Member Account Name im nShift Portal. Dies ist der Ort, an dem die Sendungen erstellt werden. Beachten Sie, dass Sie eine Organization Unit und einen Member Account speziell für Delivery Cloud erstellen müssen, auch wenn Sie bereits ein bestehendes Mitgliedskonto im nShift Portal haben.

  1. Melden Sie sich im nShift Portal an und klicken Sie oben links auf Settings.
     
  2. Wählen Sie Company Management > Delivery Cloud Configuration. (Falls diese Option nicht angezeigt wird, müssen Sie den nShift Customer Service kontaktieren, um sie aktivieren zu lassen).


     
  3. Klicken Sie auf Create und anschließend auf Add Organization Unit.


     
  4. Geben Sie einen Organization Unit Name und einen Member Account Name ein.


     
  5. Klicken Sie auf Save.
     
  6. Vergessen Sie nicht, Ihre Organization ID und Member Account ID zu kopieren und zu speichern, da diese Werte für die API-Anfragen benötigt werden. Wenn Sie Copy ID auswählen, wird der Wert in Ihre Zwischenablage kopiert.



 

Erstellen einer Client ID und eines geheimen Schlüssels

Die Delivery Cloud API erfordert die Verwendung von Tokens (Client IDs und Client Secrets).

Beginnen Sie mit dem Erstellen der Client ID und des geheimen Schlüssels, die für die Authentifizierung erforderlich sind.

  1. Melden Sie sich im nShift Portal an. (Wenn Sie kein Owner account verwenden, müssen Sie möglicherweise Zugriff beim Owner/Admin anfordern).
     
  2. Klicken Sie oben rechts auf Settings.

    nav-settings.png
     
  3. Wählen Sie im linken Menü API Configuration > Clients.
     
  4. Klicken Sie auf der Seite Clients auf die Schaltfläche Add.
     
  5. Füllen Sie Display name und Description aus. Wählen Sie einen Namen und eine Beschreibung, damit Sie das Token später leichter identifizieren können. Aktivieren Sie das Kontrollkästchen Enable, um das Token sofort zu aktivieren. (Sie können das Token jederzeit nach der Erstellung aktivieren oder deaktivieren).

    Delivery Cloud-client.png
     
  6. Wählen Sie unter Allowed Scopes die Option Portal Shipment Data API , also die APIs, auf die Sie Zugriff benötigen. 
     
  7. Klicken Sie auf Save. Ihre Client ID und Ihr Client Secret werden nun generiert und auf dem Bildschirm angezeigt. Wichtig: Das Client Secret ist nicht mehr verfügbar, nachdem Sie das Popup-Fenster geschlossen haben. Stellen Sie daher sicher, dass Sie es kopieren.
     
  8. Klicken Sie auf Close. Die Client ID wird nun auf der Seite Clients angezeigt. Sie können jederzeit auf eine Client ID klicken, um sie zu bearbeiten, zu löschen oder zu aktivieren/deaktivieren.

 

 

Token anfordern

Die Delivery Cloud API verwendet OAuth 2.0. Verwenden Sie Ihre Client ID und Ihr Client Secret, um ein Zugriffstoken zu generieren. Senden Sie dazu eine POST-Anfrage an den folgenden Endpunkt:
 

  • Produktion: https://account.nshiftportal.com/idp/connect/token
  • Test: https://account.qa.nshiftportal.dev/idp/connect/token


Setzen Sie den Header Content-Type auf application/x-www-form-urlencoded und senden Sie die folgenden Werte im Anfragetext:

  • grant_type: client_credentials
  • client_id: Ihre Client-ID
  • client_secret: Ihr Client-Geheimnis

 

Wenn die Anfrage gültig und der Client korrekt konfiguriert ist, erhalten Sie eine JSON-Antwort:

{
    "access_token": "some-real-token-data-dskjfhsuijkdhfgjkasjdgfhqoeiefoiknsdfgvoiltgjvp...",
    "expires_in": 3600,
    "token_type": "Bearer"
}

 

Zugriffstoken verwenden

Alle Anfragen müssen das Token im Authorization-Header enthalten. Senden Sie das zurückgegebene access_token im Authorization-Header jeder Anfrage: Authorization: Bearer {access_token}.

 

Das Bearer-Token ist eine Stunde lang gültig. Fordern Sie ein neues Token an, wenn das aktuelle abläuft.

 

 

Verwendung der Delivery Cloud API

Sobald Sie authentifiziert sind, können Sie mit der Nutzung der Delivery Cloud API beginnen. Starten Sie mit dem Abrufen der Liste aller Frachtführer. Identifizieren Sie den gewünschten Frachtführer und rufen Sie anschließend die Services und Add-ons dieses Frachtführers ab. Sobald Sie die richtigen IDs für Frachtführer, Service und Add-ons haben, können Sie die Sendung erstellen.

 

Übersicht der Methoden und Schritte, die erforderlich sind, um Ihre Sendungen zum nShift Portal hinzuzufügen:

  1. Rufen Sie eine Liste aller Frachtführer ab und identifizieren Sie die ID des benötigten Frachtführers.

    GET /metadata/carriers

    Hinweis: Die in dieser Anfrage verwendete organizationId ist die ID, die Sie nach dem Erstellen der Organization Unit kopiert und gespeichert haben. 
     

  2. Rufen Sie eine Übersicht der Services eines Frachtführers ab. Verwenden Sie die Frachtführer-ID, die Sie aus der Liste der Frachtführer erhalten haben.

    GET /metadata/carriers/{carrierId}/services

     

  3. Rufen Sie eine Übersicht der verfügbaren Add-ons für einen Frachtführer ab. Verwenden Sie die Frachtführer-ID, die Sie aus der Liste der Frachtführer erhalten haben. Add-ons werden nicht immer verwendet, daher ist dieser Schritt optional, wenn Ihre Sendungen keine Add-ons enthalten.

    GET /metadata/carriers/{carrierId}/addons

     

  4. Erstellen Sie Sendungen mithilfe der Frachtführer-ID, der Service-ID und der Add-on-ID.

    PUT /shipments

    Hinweis: Die in dieser Anfrage verwendete accountId ist die Member Account UUID, die Sie nach dem Erstellen der Organization Unit und des Member Account kopiert und gespeichert haben. Denken Sie daran, die Member Account ID und nicht die Organization ID zu verwenden. 
     

Zur technischen API-Dokumentation

Verwandte Beiträge