Webhook Ver. 1.2

rel. 1.2.30

Introduzione

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

I Webook 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

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 = '01306b82789acd2d9317e12f2s70c4z0e0f4669c21e4c88df2c8a919e0a0d';

//...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 possbile stato del corriere.

idNomeDescrizione
2INFO RECEIVEDThe courier didn’t pick up the shipment yet.
20DEPARTEDShipment departed.
3IN TRANSITThe goods are in transit.
50PROCESSINGProcessing
4OUT FOR DELIVERYShipment in delivery.
5FAILED ATTEMPTDelivery failed. Early warning for potential problems.
8DELAYShipment is suffering delay.
6EXCEPTIONThere is a problem; generic or explained by additional icons.
10PICKUP POINTDelivered to a PickUp Point.
95RETURNEDShipment returned to sender.
99DELIVEREDThe shipment has been delivered to the recipient.
Dettaglio stato

L'eventuale dettaglio aggiuntivo dello stato.

idNomedetailIDNomeDescrizione
6EXCEPTION1STOCK
6EXCEPTION2RETURN
6EXCEPTION3DAMAGED
6EXCEPTION4LOST

Corrieri

Elenco dei codici Qapla' per corriere, in ordine alfabetico.
CodiceNome
4PX4PX4PXcn
AIR-EXPRESS-ITAIR-EXPRESS-ITAir Expressit
ALIEXPRESSALIEXPRESSAliexpresscn
AMATI-JRAMATI-JRAmati JRit
AN-POSTAN-POSTAn Postie
ARAMEXARAMEXAramexglobal
ARCOARCOArco Spedizioniit
ASENDIAASENDIAAsendia Europeeu
ASENDIA-DEASENDIA-DEASENDIA Germanyde
ASENDIA-USAASENDIA-USAASENDIA USAus
ASMASMASMes
AUSTRIAN-POSTAUSTRIAN-POSTAustrian Postat
BETSERVICEBETSERVICEB&T Serviceit
BIZ-COURIERBIZ-COURIERBiz Couriergr
BRTBRTBRTit
CBL-LOGISTICACBL-LOGISTICACBL Logisticaes
CZECH-POSTCZECH-POSTČeská poštacz
CHINA-EMSCHINA-EMSChina EMScn
CHINA-POSTCHINA-POSTChina Postcn
CHRONOPOST-FRCHRONOPOST-FRChronopost Francefr
CAQ-ITACAQ-ITAClick & Quickit
CNE-EXPRESSCNE-EXPRESSCNE Expresscn
COLIS-PRIVECOLIS-PRIVEColis Privéfr
COLISSIMOCOLISSIMOColissimofr
CORREOSCORREOSCorreoses
CORREOS-EXPRESSCORREOS-EXPRESSCorreos Expresses
COURIER-EXPRESS-ITCOURIER-EXPRESS-ITCourier expresit
CRONO-PTICRONO-PTICrono Posteit
CTS_GROUPCTS_GROUPCTS GROUPnl
DAC-ITDAC-ITD.A.Cit
DBSCHENKERDBSCHENKERDB Schenkerglobal
DHL-DEDHL-DEDeutsche Post DHLde
DHL-ECOMMERCEDHL-ECOMMERCEDHL eCommerceus
DHLDHLDHL Expressglobal
DHL-FREIGHTDHL-FREIGHTDHL Freightglobal
DHL-PAKETDHL-PAKETDHL Paketde
DHLPARCEL-NLDHLPARCEL-NLDHL Parcel NLnl
DHLPARCEL-ESDHLPARCEL-ESDHL Parcel Spaines
DMMDMMDMM Networkit
DPDDPDDPDglobal
DPD-FRDPD-FRDPD Francefr
DSVDSVDSVglobal
ENERGO-LOGISTICENERGO-LOGISTICEnergo Logisticit
ENVIALIAENVIALIAEnvialiaes
FAST-WLFAST-WLFAST WORLD LOGISTICfr
FEDEXFEDEXFedExglobal
FERCAMFERCAMFERCAM Logisticsit
FERMOPOINTFERMOPOINTFermopointit
FINESSOFINESSOFinessoit
GLOBALTRGLOBALTRGlobal Trasportiit
GLS-ITAGLS-ITAGLSit
GLSGLSGLS Europeeu
HERMES-DEHERMES-DEHermes Germanyde
HERMES-ITHERMES-ITHermes Italyit
HERMESHERMESHermes UKgb
HONG-KONG-POSTHONG-KONG-POSTHong Kong Posthk
INSTALLOINSTALLOInstalloit
LA-POSTELA-POSTELa Postefr
MBE-ITMBE-ITMail Boxes Etc. Italiait
MILKMANMILKMANMilkmanit
MONDIALRELAYMONDIALRELAYMondial Relayfr
MRW-ESMRW-ESMRWes
NACEX-ESNACEX-ESNacexes
NEXIVENEXIVENexiveit
NOPARNOPARNopar Solutionses
ONEXPONEXPOne Expressit
ONTRACONTRACOnTracglobal
PALLETWPALLETWPalletwayseu
PARCEL-FORCEPARCEL-FORCEParcel Forcegb
PTIPTIPoste Italianeit
POSTNL-INTPOSTNL-INTPostNL Internationalnl
POSTNL-3SPOSTNL-3SPostNL International 3Snl
RDARDARamonedaes
ROYAL-MAILROYAL-MAILRoyal Mailgb
SF-EXPRESSSF-EXPRESSS.F. Expresscn
SAILPOSTSAILPOSTSailpostit
SMM-ITSMM-ITSan Marino Mailit
SDASDASDAit
SDA-RACCOMANDATASDA-RACCOMANDATASDA Raccomandatait
SENDABOXSENDABOXSendaboxit
SEURSEURSeures
SGTSGTSGT Corriere Espressoit
SINOTRANSSINOTRANSSinotranscn
SKYNET-ITASKYNET-ITASkyNet Italyit
SKYNETSKYNETSkyNet Worldwide Expressglobal
SPEDIAMOSPEDIAMOSpediamo.itit
SWISS-POSTSWISS-POSTSwiss Postch
TWSTWST.W.S. Express Courierit
TECNO-TRANSTECNO-TRANSTecnotransit
TIPSATIPSATIPSAes
TNTTNTTNTglobal
TNT-CLICKTNT-CLICKTNT Clickit
TNT-ESTNT-ESTNT Españaes
TNT-ITATNT-ITATNT Italiait
TNT-UKTNT-UKTNT UKgb
TOLLTOLLToll Groupglobal
TOURLINE-EXPRESSTOURLINE-EXPRESSTourline Expresses
TRAKPAKTRAKPAKTrakpakeu
UPSUPSUPSglobal
USPSUSPSUSPSus
YANWENYANWENYanwencn
YODELYODELYodel Domesticgb
YUNEXPRESSYUNEXPRESSYun Expresscn
ZELERIS-ESZELERIS-ESZelerises