PackApp Programming Interface (Rest-API) and PackApp-JSON

This article gives you a short introduction to the procedure of integrating PackApp with your own software by use of the PackApp Rest-API and PackApp-JSON.

Take full advantage of PackApps fast and efficient calculation of freight packing lists whilst not leaving your familiar development environment. Create an interface between PackApp and your software to ensure seamless data flow!

The PackApp-API allows you the following operations:

  • Transferring packing lists to PackApp originating in different applications
  • Setting of calculation parameters and starting of calculations
  • Querying calculation results
  • Deleting calculation results

In order to use the PackApp-API you need a valid user registration as well as a Client-Id and separate password (see authorization), both of which will be placed at your disposal upon request.

Data format JSON

While JSON is the standard, the PackApp-API supports both data in JSON and XML. XML is not part of this introduction.

The following example shows you a simple container-calculation consisting of one packing list comprising two positions.


    

To view JSON in regard to a calculation open the corresponding calculation results and use the menu item “calculation/download JSON” to download the according JSON:

Abbildung: Download JSON
Download JSON

Description of JSON data structure

JSON is divided into four category groups:

Header General information, e.g. a description
Packlist Packing list including the data to be calculated
Options Calculation options
Result Calculation result

Header

The header contains:

Name Type Description
Id Integer Optional Calculation-Id, is being assigned by PackApp automatically. Cannot be set for a new calculation.
Description String 50 Description/Title

Packlist

The category “Packlist” consists of a listing of entries in form of “PackListItem”. Each PackListItem includes the information that is found in the calculation input form:

Name Type Description
Id Integer Optional Being assigned by PackApp
Quantity Integer Quantity of packages
Content String Description of content
Length Decimal Length of package
Width Decimal Width of package
Height Decimal Height of package
Weight Decimal Weight of package
Color String Color-Id (For details see PackApp-Online-help for CSV-Import)
Priority Integer 1=High 2=Normal 3=Low
Rotatable Bool/td> Package stackable length- resp. crosswise
OnTop Bool Package can be stacked on top of another package
AsLower Bool Package can be stacked at the bottom
PackageType String AType of package; one of the bellow:
  • Euro-Pallet
  • Disposable pallet
  • Box
  • Crate
  • Carton
  • Drum
  • Barrel
  • Unpacked
  • Other
  • Carton on pallet
  • Euro-pallet cage

Options

All options regarding the calculation can be transferred to the category “Options”.

Name Type Description
Config String „Truck“ or „Container“
SaveOnly Bool Optional True, if data is only to be saved without performing a calculation.
StackingHeight Decimal Optional Max height of stackings
Levels Int Optional Max number of stacking levels
TransportUnitTypes String list Containers: a combination of
  • Standard20Ft
  • Standard40Ft
  • Highcube40Ft
  • OpenTop20Ft
  • OpenTop40Ft
Trucks: one of the bellow
  • Truck1
  • TruckWithTrailer1
  • Truck7x5t
OffsetWidth Int Optional Deduction of the transportation unit´s available inside width
OffsetLength Int Optional Deduction of the transportation unit´s available inside length
OffsetDoorHeight Int Optional Deduction of the available door height
OffsetDoorWidth Int Optional Deduction of the available door width
WeightLimitSquareMeter Decimal Optional Weightlimit per squaremeter
SizeOffset int Optional Max size difference of packages in order to be stacked

Result

The category “Result” contains the calculation results. This part of JSON is not used in case of starting or saving a calculation. Naturally it will be filled upon returning the calculation results via the API.

Name Type Description
Status String One of the bellow:
  • Queued = Waiting for calculation
  • Running = Running of calculation
  • Completed = Completion of calculation
  • Error = An error has occurred/li>
TransportUnits TransportUnit list Listing of transportation units to be used for packaging

The first level consists of the status and a listing of transportation units. The transportation units themselves include the description of the transportation unit (type and size) as well as the packed content in form of a listing of stackings.

Name Type Description
Id String Unique Id assigned by PackApp
Description String
TransportUnitType String Container:
  • Standard20Ft
  • Standard40Ft
  • Highcube40Ft
  • OpenTop20Ft
  • OpenTop40Ft
LKW:
  • Truck1
  • TruckWithTrailer1
  • Truck7x5t
UsedLoadMeters Decimal Utilized loading meters in regard to the transportation unit
ContainerTemplateId Integer Id of transportation unit type
Stacks Stack list Listing of package stacks packed into this transportation unit
Stack

“Stack” describes a stacking at a defined postion within a transportation unit consisting of at least one package.

Name Typ Beschreibung
X Decimal X-Position in cm in regard to the transportation unit
Y Decimal Y-Position in cm in regard to the transportation unit The coordinates 0,0 designate the position in the upper left of the top-view (front side right)
Length Decimal Combined length of stacking
Width Decimal Combined width of stacking
Height Decimal Combined height of stacking
Packages Package list Listing of packages that make up a stacking, at least one
Package

„Packages“ include:

Name Type Description
ItemNo String Package number consisting of the listing position and a serial number, e.g. 01.002
Length Decimal Length of package
Width Decimal Width of package
Height Decimal Height of package
Volume Decimal Volume of package
Weight Decimal Weight of package
X Decimal X-coordinate relativ to stacking
Y Decimal Y-coordinate relativ to stacking
Z Decimal Z-coordinate relativ to stacking The package at the bottom has the coordinates 0,0,0, all others are being defined in relation to this package
Sequencenumber int Serial number in stacking
Content String Content of package
Color String Color value

REST-Functionality

The PackApp-API is accessible under the interface base URL https://api.extern.packapp.info/api which is supplemented by the resource type “calculation”: https://api.extern.packapp.info/api/calculation.

All supported operations via http-protocol and REST standard can be found under this URL.

This also enables you to access the API using REST-tools like “postman”.

Authentification

In order to communicate with the PackApp-API your system is required to authentificate itself via the OAuth2.0 protocol. The access data like Client-Id and Client Secret will be forwarded to you upon request once you´re registered with PackApp.

Value for “Scope” is “PackApp.Api.External”.

These data allow you to request an access token at URL https://login.nextcargo.net/connect/token which further grants access to the PackApp-API.

The token is transferred as a “bearer-token” in the authorization header. More details regarding the obtainment and the tranfer of a token can be found in the OAuth 2.0 specification.

Setting up and starting of a calculation (HTTP-Post)

In order to calculate a packing list a JSON-structure in Request-Body with the HTTP-Verb “Post” will be sent to https://api.extern.packapp.info/api/calculation .

Within the JSON-structure only “Header”, “Packlist” and “Options” have to be filled in.

To transfer the data to PackApp without starting the calculation, simply set the field value for “SaveOnly” in “Options” to “true”.

URL https://api.extern.packapp.info/api/calculation
HTTP Method POST
HTTP Rückgabe-Werte 201 Created: Calculation saved successfully/started 400 Bad Request: Error occurrence 401 Unauthorized: Missing authorization
Returned Content In case of success (201) a new calculation-JSON will be returned that contains the new Id in „Header“ to be used for referencing lateron. The Result.Status shows whether a calculation has been started or is completed.

Read Calculation data (HTTP-Get)

In order to read an already existing calculation a HTTP-Get is being sent to the API, the corresponding Id will be transferred as URL parameter “Id”.

“Result.Status” will show if the calculation is completed yet. If the calculation is still in progress, the Get can be executed again at a later time.

URL https://api.extern.packapp.info/api/calculation/Id
HTTP Method GET
HTTP Return value 200 OK: Calculation returned successfully 400 Bad Request: Error occurrence 401 Unauthorized: Missing authorization 404 Not Found: Calculation not found
Returned Content Calculation-JSON for requested Id. Result.Status shows if calculation has been started or is already completed.

Delete calculation (HTTP-DELETE)

Delete an existing calculation via HTTP method “Delete”. The corresponding calculation´s Id is being transferred as URL parameter.

URL https://api.extern.packapp.info/api/calculation/Id
HTTP Method DELETE
HTTP Return value 200 OK: Calculation deleted successfully 400 Bad Request: Error occurrence 401 Unauthorized: Missing authorization 404 Not Found: Calculation not found
Returned content No content

Example using Postman

Before programming your own client application you can test the PackApp-API using a popular tool like “Postman”.

The following example shows how to request the calculation result as JSON using the API. Chosen method is “GET”, thus the URL is https://api.extern.packapp.info/api/calculation/110471 .

110471 corresponds to the calculation´s Id, i.e. here you have to enter a valid calculation Id stemming from an already completed calculation.

In “Authorization” choose “type” value “OAuth 2.0“.

The ”Postman” input mask will then look like this:

Then you have to request an access token. For “YourClientId” and “YourClientSecret” please use the values you received from NextCargo.

Image: Authorization in Postman
Postman Rest Authorization

Upon receiving the token you can submit the Get-Request. The HTTP-code should be 200 OK and show the JSON of the requested calculation.

Image: Get Request in Postman
Postman Rest Get Request