Gestione degli errori e dei timeout

La priorità assoluta nell’implementazione dell’API fiskaly SIGN DE è mantenere il sistema POS sempre operativo.

⚠️Non bloccare la cassa

Non esiste alcun obbligo che la cassa debba interrompere il proprio funzionamento o essere gravemente compromessa in qualsiasi momento. Assicurarsi che la propria integrazione non blocchi gli operatori.

Nel caso ottimale, l’API viene implementata in modo da garantire sempre il regolare funzionamento della cassa registratrice. Ecco come raggiungere questo obiettivo.

Impostare correttamente i timeout

Nel caso in cui il TSS non sia disponibile o temporaneamente instabile, il processo di pagamento non deve essere interrotto. I timeout dipendono fortemente dalla frequenza del sistema POS. Come produttore, è necessario decidere quale durata di timeout si ritiene ragionevole. Nessuna richiesta dovrebbe mai rimanere aperta abbastanza a lungo da mettere a rischio il regolare funzionamento della cassa registratrice.

Valori di timeout consigliati

Endpoint	Timeout consigliato	Note
Endpoint transazioni	3 - 5 secondi	I più critici per il flusso di pagamento
Creazione e personalizzazione TSS	Minimo 30 secondi	Operazione di configurazione una tantum
Autorizzazione	3 - 4 secondi	Rinnovo del token, non su ogni richiesta
Endpoint DSFinV-K	Fino a 10 minuti	Elaborazione intensiva / esportazioni dati

💡Rendere i timeout configurabili

Si raccomanda di creare la possibilità per i timeout di essere impostati (es. un valore tra 1,5 - 3 secondi) da un amministratore. In questo modo è possibile risparmiare preziose risorse di sviluppo e garantire un regolare funzionamento del POS.

📘Note

Se sembra esserci un problema, verificare status.fiskaly.com nonché la pagina di supporto.

Gestire gli errori in modo elegante

Quando una richiesta fallisce o va in timeout, seguire questo approccio:

1. Rilevare il guasto

   Impostare timeout appropriati per tipo di endpoint (vedere la tabella sopra). Quando si verifica un timeout o un errore HTTP, intercettarlo in modo elegante senza bloccare il pagamento.

2. Continuare il pagamento

   Consentire alla transazione di procedere anche senza una firma TSS. Registrare la transazione localmente con tutti i dati disponibili.

3. Contrassegnare la ricevuta

   Aggiungere una nota chiara sulla ricevuta come “TSS non disponibile” o “Firma TSS fallita” come raccomandato dalle autorità fiscali.

4. Registrare in DSFinV-K

   Assicurarsi che la transazione non firmata appaia nell’esportazione DSFinV-K utilizzando il campo transactions.security.error_message invece di transactions.security.tss_tx_id.

Firme mancanti

Una firma mancante sul documento non significa che il documento non sia conforme alla legge (vedere Punkt 7 AEAO to § 146a). Tuttavia, l’API fiskaly deve essere implementata in modo tale che ogni transazione richieda una firma. Se non è possibile acquisirla, si applicano le regole DSFinV-K.

⚠️Le transazioni non firmate devono comunque essere registrate

Tutte le transazioni, comprese quelle senza firma, devono apparire nell’esportazione DSFinV-K. Per le transazioni senza firma, tutti i dati noti vengono trasferiti all’esportazione DSFinV-K.

DSFinV-K e transazioni

Le autorità fiscali raccomandano di aggiungere una nota chiara sulla ricevuta per le transazioni non firmate, come:

“TSS non disponibile” o “Firma TSS fallita”

📘Note

Quando si utilizza l’API DSFinV-K di fiskaly, il campo transactions.security.error_message deve essere utilizzato invece di transactions.security.tss_tx_id all’endpoint insertCashPointClosing nel caso di transazioni non firmate.

Autorizzazione

L’autorizzazione viene inizialmente eseguita tramite Chiave API e Segreto API. Si riceveranno:

Token	Validità
access_token	24 ore
refresh_token	48 ore

È possibile utilizzare questi token per riautorizzarsi su base continuativa. Se si riceve una risposta 401, semplicemente riautorizzarsi tramite Chiave API e Segreto.

⚠️Non riautenticare ad ogni richiesta

La riautorizzazione non dovrebbe avvenire ad ogni richiesta, poiché ciò aggiungerebbe un overhead non necessario al processo di pagamento. La validità dei token è di più ore.

💡Riepilogo delle best practice

1. Impostare timeout appropriati per ciascun tipo di endpoint
2. Rendere i timeout configurabili da un amministratore
3. Non bloccare mai la cassa — consentire sempre al pagamento di procedere
4. Registrare tutte le transazioni nell’esportazione DSFinV-K, anche quelle non firmate
5. Aggiungere una nota chiara sulle ricevute quando manca una firma
6. Memorizzare nella cache i token di autorizzazione e riutilizzarli nel loro periodo di validità

Pagine correlate

Guida per i nuovi clienti

Guida completa alla configurazione inclusa l'autenticazione

Supporto

Come aprire un ticket e contattare il team di supporto