Ricevere aggiornamenti delle fatture tramite webhook

Nella sezione di configurazione API nella piattaforma Free Invoice, è possibile configurare degli endpoint a cui saranno inoltrate notifiche di ad ogni aggiornamento di fattura (sia di costo che di ricavo). In altre parole, ad ogni modifica dello stato fattura (ad esempio da “Inviata” a “Consegnata”), Free Invoice invierà una chiamata HTTP all’endpoint specificato con tutti i dettagli della fattura. Questa è la soluzione ideale per chi vuole utilizzare le API di Free Invoice in e-commerce e siti web.

Per poter funzionare, l’e-commerce deve esporre una rotta HTTP raggiungibile pubblicamente in grado di accettare chiamate POST con body in formato JSON.

Se l’utente ha configurato un endpoint “https://mioecommerce.it/freeinvoicewebhooks” ad ogni aggiornamento di una fattura sarà fatta una richiesta POST del tipo:

POST /invoiceId HTTP/ 1.1
Host: mioecommerce.it
Content-Type: application/json
x-freeinvoice-signature: cb5c4c6a2fa924e0848cd21b6935961d6851b9415d96ec8a…87c0a
x-freeinvoice-timestamp: 1602575616
Content-Length: 690
{
” type ” : ” invoice_status_changed ” ,
” data ” : {
” invoiceId ” : ” 12 ” ,

}
}

NB: il campo “data” mostrato nell’esempio è identico al campo ricevuto in risposta alla richiesta dettagli fattura. Per maggiori dettagli vedere la sezione “Visualizza i dettagli di una fattura”.

Per verificare la chiamata ricevuta sono SEMPRE NECESSARIE le seguenti operazioni:

  1. assicurarsi che il timestamp UNIX ricevuto nell’header “x-freeinvoice-timestamp” non sia distante dal timestamp attuale del sistema di oltre 5 minuti. Al fine di verificare questa condizione, assicurarsi che l’orario del webserver sia aggiornato correttamente.
  2. assicurarsi che la firma del messaggio ricevuta nell’header “x-freeinvoice-signature” sia uguale a
var timestamp = HEADER[‘x-freeinvoice-timestamp’]
var payload = BODY
var apiKey = ‘mia-api-key’
hash_hmac(‘sha256’, ” { timestamp }.{ payload } “, apiKey);

Se una delle due condizioni non è valida RIGETTARE la richiesta con HTTP status code diverso da 200. Per accettare la richiesta rispondere con HTTP status code 200.

NB: tutte le richieste rigettate saranno ritrasmesse ad intervalli regolari per tre giorni.

Questa guida è stata utile?

0