Push API reference

This article provides the REST specifications of Paazl's Push API.

The Paazl Push API pro-actively sends delivery status updates to your webshop server every time there is a change in a shipment's status.

See Generating a Push API server for an explanation of how to generate a server template that you can use to create an endpoint to receive the status updates.

Endpoint

This is the URL of the REST endpoint you have created to receive the status updates. It specifies the scheme, host, base path and path, for example:

https://api.mywebshop.com/paazl/push

You specify the URL in your Paazl web app account.

In the case of a Java implementation using a POM file, include the following dependency to enable your endpoint to receive XML objects:

<dependency>
   <groupId>com.fasterxml.jackson.dataformat</groupId>
   <artifactId>jackson-dataformat-xml</artifactId>
   <version>2.8.9</version> <!--or later -->
</dependency>

Authentication & authorization

The Push API offers two client authentication methods: one based on a security token—more specifically a bearer token—and one based on a client certificate. Both are optional and you can use them together. Security tokens are easier to implement than client certificates, which might prove challenging for novice developers.

Once you have implemented an authentication method on the Paazl side, you also have to implement it on the webshop side.

Security token

The easiest authentication method to implement is the security token. When active, Paazl sends a header called Authorization with each push notification in order for the webshop server to confirm that the message originates from our API.

The value of the header Authorization will be in the format Bearer cf50ed66-154e-4f5c-8818-e7a770d644b8 where the hash is the hash you generate on the Push API configuration page.

Client certificate

You can also use a client certificate to implement an authentication method. Paazl only supports PKCS12 certificates. Use a tool such as OpenSSL to generate client certificates. Once you have generated a .p12 file, upload it using the Push API configuration page.

Whitelisting

Whitelisting is an additional security measure, which ensures that only API calls from a specific URL will be recognised. We recommend that you whitelist Paazl's Push API. Use the following IP addresses for this purpose.

• Staging (acceptance testing): 34.90.21.169/staging.paazl.com
• Production environment: 34.91.233.81/ship.paazl.com

Server responses

HTTP method

Paazl's Push API sends requests using the POST method.

Message format

The Push API can send messages in either XML or JSON format. XML is the default. Specify the message format in your Paazl web app account.

Schema

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="http://www.paazl.com/schemas/push"
           xmlns:push="http://www.paazl.com/schemas/push"
           elementFormDefault="qualified">

    <xs:element name="labelStatusNotification" type="push:labelStatusNotification" />

    <xs:complexType name="labelStatusNotification">
        <xs:all>
            <xs:element name="orderReference" type="xs:string"/>
            <xs:element name="webshop" type="xs:long"/>
            <xs:element name="barcode" type="xs:string"/>
            <xs:element name="status" type="push:paazlStatusType" />
            <xs:element name="carrierStatus" type="push:carrierStatus"/>
            <xs:element name="deliveryDate" type="xs:dateTime"/>
            <xs:element name="trackTraceURL" type="xs:string"/>
            <xs:element name="deliveryWindowStart" type="xs:time" />
            <xs:element name="deliveryWindowEnd" type="xs:time"/>
            <xs:element name="deliveryInformation" type="xs:string"/>
        </xs:all>
    </xs:complexType>

    <xs:simpleType name="paazlStatusType">
        <xs:restriction base="xs:string">
            <xs:enumeration value="CREATED"/>
            <xs:enumeration value="DELETED"/>
            <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="UNKNOWN"/>
            <xs:enumeration value="MANCO"/>
            <xs:enumeration value="NOT_AT_HOME"/>
        </xs:restriction>
    </xs:simpleType>

    <xs:complexType name="carrierStatus">
        <xs:sequence>
            <xs:element name="name" type="xs:string"/>
            <xs:element name="description" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>

</xs:schema>

Explanation of parameters

Header

Body

Sample update messages

JSON

{
   "orderReference": "ref123",
   "webshop": 8,
   "barcode": "AABBCCEEFFG",
   "status": "CREATED",
   "deliveryDate": "2017-07-17T16:00",
   "trackTraceURL": "https://www.dhlexpress.nl/nl/track-trace?gclid=CPfEzdayhtUCFekp0wode38N7w",
   "deliveryWindowStart": "08:00",
   "deliveryWindowEnd": "13:00"
}

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <ns2:labelStatusNotification xmlns:ns2="http://www.paazl.com/schemas/push">
   <ns2:orderReference>ref123</ns2:orderReference>
   <ns2:webshop>8</ns2:webshop>
   <ns2:barcode>ABCC</ns2:barcode>
   <ns2:status>CREATED</ns2:status>
   <ns2:deliveryDate>2017-07-17T04:00:00</ns2:deliveryDate>
   <ns2:trackTraceURL>
    https://www.dhlexpress.nl/nl/track-trace?gclid=CPfEzdayhtUCFekp0wode38N7
   </ns2:trackTraceURL>
   <ns2:deliveryWindowStart>08:00:00</ns2:deliveryWindowStart>
   <ns2:deliveryWindowEnd>12:00:00</ns2:deliveryWindowEnd>
   </ns2:labelStatusNotification>