Push API-referentie

Dit artikel bevat de REST-specificaties van de Push API van Paazl.

De Paazl Push API stuurt proactief updates over de leveringsstatus naar je webshopserver telkens wanneer er een wijziging is in de status van een zending.

Zie Een Push API-server genereren voor een uitleg over hoe je een server-template genereert die je kunt gebruiken om een eindpunt te maken voor het ontvangen van status-updates.

Eindpunt

Dit is de URL van het REST-eindpunt dat je hebt aangemaakt om de status-updates te ontvangen. Het geeft het schema, de host, het basispad en het pad aan, bijvoorbeeld:

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

Je geeft de URL op in je Paazl web-app-account.

In het geval van een Java-implementatie met een POM-bestand, voeg je de volgende dependency toe om je eindpunt in staat te stellen XML-objecten te ontvangen:

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

Authenticatie & autorisatie

De Push API biedt twee methoden voor clientauthenticatie: één op basis van een beveiligingstoken (meer specifiek een bearer-token) en één op basis van een clientcertificaat. Beide zijn optioneel en je kunt ze gecombineerd gebruiken. Beveiligingstokens zijn eenvoudiger te implementeren dan clientcertificaten, wat voor beginnende ontwikkelaars een uitdaging kan zijn.

Zodra je een authenticatiemethode aan de zijde van Paazl hebt geïmplementeerd, moet je deze ook aan de zijde van de webshop implementeren.

Beveiligingstoken

De eenvoudigst te implementeren authenticatiemethode is het beveiligingstoken. Wanneer dit actief is, stuurt Paazl bij elke pushmelding een header genaamd Authorization mee, zodat de webshopserver kan bevestigen dat het bericht afkomstig is van onze API.

De waarde van de header Authorization heeft de indeling Bearer cf50ed66-154e-4f5c-8818-e7a770d644b8, waarbij de hash de hash is die je genereert op de Push API-configuratiepagina.

Clientcertificaat

Je kunt ook een clientcertificaat gebruiken om een authenticatiemethode te implementeren. Paazl ondersteunt alleen PKCS12-certificaten. Gebruik een tool zoals OpenSSL om clientcertificaten te genereren. Zodra je een .p12-bestand hebt gegenereerd, upload je dit via de Push API-configuratiepagina.

Whitelisting

Whitelisting is een aanvullende beveiligingsmaatregel die ervoor zorgt dat alleen API-calls vanaf een specifieke URL worden herkend. We raden je aan de Push API van Paazl op de whitelist te zetten. Gebruik hiervoor de volgende IP-adressen.

• Staging (acceptatietest): 34.90.21.169/staging.paazl.com
• Productieomgeving: 34.91.233.81/ship.paazl.com

Serverantwoorden

HTTP-methode

De Push API van Paazl verstopt verzoeken met behulp van de POST-methode.

Berichtindeling

De Push API kan berichten versturen in XML- of JSON-indeling. XML is de standaardinstelling. Stel de berichtindeling in in je 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>

Uitleg van parameters

Header

Body

Voorbeelden van updateberichten

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>