PackApp-Programmierschnittstelle (Rest-API) und PackApp-JSON
Dieser Artikel enthält eine kurze Einführung zur Integration anderer Anwendungen mit PackApp mit Hilfe der PackApp Rest-API und PackApp-JSON.
Nutzen Sie alle Vorteile der schnellen Berechnung von Packlisten durch PackApp ohne Ihre gewohnte Arbeitsumgebung zu verlassen. Realisieren Sie eine Schnittstelle zwischen Ihrer Software und PackApp und stellen Sie so einen nahtlosen Datenaustausch sicher!
Über die PackApp-API können Sie die folgenden Aktionen ausführen:
- Übergabe von Packlisten an PackApp, zum Beispiel von anderen Anwendungen
- Setzen von Berechnungsparametern und das Starten von Berechnungen
- Abfragen von Berechnungsergebnissen
- Löschen von Berechnungen
Um die PackApp-API nutzen zu können, müssen Sie zum einen über eine Registrierung als Benutzer verfügen, zum anderen benötigen Sie für die API eine Client-ID und ein separates Kennwort (siehe auch Authentifizierung), die wir Ihnen auf Anfrage zur Verfügung stellen.
Datenformat JSON
Die Daten werden standardmäßig im JSON-Format übertragen. XML wird ebenfalls unterstützt, ist aber nicht Teil dieser Information.
Nachfolgend nun ein Beispiel für eine einfache Container-Berechnung bestehend aus einer Packliste mit zwei Positionen:
Sie können das JSON zu einer Berechnung direkt ansehen, indem Sie in PackApp die Berechnungsergebnisse aufrufen und dort den Menüpunkt „Berechnung|Download JSON“ aufrufen und dieses herunterladen:
Abbildung: Download JSON
Beschreibung der JSON-Struktur
Das JSON ist in vier Bereiche unterteilt:
| Header | Allgemeine Informationen, wie eine Beschreibung |
| Packlist | Die Packliste mit den zu berechnenden Daten |
| Options | Optionen für die Berechnung |
| Result | Das Berechnungsergebnis |
Header
Der Header enthält die folgenden Felder:
| Name | Typ | Beschreibung | |
|---|---|---|---|
| Id | Integer | Optional | Id der Berechnung, wird von PackApp vergeben. Sie ist nicht für eine neue Berechnung zu setzen |
| Description | String 50 | Beschreibung/Titel |
Packlist
„Packlist“ besteht aus einer Liste von Einträgen vom Typ „PackListItem“. Jedes PackListItem enthält die Informationen, die auch im Eingabeformular zu einer Berechnung enthalten sind:
| Name | Typ | Beschreibung | |
|---|---|---|---|
| Id | Integer | Optional | Wird von PackApp vergeben |
| Quantity | Integer | Anzahl der Packstücke | |
| Content | String | Bezeichnung des Inhalts | |
| Length | Decimal | Länge des Packstückes | |
| Width | Decimal | Breite des Packstückes | |
| Height | Decimal | Höhe des Packstückes | |
| Weight | Decimal | Gewicht des Packstückes | |
| Color | String | Farb-Id (Details siehe Online-Hilfe CSV-Import) | |
| Priority | Integer | 1=Hoch 2=Normal 3=Niedrig | |
| Rotatable | Bool/td> | Packstück längs oder quer staubar | |
| OnTop | Bool | Packstück darf auf anderes Packstück gestapelt werden | |
| AsLower | Bool | Packstück darf bei Stapelung unten stehen | |
| PackageType | String |
Art des Packstücks, einer der Werte:
|
Options
Die Berechnungs-Optionen können in „Options“ übergeben werden.
| Name | Typ | Beschreibung | |
|---|---|---|---|
| Config | String | „Truck“ oder „Container“ | |
| SaveOnly | Bool | Optional | true, wenn die Daten nur gespeichert und keine Berechnung durchgeführt werden soll. |
| StackingHeight | Decimal | Optional | Maximale Höhe für die Bildung von Stapeln |
| Levels | Int | Optional | Maximale Anzahl von Stapelebenen |
| TransportUnitTypes | String-Aufzählung |
Für Container eine Kombination der Werte:
|
|
| OffsetWidth | Int | Optional | Abzug von der verfügbaren Innenbreite der Transport-Einheit |
| OffsetLength | Int | Optional | Abzug von der verfügbaren Innenlänge der Transport-Einheit |
| OffsetDoorHeight | Int | Optional | Abzug von der nutzbaren Türhöhe |
| OffsetDoorWidth | Int | Optional | Abzug von der nutzbaren Türbreite |
| WeightLimitSquareMeter | Decimal | Optional | Gewichtslimit pro Quadratmeter |
| SizeOffset | int | Optional | Maximaler Größenunterschied zwischen Packstücken die gestapelt werden dürfen |
Result
Der Bereich „Result“ enthält die Ergebnisse einer Berechnung. Wenn eine Berechnung gestartet oder gespeichert wird, wird dieser Teil des JSON nicht verwendet. Er wird von PackApp mit den Berechnungsergebnissen gefüllt, wenn eine Berechnung über die Schnittstelle zurückgegeben wird.
| Name | Typ | Beschreibung | |
|---|---|---|---|
| Status | String |
Einer der folgenden Werte:
|
|
| TransportUnits | TransportUnit-Aufzählung | Liste der Transporteinheiten, die für das Packen benötigt wird. |
Die erste Ebene enthält den Status und eine Liste von Transporteinheiten. Die Transporteinheiten enthalten eine Beschreibung der Transporteinheit, also Typ und Größe sowie den gepackten Inhalt in Form einer Liste von Stapeln („Stack“).
| Name | Typ | Beschreibung | |
|---|---|---|---|
| Id | String | Eindeutige Id, die von PackApp zugewiesen wird | |
| Description | String | ||
| TransportUnitType | String |
Container:
|
|
| UsedLoadMeters | Decimal | Verwendete Lademeter in der Transporteinheit | |
| ContainerTemplateId | Integer | Id des Transporteinheiten-Typs | |
| Stacks | Stack-Aufzählung | Liste mit Packstück-Stapeln, die in diese Transporteinheit gepackt wurden |
Stack
Ein „Stack“ beschreibt einen Stapel in einer Transporteinheit an einer bestimmten Position. Dieser besteht aus mindestens einem „Package“ bzw. Packstück.
| Name | Typ | Beschreibung | |
|---|---|---|---|
| X | Decimal | X-Position in cm in der Transporteinheit. | |
| Y | Decimal | Y-Position in cm in der Transporteinheit. Die Koordinate 0,0 bezeichnet die Position oben links im Aufsicht-Plan (Stirnseite-Rechts) | |
| Length | Decimal | Kombinierte Länge des Stapels | |
| Width | Decimal | Kombinierte Breite des Stapels | |
| Height | Decimal | Kombinierte Höhe des Stapels | |
| Packages | Package-Aufzählung | Liste der Packstücke, aus denen der Stapel besteht (mindestens eins) |
Package
Die Packstücke enthalten folgende Eigenschaften:
| Name | Typ | Beschreibung | |
|---|---|---|---|
| ItemNo | String | Packstück-Nummer bestehend aus der Listenposition und einer fortlaufenden Nummer, z.B. 01.002 | |
| Length | Decimal | Länge des Packstückes | |
| Width | Decimal | Breite des Packstückes | |
| Height | Decimal | Höhe des Packstückes | |
| Volume | Decimal | Volume des Packstückes | |
| Weight | Decimal | Gewicht des Packstückes | |
| X | Decimal | X-Koordinate relativ zum Stapel | |
| Y | Decimal | Y-Koordinate relativ zum Stapel | |
| Z | Decimal | Z-Koordinate relativ zum Stapel Das unterste Packstück hat die Koordinate 0,0,0, die anderen Packstücke des Stapels werden relativ dazu angegeben. | |
| Sequencenumber | int | Laufende Nummer im Stapel | |
| Content | String | Inhalt des Packstückes | |
| Color | String | Farbwert |
REST-Funktionalität
Die PackApp-API ist unter der Basis-URL der Schnittstelle https://apiextern.packapp.info/api erreichbar. Die URL wird ergänzt um den Resourcen-Typ „Calculation“, die komplette URL lautet also https://apiextern.packapp.info/api/calculation.
Unter dieser URL werden die verschiedenen unterstützten Aktionen über das http-Protokoll nach dem REST-Standard angeboten.
Damit können Sie auch mit beliebten Rest-Tools wie „Postman“ auf die Schnittstelle zugreifen.
Authentifizierung
Um mit der PackApp-Schnittstelle zu kommunizieren, muss sich ihr System zunächst authentifizieren. Dies wird über das OAuth2.0 Protokoll durchgeführt. Die dazu notwendigen Zugangsdaten, die „Client-Id“ und „Client Secret“, erhalten Sie als registrierter Benutzer auf Anfrage von NextCargo.
Der Wert für den sogenannten „Scope“ ist „PackApp.Api.External“. An der URL https://login.nextcargo.net/connect/token kann mit diesen Daten ein Zugriffs-Token angefordert werden, mit dem nachfolgende Aufrufe an die PackApp-API erfolgen können.
Dieses Token wird dann im Authorization-Header als sogenanntes „Bearer-Token“ übergeben.
Details zum Erhalt und zur Übergabe des Tokens entnehmen Sie bitte der OAuth 2.0 Spezifikation.
Berechnung anlegen/starten (HTTP-Post)
Zum Berechnen einer Packliste wird eine JSON-Struktur im Request-Body mit dem HTTP-Verb „POST“ an https://apiextern.packapp.info/api/calculation gesendet.
Es müssen nur die Bereiche „Header“, „Packlist“ und „Options“ der JSON-Struktur gefüllt werden. Möchten Sie lediglich die Daten an PackApp übergeben ohne die Berechnung zu starten, setzen Sie in den Optionen den Wert für „SaveOnly“ auf „true“.
| URL | https://apiextern.packapp.info/api/calculation |
| HTTP-Methode | POST |
| HTTP Rückgabe-Werte | 201 Created: Berechnung erfolgreich gespeichert/gestartet 400 Bad Request: Es ist ein Fehler aufgetreten 401 Unauthorized: Fehlende Berechtigung |
| Zurückgegebener Content | Im Erfolgsfall (201) wird eine neues Calculation-JSON zurückgegeben. Dieses enthält im Header die neue Id, die für spätere Referenzierung verwendet werden kann. In Result.Status kann abgelesen werden, ob die Berechnung gestartet wurde oder bereits fertig ist |
Berechnungsdaten lesen (HTTP-Get)
Zum Lesen einer vorhandenen Berechnung wird ein HTTP-Get an die Schnittstelle gesendet. Die Id der gewünschten Berechnung wird als URL-Parameter „Id“ übergeben.
Im Feld Result.Status kann abgelesen werden, ob die Berechnung bereits abgeschlossen ist oder noch läuft. In diesem Fall kann dieser Get später nochmals ausführt werden.
| URL | https://apiextern.packapp.info/api/calculation/Id |
| HTTP-Methode | GET |
| HTTP Rückgabe-Werte | 200 OK: Berechnung wurde erfolgreich zurückgegeben 400 Bad Request: Es ist ein Fehler aufgetreten 401 Unauthorized: Fehlende Berechtigung 404 Not Found: Berechnung wurde nicht gefunden |
| Zurückgegebener Content | Calculation-JSON für die angeforderte Id. In Result.Status kann abgelesen werden, ob die Berechnung gestartet wurde oder bereits fertig ist. |
Berechnung löschen (HTTP-DELETE)
Über die Http-Methode „Delete“ kann eine vorhandene Berechnung gelöscht werden. Die Id der zu löschenden Berechnung wird als URL-Parameter übergeben.
| URL | https://apiextern.packapp.info/api/calculation/Id |
| HTTP-Methode | DELETE |
| HTTP Rückgabe-Werte | 200 OK: Berechnung wurde erfolgreich gelöscht 400 Bad Request: Es ist ein Fehler aufgetreten 401 Unauthorized: Fehlende Berechtigung 404 Not Found: Berechnung wurde nicht gefunden |
| Zurückgegebener Content | Kein Content |
Beispiel mit Postman
Bevor Sie eine eigene Client-Anwendung entwickeln, können Sie die PackApp-API zum Beispiel mit dem Tool „Postman“ testen.
Das folgende Beispiel zeigt, wie Sie das Ergebnis einer Berechnung als JSON über die API abrufen. Als Methode wird „GET“ ausgewählt.
Die Url lautet somit https://apiextern.packapp.info/api/calculation/110471
Die 110471 entspricht hier der ID der Berechnung, d.h. Sie müssen eine gültige Id aus den Berechnungen, die Sie bereits durchgeführt haben, eintragen.
Unter Authorization muss als „Type“ der Wert „OAuth 2.0“ gewählt werden.
Die Eingabemaske in Postman sieht dann wie folgt aus:
Dann müssen Sie ein Zugangs-Token anfordern.
Statt „YourClientID“ und „YourClientSecret“ geben Sie bitte die Werte an, die Sie von uns erhalten haben.
Abbildung: Authorization in Postman
Nachdem Sie das Token erhalten haben, können Sie der Get-Request absenden. Der HTTP sollte 200 OK lauten und das Ergebnis der Berechnung als JSON angezeigt werden:
Abbildung: Get Request in Postman
