Submitting a new delivery to be tracked by parcelLab is called creating a tracking. For this, different channels can be used:

Channel Notes
RESTful API Recommended for direct integration with own system
Email BCC Fastest integration, if shipping confirmation available
FTP Upload Recommended for batch upload
HTTP/ FTP Download Legacy option, not recommended

RESTful API

The API offers an endpoint to create a new tracking:

POST 'https://api.parcellab.com/track/'
HEADERS
+ user: Number
+ token: String
+ content-type: 'application/json'
BODY
+ payload: Object/JSON

The payload holds the tracking specific information, as specified in the glossary. All attributes are named key/value pairs in a flat JSON formatted object.

{
  "tracking_number": "1234567890",
  "courier": "dhl-germany",
  "zip_code": "12345",
  "deliveryNo": "LIEFNR-AB1234"
}

The result in the case of successful call, the return has status code 202 and reads Accepted.

Requests that are structurally fine but contain insufficient data or other errors return status code 400 with an error info in the body like Invalid request. Internal errors are met with a 500, and in critical cases with an error reference like so: Error encountered. Please contact support with reference: SOMEHASH.

Below, examples in different languages for interfacing with the API endpoint are given.

curl

For a simple test, cURL can be used:

echo '{"tracking_number": "1234567890", "courier": "dhl-germany"}' | curl -d @- https://api.parcellab.com/track/ -H "Content-Type: application/json" -H "user: 1" -H "token: parcelLabAPItoken-30characters"

Examples in other Frameworks/ Languages

Further examples, in jQuery, Node, Ruby, Python (Requests), PHP, and Go, can be found on the very top of our extended API documentation. You can select your target langauge on the top-right corner.

Event more examples, e.g. in C, C#, Java, Shell formats, can be provided upon request by our support team.

FTP Upload

Note: To activate this feature and retrieve credentials, please get in contact with the parcelLab Team.

To create more than one tracking in a batch, either a CSV file or a XML document can be uploaded to the FTP server. Connection to our FTP is secured with its own certificate.

Option 1: CSV Files

There are requirements for the uploaded CSV file (see the sample file):

A list of all possible columns can be found in the data model.

Option 2: XML Documents

Alternatively, XML documents can be uploaded. This is preferred over CSV files, if also a list of articles per tracking should be transmitted.

We do prefer simple, nested XML documents. We do offer an example document, as well as a XSD with the most commonly used keys and the overall structure.

The list of all possible fields again can be found in the data model.

Connecting to the FTP

Our server can be reached via:

Protocol: FTP-SSL (Explicit Auth TLS)
Server: upload.parcellab.com
Port: 21
Path: /
Connect Mode: Passive
Encoding: UTF-8

Uploaded files are archived by the system after successful import, i.e. moved out of the import folder. The import is event driven and should be done a couple of seconds after upload depending on the size of the uploaded file.

Q: The connection times out when listing the directory.
A: If the connection times out on listing the directory contents right after authenticating successfully, this is most likely due to an active firewall. On the client site, the outgoing ports 35000 - 36000 have to be opened.

Q: The connection cannot be established because the server’s certificate cannot be verified.
A: If the uploading machine does not accept the certificate during upload, the FTP server’s certificate can be downloaded and provided directly to the uploading machine. By adding it to the certificate store, it will be accepted when connecting.

Automated FTP Upload with winscp

A connection via winscp from Windows hosts to automatically upload tracking numbers can be achieved with this command (which can be run simply by putting it into a .bat-file):

"$path-to-winscp-com-file" /certificate=28:42:b8:ef:45:c8:5d:10:24:da:54:2c:5d:69:fd:50:f5:c4:43:a9 /command "open ftp://$username:$password@upload.parcellab.com:21/ -explicittls" "put $your-file" "close" "exit"

First locate your WinSCP.com, usually located at C:\Program Files (x86)\WinSCP\WinSCP.com. Then insert you $username and $password and define which files to upload. You can use an explicit filename like Tracking-Data-for-parcelLab.csv or a wildcard like *.csv.

Note: The parameter /certificate= includes our server’s certificate’s fingerprint, because this is a self-signed certificate.

HTTP/ FTP Download

Note: To activate this feature, please get in contact with the parcelLab Team.

If you prefer to simply provide a CSV file to be exported, we can activate an automated import as well. Please make sure to enable a secure connection from the host via SSL/TLS. For the CSV file, the same requirements as for FTP Upload apply. Please get in contact with us and provide us with the endpoint and credentials.