Pianificazione dell'integrazione

Questa pagina è per product manager e responsabili tecnici che pianificano un’integrazione fiskaly. Copre stime dello sforzo, requisiti del team, dipendenze tra prodotti, milestone di conformità e un modello di timeline di rollout.

💡Per gli sviluppatori

Se vuoi scrivere codice, inizia dall’Avvio rapido.

Passo 1: Scegli la tua architettura API

fiskaly fornisce due architetture API. La tua scelta dipende dai paesi di cui hai bisogno:

Se hai bisogno di…	Usa…	Perché
Solo Germania, Austria o Spagna	API Specializzata per quel paese	Costruita appositamente, supporto più approfondito per quel paese
Solo Francia o Italia	API Unificata	Architettura multi-paese — aggiungere l’altro richiede ~1 settimana
Francia + Italia (o + Svezia)	API Unificata	Integra una volta, espandi cambiando lo schema payload
Germania + Francia/Italia	Entrambe	API Specializzata per DE + API Unificata per FR/IT. Stesso schema auth, modelli di risorse diversi.
3+ paesi inclusi FR/IT	Inizia con API Unificata	Poi aggiungi API Specializzate per DE/AT/ES secondo necessità

Consulta L’API Unificata per il confronto completo dell’architettura, il modello di risorse e la mappatura della terminologia.

Passo 2: Determina la portata del prodotto

I prodotti fiskaly di cui hai bisogno dipendono da dove operi e da quali normative si applicano. Usa questo albero decisionale:

Gestisci sistemi POS in uno di questi paesi?

Germania -> SIGN DE + DSFinV-K + SUBMIT DE (tutti e tre obbligatori)
Austria -> SIGN AT
Francia -> SIGN FR (certificazione NF525 obbligatoria)
Spagna -> SIGN ES (TicketBAI o Verifactu, a seconda della regione)
Italia -> SIGN IT
Svezia -> SIGN SE (InfraSec TCS)
Belgio -> E-Invoice (solo B2B, via Peppol)

Hai bisogno di archiviazione a lungo termine conforme? -> Aggiungi SAFE o SAFE flex

Vuoi sostituire le ricevute cartacee? -> Aggiungi eReceipt (opzionale, qualsiasi paese UE)

La Germania è la più complessa

La Germania richiede tre prodotti che lavorano insieme. Ecco come si relazionano:

SIGN DE (firma transazioni)
  |
  +--> DSFinV-K (generazione export fiscale, fa riferimento ai dati SIGN DE)
  |
  +--> SUBMIT DE (presentazione ELSTER, fa riferimento ai client e TSS SIGN DE)
  |
  +--> SAFE (archiviazione opzionale degli export)

Per gli altri paesi, SIGN è tipicamente l’unica integrazione obbligatoria.

Passo 3: Stima lo sforzo di integrazione

Queste sono le timeline tipiche per un team di 1-2 sviluppatori backend con esperienza nel dominio POS. La tua timeline effettiva dipende dall’architettura del tuo POS, dalla cadenza dei rilasci e dai requisiti di test.

API Specializzate (SIGN DE, SIGN AT, SIGN ES)

Prodotto	Prima integrazione	Da SIGN DE	Note
SIGN DE	4-8 settimane	—	Provisioning TSS, firma transazioni, QR code ricevuta, gestione errori
SIGN AT	3-5 settimane	1-2 settimane	Più simile a SIGN DE. SCU invece di TSS, registrazione FinanzOnline.
SIGN ES	5-7 settimane	2-4 settimane	Gestione certificati, 6 tipi di fattura, invio in tempo reale

API Unificata (SIGN FR, SIGN IT, SIGN SE)

Prodotto	Primo paese API Unificata	Ogni paese aggiuntivo	Da SIGN DE	Note
SIGN FR	4-6 settimane	—	1-3 settimane	La certificazione NF525 aggiunge 4-8 settimane separatamente
SIGN IT	4-6 settimane	—	1-3 settimane	Lotteria degli scontrini, gestione perdita connessione
FR + IT	4-6 settimane (primo)	~1 settimana (secondo)	—	Stesso modello di risorse — differiscono solo payload e fiscalizzazione Taxpayer
SIGN SE	2-4 settimane	—	—	Attualmente InfraSec TCS (XML, X.509); API Unificata in arrivo

Prodotti complementari

Prodotto	Durata	Note
DSFinV-K	2-4 settimane	Solo Germania. Mappatura del modello dati POS alla tassonomia DSFinV-K.
SUBMIT DE	1-2 settimane	Solo Germania. Semplice se SIGN DE è già integrato.
SAFE	1 settimana (SAFE) / 2 settimane (flex)	SAFE si collega automaticamente a SIGN; SAFE flex richiede logica di upload manuale.
E-Invoice	2-4 settimane	Belgio live; altri in arrivo. Separato da SIGN.
eReceipt	1-2 settimane	Indipendente dal paese. Principalmente lavoro frontend (visualizzazione QR).

Timeline tipica solo Germania

Settimane 1-2:  Configurazione account, accesso sandbox, auth SIGN DE + provisioning TSS
Settimane 3-5:  Firma transazioni, generazione ricevute, gestione errori
Settimane 5-6:  Mappatura DSFinV-K e generazione export
Settimane 6-7:  Integrazione SUBMIT DE
Settimane 7-8:  Test end-to-end in sandbox
Settimane 8-9:  Preparazione go-live, provisioning ambiente LIVE
Settimane 9-10: Rollout produzione, monitoraggio

Totale: ~10 settimane dall’avvio alla produzione per la Germania (SIGN DE + DSFinV-K + SUBMIT DE).

Timeline rollout multi-paese

Se stai espandendo da un’integrazione SIGN DE esistente:

Settimana 1:    Revisione documentazione paese target, identificazione differenze payload
Settimana 2:    Implementazione adapter specifico per paese, test sandbox
Settimana 3:    QA, validazione conformità ricevute, go-live

Totale: ~3 settimane per ogni paese aggiuntivo (AT, FR, IT, ES).

Passo 4: Pianifica il tuo team

Ruolo	Responsabilità	Quando necessario
Sviluppatore backend (1-2)	Integrazione API, firma transazioni, gestione errori, logica di retry	Per tutta la durata dell’integrazione
Sviluppatore frontend (0-1)	Rendering ricevute, visualizzazione QR code, interfaccia eReceipt	Dopo che la firma backend funziona
QA engineer (1)	Test end-to-end, validazione conformità, casi limite (timeout, offline)	Dalla settimana 5 in poi
Product manager	Decisioni di portata, raccolta requisiti di conformità, checklist go-live	Per tutta la durata
DevOps / Infra (0-1)	Gestione segreti, monitoraggio, alerting per guasti di firma	Preparazione go-live

Passo 5: Comprendi la checklist di conformità

Prima di andare in produzione in qualsiasi paese, verifica questi elementi:

Checklist universale (tutti i paesi)

Credenziali API conservate in un gestore di segreti (non nel codice sorgente)
Caching del token implementato (non ri-autenticarsi per transazione)
Logica di retry con exponential backoff per errori 5xx e timeout
Timeout di firma configurato (3-5 secondi) e non blocca il checkout
La ricevuta include tutti i campi obbligatori per il paese target
La gestione degli errori copre l’indisponibilità del TSS (vedi guida alla gestione degli errori)
I test di integrazione nell’ambiente TEST passano
Ambiente LIVE provisioned tramite HUB
Monitoraggio/alerting configurato per guasti di firma e latenza

Checklist specifica per la Germania

TSS creato, PIN Admin impostato e TSS inizializzato
Client creato per ogni terminale POS
La ricevuta include il QR code KassenSichV (vedi dati ricevuta)
Il QR code si convalida correttamente (vedi validazione QR code)
L’export DSFinV-K genera e si convalida
La dichiarazione SUBMIT DE viene presentata correttamente con ELSTER
Logout Admin dopo il provisioning

Checklist specifica per la Francia

Processo di certificazione NF525 avviato con il supporto fiskaly
Chiusure di periodo implementate (giornaliere, mensili, annuali)
Generazione archivi automatizzata
Modalità replay offline testata

Checklist specifica per l’Italia

Campi della lotteria degli scontrini (Lotteria degli Scontrini) inclusi
Gestione perdita connessione testata
Stati di location e system del Taxpayer gestiti correttamente

Passo 6: Preparazione al go-live

Completare i test in sandbox
Esegui la tua suite di test completa nell’ambiente TEST. Verifica tutti i tipi di transazione, gli scenari di errore e la generazione degli export.
Richiedere l'accesso LIVE
Passa la tua organizzazione all’ambiente LIVE tramite HUB. Contatta il tuo account manager se hai bisogno di assistenza.
Provisionare le risorse LIVE
Le risorse di TEST non vengono trasferite. Riesegui il tuo flusso di provisioning (creazione TSS, registrazione client) nell’ambiente LIVE.
Rollout graduale
Inizia con una singola sede o terminale. Monitora la latenza di firma, i tassi di errore e la conformità delle ricevute per 1-2 settimane prima di espandere.
Configurare il monitoraggio
Monitora: tasso di successo della firma, latenza media di firma, tasso di errori 401 (problemi di aggiornamento token) e tasso di errori 5xx (problemi del servizio). Alerta se il tasso di guasto della firma supera l’1%.

⚠️TEST e LIVE sono completamente separati

TSS, client, transazioni ed export creati in TEST non esistono in LIVE. Il tuo deployment di go-live deve includere un passaggio di provisioning.

Link chiave per i PM

Panoramica prodotti

Cosa fa ogni prodotto e quando ne hai bisogno

Copertura paesi (E-Invoice)

Quando i nuovi moduli paese diventano disponibili

SAFE vs SAFE flex

Quale opzione di archiviazione si adatta al tuo caso d'uso

Riferimento codici di errore

Ogni errore che il tuo team incontrerà e come risolverlo

HUB (dashboard)

Gestisci organizzazioni, chiavi API ed export di conformità senza codice

Changelog

Modifiche alle API, nuove funzionalità e avvisi di deprecazione

Was this page helpful?