Carrier integration

This documentation covers how a new carrier can be integrated. This documentation is meant for freight and home delivery carriers, not for courier, parcel and express deliveries.

If there's a need for setting up a new interface, consider these guidelines. The following guidelines can be understood as a point of reference rather than strict requirements.

πŸ‘·β€β™€οΈPlease read me first:

If the carrier already features some means of providing status information, please do not follow this guide. parcelLab will integrate with the carrier. So if there is already an interface via API, Push/ Webhook or File-based, please reach out to:

​support@parcellab.com​

This guide will cover the following topics:

  1. Data transmission: How to get data from the carrier to parcelLab.

  2. Scans and status events: The data model on how to describe and format scans and other events during delivery.

  3. Live geo tracking: The data model on how to describe the live position of the truck during the last mile.

Overview

Goal of this integration guide is to show how carriers can send their relevant status data to parcelLab. This covers discrete scans during the delivery, which represent the information usually shown on a track & trace page. It also includes a tour plan for the last mile of the delivery, where the individual stops of the truck are listed. During last mile delivery, the truck can send its current geo coordinates.

Checklist and how-to

πŸ‘·β€β™€οΈ Please consider this a guide on how to approach this documentation:

  • Decide how you want to send your data to parcelLab: You can send your data via the parcelLab API or file-based via SFTP (section data transmission).

  • You will need credentials to send data for both SFTP (server, username, password) as well as API (token), so reach out to support@parcellab.com to get them.

  • Your system will already have scans and status events, so you can with the according setup (section scans and status events).

  • Typically, you won't have the scheduling where you decide in what time window the goods will probably be delivered as an event. So this will be an additional event to be provided to parcelLab (section scans and status events).

  • After this is done, we can tackle the live geo tracking. First, you'll have to link every order/ shipment to a tour, so parcelLab knows what order is on which truck (section live geo tracking). You can either explicitly tell us your tour plan, our you implicitly book an order onto a tour by extending the scan/ status event.

  • Finally, you start sending the geo coordinates of each truck every few minutes (section live geo tracking).

We recommend going through list from top to bottom, as the individual steps build on each other.

Data transmission

This section will cover how to send data to parcelLab. Data transfer is independent from the content of the transfer itself, which is covered in its respective sections. There are three ways to do send updates for both scans and status events as well as live geo tracking to the parcelLab system:

  1. Calling the parcelLab API

  2. Providing an API for parcelLab to call

  3. Sending files to parcelLab

Scans and status events

Scans and status events describe discrete scans (like a goods receipt scan at the warehouse) or an event of the delivery planning (like the confirmation of the planned delivery time via phone with the recipient). This section gives details about the structure of such scans and status events as well as how to transmit them to parcelLab.

Live geo tracking

parcelLab's live geo tracking aims to provide the recipient with a very detailed current status of their delivery during the last mile, i.e. when goods have been loaded onto the delivery truck and are on their final way to the recipient.

Therefore, we consider the current status of a delivery on its last mile to consists of:

  • Current location of the delivery truck on a map

  • Progress of the tour of the truck, i.e. how many other stops will be done before the truck will arrive at the recipients location

  • If available, estimated time of delivery based on the current progress

We describe how to transfer that information here:

​