Germania (SIGN DE)

📘API specializzata

SIGN DE è un’API specializzata — progettata specificamente per la conformità tedesca KassenSichV, certificata BSI e il prodotto più maturo di fiskaly. Utilizza una superficie API dedicata con propri endpoint e modello di risorse. Per l’architettura API unificata multi-paese (che copre Francia, Italia, Svezia), consulta L’API unificata.

Cosa devi sapere

La Germania ha i requisiti di conformità fiscale più completi tra tutti i paesi supportati da fiskaly. Un’integrazione tedesca completa richiede tre prodotti che lavorano insieme:

Prodotto	Funzione	Obbligatorio?
SIGN DE	Firma crittograficamente ogni transazione tramite una Cloud-TSS certificata BSI	Sì — KassenSichV
DSFINVK DE	Genera esportazioni di dati fiscali pronti per l’audit dalle chiusure di cassa	Sì — per le verifiche fiscali
SUBMIT DE	Invia dichiarazioni elettroniche a ELSTER (interfaccia dell’autorità fiscale tedesca)	Sì — dal 2025
SAFE	Archivia i dati fiscali per 10–30 anni in data center certificati	Consigliato

💡Nuovo su fiskaly?

Inizia con la Guida rapida per ottenere una transazione firmata in 5 minuti. Torna qui per il quadro completo.

Cos’è KassenSichV?

La Kassensicherungsverordnung (KassenSichV) impone a tutti i sistemi elettronici di registrazione (ERS) in Germania di:

• Utilizzare un sistema di sicurezza tecnica (TSS) certificato per firmare ogni transazione
• Mantenere tracciati di verifica a prova di manomissione con firme crittografiche
• Generare esportazioni DSFinV-K per i revisori fiscali
• Stampare codici QR sulle ricevute contenenti i dati della firma

La Cloud-TSS di fiskaly è la prima TSS basata su cloud ad aver ottenuto la certificazione BSI, attualmente valida fino al 2033. Nessun hardware, nessun modulo crittografico locale — solo chiamate API.

Effort di integrazione

Per i PM che stimano il lavoro:

Fase	Durata	Cosa succede
Configurazione sandbox	1–2 giorni	Creazione account, chiavi API, prima transazione firmata
Integrazione SIGN DE	3–5 settimane	Provisioning TSS, firma transazioni, QR code sulle ricevute, gestione degli errori
Integrazione DSFINVK DE	2–3 settimane	Mappare il modello dati POS sulla tassonomia DSFINVK DE, implementare chiusure di cassa
Integrazione SUBMIT DE	1–2 settimane	Registrazione contribuente, presentazione dichiarazioni
Test end-to-end	1–2 settimane	Validazione completa del flusso in sandbox
Go-live	1 settimana	Provisioning LIVE, rollout graduale, configurazione monitoraggio
Totale	8–13 settimane	1–2 sviluppatori backend con esperienza nel dominio POS

Consulta la Guida alla pianificazione dell’integrazione per i requisiti del team, le mappe delle dipendenze e un modello di cronologia di lancio.

Panoramica dell’architettura

Il tuo sistema di cassa
  |
  |-- POST /auth (chiave API + segreto) --> Token Bearer (24h)
  |
  |-- PUT /tss/{id} -----------------> Creare + inizializzare TSS (una volta per sede)
  |-- PUT /tss/{id}/client/{id} -----> Creare client (uno per terminale POS)
  |
  |-- PUT /tss/{id}/tx/{id} ---------> Avviare transazione (stato: ACTIVE)
  |-- PUT /tss/{id}/tx/{id} ---------> Completare transazione (stato: FINISHED)
  |                                     La risposta include firma + dati QR code
  |
  |-- POST /dsfinvk/closings --------> Inviare dati di chiusura cassa
  |-- GET  /dsfinvk/exports  --------> Generare file di esportazione DSFinV-K
  |
  |-- POST /submission/submit -------> Presentare dichiarazione a ELSTER

Responsabilità

La tua responsabilità (fornitore del sistema di cassa)

• Integrare la TSS di fiskaly nel tuo ERS
• Assicurarti che ogni transazione sia firmata prima dell’emissione della ricevuta
• Stampare QR code con i dati della firma sulle ricevute
• Generare chiusure di cassa DSFINVK DE a fine giornata
• Presentare dichiarazioni tramite SUBMIT DE
• Gestire i timeout correttamente (vedi gestione degli errori)

Responsabilità del tuo cliente (contribuente)

• Avere un ERS con TSS integrata collegata al proprio account
• Consegnare le esportazioni TSS e DSFinV-K ai revisori entro i termini richiesti
• Mantenere backup dei dati fiscali (conservazione di 10–30 anni, si raccomandano due sedi fisiche)

Responsabilità di fiskaly

• Operare e mantenere la Cloud-TSS certificata (SLA disponibilità 99,9%)
• Fornire aggiornamenti software e patch di sicurezza (gratuiti)
• Gestire i rinnovi della certificazione
• Mantenere la disponibilità e le prestazioni dell’API

Checklist di conformità per il go-live

Prima del lancio in produzione, verifica:

• Per ogni sede/negozio, assicurati di avere una TSS individuale creata, impostata su UNINITIALIZED, PIN amministratore impostato e TSS impostata su INITIALIZED
• Client creato per ogni terminale POS
• Ogni transazione è firmata (ciclo di vita start + finish)
• La ricevuta include il QR code KassenSichV (riferimento formato)
• Il QR code si valida correttamente (strumento di validazione)
• Le chiusure di cassa DSFINVK DE vengono generate correttamente
• La dichiarazione SUBMIT DE viene accettata da ELSTER
• Il timeout di firma è di 3–5 secondi e non blocca il processo di pagamento
• La logica di retry gestisce gli errori 5xx con backoff esponenziale
• L’amministratore è disconnesso dopo il provisioning
• L’ambiente LIVE è fornito separatamente da TEST

⚠️Una firma mancante non invalida una ricevuta

Se la TSS non è disponibile, emetti la ricevuta con una nota come “TSS non disponibile” e includi la transazione non firmata nella tua esportazione DSFinV-K. Vedi gestione degli errori per i dettagli.

Documentazione

Per iniziare

Introduzione

Contesto KassenSichV, acquisizione Deutsche Fiskal, dettagli sulla certificazione

Guida per i nuovi clienti

Passo dopo passo: dalla configurazione dell'account alla prima transazione firmata con esempi di codice

Dettagli tecnici

Architettura TSS, flusso dati delle transazioni e processo di firma crittografica

Guide

Gestione degli errori

Strategia di timeout, logica di retry e cosa fare quando la TSS non è disponibile

Tutorial Postman

Esplorazione interattiva dell'API — senza necessità di codice

Manuale del dashboard

Gestire organizzazioni, chiavi API e TSS tramite l'interfaccia web

Conformità

Dati della ricevuta

Campi obbligatori della ricevuta e specifica del contenuto del QR code

Validazione QR code

Verifica che i tuoi QR code siano conformi a KassenSichV

Certificazione

Documenti di certificazione BSI e periodi di validità

Prodotti correlati

DSFINVK DE

Esportazione dati fiscali — obbligatoria per la Germania, fa riferimento ai dati SIGN DE

SUBMIT DE

Dichiarazione ELSTER — obbligatoria per la Germania dal 2025

SAFE

Archiviazione a lungo termine delle esportazioni fiscali (consigliato)

Riferimento

Riferimento API (SIGN DE v2)

Documentazione interattiva degli endpoint con tutti gli schemi

Glossario

Termini KassenSichV: TSS, ERS, DSFinV-K e altro

Supporto

Come ottenere aiuto, raccolte di esempio e canali di contatto