About the tracking file
This article provides the technical details of the XML file that carriers place on the SFTP in order to update the delivery status of an order in Paazl. The file needs to contain Paazl delivery statuses and the unique identifier for parcels is the barcode as communicated via the registration file.
The file can be placed by the carrier at any time, Paazl will poll the SFTP folder for activity every 30 minutes. Depending on the setup of the webshop they will be able to use the order updates to notify their customers with actual parcel delivery statuses.
File name format
There are no filename requirements. Paazl will process any files placed by the carrier in its SFTP folder.
Element specifications
| Element | Type | Required? | Description |
|---|---|---|---|
| statuses | Complex element | Required |
Contains information on the delivery statuses of the various shipments making up an order. |
| status | Complex element | Required |
Contains information on the delivery status of a shipment in an order. The Paazl delivery status code for a shipment. See About Paazl delivery status codes for the meaning of the various codes. |
| timestamp | dateTime | Required |
The time when the delivery status of a shipment was registered. Optionally, you can include the original timezone expressed as an offset to UTC. For example: |
| barcode | String | Required |
The barcode that a carrier assigns to a shipping order |
| trackingURL |
String | Optional |
The tracking link that is generated by the carrier. Can be used to track the order. |
| carrierStatus | String | Optional |
A shipment's delivery status code as provided by the carrier |
| carrierStatusDescription | String | Optional |
A shipment's delivery status description as provided by the carrier |
| status | statusType | Required |
The Paazl delivery status code for a shipment. See About Paazl delivery status codes for the meaning of the various codes. |
| town | String | Optional |
The city or town of the address to which an order is being shipped. |
| country | String | Optional |
The ISO 3166-2 code for the country of the address to which an order is being shipped. |
| deliveryInformation | String | Optional |
Additional information concerning the status of a delivery |
| deliveryWindowFrom | time | Optional |
The start of a particular shipping option’s delivery time range. |
| deliveryWindowTo | time | Optional |
The end of a particular shipping option’s delivery time range. |
| version | String | Required |
The status of the delivery status code mapping used by a carrier |
| timestamp | dateTime | Required |
The time when this tracking file was sent |
The <status> element
The status element needs to contain one of the following values. Please map each status to a shipping status that corresponds with the current status of the shipment.
|
Delivery status |
Status code |
Explanation |
|
When sorted by carrier |
SCANNED |
The parcel has been picked up by your carrier and scanned in its sorting center |
|
Out for delivery |
UITLEVERING |
Delivery of the parcel is underway |
|
Delivered |
DELIVERED |
The parcel has been delivered to the shipping address |
|
Delivered at pick up point |
AVAILABLE_AT_PICKUP_POINT |
The parcel is ready for pick-up at the pick-up location concerned |
|
Delivered at neighbor |
DELIVEREDBB |
The parcel has been delivered at a neighbor’s address |
|
Picked up at pickup point |
PICKEDUP |
The parcel concerned has been picked up |
|
Consignee was not at home |
NOT_AT_HOME |
The parcel could not be delivered as there was no-one at home to receive it |
|
Undeliverable |
MANCO |
The parcel was not deliverable. Further action is needed to inform the customer |
|
Return |
RETOUR |
The order is being returned by the customer |
XSD
<xs:schema targetNamespace="http://www.paazl.com/schemas/tracking" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tracking="http://www.paazl.com/schemas/tracking">
<xs:element name="tracking">
<xs:complexType>
<xs:sequence>
<xs:element name="statuses" type="tracking:StatusesType"/>
</xs:sequence>
<xs:attribute name="version" type="xs:string" use="required"/>
<xs:attribute name="timestamp" type="xs:dateTime" use="required"/>
</xs:complexType>
</xs:element>
<xs:complexType name="StatusesType">
<xs:sequence>
<xs:element name="status" type="tracking:StatusData" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="StatusData">
<xs:sequence>
<xs:element name="timestamp" type="xs:dateTime"/>
<xs:element name="barcode" type="xs:string"/>
<xs:element name="trackingURL" type="xs:string"/>
<xs:element name="carrierStatus" type="xs:string"/>
<xs:element name="carrierStatusDescription" type="xs:string"/>
<xs:element name="status" type="tracking:statusType" minOccurs="0"/>
<xs:element name="town" type="xs:string" minOccurs="0"/>
<xs:element name="country" type="xs:string" minOccurs="0"/>
<xs:element name="deliveryInformation" type="xs:string" minOccurs="0"/>
<xs:element name="deliveryWindowFrom" type="xs:time" minOccurs="0"/>
<xs:element name="deliveryWindowTo" type="xs:time" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="statusType">
<xs:restriction base="xs:string">
<xs:enumeration value="READY_TO_POST"/>
<xs:enumeration value="SCANNED"/>
<xs:enumeration value="AVAILABLE_AT_PICKUP_POINT"/>
<xs:enumeration value="DELIVERED"/>
<xs:enumeration value="DELIVEREDBB"/>
<xs:enumeration value="RETOUR"/>
<xs:enumeration value="PICKEDUP"/>
<xs:enumeration value="UITLEVERING"/>
<xs:enumeration value="MANCO"/>
<xs:enumeration value="NOT_AT_HOME"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tracking xmlns="http://www.paazl.com/schemas/tracking" version="1.0" timestamp="2019-03-27T15:29:52.321Z">
<statuses>
<status>
<timestamp>2019-03-27T15:11:11+00:00</timestamp>
<barcode>231300687629631</barcode>
<trackingURL>https://www.carrier.com/en/orderinformation?12345</trackingURL>
<carrierStatus>4</carrierStatus>
<carrierStatusDescription>Shipper approves shipment for collection</carrierStatusDescription>
<status>SCANNED</status>
<town>Vianen</town>
<country>NL</country>
<deliveryInformation>Your package is colored blue</deliveryInformation>
<deliveryWindowFrom>10:00:00</deliveryWindowFrom>
<deliveryWindowTo>19:00:00</deliveryWindowTo>
</status>
</statuses>
</tracking>