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 tipoPOST / HTTP/1.1 Content-Type: application/json; Content-Length: 1232 Host: webhook.qapla.it Connection: Keep-Alive User-Agent: Mozilla/5.0Verrà 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 |
Parametro | Descrizione | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
rows(array) |
|
||||||||||||||||||||||||||||||||||||
parcels(array) |
|
||||||||||||||||||||||||||||||||||||
consignee(object|null) |
|
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 POSTPOST / 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[]) |
|
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 tipoPOST / HTTP/1.1 Content-Type: application/json; Content-Length: 1232 Host: webhook.qapla.it Connection: Keep-Alive User-Agent: Mozilla/5.0Verrà inviata la seguente comunicazione:
Descrizione
apiKey(string) | La API Key del canale dal quale stiamo ricevendo la notifica. | ||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
orders(array) |
È un array di ordini.
|
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 | |
---|---|---|---|---|
0 | ATTESA ELABORAZIONE | La gestione automatica di interrogazione del corriere non è ancora stata eseguita. | ||
1 | IN SOSPESO | La spedizione è stata trovata ma non ci sono ancora notizie da parte del corriere. | ||
2 | ATTESA RITIRO | Il corriere non ha ancora ritirato la spedizione. | ||
20 | PARTITO | La spedizione è partita. | ||
3 | IN TRANSITO | La merce è in transito. | ||
50 | IN LAVORAZIONE | Spedizione in lavorazione | ||
50 | 1 | IN LAVORAZIONE • DOGANA | ||
4 | IN CONSEGNA | Spedizione in consegna. | ||
5 | TENTATIVO DI CONSEGNA FALLITO | La consegna è fallita. Pre-allarme per possibili problemi. | ||
8 | RITARDO | La spedizione sta subendo dei ritardi. | ||
6 | ECCEZIONE | Viene segnalato un qualche problema che può essere generico o spiegato da ulteriori icone. | ||
6 | 1 | ECCEZIONE • GIACENZA | La spedizione è in giacenza | |
6 | 2 | ECCEZIONE • SPEDIZIONE IN RIENTRO / RIFIUTATA | La spedizione è stata rifiutata e la merce è in rientro. | |
6 | 3 | ECCEZIONE • DANNEGGIAMENTO | Il corriere segnala che la merce risulta danneggiata. | |
6 | 4 | ECCEZIONE • SMARRIMENTO | Il corriere segnala che la merce risulta smarrita. | |
6 | 5 | ECCEZIONE • CONSEGNA PARZIALE | ||
10 | PUNTO DI RITIRO | La spedizione è stata consegnata in un Punto di Ritiro. | ||
95 | RIENTRATO | La spedizione è rientrata al mittente. | ||
99 | CONSEGNATO | La spedizione è stata consegnata al destinatario. |