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.myweshop.com/paazl/push.

You specify the URL in your Paazl web app account.

Note

Before registering your endpoint with Paazl, ensure that it can receive POST messages.

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.

Note

Do not choose a password when generating a client certificate for Paazl's Push API.

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): 87.233.148.159/staging.paazl.com
  • Production environment: 87.233.148.157/jobs01.paazl.com

Server responses

Note

You have to return an HTTP 200 status code if a Push request is successful. If your server returns anything other than a HTTP 200 status code it will assume that the Push request concerned has failed. It will send you an error message and its retry-policy will kick in.

A common mistake is to not send any response at all, or, for example when order creation fails in your webshop, to pass an internal webshop error back to Paazl's Push API. Please make sure you return an HTTP 200 status code if Paazl has successfully sent you an update, regardless of what your webshop does with that update.

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.

Note

If you change the message format, the change will be reflected immediately in the datebase. However, because the configuration settings are cached, it will take 5 minutes before the change actually takes effect.

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

Parameter Required / Optional Explanation
contentType Required

This parameter can have one of two values depending on the format you specify in your Paazl web app account:

  • "application/json"
  • "application/xml"
authorization Optional

This is the value of the security token you generate in your Paazl web app account.

If you use a security token, you can be sure that the status updates you receive have been sent by Paazl.

Note

The security token is a bearer key.

Body

Parameter Required / Optional Type Explanation
orderReference Required String

Example: reference:"myOrder00123"

webshop Required Integer

Paazl’s internal code for your webshop. You will find it in your Paazl web app account under Settings > Account > My account > Login details > Webshop ID.

Example: webshopId: 697

barcode Required String

A shipping label's barcode, either provided by a carrier, or by Paazl within a range specified by the carrier concerned

Example: barcode: "3STESP0125770"

status Required String

The Paazl delivery status of a shipment.

About Paazl delivery status codes explains what the various codes mean.

Note

In principle, Paazl will only send a given status once for a particular shipment. However, if a shipment is returned, Paazl may send some statuses twice.

Note

If a shipment's status changes while the Push API is disabled, those statuses will not be sent when the API is re-enabled.

Note

The Push API does not keep a status history. It only sends real-time statuses

Possible values are: "CREATED", "DELETED", "READY_TO_POST", "SCANNED", "AVAILABLE_AT_PICKUP_POINT", "DELIVERED", "DELIVEREDBB", "RETOUR", "PICKEDUP", "UITLEVERING", "UNKNOWN", "MANCO", and "NOT_AT_HOME"

carrierStatus Optional Object

Contains details of delivery status of a shipment as provided by a carrier.

Note

This attribute is not in use yet

name Optional String

The status code

Note

This attribute is not in use yet

Example: name: "Scanned"

description Optional String

A description of the status code

Note

This attribute is not in use yet

Example: description: "Shipment awaiting pickup in warehouse"

deliveryDate Optional String

The date on which a shipment will be delivered to a home address or a pick-up location.

Format: "YYYY-MM-DD”

Example: deliveryDate: "2019-04-02"

trackTraceUrl Optional String

A URL of a web page containing track and trace information that is provided by a carrier.

Example: trackTraceUrl: "https://www.carrier.nl/track-trace?gclid=CPfEzday"

deliveryWindowStart Optional String

The global start of a delivery time range as configured by Paazl Customer Support. This is the fall-back if the time range start hasn't been set at a shipping option level.

Note

The time zone is usually omitted. If present, its default value will be "CET".

deliveryWindowEnd Optional String

The global end of a delivery time range as configured by Paazl Customer Support. This is the fall-back if the end of the time range hasn't been set at a shipping option level.

Note

The time zone is usually omitted. If present, its default value will be "CET".

deliveryInformation Optional String

Additional information concerning the delivery of a shipment.

Note

This attribute is currently not in use

Example: deliveryInformation: "If not at home, deliver at neighbor"

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>

Was this article helpful?