Vai al contenuto
v26.3

Conformità TSE — Documentazione per i verificatori fiscali

Questo documento è rivolto a verificatori fiscali, autorità tributarie e consulenti fiscali e descrive l'implementazione tecnica del collegamento TSE nel sistema di cassa DiKAS, conformemente ai requisiti di legge vigenti.

1. Basi legali

DiKAS soddisfa i requisiti delle seguenti normative:

Normativa Contenuto
§ 146a AO Tenuta regolare della cassa, obbligo di utilizzo di una TSE
KassenSichV Regolamento sulla sicurezza delle casse — requisiti tecnici per la TSE
AEAO relativo al § 146a AO Disposizione applicativa con specifiche di dettaglio su ProcessTypes, ProcessData, codice QR
DSFinV-K Interfaccia digitale dell'amministrazione finanziaria per i sistemi di cassa
GDPdU / GoBD Principi per la tenuta e la conservazione regolari dei libri contabili (verifica fiscale digitale)

2. Tipi di processo firmati (ProcessTypes)

DiKAS firma tutti i processi rilevanti ai fini di cassa secondo l'AEAO relativo al § 146a AO — non solo gli scontrini di cassa. Vengono utilizzati tre ProcessTypes secondo DSFinV-K:

2.1 Kassenbeleg-V1

Proprietà Valore
ProcessType Kassenbeleg-V1
Processi attivanti Ogni pagamento concluso (vendita diretta, pagamento al tavolo, storno)
Entities Receipt (DocumentType: Receipt2)

Formato ProcessData: 

Beleg^{BruttoGesamt}_{MwStSatz1}:{MwStBetrag1}_{MwStSatz2}:{MwStBetrag2}_...

Esempi: 

Beleg^119.00_19.00:19.00                          # Ein Steuersatz (19%)
Beleg^50.00_19.00:5.00_7.00:2.00                  # Zwei Steuersätze (19% + 7%)
Beleg^0.00_0.00:0.00                              # Nullbeleg

Tutti gli importi vengono formattati con due cifre decimali e il punto come separatore decimale (Invariant Culture), in conformità con la specifica DSFinV-K.

2.2 Bestellung-V1

Proprietà Valore
ProcessType Bestellung-V1
Processi attivanti Ogni ordine effettuato nel servizio al tavolo
Entities OpenBon (DocumentType: OpenBon)

Formato ProcessData: 

{Menge}^{Artikeltext}^{BruttoBetrag};{Menge}^{Artikeltext}^{BruttoBetrag};...

Esempio: 

2.00^Cola^7.00;1.00^Pizza^11.50

In caso di ordini cumulativi (batch), la firma TSE viene memorizzata sul primo scontrino del lotto. I ProcessData contengono tutte le posizioni dell'intero ordine.

2.3 SonstigerVorgang

Proprietà Valore
ProcessType SonstigerVorgang
Processi attivanti Apertura turno, chiusura turno, chiusura giornaliera, spese
Entities Exchange, DayClose, Spending

Formato ProcessData: 

{Vorgangstyp}^{Vorgangsdaten}

Tipi di processo concreti:

Tipo di processo Descrizione Esempio ProcessData
AVSichOpen Apertura turno AVSichOpen^Schichteroeffnung^200.00
AVSichClose Chiusura turno AVSichClose^Schichtschliessung^350.00
AVKassenschnitt Chiusura giornaliera (report Z) AVKassenschnitt^Tagesabschluss^1500.00
AVBelegabbruch Processo di storno AVBelegabbruch^Storno
AVSons662 Spesa/prelievo di contanti AVSonstige^Ausgabe^50.00

3. Campi dati TSE sui documenti

Ogni documento firmato memorizza i seguenti 9 campi TSE (implementati tramite l'interfaccia ITseDataHolder):

Campo Tipo Descrizione
TseTransactionNumber String Numero di transazione univoco della TSE
TseSignature String Firma digitale (codificata in Base64)
TseStartTime DateTime Inizio della firma (UTC)
TseEndTime DateTime Fine della firma (UTC)
TseSignatureCounter UInt64 Contatore di firma monotòno crescente
TseProcessData String Dati di processo firmati (vedere sezione 2)
TseProcessType String Identificatore ProcessType
TseSerialNumber String Numero di serie della TSE utilizzata
TseError String Messaggio di errore in caso di errore di firma (null in caso di successo)

Questi campi vengono memorizzati sulle seguenti entità:

  • Receipt — Scontrini di cassa (vendita, storno, reso)
  • OpenBon — Posizioni d'ordine (scontrino capofila negli ordini cumulativi)
  • Exchange — Aperture e chiusure di turno
  • DayClose — Chiusure giornaliere (report Z)
  • Spending — Spese e prelievi di contanti

4. Formato del codice QR (DSFinV-K Allegato I)

Ogni scontrino di cassa contiene un codice QR con i dati TSE nel formato standardizzato secondo DSFinV-K Allegato I:

V0;{KassenSeriennummer};{ProcessType};{ProcessData};{TransaktionsNr};{SignaturZähler};{StartZeit};{EndZeit};{SigAlgorithmus};{LogZeitformat};{Signatur};{PublicKey}

Concretamente: 

V0;KASSE-001;Kassenbeleg-V1;Beleg^29.30_19.00:4.68;12345;67890;2026-03-13T18:30:00.000Z;2026-03-13T18:30:01.000Z;ecdsa-plain-SHA256;unixTime;a8f3c2d1e5b7...;PK123...

Posizione Campo Origine
1 Versione Sempre V0
2 Numero di serie della cassa CashPointSerialNumber da BackendConfig
3 ProcessType TseProcessType dal giustificativo
4 ProcessData TseProcessData dal giustificativo
5 Numero di transazione TseTransactionNumber dal giustificativo
6 Contatore di firma TseSignatureCounter dal giustificativo
7 Ora di inizio TseStartTime (ISO 8601, UTC)
8 Ora di fine TseEndTime (ISO 8601, UTC)
9 Algoritmo di firma SigAlg da TseConfig (predefinito: ecdsa-plain-SHA256)
10 Formato dell'ora di log LogTimeFormat da TseConfig (predefinito: unixTime)
11 Firma TseSignature dal giustificativo
12 Chiave pubblica PublicKey da TseConfig

5. Identificazione della cassa (ClientId)

L'identificazione della cassa segue una catena di fallback a tre livelli:

Priorità Origine Descrizione
1 CashPointSerialNumber Numero di serie della cassa configurato esplicitamente (licenza)
2 BonIdServer Identificativo del server scontrini da BackendConfig
3 "1" Valore predefinito di fallback

Questa ClientId viene trasmessa come identificatore della cassa a ogni firma TSE e appare nel codice QR come numero di serie della cassa.

6. Configurazione TSE

La configurazione TSE viene memorizzata nel documento configTSE (TseConfig):

Campo Descrizione
PublicKey Chiave pubblica della TSE
Serial Numero di serie della TSE
SigAlg Algoritmo di firma (predefinito: ecdsa-plain-SHA256)
LogTimeFormat Formato dell'ora dei log TSE (predefinito: unixTime)
LocalPath Percorso locale della TSE hardware
SetupDate Data di messa in servizio della TSE
DecomissionDate Data di messa fuori servizio della TSE
TSESerialId ID serial interno

Collegamenti TSE supportati

Tipo Implementazione Descrizione
Hardware (Swissbit) SwissbitTseService Accesso USB diretto alla TSE Swissbit
Proxy (rete) TseProxyService TSE tramite proxy HTTP (ad es. Fiskaltrust)
Router TseServiceRouter Inoltro automatico: proxy preferito, fallback su hardware

7. Resilienza ai guasti e protocollazione

Registro delle interruzioni TSE (TseOutageLog)

Conformemente all'AEAO relativo al § 146a AO, DiKAS documenta automaticamente ogni interruzione della TSE:

Campo Descrizione
StartTime Inizio dell'interruzione (UTC)
EndTime Fine dell'interruzione (UTC, null se ancora in corso)
Reason Causa (ad es. „TSE not available", „TSE timeout")
AffectedTransactions Numero di transazioni interessate

Svolgimento in caso di interruzione della TSE:

  1. La firma TSE fallisce → il campo TseError sul documento viene impostato
  2. Viene creata una nuova voce TseOutageLog (con StartTime e Reason)
  3. Il processo di cassa non viene bloccato — la transazione viene memorizzata senza firma
  4. Alla successiva firma riuscita, tutte le voci di interruzione aperte vengono chiuse (EndTime impostato)

Timeout: Ogni firma TSE ha un timeout di 5 secondi. In caso di superamento viene impostato TseError = "TSE timeout".

Verifica in fase di controllo

Per ogni documento con TseError != null è presente un errore di firma documentato. La voce TseOutageLog corrispondente attesta il periodo e la causa dell'interruzione.

8. Esportazione dei dati per la verifica fiscale

8.1 Esportazione DSFinV-K

DiKAS esporta tutti i dati di cassa nel formato DSFinV-K (interfaccia digitale dell'amministrazione finanziaria per i sistemi di cassa):

  • Tutti i file CSV prescritti secondo la specifica DSFinV-K
  • Esportazione per periodo possibile
  • Contiene: registrazioni singole, dati anagrafici, dati TSE, chiusure di cassa

8.2 Esportazione TSE-TAR

Esportazione diretta dei dati di log TSE come archivio TAR:

  • Esportazione completa: tutte le transazioni memorizzate della TSE
  • Esportazione filtrata: per periodo (startDate/endDate)
  • Endpoint API: GET /api/v1/tse/export/tar

8.3 Esportazione GDPdU

Per la verifica fiscale digitale secondo GDPdU/GoBD:

  • File di esportazione strutturato con tutti i dati fiscalmente rilevanti
  • Leggibile dalle macchine per software di controllo (IDEA, AIS, ecc.)

8.4 Esportazione DATEV

Per la contabilità corrente presso il consulente fiscale:

  • 7 modalità di esportazione (chiusura giornaliera, ProBon, ProÖffnungstag, WGR, WGR2, NachRechnung, spese)
  • Formato EXTF v13 con chiavi BU corrette (USt 3/2/40, VSt 9/8/40)
  • Opzionalmente crittografato (AES-256 ZIP) e inviabile via e-mail

9. Processo di firma nel dettaglio

9.1 Svolgimento di una firma

Kassenvorgang → TseSigningHelper → ITseService → TSE (Hardware/Proxy)
                     │                                    │
                     │  1. BackendConfig laden             │
                     │  2. Prüfen: TSE verfügbar?          │
                     │  3. ProcessData aufbauen             │
                     │  4. ClientId auflösen                │
                     │  5. SignReceiptAsync aufrufen ───────→│
                     │  6. Ergebnis auf Entity speichern ←──│
                     │  7. OutageLog aktualisieren          │
                     └──────────────────────────────────────┘

9.2 Quali handler firmano?

Handler Processo ProcessType
ProcessDirectSaleCommand Vendita diretta Kassenbeleg-V1
ProcessTablePaymentCommand Pagamento al tavolo Kassenbeleg-V1
VoidReceiptCommand Storno Kassenbeleg-V1
CreateOpenBonCommand Ordine singolo Bestellung-V1
CreateOpenBonsBatchCommand Ordine cumulativo Bestellung-V1
OpenExchangeCommand Apertura turno SonstigerVorgang
CloseExchangeCommand Chiusura turno SonstigerVorgang
PerformDayCloseCommand Chiusura giornaliera SonstigerVorgang
CreateSpendingCommand Spesa/prelievo di contanti SonstigerVorgang

9.3 Gestione degli errori

La firma TSE è implementata in modo non bloccante:

  • Gli errori TSE vengono documentati nel campo TseError, il processo viene comunque memorizzato
  • Un try/catch attorno all'intero processo di firma impedisce che i problemi della TSE compromettano l'attività di cassa
  • Il metodo HandleOutageLogAsync aggiorna il registro delle interruzioni dopo ogni firma (successo o errore)

10. Completezza delle registrazioni

Firma senza lacune

DiKAS garantisce la firma senza lacune di tutti i processi rilevanti ai fini di cassa mediante:

  1. Logica di firma centralizzata: tutte le firme passano attraverso TseSigningHelper — non esiste alcun modo per concludere un processo rilevante ai fini di cassa senza una chiamata alla TSE
  2. Contatore di firma monotòno: il TseSignatureCounter è gestito dalla TSE e cresce in modo monotòno. Le lacune nel contatore indicano interruzioni, documentate nel TseOutageLog
  3. Numeri di transazione: ogni transazione TSE riceve un TseTransactionNumber univoco
  4. Timestamp: l'ora di inizio e di fine di ogni firma vengono memorizzate

Protezione contro le manipolazioni

  • Algoritmo di firma: ECDSA con SHA-256 (ecdsa-plain-SHA256)
  • L'hardware TSE è certificato BSI (Common Criteria)
  • La chiave pubblica della TSE è memorizzata nella TseConfig e può essere utilizzata per la verifica della firma
  • Le modifiche a posteriori ai documenti firmati sono rilevabili tramite la firma crittografica

11. Indicazioni per i verificatori fiscali

Dove trovare i dati TSE?

Fonte dei dati Accesso
Campi TSE sui giustificativi In ogni documento Receipt/OpenBon/Exchange/DayClose/Spending
Codici QR Sugli scontrini di cassa stampati
Registro delle interruzioni TSE Documenti TseOutageLog nel database
Configurazione TSE Documento configTSE
Esportazione DSFinV-K Admin → Impostazioni → Esportazione → DSFinV-K
Esportazione TSE-TAR Admin → Impostazioni → TSE → Esportazione
Esportazione GDPdU Admin → Impostazioni → Esportazione → GDPdU

Come verificare le firme?

  1. Scansionare il codice QR: ogni scontrino contiene un codice QR nel formato V0 (DSFinV-K Allegato I)
  2. Esportare il TSE-TAR: il file TAR contiene tutti i dati di log TSE e può essere validato con strumenti di controllo
  3. Verificare il contatore di firma: il contatore monotòno crescente non deve presentare lacune inspiegabili
  4. Registro delle interruzioni: le lacune nel contatore di firma devono essere spiegate da voci TseOutageLog
  5. Chiave pubblica: si trova nella TseConfig e può essere utilizzata per la verifica matematica delle singole firme

Lista di controllo per la verifica della cassa

  • Il numero di serie della TSE corrisponde a quello comunicato all'Agenzia delle Entrate
  • Il contatore di firma è privo di lacune (lacune spiegabili tramite i registri delle interruzioni)
  • I ProcessTypes corrispondono alle disposizioni AEAO (Kassenbeleg-V1, Bestellung-V1, SonstigerVorgang)
  • I formati ProcessData sono conformi a DSFinV-K
  • Il formato del codice QR corrisponde a DSFinV-K Allegato I (formato V0)
  • I timestamp sono plausibili (inizio < fine, crescenti cronologicamente)
  • I tempi di interruzione della TSE sono documentati e tracciabili
  • Tutti i tipi di processo rilevanti ai fini di cassa vengono firmati (non solo gli scontrini di cassa)
  • L'esportazione DSFinV-K è completa e leggibile dalle macchine
  • Il certificato TSE era valido nel periodo di verifica

12. Dati tecnici essenziali

Proprietà Valore
Algoritmo di firma ECDSA con SHA-256 (ecdsa-plain-SHA256)
Formato del codice QR DSFinV-K Allegato I, versione V0
Formato dell'ora ISO 8601, UTC (yyyy-MM-ddTHH🇲🇲ss.fffZ)
Formato degli importi Invariant Culture, 2 cifre decimali (ad es. 119.00)
Timeout TSE 5 secondi per firma
TSE supportate Swissbit (USB), proxy di rete
Comportamento in caso di guasto Non bloccante, protocollazione automatica
Database CouchDB oppure SQLite/SQL Server (configurabile)
Base API .NET 10, Clean Architecture, CQRS con MediatR
Copertura dei test 17 test TSE dedicati (firma, ProcessData, codice QR, fallback)

Appendice: Associazione tipo di processo → documento → database

Processo di cassa ProcessType Entity DocumentType Collezione del database
Vendita diretta (contanti/carta) Kassenbeleg-V1 Receipt Receipt2 receipt2
Pagamento al tavolo Kassenbeleg-V1 Receipt Receipt2 receipt2
Storno Kassenbeleg-V1 Receipt Receipt2 receipt2
Ordine (tavolo) Bestellung-V1 OpenBon OpenBon openbon
Ordine cumulativo Bestellung-V1 OpenBon OpenBon openbon
Apertura turno SonstigerVorgang Exchange Exchange2 exchange2
Chiusura turno SonstigerVorgang Exchange Exchange2 exchange2
Chiusura giornaliera (report Z) SonstigerVorgang DayClose DayClose2 dayclose2
Spesa/prelievo di contanti SonstigerVorgang Spending CashPointSpending cashpointspending