Un Webhook è una notifica inviata a un URL a tua scelta, ogni volta che si verifica un determinato evento.
I Webhook sono utili per l’integrazione con servizi di terze parti e altre API esterne che li supportano.
Qapla’ ha due tipologie di webhook:
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 Private
Attenzione: la chiave API Key Private deve essere protetta e mantenuta segreta.
Shipments webhook – notifica tracking spedizioni
Shipments webhook permette di ricevere una notifica POST in formato JSON ad ogni cambio di stato comunicato dal corriere, esempio se la spedizione passa da “in consegna” a “consegnato”.
Per configurare il webhook di notifica tracking spedizioni andare su sezione:
Impostazioni > Canali [Nome canale] > Configura > Aggiornamenti > Webhook > Webhook di notifica tracking spedizioni
Impostare:
- Attivazione: spuntare “Attiva” per l’abilitazione
- URL: inserire la URL che riceverà la notifica
- Versione: selezionare la versione
- 1.2 versione classica
- 1.3 versione consigliata, aggiornata per permettere di ricevere anche le informazioni relative ai prodotti, i colli e destinatario.
Shipments return webhook
Nel caso di spedizioni di reso, gestite tramite il servizio Resi automatici (Resi di tipo 3, prodotto che richiede l’acquisto e attivazione), verrà inviata una notifica POST in formato JSON ad ogni richiesta di reso da parte del cliente finale, indicando i dettagli della spedizioni in rientro.
Ulteriori informazioni
Il webook di notifica tracking spedizioni viene inviato quando:
- E’ attivo nelle impostazioni di configurazione.
- La spedizione cambia di stato, esempio quando passa da “in consegna” a “consegnato”.
Il trigger è il cambio di stato comunicato dal corriere.
Puoi verificare lo storico degli invii del webhook direttamente da Qapla’ dalla sezione Tracking, seleziona la spedizione e clicca sulla voce Webhook:
Test
Si consiglia di testare il proprio endpoint tramite l’apposito strumento di Test: Shipments webhook Test
Orders webhook – notifica generazione spedizioni
Orders webhook permette di ricevere una notifica POST in formato JSON in caso di uno dei seguenti eventi:
- Alla creazione, quando l’ordine viene generato (l’ordine passa da fase “Crea” a “Stampa” creando dunque la spedizione)
- Alla trasmissione , quando si esegue la trasmissione delle spedizioni generate (fase “Trasmetti”, ultima fase della generazione, ovvero l’invio dei dati al corriere)
Per configurare il webhook di notifica generazione spedizioni andare su sezione:
Impostazioni > Canali [Nome canale] > Configura > Aggiornamenti > Webhook > Webhook di notifica generazione spedizioni
Impostare:
- Attivazione: spuntare “Attiva” per l’abilitazione
- URL: inserire la URL che riceverà la notifica
- Evento: selezionare l’evento
- Alla creazione
- Alla trasmissione
Ulteriori informazioni
Il webhook di notifica generazione spedizioni non è previsto per chi usa la generazione delle spedizioni via API (createLabel e confirmLabel), ma solo chi esegue la generazione delle spedizioni tramite Control Panel Qapla’ (fasi Crea, Stampa e Trasmetti).
Il webook di notifica generazione spedizioni viene inviato quando:
- E’ attivo nelle impostazioni di configurazione.
- Si verifica l’evento selezionato in fase di configurazione.
Il trigger è l’evento selezionato su configurazione: alla creazione o alla trasmissione della spedizione.
Test
Si consiglia di testare il proprio endpoint tramite l’apposito strumento di Test: Orders webhook Test
