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
- 35.195.158.219
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:
"statusDetails" sarà inviato se necessario, come segue. Ad esempio, si noti il dettaglio di stato "GIACENZA", riferito allo stato "ECCEZIONE".
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.
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 |
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'.
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
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:
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'.
Qapla' Status
È l'interpretazione dello stato della spedizione con dei valori che Qapla' assegna a ciascun possibile stato del corriere.
| id | detailID | Nome | Descrizione |
|---|
Corrieri
Elenco dei codici Qapla' per corriere, in ordine alfabetico.
