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": "DCW-00123", "idtrx": "123456", "document": {...dati documento...}, "document_id": "23738-fwej334fw-324ffws", "date": "2022-10-09T15:30:45.123456+01:00" }

Descrizione dei campi

CampoDescrizione
eventTipo di evento. In questo caso sempre "document_generated"
progressivoNumero progressivo del documento assegnato internamente (generato da AdE)
idtrxIdentificativo unico della transazione/vendita (generato da AdE)
documentOggetto contenente tutti i dettagli del documento fiscale trasmesso dal client precedentemente
document_idIdentificativo unico che permette di recuperare lo scontrino non fiscalizzato in pending e convertirlo in fiscale
dateData documento al momento della registrazione sul cassetto fiscale

All'interno dei campi document document_id e date troverai tutti i dati utili per:

  • Aggiornare lo stato del documento in pending
  • Memorizzare numero, data e progressivo 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

Developer – Come generare una DataCash-Key

Se vuoi integrare i nostri servizi per lo scontrino digitale nel tuo gestionale allora ti serve generare una datacash-key ovvero una chiave api che ti permette di autenticarti con i nostri servizi così da poter utilizzare le nostre API.

La prima cosa da fare è ovviamente registrarsi sul nostro sito nella sezione developer, selezionate il tipo di abbonamento e compilate il form.

Una volta avvenuta la registrazione possiamo andare sulla pagina di licenza datacash e generare l’api key.

Andare su datacash.it > accesso area clienti. Area Clienti.

Qui nella sezione abbonamenti in fondo alla pagina potete notare due pannelli di controllo istanza

  • Istanza Documento Commerciale Online API: servizio per l’emissione dello scontrino digitale
  • Istanza Fatturazione Elettronica API: servizio per l’emissione di fatture elettroniche tramite PEC

Come potete notare in alto a destra sul pannello di controllo istanza avete la documentazione swagger interattiva mentre un pò più in basso delle informazioni sulle chiavi api generate

Attenzione

le api key generate valgono sia per un’ istanza che per l’altra. Ovviamente il conteggio documenti sarà separato ma a livello di autenticazione non serve generare due api key per le due istanze, potete utilizzarne una per tutte e due

Per aggiungere un api key basta cliccare su aggiungi

Attenzione

le api key sono collegate ad una partita IVA. Questa partita IVA poi verrà confrontata con la partita IVA delle credenziali cifrate inviate al nostro server. Questo vuol dire che un api key può operare con una sola partita IVA. Se avete bisogno di emettere scontrini e fatture anche da un’altra partita IVA allora dovete aggiungere un’altra api key. Non c’è limite al numero di api key che potete aggiungere ed usare contemporaneamente

A questo punto inserite la partita IVA per cui volete emettere scontrini

salvare

Salvate l’api key da qualche parte nel vostro gestionale

Attenzione

la validità dell’api key dipende dalla licenza appena la licenza scade l’api key perde di validità e si riattiva una volta che avete riattivato la licenza

A questo punto la licenza è valida ed attiva

Ogni volta che effettuerete uno scontrino sulla partita IVA che avete agganciato all’api key si incrementerà il contatore documenti

Attenzione

sul contatore documenti potete notare un icona excel, se si clicca sull’icona viene scaricato un file con tutte le informazioni di emissione documento come data, tipo (se vendita, annullo o reso) e infine gli identificativi del documento

Nel momento in cui non operate più con quella partita IVA o la volete sostituire con un’altra potete disattivare l’api key

Una volta disattivata l’api key potete aggiungerne un’altra

Attenzione

si possono aggiungere quante api key si vogliono ovviamente con un limite che dipende dalla licenza

Nel casso volessimo aggiungere un’altra api key è il limite non me lo permette allora devo pagare un’ add-on api key

Andare in abbonamenti

Prima firmare il contratto se non lo avete già fatto qui una guida su come fare

Adesso cliccare su “+ Aggiungi add on”

Selezionate il tipo di Add-on API Key (se light, standard o premium), ignorate gli altri tipi di add-on, poi inserite il numero di api key che volete aggiungere, infine potete procedere con il pagamento

Una volta pagato l’add-on verrà incrementato il contatore delle api key disponibili

Recuperare le credenziali Fisconline dal proprio cassetto fiscale

ATTENZIONE
L’Agenzia può rilasciare credenziali Fisconline esclusivamente alle persone titolari di partita IVA o che risultino già autorizzate ad operare in nome e per conto di società, enti o professionisti (gestori incaricati e operatori incaricati).

1.1 Accesso area riservata Agenzia delle Entrate

Andare sul sito web dell’Agenzia delle Entrate al link https://www.agenziaentrate.gov.it e cliccare sul pulsante area riservata.

1) Accesso tramite SPID:

cliccare sulla scheda SPID

guida all'integrazione credenziali fisconline

selezionare il proprio gestore di identità digitale

inserire le proprie credenziali SPID ed accedere.

2) Accesso tramite CNS:

ATTENZIONE
tenere presente che la Carta Nazionale dei Servizi che dovrai utilizzare deve essere quella del rappresentante legale o quella dell’incaricato.

cliccare sulla scheda CNS

inserire la CNS nel lettore smart card o nella porta USB, se provvisti di chiavetta, e cliccare sul pulsante “Accedi con CNS”.

——————————————————————————————————–

Una volta entrati all’interno dell’Area Riservata, cliccare sulla voce di menù

“Profilo utente”

verificare che nel riquadro dei contatti sia presente un indirizzo email valido. Questo indirizzo verrà utilizzato dall’Agenzia delle Entrate per il recupero delle credenziali. Per aggiungere un indirizzo email o per verificare che l’indirizzo presente sia abilitato cliccare sulla voce “Gestisci contatti”.

Per aggiungere un contatto email, cliccare sulla voce “Aggiungi contatto”, selezionare “Indirizzo email”, inserire l’indirizzo, accettare l’informativa sulla privacy e cliccare su “Aggiungi”

Successivamente sotto la voce azioni, cliccare sulla matita e spuntare in corrispondenza della colonna avvisi. Una volta fatto cliccare sul simbolo a forma di floppy disk per salvare.

Sul menù “Profilo utente” selezionare la voce “Credenziali di sicurezza”.

ATTENZIONE
La voce “Credenziali di sicurezza” è stata cambiata con la voce “Sicurezza e privacy”.

Cliccare su “Prelievo credenziali” per generare la prima parte del codice PIN che verrà visualizzato nelle stessa videata. Nello stesso tempo, all’indirizzo e-mail che hai inserito all’interno dei contatti, riceverai la seconda parte del codice PIN. In tutto il PIN si compone di 10 cifre.

1.2 Recupero della password iniziale
Per recuperare la password iniziale accedere al seguente link dell’Agenzia delle Entrate

Inserire il codice fiscale, il codice PIN ricevuto dall’Agenzia delle Entrate spiegato nel paragrafo precedente e il codice di sicurezza, infine premere il tasto “Richiedi”.

Successivamente ci sono due possibili scenari, il primo è che l’Agenzia delle Entrate richiede di inserire il codice di verifica inviato sulla mail registrata precedentemente nei contatti, altrimenti viene visualizzato il messaggio “Gentile utente, ti ricordiamo che puoi accedere alla tua area riservata solo con SPID, Carta di identità elettronica (CIE) o Carta Nazionale dei Servizi (CNS), in linea con il Decreto Semplificazione e Innovazione digitale.”

Nel caso in cui venga richiesto di inserire il codice di verifica, apparirà questa schermata.

Quindi inserire il codice ricevuto per email e cliccare su verifica. A questo punto hai recuperato la password iniziale.

ATTENZIONE
conservare la password iniziale perchè sarà utile in caso di smarrimento della password personale.

Nel caso in cui non venga richiesto l’inserimento del codice di verifica, ma venga visualizzato il messaggio “Gentile utente, ti ricordiamo che puoi accedere alla tua area riservata solo con SPID, Carta di identità elettronica (CIE) o Carta Nazionale dei Servizi (CNS), in linea con il Decreto Semplificazione e Innovazione digitale.”, allora bisogna verificare che nella sezione “Profilo utente”, alla voce “Incarichi” e successivamente in “Visualizza chi mi ha incaricato” sia inserito il codice fiscale o la partita IVA dell’impresa.

Se non è presente questo dato bisogna accedere all’area riservata dell’Agenzia delle Entrate con le credenziali del rappresentante legale e creare un incarico.

Il rappresentante legale, nomina il gestore incaricato (o i gestori incaricati fino a un massimo di quattro) attraverso la funzionalità “Gestisci incaricati come rappresentante legale” presente all’interno dell’area riservata del sito web dell’Agenzia delle Entrate, nella sezione “Profilo utente”.

Sotto “Gestisci i tuoi incaricati” cliccare sulla voce “Come rappresentante legale”. A questo punto il rappresentante legale dovrà indicare il codice fiscale della società.

Successivamente, cliccare sulla voce “Aggiungi incaricato” e inserire il codice fiscale del gestore incaricato.
Fatto ciò, il nuovo gestore incaricato (che accede con le proprie credenziali) avrà pieno accesso all’utenza della società.

1.3 Creazione password di accesso ai servizi tramite password iniziale

Una volta recuperata la password iniziale, accedere al seguente link compilare tutti i campi e premere invia.

Ottimo hai recuperato le credenziali Fisconline.

ATTENZIONE

Se non riuscite a recuperare la password iniziale perchè non vi è nessuna password associata alla vostra utenza gli step da seguire sono questi:

1. COLLEGARE PARTITA IVA ALLA PERSONA FISICA

Molto probabilmente risultate già collegati alla Partita Iva della sua società, nel caso in cui non lo fosse, è necessario richiedere il collegamento.

2. RICHIESTA RESET UTENZA PERSONALE

Quando la persona fisica risulta collegata alla Partita Iva, basterà richiedere il reset dell’utenza personale (non il reset della società).

Il reset può essere anche chiamato disabilitazione e abilitazione dell’utenza personale.

Una volta completati questi due passaggi, potete riprovare a recuperare le credenziali Fisconline.