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 \ [NOME_CANALE]"

Questa chiave API deve essere protetta e mantenuta segreta.

Security

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

• 34.96.89.1
• 35.195.3.242
• 35.205.84.188
• 35.205.236.254
• 34.78.56.172
• 35.195.153.127
• 35.205.146.223

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": "" }

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

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", "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 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 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": "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.