Webhook Ver. 1.2

rel. 1.2.33
Qapla' srl   •   06492420481

Introduzione

Un Webhook è una notifica di un evento inviata a un URL di tua scelta.

I Webhook sono utili per l'integrazione con servizi di terze parti e altre API esterne che li supportano.

Qapla' webhook fa parte delle API di Qapla'.

API Key

Per poter utilizzare le API è necessario essere a conoscenza delle API Key private assegnate al/ai tuo/i canale/i, che si trovano sul Control Panel nella sezione "Impostazioni \ [NOME_CANALE]"

Questa chiave API deve essere protetta e mantenuta segreta.

API Key

Security

Gli indirizzi IP dai quali sarà possibile ricevere le POST del webhook sono:

Shipments webhook

Ad ogni cambio di stato della spedizione comunicata dal corriere (es: se la spedizione passa da "in consegna" a "consegnato"), una POST in formato JSON viene inviata alla URL indicata nella configurazione del canale sul Control Panel di Qapla'.
POSThttps://[YOUR_ENDPOINT]
HTTP POST
In una POST all'endpoint indicato nella configurazione del canale su Control Panel di Qapla', del tipo
POST / HTTP/1.1
Content-Type: application/json;
Content-Length: 1232
Host: webhook.qapla.it
Connection: Keep-Alive
User-Agent: Mozilla/5.0
Verrà inviata la seguente comunicazione:


    
Descrizione
A seguire la descrizione dei singoli parametri.
Parametro Descrizione
apiKey(string) La API Key del canale dal quale stiamo ricevendo la notifica.
trackingNumber(string) Il tracking number della spedizione
return(bool) È 1 se è una spedizione in rientro (reso)
hasChildren(bool) È 1 se è la spedizione ha delle spedizioni "figlio"
isChild(bool) È 1 se la spedizione è una spedizione "figlio"
courier(string) Il codice corriere di Qapla'
reference(string) Il riferimento alfanumerico dell'ordine
date(string) La data dello stato, come riportata dal corriere
courierStatus(string) Lo stato comunicato dal corriere
place(string) Il luogo comunicato dal corriere
qaplaStatusID(string) La "traduzione" dello stato del corriere negli stati di Qapla'
qaplaStatus La descrizione dello stato
statusDetails L'ID dell'eventuale dettaglio
custom1 L'eventuale valore custom1 della spedizione
custom2 L'eventuale valore custom2 della spedizione
custom3 L'eventuale valore custom3 della spedizione
Risposta
La risposta dell'URL chiamato dovrà essere:
{"result": "OK"}
Mentre solo in caso di errore sarà:
{"result": "KO"}
Retry

Il result "KO" o qualunque altro tipo di riposta errata che non sia "OK" forzerà il webhook a riprovare la trasmissione altre 2 volte nelle successive ore.

Abuse

Dopo 100 tentativi di trasmissione andati in errore (ovvero con risposta "KO" o risposta non conforme) il servizio verrà disattivato.

Esempio di endpoint
POSThttps://[YOUR_URL]/qaplaWebhook.php
Il seguente esempio di pagina "in ascolto" prende il contenuto JSON e lo elabora.
<?php
//...Imposto il content-type come JSON
header('Content-type: application/json; charset=utf-8');

//...L'API Key che mi aspetto
const API_KEY = '[API_KEY]';

//...Ottengo la stringa inviata come POST
$data = file_get_contents('php://input');

//...Se è vuota mi arrabbio moltissimo
if(empty($data)):
    exit('{"result": "KO"}');
endif;

//...La trasformo in JSON
$json = json_decode($data);

//...Se è un JSON errato mi arrabbio ancora di più
if(($json === false))
    exit('{"result": "KO"}');
endif;

//...Verifico che l'API KEY postata corrisponda, controllo di sicurezza.
if($json->apiKey !== API_KEY):
    exit('{"result": "KO"}');
endif;

//... Aggiorno l'eventuale tabella
$sql = "UPDATE orders-shipments SET status = ".$json->qaplaStatusID." WHERE id = ".$json->reference;

//...Tutto a posto, scrivo "result": "OK" in JSON
echo '{"result": "OK"}';
?>
Test

Testa il tuo endpoint inviando una tipica trasmissione da Qapla'.

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

Orders webhook

Il webhook può essere configurato per essere inviato alla creazione della spedizione (stampa etichetta) o alla trasmisione (invio conferma al corriere) , nell'apposita sezione sul Control Panel di Qapla'.
POSThttps://[YOUR_ENDPOINT]
HTTP POST
In una POST all'endpoint indicato nella configurazione del canale su Control Panel di Qapla', del tipo
POST / HTTP/1.1
Content-Type: application/json;
Content-Length: 1232
Host: webhook.qapla.it
Connection: Keep-Alive
User-Agent: Mozilla/5.0
Verrà inviata la seguente comunicazione:


    
Descrizione
apiKey(string) La API Key del canale dal quale stiamo ricevendo la notifica.
orders(array) È un array di ordini.
reference(string) Il riferimento ordine
orderDate Data dell'ordine
shipDate Data di creazione della spedizione
courier Il codice corriere di Qapla'
trackingNumber Il tracking number della spedizione
return(bool) È true se la spedizione ha un reso
returnTrackingNumber(string) L'eventuale tracking number della spedizione di reso
weight(float) Peso
parcels(int) Colli
length(float) Lunghezza
width(float) Profondità
height(float) Altezza
amount(string) Importo della spedizione
isPOD(bool) È true se la spedizione è in contrassegno
customerName(string) Nominativo del destinatario
customerAddress(string) Indirizzo del destinatario
customerCity(string) Città del destinatario
customerState(string) Provincia del destinatario
customerZip(string) CAP del destinatario
customerCountry(string) Nazione del destinatario
customerTelephone(string) Telefono del destinatario
customerEmail(string) Email del destinatario
notes(string) Eventuali note dell'ordine
Test

Testa il tuo endpoint inviando una tipica trasmissione da Qapla'.

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

È l'interpretazione dello stato della spedizione con dei valori che Qapla' assegna a ciascun possibile stato del corriere.

idNomeDescrizione
0 ATTESA ELABORAZIONE La gestione automatica di interrogazione del corriere non è ancora stata eseguita.
1 IN SOSPESO La spedizione è stata trovata ma non ci sono ancora notizie da parte del corriere.
2 ATTESA RITIRO Il corriere non ha ancora ritirato la spedizione.
20 PARTITO La spedizione è partita.
3 IN TRANSITO La merce è in transito.
50 IN LAVORAZIONE Spedizione in lavorazione
50 IN LAVORAZIONE • DOGANA
4 IN CONSEGNA Spedizione in consegna.
5 TENTATIVO DI CONSEGNA FALLITO La consegna è fallita. Pre-allarme per possibili problemi.
8 RITARDO La spedizione sta subendo dei ritardi.
6 ECCEZIONE Viene segnalato un qualche problema che può essere generico o spiegato da ulteriori icone.
6 ECCEZIONE • GIACENZA La spedizione è in giacenza
6 ECCEZIONE • SPEDIZIONE IN RIENTRO / RIFIUTATA La spedizione è stata rifiutata e la merce è in rientro.
6 ECCEZIONE • DANNEGGIAMENTO Il corriere segnala che la merce risulta danneggiata.
6 ECCEZIONE • SMARRIMENTO Il corriere segnala che la merce risulta smarrita.
6 ECCEZIONE • CONSEGNA PARZIALE
10 PUNTO DI RITIRO La spedizione è stata consegnata in un Punto di Ritiro.
95 RIENTRATO La spedizione è rientrata al mittente.
99 CONSEGNATO La spedizione è stata consegnata al destinatario.

Corrieri

Elenco dei codici Qapla' per corriere, in ordine alfabetico.
CodiceNomeURL
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
PALLEX PALLEX Pallex https://www.pallex.it/ IT
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