Guida all'integrazione SAFE

Guida all’integrazione — fiskaly SAFE

fiskaly SAFE fornisce archiviazione automatica dei dati fiscali dai servizi fiskaly connessi (SIGN DE, SIGN AT, DSFinV-K, ecc.) senza richiedere caricamenti manuali o chiamate API dirette. L’archiviazione è configurata e gestita tramite il fiskaly HUB.

📘SAFE vs SAFE flex

Questa guida tratta SAFE (archiviazione automatica gestita dall’HUB). Se si ha bisogno del controllo completo dell’API su cosa viene archiviato e quando, consultare invece la Guida all’integrazione SAFE flex. Per un confronto, vedere SAFE vs SAFE flex.

Prerequisiti

Prima di iniziare, assicurarsi di avere:

• Un’organizzazione fiskaly attiva con almeno un servizio connesso (p. es., SIGN DE, DSFinV-K)
• Accesso al fiskaly HUB con autorizzazioni di amministratore
• Un ambiente LIVE o TEST con TSS attivo o dati fiscali

Come funziona SAFE

SAFE archivia automaticamente le esportazioni dai servizi fiskaly connessi in base a un calendario configurato nell’HUB. Il processo è completamente gestito:

1. fiskaly genera le esportazioni dai servizi connessi (esportazioni TSE, chiusure DSFinV-K, ecc.)
2. SAFE archivia i dati nello spazio di archiviazione cloud certificato nella giurisdizione legalmente richiesta
3. I dati rimangono ricercabili ed esportabili per le verifiche (livelli di accesso Z1, Z2, Z3)

Non sono necessarie modifiche al codice nell’integrazione del registratore di cassa — SAFE si collega ai servizi fiskaly esistenti.

Configurazione tramite fiskaly HUB

1. Accedere all'HUB

   Andare su hub.fiskaly.com e accedere con le credenziali dell’organizzazione. Selezionare l’organizzazione per cui si vuole configurare SAFE.

2. Attivare SAFE

   Andare su Servizi > SAFE nella navigazione dell’HUB. Fare clic su Attiva SAFE per abilitare l’archiviazione automatica per la propria organizzazione. Verrà richiesto di selezionare la posizione di archiviazione (paese) in base ai requisiti legali.

3. Configurare la pianificazione dell'archiviazione

   Scegliere la frequenza di esportazione per l’archiviazione automatica:

   Frequenza	Ideale per
   Giornaliera	Operazioni ad alto volume che necessitano di archivi quasi in tempo reale
   Settimanale	Operazioni di vendita al dettaglio standard
   Mensile	Operazioni a basso volume o attività stagionali

   La pianificazione determina la frequenza con cui SAFE estrae nuove esportazioni dai servizi connessi e le archivia.

4. Selezionare i servizi connessi

   Scegliere quali servizi fiskaly devono alimentare SAFE:

   • SIGN DE — Archivia le esportazioni di transazioni TSE
   • SIGN AT — Archivia le esportazioni RKSV/DEP
   • DSFinV-K — Archivia le esportazioni di chiusura punto cassa
   • Ulteriori servizi man mano che diventano disponibili

   Ogni servizio viene attivato in modo indipendente. È possibile aggiungere o rimuovere servizi in qualsiasi momento.

5. Verificare il primo archivio

   Dopo la prima esecuzione pianificata, controllare la sezione SAFE > Archivi nell’HUB. Dovresti vedere:

   • Voci di archivio con timestamp e servizio di origine
   • Conteggio file e spazio di archiviazione totale utilizzato
   • Indicatori di stato (Elaborato, In attesa, Fallito)

   Se il primo archivio viene completato con successo, SAFE è pienamente operativo.

💡Testare prima nell'ambiente di test

Configurare e testare SAFE nell’ambiente TEST prima di abilitarlo in LIVE. Il comportamento è identico, ma è possibile verificare il flusso di archiviazione senza influire sui dati di produzione.

Accesso ai dati archiviati

Tramite HUB

1. Andare su SAFE > Archivi nell’HUB
2. Usare i filtri per restringere per intervallo di date, servizio o stato dell’archivio
3. Fare clic su qualsiasi voce di archivio per visualizzare i dettagli e scaricare i file
4. Usare il pulsante Esporta per scaricare gli archivi in blocco (formato ZIP)

Tramite API

I dati archiviati sono accessibili anche tramite l’API SAFE per l’accesso programmatico:

# Elencare gli archivi della propria organizzazione
curl -X GET "https://safe.fiskaly.com/api/v0/archives" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Scaricare un archivio specifico
curl -X GET "https://safe.fiskaly.com/api/v0/archives/{archive_id}/download" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o archive.zip

Per la documentazione API completa, consultare il Riferimento API SAFE.

Supporto per le verifiche

SAFE supporta tre livelli di accesso per le verifiche come definiti dalle autorità fiscali tedesche (e requisiti analoghi in altri paesi):

Livello di accesso	Descrizione	Come SAFE aiuta
Z1 — Accesso diretto	Il revisore accede direttamente al sistema	Fornire al revisore accesso in sola lettura tramite HUB
Z2 — Accesso indiretto	Il contribuente fornisce i dati su richiesta del revisore	Esportare da SAFE e consegnare al revisore
Z3 — Supporto dati	Esportazione leggibile da macchina su supporto di archiviazione	Scaricare gli archivi SAFE in formati standard

Conservazione e conformità

• I dati archiviati vengono conservati per il periodo di conservazione legalmente richiesto (tipicamente 10 anni in Germania, 7 anni in Austria)
• La posizione di archiviazione è determinata dal paese configurato durante l’attivazione
• I dati vengono archiviati in modo inalterabile in data center certificati di Google Cloud
• Viene mantenuto un registro di audit completo di tutte le operazioni di archiviazione

⚠️Responsabilità di conservazione

Sebbene SAFE gestisca l’archiviazione tecnica, l’utente rimane responsabile di garantire che la pianificazione dell’archiviazione acquisisca tutti i dati legalmente richiesti. Consultare il proprio consulente fiscale per i requisiti di conservazione specifici della propria giurisdizione.

Risoluzione dei problemi

Problema	Causa	Soluzione
Nessun archivio visualizzato	La pianificazione non è ancora stata attivata	Attendere la prossima esecuzione pianificata oppure attivare un archivio manuale dall’HUB
Stato archivio “Fallito”	Il servizio di origine non ha nuovi dati, o la generazione dell’esportazione è fallita	Controllare lo stato del servizio connesso nell’HUB; verificare che il TSS sia attivo
Dati mancanti nell’archivio	L’ambito di esportazione non include l’intervallo di date previsto	Verificare che la pianificazione dell’archivio copra il periodo; controllare eventuali lacune nei dati di origine

Passi successivi

Guida SAFE flex

Controllo API completo per flussi di archiviazione personalizzati

Dettagli di conformità

Requisiti legali di archiviazione per paese

Configurazione HUB SAFE

Configurazione dettagliata dell'HUB per SAFE