Retrieving a tracking from parcelLab refers to the act of requesting the information about a certain delivery from parcelLab to be used somewhere else, e.g. in the user account within the shop interface, to indicate the progress of the delivery to the recipient. We call this information about the progress up to now the trace. For this, also different channels can be used, of which only one is ready for production as yet:

Channel Notes
RESTful API Recommended for direct integration with own system
Tracking Website No integration effort at all, just link to a URL
JavaScript Libraries For super-fast integration in own shop, with possible customization

RESTful API

Request

The API offers an endpoint to retrieve the information about a tracking, for that tracking number and courier code need to be supplied in the URL:

URL Parameter Description
tno Tracking number of the tracking
courier Courier code of the tracking
lang Language for result as ISO 3166-1 alpha-3
GET 'https://api.parcellab.com/v2/checkpoints/'
QUERY
+ tno: String
+ courier: String
+ lang: String

Return

The return of a successful call of this endpoint yields status code 200 OK, and an JSON encoded response object. This object consists of a header and body.

Return Header

The header is an array listing an overview over all trackings returned. When requesting the API like documented here with a combination of courier and tracking_number the array with always have header.length === 1.

The overview for each tracking (see example) is structured like this:

Key Type Description
id String id of the tracking which serves as key in the body
tracking_number String tracking number of the tracking
courier Object details about the courier, explained below
last_delivery_status Object details about the current status of the tracking, explained below
delay Boolean true if a delay of this delivery has been detected by parcelLab
exception Boolean true if an escalated problem has been detected

Return object courier

Key Type Description
name String the courier code (e.g. dhl-germany)
prettyname String pretty name of the courier to be displayed (e.g. DHL)
trackingurl String URL of courier’s own tracking page
trackingurl_label String localized label for trackingurl

Return object last_delivery_status

Key Type Description
status String see below in description of checkpoints
status_details String see below in description of checkpoints
code String see below in description of checkpoints

Return Body

The body simply is an object where for each tracking in the header, identified by their id, an array of checkpoints is given. This array has the following structure:

Key Type Description
shown Boolean parcelLab automatically filters checkpoints provided by the courier which are unclear and do not help the recipient to understand the current status of the delivery. These unclear status are marked with false.
status String One of the parcelLab status codes
status_text String A localized short description of the current status of the delivery
status_details String A localized longer, more detailed description of the current status of the delivery
full_courier_status String The full status code provided by the courier for reference, not recommended to display to recipient
location String Location of checkpoint if available, else empty string ""
timestamp String Date and time of checkpoint formatted as Date.prototype.toJSON()

Example of Return

{
  "header": [
    {
      "id": "579f6444b6a1bb4fbaab5610",
      "tracking_number": "00340000000000000001",
      "courier": {
        "name": "dhl-germany",
        "prettyname": "DHL",
        "trackingurl": "https://nolp.dhl.de/ne~~~00001",
        "trackingurl_label": "Klicken Sie hier für weitere Informationen zur Sendung."
      },
      "last_delivery_status": {
        "status": "Zugestellt",
        "status_details": "Die Ware wurde erfolgreich zugestellt.",
        "code": "Delivered"
      },
      "delay": false,
      "exception": false
    }
  ],
  "body": {
    "579f6444b6a1bb4fbaab5610": [
      {
        "shown": true,
        "status": "OrderProcessed",
        "status_text": "Bestellung verarbeitet",
        "status_details": "Die Bestellung wurde verarbeitet.",
        "full_courier_status": "If exists, date of order, else date of import to parcelLab",
        "location": "Sample City",
        "timestamp": "2015-08-10T15:18:27.000Z"
      }
    ]
  }
}

Tracking Website

We offer a free to use, high performant tracking website to be exposed to the recipient of a tracking. This website follows a simple URL scheme, and is activated for any tracking in the parcelLab system by default. To have it included into any notification by default, just let us know. The tracking website can be reached at either versand-status.de or paket-fuer-mich.de. The URL scheme is identical to the API endpoint, i.e.:

http://www.versand-status.de/?courier=gls&trackingNo=63239781053

JavaScript Libraries

parcelLab becomes prepared with JavaScript libraries, which can be used to integrate the API in asynchronous fashion directly in the browser without much effort. This can be done without customization through our CDN, or with customization on your own servers.

Through parcelLab CDN

All required libraries are hosted on our high-performant and high-available CDN. For this, following modifications have to be done on any page, where the trace of a tracking should be displayed.

1. Loading depenencies

At the bottom of the head of the website displaying the trace, following references to two CSS files need to be included. The first one does some simple formatting, the second one loads the Font Awesome Icons in version 4.4.0, which is guaranteed to be compatible.

<head>
  ...
  <link href="https://cdn.parcellab.com/css/v3/parcelLab.min.css" rel="stylesheet">
  <link href="https://cdn.parcellab.com/css/font-awesome.min.css" rel="stylesheet">
</head>

At the bottom of the body, the JavaScript references are included. This allows the website to be loaded and displayed, before any additional scripts are loaded.

<body>
  ...
  <script src="https://cdn.parcellab.com/js/v3/parcelLab.min.js" charset="utf-8"></script>
  <script type="text/javascript">
    var parcelLab = new ParcelLab('#parcelLab-trace-container'); // <~ where the trackings will be rendered...
    parcelLab.initialize();
  </script>
</body>

2. Preparing the content

Next, the container for the content to be shown needs to be defined in the body. For this, only the central node in the DOM where the trace should be included needs to be specified. The id (some-dom-id in the example below) has to referred to by the included JavaScript. If the default stylesheet should be applied to the trace (this recommended), then additional class="parcelLab-style" has to be added.

<div id="parcelLab-trace-container" class="parcelLab-style"></div>

3. Loading content

The code is prepared, the content container is present, now the script will automatically load and show the trace.

Identification of the tracking is read from the URL: for that you simply have to include the queries courier and trackingNo in the URL, analogous to the API or Tracking Website. The URL of the page then could look like this:

https://www.your-shop.com/order-status/?courier=gls&trackingNo=63239781053

Another optional key is &lang=de to specify language.

3. II. Search form (optional)

The plugin offers functionality to display a search form when the tracking page is opened without any tracking identifier. This search form performs a search on the field orderNo of the trackings. For that, the search form has be to be activated, and a valid and correct userId has to be supplied. This is the same userId as in the credentials.

To inject these settings, the function .initialize() has to be passed an object as parameter:

var parcelLab = new ParcelLab('#parcelLab-trace-container', {
  show_searchForm: true,
  userId: 123,
});
parcelLab.initialize();

4. Voilá

All done. To modify any behavior or styling of the code, the hosted libraries and stylesheets can be modified as described below.

Customize JavaScript Libraries

To modify any behavior or style of the code, all required resources are available in developer form as Open Source at GitHub / parcelLab / parcelLab-js-plugin. Feel free to fork or clone, change and host, or create pull requests.

Copy-paste snippets for shop platforms