Webhook Ver. 1.2

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 > Canali > [NOME_CANALE] > "Configura" > Canale > API Key Privata

Questa chiave API deve essere protetta e mantenuta segreta.

Risposta

La risposta dell'URL chiamato dovrà essere:

{"result": "OK"}

Mentre solo in caso di errore sarà:

{"result": "KO"}

Abuse

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

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: { "apiKey": "[API_KEY]", "trackingNumber": "2253647804", "return": 0, "hasChildren": 0, "isChild": 0, "courier": "DHL", "reference": "2007135", "date": "2019-06-18 20:35:53", "courierStatus": "PL", "place": "LEGHORN/LIVORNO-ITA", "qaplaStatusID": "3", "qaplaStatus": "IN TRANSIT", "statusDetails": [], "custom1": "", "custom2": "", "custom3": "" }

"statusDetails" sarà inviato se necessario, come segue. Ad esempio, si noti il dettaglio di stato "GIACENZA", riferito allo stato "ECCEZIONE". { "apiKey": "[API_KEY]", "trackingNumber": "2253647804", "return": 0, "hasChildren": 0, "isChild": 0, "courier": "DHL", "reference": "2007135", "date": "2019-06-18 20:35:53", "courierStatus": "PL", "place": "LEGHORN/LIVORNO-ITA", "qaplaStatusID": "6", "qaplaStatus": "ECCEZIONE", "statusDetails": [{ "id": 1, "detail": "GIACENZA" }], "custom1": "", "custom2": "", "custom3": "" }

Abilitare la ricezione di prodotti, colli e destinatario

Abilitando da Qapla' Control Panel il webhook 1.3 è possibile ricevere le informazioni relative ai prodotti, i colli ed il destinatario. { "apiKey": "[API_KEY]", "trackingNumber": "2253647804", "return": 0, "hasChildren": 0, "isChild": 0, "courier": "DHL", "reference": "2007135", "date": "2019-06-18 20:35:53", "courierStatus": "PL", "place": "LEGHORN/LIVORNO-ITA", "qaplaStatusID": "6", "qaplaStatus": "ECCEZIONE", "statusDetails": [{ "id": 1, "detail": "GIACENZA" }], "custom1": "", "custom2": "", "custom3": "", "parcels": [{ "boxCode": "Busta gialla", "weight": 1.0, "length": 1.0, "width": 1.0, "originCountry": "IT", "content": "Some stuff" }], "rows": [{ "id": "1234567890", "sku": "t-shirt-white-xl", "name": "T-Shirt white XL", "price": "20.0", "total": "40.0", "weight": "1", "qty": "2", "url": "https://my-shop.com/products/t-shirt-white-xl", "imageUrl": "https://my-shop.com/assets/1234567890.jpeg", "isReturnable": false, "notes": "", "customsCode": "", "netWeight": "", "originCountry": "IT", "unitOfMeasurement": "", "parcelID": "0" }], "consignee": { "name": "Mario Rossi", "address": "Via degli indirizzi, 56", "city": "Milan", "state": "MI", "postCode": "20100", "country": "IT", "email": "mario.rossi@email.it", "phone": "320123456" } }

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(int)	È 1 se è una spedizione in rientro (reso)
hasChildren(int)	È 1 se è la spedizione ha delle spedizioni "figlio"
isChild(int)	È 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

Descrizione dei parametri aggiuntivi se abilitata la versione 1.3:

Parametro	Descrizione
rows(array)	Parametro Descrizione id(string) sku(string) Codice articolo name(string) Descrizione articolo price(string) Prezzo total(string) Prezzo totale weight(string) Eventuale peso dell'articolo qty(string) Quantità url(string) La url specifica del prodotto imageUrl(string) La url dell'immagine del prodotto isReturnable(boolean) Se è true indica la possibilità di reso del singolo articolo customsCode(string) Eventuale Codice Doganale (HSCode) notes(string) Eventuali note sul prodotto customsCode(string) Eventuale Codice Doganale (HSCode, Taric, ecc.) netWeight(string) Eventuale peso netto del prodotto originCountry(string) Nazione di origine del prodotto in formato ISO 3166-1 alpha-2 (Esempio: IT) unitOfMeasurement(string) Eventuale unità di misura parcelID(string) Eventuale numero progressivo, identificativo del numero collo in cui viene spedito il prodotto
parcels(array)	Parametro Descrizione boxCode(string) Eventuale codice scatola (se utilizzato le misure verranno prese dalla scatola con codice corrispondente) weight(float) Eventuale peso della spedizione length(float) Eventuali misure: lunghezza height(float) Eventuali misure: altezza width(float) Eventuali misure: profondità originCountry(string) Nazione di origine del collo in formato ISO 3166-1 alpha-2 (Esempio: IT) content(string) Eventuale descrizione del contenuto
consignee(object|null)	Parametro Descrizione name (string) Il nominativo del destinatario address (string) L'indirizzo del destinatario city (string) La città del destinatario state (string) Lo stato o la provincia del destinatario postCode (string) Il codice postale del destinatario country (string) La nazione del destinatario email (string|null) Eventuale indirizzo e-mail del destinatario phone (string|null) Eventuale numero di telefono del destinatario

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'.

Compila i campi per inviare una request di esempio all'endpoint segnalato.

Verranno inviati esattamente i campi compilati.

API Key*
URL*
Tracking Number*
Courier*
Reference*
Courier Status*
Place*
Qapla' Status	[2] INFO RECEIVED[20] DEPARTED[3] IN TRANSIT[50] PROCESSING[4] OUT FOR DELIVERY[5] FAILED ATTEMPT[8] DELAY[6] EXCEPTION[10] PICKUP POINT[95] RETURNED[99] DELIVERED

Shipments return webhook

Ad ogni richiesta di reso da parte del cliente finale* verrà trasmesso ad un endpoint definito sul Control Panel di Qapla', i dettagli della spedizione in rientro.

POSThttps://[YOUR_ENDPOINT]

*Questo servizio è disponibile solamente previa abilitazione, configurazione ed acquisto del servizio Resi automatici(Resi di tipo 3) sullo Store di Qapla'.

HTTP POST

Di seguito un'esempio di dettaglio della POST

POST / HTTP/1.1
Content-Type: application/json;
Content-Length: 1232
Host: webhook.qapla.it
Connection: Keep-Alive
User-Agent: Mozilla/5.0

{ "webhookReturnShipments": { "id": "123456789098765432", "apiKey": "[API_KEY]", "version": 1.0, "count": 1, "returnShipments": [ { "date": "2022-01-01", "reference": "123456fgh", "RMA": "s3d3d", "parcels": 1, "weight": 1, "trackingNumber": "ZZ12356897654", "refundMethodCode": "0001", "courier": { "code": "CRONO-REVERSE", "name": "Crono reverse", "icon": "https://cdn.qapla.it/courier/CRONO-REVERSE.svg" }, "sender": { "name": "Pepito Sbazzeguti", "address": "Via Don Camillo Martire,90", "city": "Brescello", "state": "RE", "postCode": "42041", "country": "IT", "email": "pepito@sbazzeguti.it", "telephone": "3473432522" }, "consignee": { "name": "The merchant SRL", "address": "Via enterprise,10", "city": "Milano", "state": "MI", "postCode": "20100", "country": "IT" }, "rows": [ { "sku": "A-1233", "name": "Whisky in the Jar", "qty": 1, "total": "12.00", "reason": "Jar empty" } ] } ] } }

Descrizione

A seguire la descrizione dei singoli parametri.

Parametro	Descrizione
apiKey(string)	La API Key del canale dal quale stiamo ricevendo la notifica.
returnShipments(object[])	Parametro Descrizione date(string) Data di creazione di reso reference(string) Riferimento ordine RMA(string) Codice Return Merchandise Authorization parcels(integer) Colli weight(float) Peso trackingNumber(string) Il tracking number della spedizione di reso refundMethodCode(string) Il codice del metodo di rimborso scelto courier(object) Parametro Descrizione code(string) Codice name(string) Nome icon(string) Link all'icona sender(object) È il mittente della spedizione se diverso dall'intestatario del contratto. Parametro Descrizione name(string) Nome del Mittente address(string) Indirizzo del mittente city(string) Città del mittente state(string) Provincia postCode(string) CAP country(string) Nazione in formato ISO 3166-1 alpha-2 (Esempio: IT) email(string) Email del mittente telephone(string) Telefono del mittente consignee(object) È il destinatario della spedizione di Reso. Parametro Descrizione name(string) Nome / Ragione sociale address(string) Indirizzo city(string) Città state(string) Provincia postCode(string) CAP country(string) Nazione in formato ISO 3166-1 alpha-2 (Esempio: IT) rows(array of objects) Lista articoli in restituzione Parametro Descrizione sku(string) SKU name(string) Nome articolo qty(string) Quantità total(string) Costo totale articolo reason(string) Causale di restituzione dell'articolo

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.

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 di impostazioni del canale sul Control Panel di Qapla' ("Aggiornamenti" > "Webhook").

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: { "apiKey": "01306b82789acd2d9317e12f2s70c4z0e0f4669c21e4c88df2c8a919e0a0d", "orders": [{ "reference": "51704", "orderDate": "2018-02-21 14:04:19", "shipDate": "2018-02-22 12:54:15", "courier": "GLS-ITA", "trackingNumber": "XX580104809", "return": null, "returnTrackingNumber": null, "weight": 1, "parcels": 1, "length": 0, "width": 0, "height": 0, "amount": "€ 28.74", "isPOD": false, "customerName": "Pepito Sbazzeguti", "customerAddress": "Via Don Camillo Martire,90", "customerCity": "Brescello", "customerState": "RE", "customerZip": "42041", "customerCountry": "IT", "customerTelephone": "3473432522", "customerEmail": "pepito@sbazzeguti.it", "notes": "" }] }

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.

Corrieri

Elenco dei codici Qapla' per corriere, in ordine alfabetico.