Anmelden

nShift Help Center

Erste Schritte mit der DeliveryCloud 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 DeliveryCloud 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 DeliveryCloud 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 DeliveryCloud 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 DeliveryCloud 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 DeliveryCloud API können alle in einem anderen System gebuchten Sendungen übertragen und die Vorteile von nShift Track genutzt werden.

 

 

Erstellen einer DeliveryCloud-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 DeliveryCloud 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 DeliveryCloud 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).

    deliverycloud-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.

 

 

Anfordern eines Tokens

Verwenden Sie Ihre Client ID und Ihr Client Secret, um ein Zugriffstoken zu generieren. Dies erfolgt durch das Senden einer POST-Anfrage an folgenden Endpoint:
 

https://api.nshiftportal.com/delivery-cloud/idp/connect/token


Beispiel:
POST https://api.nshiftportal.com/delivery-cloud/idp/connect/token
Cache-Control: no-cache
Host: www.nshiftportal.com 
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials

 

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

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

Das Bearer-Token ist eine Stunde lang gültig. Alle Anfragen müssen das Token im Authorization-Header enthalten.

 

 

Verwendung der DeliveryCloud API

Sobald Sie authentifiziert sind, können Sie mit der Nutzung der DeliveryCloud 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