Table of Contents

Public API

Die Public API von shippingNET ist eine Web-API nach neuestem Stand der Technik in REST-Architektur („Representational State Transfer“).

Voraussetzungen

  1. Ein mittels https erreichbares shippingNET System.
  2. Konfiguration der Aufbauorganisation mit hinterlegter Geschäftspartner Nr. (BusinessPartnerNumber). Siehe auch: Organisation erstellen.
  3. Postman um Beispielrequests abzusetzen (Kostenloses Tool: https://www.postman.com/downloads/).
  4. Anmeldeinformationen für die Authentifizierung der Requests.

Anmeldeinformationen erhalten

  1. Navigieren Sie in der Hauptansicht zu dem Menüpunkt Systemkonfiguration.
  2. Klicken Sie im Bereich Organisation auf den Unterpunkt API.
  3. Im Bereich Anmeldeinformationen finden Sie die Parameter für die Authentifizierung:

Sie benötigen nur mehr den api-key: Das ist ein zusammengesetzter Schlüssel der die ClientID, OrgUnitID und OrgUnitGUID kombiniert.

Beispielrequest für Artikelanlage mit Postman

Für den Import von Artikeldaten gehen Sie wie folgt vor.

  1. Navigieren Sie in der Hauptansicht zu dem Menüpunkt Systemkonfiguration.
  2. Klicken Sie im Bereich Organisation auf den Unterpunkt API.
  3. Im Bereich APIs klicken Sie in der Liste der verfügbaren APIs auf Article.
  4. Sie sehen nun die Dokumentation für die Artikel-API mit den verfügbaren Methoden und deren Request-Aufbau. Artikel API
  5. Klicken Sie auf die Aktion Download und speichern Sie die OpenAPI-Spezifikation für das Artikel-Service lokal auf Ihren PC.
  6. Öffnen Sie das Porgramm Postman und importieren Sie die Datei. Klicken Sie dazu in Postman unter Workspaces/My Workspace auf die Aktion Import und wählen Sie die Datei aus.
  7. Hinterlegen Sie nun in der Collection shippingNET PublicApi Article Service die Anmeldeinformationen. Für Versionen vor 24.1.0.0 setzen Sie unter Variablen die Werte für client-id, orgunit-id und auth-token. Ab Version 24.1.0.0 setzen Sie unter Variablen nur mehr den apiKey.
  8. Bearbeiten Sie unter der Karteikarte Body den Request und geben Sie die gewünschten Artikelinformationen ein. Siehe auch Artikelfelder.
  9. Klicken Sie abschließend rechts neben der Adresse auf die Aktion Send um den Import durchzuführen.
Tipp

Starten Sie mit einem minimalen Set an Feldern und weiten Sie schrittweise die zu übertragende Daten aus!

Tipp

Manche Felder benötigen die Übergabe von Codes bzw. IDs. Diese Werte hängen mit der Freischaltung diverser Stammdaten in der Systemkonfiguration zusammen. Die Liste mit den Codes und deren Bedeutung finden Sie in der Systemkonfiguration im Bereich Organisation im Unterpunkt API. Klicken Sie im Bereich Beschreibung auf Sendungsübersicht.

Hinweis

Feldwerte die im Request nicht mitgeschickt werden, bleiben unverändert! Um Felder auf NULL bzw. '' (leer) zu setzen, übergeben Sie das Feld mit NULL bzw. '' (leer).

Hinweis

Sie können auch Datei-Anhang zum Beispiel beim Statusimport oder Dokumente zu einer Sendung importieren. Das Limit der Dateigröße ist auf maximal 2MB festgesetzt. Folgende Dateitypen sind erlaubt: PDF, PNG, JPG, Ab der Version 26.1 auch XLSX, MSG Sie müssen die Datei in einen Bas64 String konvertiert werden.

Bei einem erfolgreichen Request (Status Code 200) werden die im Body angeforderten Felder zurückgeliefert.

{
  "Article": {
    "ID": "<number>",
    "Number": "<string>",
    "CustomerBusinessPartnerNumber": "<string>"
  }
}

Im Fehlerfall (Status Code 500) erhalten Sie die Fehlerursache in folgender Form:

{
  "ExceptionCode": "<string>",
  "ExceptionType": "<string>",
  "ExceptionMessage": "<string>",
  "Source": "<string>"
}