Webhook Ver. 1.2

rel. 1.2.33
Qapla' srl   •   06492420481

Introduction

Webhook is a notification of an event published in a URL of your choice.

Webhooks are useful for integration with third-party services and other external APIs that support them.

Qapla' webhook is part of the API of Qapla'.

API Key

In order to use the APIs it is necessary to be aware of the Private API Keys assigned to your channel(s), which are located on the Control Panel in section "Settings \ [CHANNEL_NAME]"

This API key must be protected and kept secret.

API Key

Security

The IP addresses from which it will be possible to receive the POST of the webhook are:

Shipments webhook

Each change of shipment status communicated by the courier (ex: if the shipment changes from "delivery" to "delivered"), a POST in JSON format is sent to the URL indicated in the channel configuration on the Qapla' control panel.
POSThttps://[YOUR_ENDPOINT]
HTTP POST
In a POST at the endpoint indicated in the channel configuration Qapla' Control Panel, like:
POST / HTTP/1.1
Content-Type: application/json;
Content-Length: 1232
Host: webhook.qapla.it
Connection: Keep-Alive
User-Agent: Mozilla/5.0
it will be sent the following communication:


    
Description
Following the description of the individual parameters.
Parameter Description
apiKey(string) The API Key of the channel from which we are receiving the notification.
trackingNumber(string) The tracking number of the shipment
return(bool) It is 1 if it is a return shipment
hasChildren(bool) It is 1 if the shipment has "child" shipments
isChild(bool) It is 1 if the shipment is a "child" shipment
courier(string) The Qapla' courier code
reference(string) Order's alphanumeric reference
date(string) The status date, as reported by the courier
courierStatus(string) The status communicated by the courier
place(string) The place communicated by the courier
qaplaStatusID(string) The "translation" of the status of the courier in the Qapla' status
qaplaStatus Status description
statusDetails The ID of possible detail
custom1 Possible custom1 value of the shipment
custom2 Possible custom2 value of the shipment
custom3 Possible custom3 value of the shipment
Response
The response from URL called must be:
{"result": "OK"}
Only in case of error will be:
{"result": "KO"}
Retry

The result "KO" or any other type of wrong answer that is not "OK" will force the webhook to retry the transmission 2 more times in the following hours.

Abuse

After 100 failed transmission attempts (i.e. with "KO" response or non-compliant response) the service will be disabled.

Enpoint example
POSThttps://[YOUR_URL]/qaplaWebhook.php
The following example of a "listening" page takes the JSON content and processes it.
<?php
//...I set the content-type as JSON
header('Content-type: application/json; charset=utf-8');

//...API Key that I expect
const API_KEY = '01306b82789acd2d9317e12f2s70c4z0e0f4669c21e4c88df2c8a919e0a0d';

//...I obtain the string sent as a POST
$data = file_get_contents('php://input');

//...If it is empty I get very angry
if(empty($data)):
    exit('{"result": "KO"}');
endif;

//...I turn it in a JSON
$json = json_decode($data);

//...If it's an incorrect JSON, I get even more angry
if(($json === false))
    exit('{"result": "KO"}');
endif;

//...I verify that the API KEY posted matches, security check.
if($json->apiKey !== API_KEY):
    exit('{"result": "KO"}');
endif;

//...I update the potential table
$sql = "UPDATE orders-shipments SET status = ".$json->qaplaStatusID." WHERE id = ".$json->reference;

//...Everything right, I write "result": "OK" in JSON
echo '{"result": "OK"}';
?>
Test

Test your endpoint and send a typical Qapla' transmission.

API Key*
URL*
Tracking Number
Courier
Reference
Courier Status
Place
Qapla' Status

Orders webhook

Webhook can be configured to be sent when the shipment is created (label printing) or sent (sending confirmation to the courier), in the appropriate section on Control Panel of Qapla'.
POSThttps://[YOUR_ENDPOINT]
HTTP POST
In a POST at the endpoint indicated in the channel configuration on Qapla' Control Panel, like:
POST / HTTP/1.1
Content-Type: application/json;
Content-Length: 1232
Host: webhook.qapla.it
Connection: Keep-Alive
User-Agent: Mozilla/5.0
it will be sent the following communication:


    
Description
apiKey(string) The API Key of the channel from which we are receiving the notification.
orders(array) It is an array of orders.
reference(string) Order reference
orderDate Order date
shipDate Order creation date
courier The Qapla' courier code
trackingNumber The tracking number of the shipment
return(bool) It is true if the shipment has a return
returnTrackingNumber(string) Possible tracking number of return shipment
weight(float) Weight
parcels(int) Packages
length(float) Length
width(float) Width
height(float) Height
amount(string) Shipment cost
isPOD(bool) It is true if the shipment is cash on delivery
customerName(string) Recipient name
customerAddress(string) Recipient address
customerCity(string) Recipient City
customerState(string) Recipient province
customerZip(string) Recipient postal code
customerCountry(string) Recipient country
customerTelephone(string) Recipient telephone
customerEmail(string) Recipient email
notes(string) Any order notes
Test

Test your endpoint and send a typical Qapla' transmission.

API Key*
URL*
Reference*
Order date
Ship date
Tracking Number
Courier
Weight
Parcels
Length
Width
Height
Amount
Is POD
Customer Name
Customer Address
Customer City
Customer State
Customer Zip
Customer Country
Customer Telephone
Customer Email
Notes

Qapla' Status

It is the interpretation of the status of the shipment with values that Qapla' assigns to each possible state of the courier.

idNameDescription
0 WAITING TO COMPUTE
1 PENDING Shipment found but any news yet from courier.
2 INFO RECEIVED The courier didn’t pick up the shipment yet.
20 DEPARTED Shipment departed.
3 IN TRANSIT The goods are in transit.
50 PROCESSING Processing
50 PROCESSING • CUSTOMS
4 OUT FOR DELIVERY Shipment in delivery.
5 FAILED ATTEMPT Delivery failed. Early warning for potential problems.
8 DELAY Shipment is suffering delay.
6 EXCEPTION There is a problem; generic or explained by additional icons.
6 EXCEPTION • STOCK
6 EXCEPTION • RETURN
6 EXCEPTION • DAMAGED
6 EXCEPTION • LOST
6 EXCEPTION • PARTIAL DELIVERY
10 PICKUP POINT Delivered to a PickUp Point.
95 RETURNED Shipment returned to sender.
99 DELIVERED The shipment has been delivered to the recipient.

Couriers

List of Qapla's couriers' codes, in alphabetical order.
CodeNameURL
AIR-EXPRESS-IT AIR-EXPRESS-IT Air Express https://airexpress.it/ it
ALIEXPRESS ALIEXPRESS Aliexpress https://www.aliexpress.com/‎ cn
AMATI-JR AMATI-JR Amati JR http://www.amatijrtrasporti.it/ it
AN-POST AN-POST An Post https://www.anpost.com/ ie
APP2DELIVERY APP2DELIVERY App2delivery it
ARAMEX ARAMEX Aramex http://www.aramex.com global
ARCO ARCO Arco Spedizioni http://www.arco.it/ it
ASENDIA ASENDIA Asendia Europe https://www.asendia.com eu
ASENDIA-DE ASENDIA-DE ASENDIA Germany http://www.asendia.de/ de
ASENDIA-USA ASENDIA-USA ASENDIA USA http://www.asendiausa.com/ us
ASM ASM ASM http://www.asmred.com es
AUSTRIAN-POST AUSTRIAN-POST Austrian Post https://www.post.at at
BETSERVICE BETSERVICE B&T Service http://www.betservice.net/ it
BIZ-COURIER BIZ-COURIER Biz Courier https://www.bizcourier.eu/ gr
BPOST BPOST BPost https://track.bpost.be be
BRAZIL-CORREIOS BRAZIL-CORREIOS Brazil Correios http://correios.com.br/ br
BRT BRT BRT http://www.brt.it it
BULGARIAN-POSTS BULGARIAN-POSTS Bulgarian Posts https://www.bgpost.bg/en BG
CBL-LOGISTICA CBL-LOGISTICA CBL Logistica http://www.cbl-logistica.com es
CZECH-POST CZECH-POST Česká pošta https://www.ceskaposta.cz cz
CHINA-EMS CHINA-EMS China EMS http://www.11183.com.cn/english.html cn
CHINA-POST CHINA-POST China Post http://www.chinapost.com.cn/ cn
CHRONOPOST-FR CHRONOPOST-FR Chronopost France http://www.chronopost.fr/ fr
CNE-EXPRESS CNE-EXPRESS CNE Express http://www.cnexps.com/ cn
COLIS-PRIVE COLIS-PRIVE Colis Privé https://www.colisprive.com fr
COLISSIMO COLISSIMO Colissimo http://www.colissimo.fr fr
CORREOS CORREOS Correos http://www.correos.es es
CORREOS-EXPRESS CORREOS-EXPRESS Correos Express https://www.correosexpress.com es
COURIER-EXPRESS-IT COURIER-EXPRESS-IT Courier expres http://www.spacecomputer-web.it/web/courier it
CRONO-PTI CRONO-PTI Crono Poste http://www.poste-impresa.it/online/pmi/postali/italia/crono-gamma.shtml it
CRONO-REVERSE CRONO-REVERSE Crono Reverse https://business.poste.it/professionisti-imprese/prodotti/crono-reverse-gestione-resi-ecommerce.html it
CTS_GROUP CTS_GROUP CTS GROUP https://www.ctsgroup.nl/en/ nl
CTT CTT CTT https://www.ctt.pt pt
CYPRUS-POST CYPRUS-POST Cyprus Post https://www.cypruspost.post/ cy
DAC-IT DAC-IT D.A.C https://dac-it.com/ it
DBSCHENKER DBSCHENKER DB Schenker https://www.dbschenker.com/ global
DHL-DE DHL-DE Deutsche Post DHL http://www.dpdhl.com/ de
DHL-ECOMMERCE DHL-ECOMMERCE DHL eCommerce http://webtrack.dhlglobalmail.com/ us
DHL DHL DHL Express http://www.dhl.com/ global
DHL-FREIGHT DHL-FREIGHT DHL Freight https://www.logistics.dhl global
DHL-PAKET DHL-PAKET DHL Paket https://www.dhl.de/ de
DHLPARCEL-NL DHLPARCEL-NL DHL Parcel NL https://www.dhlparcel.nl/ nl
DHLPARCEL-ES DHLPARCEL-ES DHL Parcel Spain https://www.dhlparcel.es es
DMM DMM DMM Network http://www.dmmnetwork.it/ it
DPD DPD DPD http://www.dpd.com/ global
DPD-FR DPD-FR DPD France http://www.dpd.fr fr
DPD-UK DPD-UK DPD UK http://www.dpd.co.uk/ gb
DSV DSV DSV http://www.dsv.com/ global
ELTA-HELLENIC-POST ELTA-HELLENIC-POST ELTA Hellenic Post https://www.elta.gr gr
EMIRATES-POST EMIRATES-POST Emirates Post https://www.epg.gov.ae/ ae
ENERGO-LOGISTIC ENERGO-LOGISTIC Energo Logistic https://www.energologistic.it/ it
ENVIALIA ENVIALIA Envialia http://www.envialia.com/ es
FAST-WL FAST-WL FAST WORLD LOGISTIC http://www.fastwl.com/ fr
FEDEX FEDEX FedEx http://www.fedex.com/ global
FERCAM FERCAM FERCAM Logistics http://www.fercam.com/ it
FERMOPOINT FERMOPOINT Fermopoint https://www.fermopoint.it it
FINESSO FINESSO Finesso https://www.finesso.it/ it
GLOBALTR GLOBALTR Global Trasporti http://www.globaltrasporti.com/ it
GLS-ITA GLS-ITA GLS http://www.gls-italy.com it
GLS GLS GLS Europe https://gls-group.eu/ eu
GLS-SPAIN GLS-SPAIN GLS Spain https://m.gls-spain.es/ es
GO-EXPRESS GO-EXPRESS GO! Express & Logistics https://www.general-overnight.com de
HERMES-DE HERMES-DE Hermes Germany https://www.myhermes.de de
HERMES-IT HERMES-IT Hermes Italy http://www.hermes-italy.it/ it
HERMES HERMES Hermes UK https://www.myhermes.co.uk gb
HONG-KONG-POST HONG-KONG-POST Hong Kong Post https://www.hongkongpost.hk/en/home/index.html hk
HRVATSKA-POSTA HRVATSKA-POSTA Hrvatska pošta https://www.posta.hr hr
INSTALLO INSTALLO Installo https://www.installo.it/ it
JERSEY-POST JERSEY-POST Jersey Post https://www.jerseypost.com/ gb
KOREA-POST KOREA-POST Korea Post https://www.epost.go.kr kr
LA-POSTE LA-POSTE La Poste https://www.laposte.fr/ fr
LATVIJAS-PASTS LATVIJAS-PASTS Latvijas Pasts https://pasts.lv/ lv
LIETUVOS-PASTAS LIETUVOS-PASTAS Lietuvos Paštas https://www.post.lt/ lt
LUXEMBOURG-POST LUXEMBOURG-POST Luxembourg Post https://www.post.lu lu
MAGYAR-POSTA MAGYAR-POSTA Magyar Posta https://www.posta.hu/ hu
MBE-IT MBE-IT Mail Boxes Etc. Italia https://www.mbe.it/ it
MALTA-POST MALTA-POST Malta Post https://www.maltapost.com/ mt
MILKMAN MILKMAN Milkman https://www.milkman.it/ it
MONDIALRELAY MONDIALRELAY Mondial Relay https://www.mondialrelay.fr fr
MRW-ES MRW-ES MRW http://www.mrw.es/ es
NACEX-ES NACEX-ES Nacex https://www.nacex.es/ es
NEXIVE NEXIVE Nexive http://www.nexive.it/ it
NOPAR NOPAR Nopar Solutions http://noparsolutions.com/ es
OMNIVA OMNIVA Omniva https://www.omniva.ee ee
ONEXP ONEXP One Express http://www.oneexpress.it it
ONTRAC ONTRAC OnTrac http://www.ontrac.com global
PALLETW PALLETW Palletways http://www.palletways.com eu
PARCEL-FORCE PARCEL-FORCE Parcel Force http://www.parcelforce.com gb
POCZTA-POLSKA POCZTA-POLSKA Poczta Polska http://www.poczta-polska.pl pl
POS-MALAYSIA POS-MALAYSIA Pos Malaysia https://www.pos.com.my/ my
POSTA-ROMANA POSTA-ROMANA Poșta Română https://www.posta-romana.ro/ RO
SLOVENIA-POST SLOVENIA-POST Pošta Slovenije https://www.posta.si si
PTI PTI Poste Italiane http://www.poste.it it
POSTEN-NORGE POSTEN-NORGE Posten Norge https://www.posten.no/ no
POSTI POSTI Posti https://www.posti.fi/ fi
POSTNL-INT POSTNL-INT PostNL International http://www.postnl.post/ nl
POSTNL-3S POSTNL-3S PostNL International 3S https://www.internationalparceltracking.com nl
POSTNORD-DENMARK POSTNORD-DENMARK PostNord Denmark https://www.postnord.dk dk
POSTNORD-SWEDEN POSTNORD-SWEDEN PostNord Sweden https://www.postnord.se/ se
QHD QHD QHD https://www.qhditalia.it/ global
RDA RDA Ramoneda http://www.ramoneda.com/ es
ROYAL-MAIL ROYAL-MAIL Royal Mail http://www.royalmail.com gb
RPOST RPOST RPost https://www.errepost.it/ IT
RUSSIAN-POST RUSSIAN-POST Russian Post https://www.pochta.ru ru
SF-EXPRESS SF-EXPRESS S.F. Express http://www.sf-express.com cn
SAILPOST SAILPOST Sailpost http://www.sailpost.it it
SMM-IT SMM-IT San Marino Mail http://www.sanmarinomail.sm it
SDA SDA SDA http://wwww.sda.it it
SDA-RACCOMANDATA SDA-RACCOMANDATA SDA Raccomandata http://wwww.sda.it it
SENDABOX SENDABOX Sendabox http://www.sendabox.it/ it
SENDING SENDING Sending Transporte Urgente https://www.sending.es es
SEUR SEUR Seur http://www.seur.com es
SGT SGT SGT Corriere Espresso http://www.sgt.it/ it
SINOTRANS SINOTRANS Sinotrans http://www.sinotrans-csc.com/ cn
SKYNET-ITA SKYNET-ITA SkyNet Italy http://www.skynetitaly.it it
SKYNET SKYNET SkyNet Worldwide Express http://www.skynetwwe.com/ global
SOUTH-AFRICAN-POST SOUTH-AFRICAN-POST South African Post https://www.postoffice.co.za za
SPEDIAMO SPEDIAMO Spediamo.it http://www.spediamo.it/ it
SPRING-GDS SPRING-GDS Spring GDS https://www.spring-gds.com/ eu
SUSA SUSA Susa https://flex.susa.it/Home IT
SWISS-POST SWISS-POST Swiss Post https://www.post.ch/ ch
TWS TWS T.W.S. Express Courier http://www.twsexpresscourier.it it
TECNO-TRANS TECNO-TRANS Tecnotrans http://www.tecnotrans.eu it
TIPSA TIPSA TIPSA http://www.tip-sa.com/ es
TNT TNT TNT http://www.tnt.com global
TNT-CLICK TNT-CLICK TNT Click http://www.tnt-click.it it
TNT-ES TNT-ES TNT España http://www.tnt.es es
TNT-ITA TNT-ITA TNT Italia https://www.tnt.it/ it
TNT-UK TNT-UK TNT UK http://www.tnt.com/express/en_gb/site/home.html gb
TOLL TOLL Toll Group https://www.tollgroup.com/ global
TOURLINE-EXPRESS TOURLINE-EXPRESS Tourline Express http://www.tourlineexpress.com es
TRAKPAK TRAKPAK Trakpak http://www.trackmytrakpak.com eu
UPS UPS UPS http://www.ups.com/ global
USPS USPS USPS https://www.usps.com/ us
YANWEN YANWEN Yanwen http://www.yw56.com.cn/ cn
YDH YDH Ydh http://www.ydhex.com/ cn
YODEL YODEL Yodel Domestic http://www.yodel.co.uk/ gb
YUNEXPRESS YUNEXPRESS Yun Express http://www.yunexpress.com/ cn
ZELERIS-ES ZELERIS-ES Zeleris https://www.zeleris.com/ es
ZUST ZUST Züst Ambrosetti http://www.zust.it/ it