Skip to main content

Impostazione del Webhook per la Fiscalizzazione Differita

Una componente fondamentale per l’integrazione del servizio DataCash API è la configurazione del webhook, che consente la gestione automatizzata delle vendite in caso di indisponibilità temporanea dei servizi dell’Agenzia delle Entrate.

Finalità del Webhook

Il webhook consente al sistema di emettere e gestire vendite anche quando l’Agenzia delle Entrate risulta non raggiungibile (es. downtime o malfunzionamenti). In tali situazioni, la nostra infrastruttura elabora la vendita e la contrassegna come pending, generando comunque un identificativo univoco del documento. Questo identificativo viene restituito nella risposta del nostro server e può essere utilizzato dal client per stampare un documento temporaneo non fiscalizzato.

Comportamento del Sistema

  1. Webhook configurato: quando l’Agenzia delle Entrate è down, il sistema registra la vendita in stato pending.
  2. Risposta immediata: viene inviata una risposta HTTP contenente:
    • Un identificativo temporaneo del documento
    • Eventuali dettagli utili per l’emissione provvisoria dello scontrino
  3. Tentativi automatici: l’infrastruttura tenterà automaticamente la fiscalizzazione del documento pending, riprovando a intervalli regolari (es. ogni ora) finché la comunicazione con l’Agenzia non avrà esito positivo.
  4. Notifica di fiscalizzazione: una volta fiscalizzata con successo, il sistema invia una notifica webhook al client contenente:
    • L’identificativo del documento pending
    • I dettagli completi del documento fiscalizzato (numero, data, codice di risposta AE, ecc.)

Benefici

Grazie a questo meccanismo, il cliente può:

  • Gestire correttamente il flusso di cassa anche in assenza temporanea di connettività con l’Agenzia delle Entrate
  • Associare in modo affidabile la fiscalizzazione posticipata al documento originario pending
  • Aggiornare lo stato fiscale del documento una volta ricevuta la conferma

⚠️ Nota: il corretto funzionamento del sistema in modalità offline è subordinato alla corretta configurazione del webhook. In assenza di webhook, la fiscalizzazione differita non potrà essere eseguita.

Configurazione del Webhook dal Pannello di Controllo

Per abilitare la gestione automatizzata delle fiscalizzazioni tramite webhook, è necessario configurare l’URL di notifica all’interno del proprio pannello di controllo cliente.

Passaggi per configurare il Webhook

  1. Accedere al portale clienti:
    • Visitare il sito https://datacash.it
    • Cliccare su Accesso Area Clienti
    • Effettuare il login con le credenziali TelnetData
  2. Accedere alla sezione Abbonamenti:
    • Una volta autenticati, cliccare sulla voce Abbonamenti
    • Verrà mostrato il pannello di controllo DataCash-API
  1. Configurare l’URL del webhook:
    • Cliccare sulla voce Webhook URL
    • Inserire l’indirizzo completo (endpoint HTTPS) su cui il vostro sistema è in ascolto per ricevere le notifiche di avvenuta fiscalizzazione
  1. Configurare il Webhook Token:
    • Nella stessa schermata è presente il campo Webhook Token
    • Questo token è un identificativo segreto che i nostri server invieranno in ogni notifica webhook
    • Inseritelo nel campo dedicato e salvatelo in modo sicuro anche lato server, poiché vi servirà per verificare l’autenticità delle chiamate ricevute
  1. Verifica e test del Webhook:
    • Dopo aver salvato l’URL e il token, è possibile cliccare sull’icona “Test” per verificare la raggiungibilità del webhook
  1. Analisi dei log di notifica:
    • Ogni notifica inviata dai nostri sistemi viene tracciata nella sezione Webhook Log
    • Qui è possibile consultare:
      • L’esito del test
      • Il payload completo
      • La presenza del webhook token nella richiesta

Sicurezza del Webhook: verifica della firma

Per garantire che le notifiche webhook provengano effettivamente dai server DataCash, ogni richiesta viene firmata utilizzando un meccanismo di HMAC-SHA256, basato su un token condiviso disponibile nel pannello di controllo.

Come funziona la firma

Quando viene inviata una notifica webhook:

  1. Il payload viene serializzato in JSON utilizzando la sintassi compatta (separators=(',', ':')).
  2. Il server genera una firma HMAC-SHA256 del payload, utilizzando il webhook_secret come chiave.
  3. La firma viene inclusa nell’header HTTP della richiesta con il nome:

X-Signature: <firma_hex>

Configurazione nel pannello di controllo

Nel portale clienti (voce Abbonamenti), oltre all’URL del webhook, è possibile inserire un Webhook Secret:

  • Questo segreto viene utilizzato per generare la firma lato server
  • Deve essere salvato anche lato client e utilizzato per verificare la firma in arrivo

Verifica lato client

Per garantire l’integrità e l’autenticità della richiesta, si consiglia di ricalcolare la firma lato client e confrontarla con il valore ricevuto nell’header X-Signature.

Esempio (Python):

Vantaggi della firma HMAC

  • 🔒 Sicurezza: impedisce a soggetti non autorizzati di inviare notifiche false
  • ✅ Integrità: garantisce che il payload non sia stato modificato in transito
  • 🔁 Verificabilità: ogni chiamata può essere tracciata e autenticata

⚠️ Importante: il segreto deve essere mantenuto privato. Non condividetelo mai pubblicamente o via canali non sicuri.

Esempio di Payload Webhook

Quando un documento pending viene fiscalizzato con successo, il sistema DataCash invia una richiesta HTTP POST all’URL configurato tramite webhook. La richiesta include nel corpo un oggetto JSON firmato (con HMAC-SHA256) che ha la seguente struttura:

Esempio reale di payload

{ "event": "document_generated", "progressivo": "00123", "idtrx": "dc_bill_20250701_ab123", "document": {...dati documento...} }

Descrizione dei campi

CampoDescrizione
eventTipo di evento. In questo caso sempre "document_generated"
progressivoNumero progressivo del documento assegnato internamente
idtrxIdentificativo unico della transazione/vendita
documentOggetto contenente tutti i dettagli del documento fiscale trasmesso dal client precedentemente

All'interno del campo document troverai tutti i dati utili per:

  • Aggiornare lo stato del documento in pending
  • Memorizzare numero, data e codice fiscale ufficiale
  • Sincronizzare articoli e metodi di pagamento con i dati effettivamente inviati all'Agenzia delle Entrate

Sicurezza del payload

Come già descritto nella sezione precedente:

  • Il payload viene firmato con algoritmo HMAC-SHA256
  • La firma è inclusa nell'header X-Signature
  • È necessario validare la firma sul proprio endpoint per garantire l’autenticità della notifica