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:
<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): 34.90.21.169/staging.paazl.com
- Production environment: 34.91.233.81/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
<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:
|
| 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 (in development) |
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 (in development) |
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 (in development) |
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 (in development) |
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
<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>