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.

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

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

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

{
"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,
"length": 1,
"width": 1,
"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. Descrizione dei parametri aggiuntivi se abilitata la versione 1.3:

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

{
"webhookReturnShipments": {
"id": "123456789098765432",
"apiKey": "[API_KEY]",
"version": 1,
"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.

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

{
"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

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.