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
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:
|
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
|
|
| 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:
|
|
| 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:
|
|
| 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
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
