FAQ

Trova le risposte a 35 domande frequenti su SIGN IT, organizzate per argomento.

Records (19)

Come rappresentare l’arrotondamento obbligatorio nei pagamenti in contanti

Dal 1° gennaio 2018, le monete da 1 e 2 centesimi non sono più prodotte.   

Ai sensi della normativa italiana (DL n. 50/2017), l’importo complessivo dovuto, se pagato unicamente in contanti, deve essere arrotondato ai 5 centesimi più vicini:

• €0.01–€0.02 → arrotondati per difetto a €0.00 

• €0.03–€0.04 → arrotondati per eccesso a €0.05 

• €0.06–€0.07 → arrotondati per difetto a €0.05 

• €0.08–€0.09 → arrotondati per eccesso a €0.10

Questa regola si applica solo se il pagamento è interamente in contanti.

La procedura web del “Documento Commerciale Online” su cui si basa SIGN IT lite tollera tecnicamente una discrepanza fino a €0.02 tra il totale del documento e il totale dei pagamenti.

Arrotondamento per difetto La differenza (€0.01 / €0.02) viene registrata come sconto a livello di pagamento: payments[type=CASH].details.discount

Esempio: se total_vat.inclusive è €23.02, l’importo da pagare in contanti è €23

"payments": [
        {
          "type": "CASH",
          "details": {
            "amount": "23.00",
            "discount: "0.02"
          }
        }
      ]

 

**Arrotondamento per eccesso ** La differenza (€0.01 / €0.02) viene aggiunta all’importo del pagamento: payments[type=CASH].details.amount

Esempio: se total_vat.inclusive è €23.09, l’importo da pagare in contanti è €23.10

"payments": [
        {
          "type": "CASH",
          "details": {
            "amount": "23.10"
          }
        }
      ]

Come individuare un documento commerciale nel portale AdE

Gli esercenti possono individuare uno specifico documento commerciale nel portale AdE (Agenzia delle Entrate) in due modi:

**Utilizzando la ****compliance.url** Dopo una trasmissione andata a buon fine, la risposta dell’API include una compliance.url. Aprendo questo link e autenticandosi con le proprie credenziali, l’utente viene indirizzato al PDF corrispondente generato nel portale AdE.  

Ricerca manuale nel portale Fatture e Corrispettivi

1. Accedere al portale Fatture e Corrispettivi. 

2. Scorrere fino alla sezione Corrispettivi e selezionare Documento Commerciale Online.

3. Nella pagina successiva, cliccare su Cerca il tuo documento. 

4. Applicare i filtri desiderati, come:    - Data emissione documento o intervallo di date    - Tipo operazione    - **Numero progressivo *(DCW) *

Se non si indica un intervallo temporale, la ricerca avverrà sui file inviati negli ultimi 31 giorni.

Guida alla gestione degli errori

La guida allegata fornisce una panoramica degli errori più comuni che si verificano durante l’invio di record tramite SIGN IT lite e di come risolverli. Tratta gli errori restituiti dall’endpoint POST /records (invio dei record), inclusi sia problemi a livello HTTP sia errori a livello applicativo.

Come identificare l’errore?

Controlla il campo logs nella risposta dell’API. Esempio:

{
  "state": "FAILED",
  "logs": [
    {
      "severity": "ERROR",
      "message": "Authentication error: ADE portal has not responded successfully"
    }
  ]
}

Il prefisso del messaggio di errore (ad esempio Authentication error, Validation error, Submission error, etc.) determina la categoria dell’errore.

Categoria	Significato	Retry?
Safe to retry*	Il documento commerciale non è stato trasmesso all’AdE perché l’errore si è verificato prima che raggiungesse l’endpoint di invio all’AdE.	Sì, con una nuova idempotency key
Requires verification	Il documento commerciale potrebbe essere stato trasmesso all’AdE poiché l’errore si è verificato durante o dopo il tentativo di invio all’AdE.	Verificare prima sul portale AdE. Se il documento commerciale non è presente, riprovare con una nuova idempotency key
In caso di errori sconosciuti o errore HTTP 500, inviare un’email a dev-support@fiskaly.com
includendo dettagli sufficienti per permetterci di indagare e fornire indicazioni sui passaggi successivi.

L’errore HTTP 503 viene restituito in caso di indisponibilità temporanea dell’infrastruttura. È sempre possibile riprovare utilizzando una nuova idempotency key. Se l’errore persiste per più di 1–2 minuti, l’infrastruttura potrebbe essere sotto carico prolungato; in quel caso, registra la transazione nel registro di emergenza e contatta dev-support@fiskaly.com.

*Nota di conformità: Le transazioni fiscali devono essere trasmesse in tempo reale. Ritardi o tentativi di ritrasmissione possono comportare rischi di non conformità e potrebbero non soddisfare i requisiti normativi.

fiskaly fornisce strumenti tecnici, ma non garantisce la conformità, che rimane responsabilità del cliente. Qualsiasi processo di ritrasmissione o recupero deve rispettare i tempi consentiti dalla legge e le normative locali. Per ulteriori dettagli, consultare la guida.  Nota: Alcuni prefissi di errore — in particolare Entity validation error e fiscalization invalid — possono verificarsi anche durante la fase in cui lo stato del Taxpayer viene aggiornato a COMMISSIONED. In quel caso, la risoluzione è più semplice: aggiorna i dati del Taxpayer in base al messaggio di errore ricevuto e riprova a impostare lo stato della risorsa su COMMISSIONED.

Come rappresentare gli sconti

Sconto a livello di riga

Si tratta di uno sconto commerciale applicato a una specifica riga e riduce la relativa base imponibile. L’IVA viene ricalcolata sulla base ridotta.

Campo utilizzato: entries[].data.value.discount (valore positivo) Impatto IVA: l’IVA viene ridotta

"entries": [
        {
          "type": "SALE",
          "details": {
            "concept": "GOOD"
          },
          "data": {
            "type": "ITEM",
            "text": "Prod A",
            "unit": {
              "quantity": "1.00",
              "price": "9.00"
            },
            "value": {
              "base": "8.18181818",
              "discount": "1.00"
            },
            "vat": {
              "type": "VAT_RATE",
              "code": "REDUCED_1",
              "percentage": "10.00",
              "exclusive": "7.27272727",
              "inclusive": "8.00",
              "amount": "0.72727273"
            }
          }
        }

Nota: mentre gli sconti parziali possono essere applicati a livello di riga, uno sconto del 100% deve essere registrato come GIFT. Scopri come nel seguente articolo: Come rappresentare un articolo in omaggio (GIFT)

Sconto sull’intero carrello Questo sconto si applica all’intera transazione. Deve essere distribuito proporzionalmente su tutte le righe imponibili e, dal punto di vista fiscale, si comporta come più sconti a livello di riga. Ogni riga interessata riceve una quota calcolata dello sconto totale e l’IVA viene ricalcolata sulle basi imponibili ridotte. 

Campo utilizzato: entries[].data.value.discount (valore positivo, distribuito proporzionalmente) Impatto IVA: VAT is reduced

Sconto a livello di pagamento Non si tratta di uno sconto commerciale, ma di un aggiustamento in fase di pagamento. La base imponibile e l’IVA delle righe restano invariate e le imposte devono comunque essere calcolate e versate sull’intero importo dello scontrino.  Questo tipo di sconto riduce esclusivamente l’importo effettivamente incassato (payments[].details.amount). 

Campo utilizzato: payments[].details.discount (valore positivo) Impatto IVA: l’IVA NON viene ridotta

"payments": [
                {
                    "type": "CASH",
                    "details": {
                        "amount":"60.00",
                        "discount":"3.00"
                    }
                }
            ]

Per ulteriori dettagli, si rimanda al seguente articolo: Calcolo dei valori e arrotondamento decimale

Nota: fiskaly non è autorizzata a fornire consulenza fiscale. Per domande di natura fiscale, rivolgiti al tuo consulente fiscale, revisore o avvocato.

Come gestire i pagamenti con buoni pasto

Quando i buoni pasto vengono utilizzati come metodo di pagamento, vanno riportati come segue:

payments[].type > CARD

payments[].kind > TICKET

payments[].number = attualmente, l’API richiede l’identificativo del buono pasto in questo campo. È possibile utilizzare anche placeholder (es. "****"). 

Se vengono utilizzati più buoni pasto, ciascun buono deve essere riportato come una voce di pagamento separata all’interno dell’array payments. L’API provvederà poi ad aggregare queste voci e a trasmettere ad AdE il numero totale di buoni utilizzati.

Esempio: pagamento di 20 EUR utilizzando due buoni pasto e una carta di debito

     "payments": [
       {
         "type": "CARD",
         "kind": "TICKET",
         "number": "1234",
         "details": {
           "amount": "5.00"
         }
       },
       {
         "type": "CARD",
         "kind": "TICKET",
         "number": "1235",
         "details": {
           "amount": "5.00"
         }
       },
       {
         "type": "CARD",
         "kind": "DEBIT",
         "number": "****",
         "details": {
           "amount": "10.00"
         }
       }
     ]

Quando va usata la CANCELLATION?

Il tipo di operazione CANCELLATION viene utilizzato quando un documento commerciale deve essere annullato.

Questo si applica, ad esempio, in caso di importo o numero di articoli errato, emissione duplicata oppure qualsiasi altro errore individuato dopo la creazione del documento commerciale.

Il Record errato viene annullato nella sua interezza; non è possibile annullare singole voci in modo indipendente.

Per emettere un documento di annullo in SIGN IT:

• crea un Record di tipo INTENTION, dopodiché

• crea un Record di tipo TRANSACTION con operazione di tipo CANCELLATION.  Qui è necessario fare riferimento sia all’ID dell’INTENTION creata nel punto 1 sia all’ID della TRANSACTION originale che si desidera annullare.

{
    "content": {
        "type": "TRANSACTION",
        "record": {
            "id": "{{recordIntentionIdB1}}"
        },
        "operation": {
            "type": "CANCELLATION",
          "record": {
              "id": "{{recordTransactionIdB0}}"
          }
        }
    }
}

La CANCELLATION è un’operazione diversa dalla CORRECTION, generalmente utilizzata in caso di resi o rimborsi.

Sebbene non esista una scadenza legale formale per annullare una transazione, è consigliabile farlo il prima possibile.

Nota: Il documento annullato andrebbe registrato come ricavo negativo non imponibile nella successiva liquidazione IVA. fiskaly non è autorizzata a fornire consulenza fiscale. Per indicazioni sulla tua situazione specifica, consulta il tuo commercialista.

Come gestire un reso (CORRECTION)

Una TRANSACTION di tipo CORRECTION viene utilizzata per registrare qualsiasi processo di reso.

Passaggi da seguire

operation.record.id → ID della transazione RECEIPT originale

entries[].type → RETURN

entries[].details.number *→ *Numero della riga (entry) dello scontrino originale a cui si riferisce il reso

entries[].data.text *→ *Deve corrispondere esattamente alla descrizione dell’articolo originale.

• Specificare la quantità effettivamente restituita e aggiornare di conseguenza i valori correlati. Sono consentiti solo valori positivi.  Per ulteriori dettagli, fare riferimento a: Calcolo dei valori e arrotondamento decimale

Esempio

TRANSACTION originale di tipo RECEIPT: vendita di 1 giacca e 2 T-shirt

{
    "content": {
        "type": "TRANSACTION",
        "record": {
            "id": "{{recordIntentionIdC0}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-12345",
                "total_vat": {
                    "amount": "18.03278689",
                    "exclusive": "81.96721311",
                    "inclusive": "100"
                }
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Jacket",
                        "unit": {
                            "quantity": "1",
                            "price": "50.00"
                        },
                        "value": {
                            "base": "40.98360656"
                        },
                        "vat": {
                            "type": "VAT_RATE",
                            "code": "STANDARD",
                            "percentage": "22.00",
                            "exclusive": "40.98360656",
                            "inclusive": "50.00",
                            "amount": "9.01639344"
                        }
                    }
                },
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "T-shirt",
                        "unit": {
                            "quantity": "2",
                            "price": "25.00"
                        },
                        "value": {
                            "base": "40.98360655"
                        },
                        "vat": {
                            "type": "VAT_RATE",
                            "code": "STANDARD",
                            "percentage": "22.00",
                            "exclusive": "40.98360655",
                            "inclusive": "50.00",
                            "amount": "9.01639345"
                        }
                    }
                }
            ],
            "customer": {
                "type": "EXTERNAL"
            },
            "payments": [
                {
                    "type": "CASH",
                    "details": {
                        "amount": "100"
                    }
                }
            ]
        }
    }
}

1. Reso merce con rimborso dell’importo pagato

Scenario di rimborso parziale TRANSACTION di tipo CORRECTION: reso di 1 T-shirt

{
  "content": {
    "type": "TRANSACTION",
    "record": {
      "id": "{{recordIntentionIdC1}}"
    },
    "operation": {
      "type": "CORRECTION",
      "record": {
        "id": "{{recordTransactionIdC0}}"
      },
      "data": {
        "type": "RECEIPT",
        "document": {
          "number": "INV-16789",
          "series": "C",
          "total_vat": {
            "amount": "4.50819672",
            "exclusive": "20.49180327",
            "inclusive": "25.000"
          }
        },
        "entries": [
          {
            "type": "RETURN",
            "details": {
              "concept": "GOOD",
              "number": "2"
            },
            "data": {
              "type": "ITEM",
              "text": "T-shirt",
              "unit": {
                "quantity": "1",
                "price": "25.00"
              },
              "value": {
                "base": "20.49180327"
              },
              "vat": {
                "type": "VAT_RATE",
                "code": "STANDARD",
                "percentage": "22.00",
                "exclusive": "20.49180327",
                "inclusive": "25.00",
                "amount": "4.50819672"
              }
            }
          }
        ],
        "customer": {
          "type": "EXTERNAL"
        },
        "payments": [
          {
            "type": "CASH",
            "details": {
              "amount": "25.00"
            }
          }
        ]
      }
    }
  }
}

Scenario di rimborso totale Per un rimborso completo dell’intero scontrino, tutte le voci dello scontrino originale devono essere elencate con i rispettivi valori.

2. Scenario di scambio merce: reso dell’articolo A e acquisto dell’articolo B Per garantire la conformità tecnica ed evitare errori di validazione, l’approccio consigliato è:

• Emettere una transazione di tipo CORRECTION per certificare il reso dell’articolo A

• Emettere una transazione di tipo RECEIPT per certificare la vendita dell’articolo B

3. Scenario: reso dell’articolo A ed emissione di un buono acquisto Questo scenario può essere gestito tramite:

• Emissione di una transazione di tipo CORRECTION per certificare il reso dell’articolo A

• Emissione di una transazione di tipo RECEIPT per la vendita di un buono (monouso o multiuso, a seconda del trattamento fiscale applicabile)

Nota: fiskaly non è autorizzata a fornire consulenza fiscale. Per domande di natura fiscale, rivolgiti al tuo consulente fiscale, revisore o avvocato.

Come gestire i pagamenti non riscossi

Il tipo di pagamento OUTSTANDING viene utilizzato per indicare i corrispettivi non riscossi. Si applica quando i beni o servizi sono già stati forniti, ma il cliente non ha ancora effettuato il pagamento.

In questo caso, la transazione è considerata completata, mentre il pagamento risulta in sospeso e verrà saldato in un momento successivo.

Per registrare correttamente un pagamento non riscosso:

• indica payments[].type: "OUTSTANDING";

• aggiungi payments[].concept e specifica se riguarda un bene (GOOD) o un servizio (SERVICE).

Esempio di pagamento non riscosso per un bene

{
  "content": {
    "type": "TRANSACTION",
    "record": {
      "id": "{{recordIntentionIdA}}"
    },
    "operation": {
      "type": "RECEIPT",
      "document": {
        "number": "INV-12345",
        "total_vat": {
          "amount": "18.03278689",
          "exclusive": "81.96721311",
          "inclusive": "100.00"
        }
      },
      "entries": [
        {
          "type": "SALE",
          "details": {
            "concept": "GOOD"
          },
          "data": {
            "type": "ITEM",
            "text": "Product XYZ",
            "unit": {
              "quantity": "1",
              "price": "100.00"
            },
            "value": {
              "base": "81.96721311"
            },
            "vat": {
              "type": "VAT_RATE",
              "code": "STANDARD",
              "percentage": "22.00",
              "exclusive": "81.96721311",
              "inclusive": "100.00",
              "amount": "18.03278689"
            }
          }
        }
      ],
      "customer": {
        "type": "EXTERNAL"
      },
      "payments": [
        {
          "type": "OUTSTANDING",
          "details": {
            "amount": "100.00"
          },
          "concept": "GOOD"
        }
      ]
    }
  }
}

Per i beni (GOOD), non è necessario emettere un ulteriore documento commerciale. È sufficiente il documento iniziale emesso con pagamento OUTSTANDING (non riscosso). Al momento dell’incasso, è sufficiente conservare o fare riferimento alla prova di pagamento.

Attenzione: per i servizi (SERVICE), poiché il momento impositivo IVA si verifica al momento dell’incasso del pagamento, il trattamento corretto può dipendere da come il documento iniziale è stato emesso e trasmesso. Per evitare qualsiasi rischio di doppia trasmissione, raccomandiamo vivamente di verificare l’approccio corretto con il proprio consulente fiscale.

 

Nota: fiskaly non è autorizzata a fornire consulenza fiscale. Per domande di natura fiscale, rivolgiti al tuo consulente fiscale, revisore o avvocato.

Calcolo dei valori e arrotondamento decimale

L’Agenzia delle Entrate richiede l’inserimento di unit.quantity, unit.price, vat.type/code/percentage e value.discount per calcolare gli altri valori. Per questi campi sono consentite solo 2 cifre decimali. 

**Livello di riga (entry) **

vat.amount e vat.inclusive vengono arrotondati all’ottava cifra decimale.  

value.base e vat.exclusive non sono mappati al portale AdE, ma si consiglia di calcolarli in modo coerente con la logica descritta sopra per garantire l’accuratezza del calcolo di vat.amount. 

Livello totali documento

total_vat.amount: il valore fornito tramite SIGN IT lite viene ricalcolato e sovrascritto dal portale dell’Agenzia delle Entrate come somma degli importi IVA a livello delle singole entries. Tale valore viene arrotondato dall’AdE (in background) all’ottava cifra decimale.  

payments[].amount, payments[].discount e total_vat.inclusive sono arrotondati a 2 cifre decimali.  Il valore fornito tramite SIGN IT lite per total_vat.inclusive viene ignorato dal portale AdE, in quanto calcolato direttamente dall’Agenzia delle Entrate sulla base delle singole entries.  

total_vat.exclusive: il valore fornito tramite SIGN IT lite viene ignorato dal portale AdE, in quanto calcolato direttamente dall’Agenzia delle Entrate sulla base delle singole entries.

Campo API	Definizione	Formula
value.base	Importo totale della riga (IVA esclusa) **prima degli sconti **	(unit.price × unit.quantity) ÷ (1 + (vat.percentage ÷ 100)) Nota: unit.price è IVA inclusa
vat.inclusive	Importo totale della riga (IVA inclusa) dopo gli sconti, se applicabili	(unit.price x unit.quantity) - value.discount Nota: unit.price è IVA inclusa
vat.exclusive	Importo totale della riga (IVA esclusa) dopo gli sconti, se applicabili	vat.inclusive ÷ (1 + (vat.percentage ÷ 100))
vat.amount	Importo IVA	vat.inclusive - vat.exclusive
Seguendo queste linee guida si evitano:

• Avvisi di validazione - WARNING "Validation checks failed.. Reasons: Received total VAT amount XXX is not equal to Tax Agency computed total VAT amount XXX"  

• Errori di trasmissione - ERROR "Validation checks failed.. Reasons: La somma delle tipologie di pagamento non risulta uguale al Totale complessivo"  

Esempio di payload

{
  "content": {
    "type": "TRANSACTION",
    "record": {
      "id": "{{recordIntentionIdA}}"
    },
    "operation": {
      "type": "RECEIPT",
      "document": {
        "number": "INV-12346",
        "total_vat": {
          "amount": "1.15104322",
          "exclusive": "9.19895678",
          "inclusive": "10.35"
        }
      },
      "entries": [
        {
          "type": "SALE",
          "details": {
            "concept": "GOOD"
          },
          "data": {
            "type": "ITEM",
            "text": "Prod A",
            "unit": {
              "quantity": "1.00",
              "price": "9.00"
            },
            "value": {
              "base": "8.18181818",
              "discount": "1.00"
            },
            "vat": {
              "type": "VAT_RATE",
              "code": "REDUCED_1",
              "percentage": "10.00",
              "exclusive": "7.27272727",
              "inclusive": "8.00",
              "amount": "0.72727273"
            }
          }
        },
        {
          "type": "SALE",
          "details": {
            "concept": "GOOD"
          },
          "data": {
            "type": "ITEM",
            "text": "Prod B",
            "unit": {
              "quantity": "2.00",
              "price": "1.20"
            },
            "value": {
              "base": "1.96721311",
              "discount": "0.05"
            },
            "vat": {
              "type": "VAT_RATE",
              "code": "STANDARD",
              "percentage": "22.00",
              "exclusive": "1.92622951",
              "inclusive": "2.35",
              "amount": "0.42377049"
            }
          }
        }
      ],
      "customer": {
        "type": "EXTERNAL"
      },
      "payments": [
        {
          "type": "CASH",
          "details": {
            "amount": "10.35"
          }
        }
      ]
    }
  }
}

Buoni monouso: emissione e utilizzo

Quando un buono monouso viene venduto o emesso, l’IVA viene applicata immediatamente, poiché la tipologia dei beni o dei servizi e la relativa natura IVA sono già noti. La tassazione, quindi, avviene al momento dell’emissione e non al riscatto.

Dal punto di vista tecnico, l’approccio corretto per gestire l’emissione e il riscatto dei buoni monouso con SIGN IT lite è il seguente:

Emissione del buono

• Assegnare un nome al buono in entries[].data.text

• Indicare l’aliquota IVA in entries[].data.vat

{
    "content": {
        "type": "TRANSACTION",
        "record": {
            "id": "{{recordIntentionIdA}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-123456",
                "total_vat": {
                    "amount": "18.03278689",
                    "exclusive": "81.96721311",
                    "inclusive": "100.00"
                }
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Voucher for service XYZ - Nr. 2345",
                        "unit": {
                            "quantity": "1",
                            "price": "100.00"
                        },
                        "value": {
                            "base": "81.96721311"
                        },
                        "vat": {
                            "type": "VAT_RATE",
                            "code": "STANDARD",
                            "percentage": "22.00",
                            "exclusive": "81.96721311",
                            "inclusive": "100",
                            "amount": "18.03278689"
                        }
                    }
                }
            ],
            "customer": {
                "type": "EXTERNAL"
            },
            "payments": [
                {
                    "type": "CASH",
                    "details": {
                        "amount":"100.00"
                     }
                }
            ]
        }
    }
}

**Riscatto del buono ** Il tipo di pagamento VOUCHER non è abilitato in SIGN IT lite. Tuttavia, dal punto di vista tecnico, è possibile registrare il buono monouso come sconto a livello di riga.

Scenario 1 – Il buono copre parte dell’acquisto

Esempio 1A Buono da €100 utilizzato per l’acquisto di un bene da €200 → i restanti €100 vengono pagati con un altro metodo di pagamento.

• Specificare il bene acquistato.

• Indicare l’aliquota IVA in entries[].data.vat

• Registrare il buono come sconto a livello di riga. In questo modo, l’IVA viene calcolata esclusivamente sulla base imponibile residua (vat.exclusive), al netto dell’importo del buono. L’IVA relativa alla quota coperta dal buono è stata già assolta al momento dell’emissione del buono stesso.

{
   "content": {
       "type": "TRANSACTION",
       "record": {
           "id": "{{intentionId}}"
       },
       "operation": {
           "type": "RECEIPT",
           "document": {
               "number": "INV-12345",
               "total_vat": {
                   "exclusive": "81.96721311",
                   "inclusive": "100",
                   "amount": "18.03278689"
               }
           },
           "entries": [
               {
                   "type": "SALE",
                   "details": {
                       "concept": "GOOD"
                   },
                   "data": {
                       "type": "ITEM",
                       "text": "Prodotto XYZ",
                       "unit": {
                           "quantity": "1",
                           "price": "200.00"
                       },
                       "value": {
                           "base": "163.93442623",
                           "discount": "100.00"
                       },
                       "vat": {
                           "type": "VAT_RATE",
                           "code": "STANDARD",
                           "percentage": "22.00",
                           "exclusive": "81.96721311",
                           "inclusive": "100",
                           "amount": "18.03278689"
                       }
                   }
               }
           ],
           "customer": {
               "type": "EXTERNAL"
           },
           "payments": [
               {
                   "type": "CASH",
                   "details": {
                       "amount": "100.00"
                   }
               }
           ]
       }
   }
}

Esempio 1B Buono da €100 utilizzato per l’acquisto di un bene da €90 e di un bene da €20 → i restanti €10 vengono pagati con un altro metodo di pagamento.

• Specificare i beni acquistati.

• Indicare l’aliquota IVA in entries[].data.vat

• Distribuire il buono come sconto a livello di riga tra le due voci, mantenendo ciascuno sconto al di sotto del unit.price. 

Nota: il portale AdE non consente che value.discount sia uguale o superiore all’importo totale della riga (unit.price x unit.quantity), altrimenti restituisce un Validation Error. Per evitare questo problema, una possibile rappresentazione tecnica per questo esempio è la seguente:

• Per la voce da €90, inserire €89.99 come value.discount
• Per la voce da €20, inserire €10.01 come value.discount

{
   "content": {
       "type": "TRANSACTION",
       "record": {
           "id": "{{intentionId}}"
       },
       "operation": {
           "type": "RECEIPT",
           "document": {
               "number": "INV-12345",
               "total_vat": {
                   "exclusive": "8.19672131",
                   "inclusive": "10.00",
                   "amount": "1.80327869"
               }
           },
           "entries": [
               {
                   "type": "SALE",
                   "details": {
                       "concept": "GOOD"
                   },
                   "data": {
                       "type": "ITEM",
                       "text": "Prodotto A",
                       "unit": {
                           "quantity": "1",
                           "price": "90.00"
                       },
                       "value": {
                           "base": "73.77049180",
                           "discount": "89.99"
                       },
                       "vat": {
                           "type": "VAT_RATE",
                           "code": "STANDARD",
                           "percentage": "22.00",
                           "exclusive": "0.00819672",
                           "inclusive": "0.01",
                           "amount": "0.00180328"
                       }
                   }
               },
               {
                   "type": "SALE",
                   "details": {
                       "concept": "GOOD"
                   },
                   "data": {
                       "type": "ITEM",
                       "text": "Prodotto B",
                       "unit": {
                           "quantity": "1",
                           "price": "20.00"
                       },
                       "value": {
                           "base": "8.18032787",
                           "discount": "10.01"
                       },
                       "vat": {
                           "type": "VAT_RATE",
                           "code": "STANDARD",
                           "percentage": "22.00",
                           "exclusive": "8.18852459",
                           "inclusive": "9.99",
                           "amount": "1.80147541"
                       }
                   }
               }
           ],
           "customer": {
               "type": "EXTERNAL"
           },
           "payments": [
               {
                   "type": "CASH",
                   "details": {
                       "amount": "10.00"
                   }
               }
           ]
       }
   }
}

Scenario 2 – Il buono copre l’intero importo dell’acquisto Esempio: buono da €100 utilizzato per l’acquisto di un bene da €100 → nessun pagamento aggiuntivo richiesto.

• Specificare il bene acquistato.

• Indicare l’aliquota IVA in entries[].data.vat

• Registrare il buono come sconto a livello di riga. 

Nota: il portale AdE non consente che value.discount sia uguale o superiore all’importo totale della riga (unit.price x unit.quantity), altrimenti restituisce un Validation Error. Per evitare questo problema, se il voucher copre esattamente l’intero prezzo della riga — come in questo scenario —, è possibile utilizzare il seguente workaround tecnico per soddisfare la validazione del portale:

• Aggiungere €0.01 a unit.price OPPURE ridurre value.discount di €0.01, così da creare una piccola differenza tra i due valori.
• Recuperare poi quel centesimo applicando uno sconto di €0.01 a livello di pagamento tramite details.discount. In questo modo, l’importo netto addebitato al cliente rimane corretto, soddisfacendo al contempo la validazione del portale. 

{
   "content": {
       "type": "TRANSACTION",
       "record": {
           "id": "{{intentionId}}"
       },
       "operation": {
           "type": "RECEIPT",
           "document": {
               "number": "INV-12345",
               "total_vat": {
                   "exclusive": "0.00819672",
                   "inclusive": "0.01",
                   "amount": "0.00180328"
               }
           },
           "entries": [
               {
                   "type": "SALE",
                   "details": {
                       "concept": "GOOD"
                   },
                   "data": {
                       "type": "ITEM",
                       "text": "Prodotto XYZ",
                       "unit": {
                           "quantity": "1",
                           "price": "100.01"
                       },
                       "value": {
                           "base": "81.97540984",
                           "discount": "100.00"
                       },
                       "vat": {
                           "type": "VAT_RATE",
                           "code": "STANDARD",
                           "percentage": "22.00",
                           "exclusive": "0.00819672",
                           "inclusive": "0.01",
                           "amount": "0.00180328"
                       }
                   }
               }
           ],
           "customer": {
               "type": "EXTERNAL"
           },
           "payments": [
               {
                   "type": "CASH",
                   "details": {
                       "amount": "0.00",
                       "discount": "0.01"
                   }
               }
           ]
       }
   }
}

Nota: L’aggiustamento di €0.01 introdotto per soddisfare la validazione del portale AdE nello Scenario 2 comporta che venga riportato un importo IVA piccolo ma non nullo, anche quando il voucher copre interamente l’acquisto. Se ciò non è desiderabile, è possibile utilizzare VAT_EXEMPTION come alternativa tecnica a VAT_RATE, ottenendo un’IVA pari a zero. In entrambi i casi, poiché questa scelta ha implicazioni sulla dichiarazione IVA, si raccomanda di verificare l’approccio più corretto con il proprio consulente fiscale.

Nota:

fiskaly non è autorizzata a fornire consulenza fiscale. Per domande di natura fiscale, rivolgiti al tuo consulente fiscale, revisore o avvocato.

Buoni multiuso: emissione e utilizzo

Quando un buono multiuso viene venduto o emesso, non si applica l’IVA. L’eventuale tassazione avviene solo al momento del riscatto, quando la fornitura effettiva di beni o servizi determina la base imponibile.

Dal punto di vista tecnico, l’approccio corretto per gestire l’emissione e il riscatto dei buoni multiuso con SIGN IT lite è il seguente: 

Emissione del buono

• Assegna un nome al buono in entries[].data.text

• Indica vat.type: VAT_EXEMPTION e vat.code: NOT_SUBJECT

{
    "content": {
        "type": "TRANSACTION",
        "record": {
            "id": "{{recordIntentionIdA}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-12345",
                "total_vat": {
                    "amount": "0.00",
                    "exclusive": "100.00",
                    "inclusive": "100.00"
                }
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Voucher XYZ",
                        "unit": {
                            "quantity": "1",
                            "price": "100.00"
                        },
                        "value": {
                            "base": "100.00"
                        },
                        "vat": {
                            "type": "VAT_EXEMPTION",
                            "code": "NOT_SUBJECT"
                        }
                    }
                }
            ],
            "customer": {
                "type": "EXTERNAL"
            },
            "payments": [
                {
                    "type": "CASH",
                    "details": {
                        "amount":"100.00"
                    }
                }
            ]
        }
    }
}

Riscatto del buono

Il tipo di pagamento VOUCHER non è abilitato in SIGN IT lite. Dal punto di vista tecnico, è comunque possibile riscattare un buono multiuso seguendo i passaggi indicati di seguito.

• Specifica i dettagli IVA applicabili al bene o servizio fornito.

• Registra il buono come uno sconto (discount) a livello del pagamento.

Scenario 1 – Il buono copre l’intero importo dell’acquisto Esempio: buono da 100 EUR utilizzato per un acquisto da 100 EUR → non è richiesto alcun pagamento aggiuntivo

{
    "content": {
        "type": "TRANSACTION",
        "record": {
            "id": "{{recordIntentionIdA}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-123456",
                "total_vat": {
                    "amount": "18.03278689",
                    "exclusive": "81.96721311",
                    "inclusive": "100.00"
                }
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Product XYZ",
                        "unit": {
                            "quantity": "1",
                            "price": "100.00"
                        },
                        "value": {
                            "base": "81.96721311"
                        },
                        "vat": {
                            "type": "VAT_RATE",
                            "code": "STANDARD",
                            "percentage": "22.00",
                            "exclusive": "81.96721311",
                            "inclusive": "100",
                            "amount": "18.03278689"
                        }
                    }
                }
            ],
            "customer": {
                "type": "EXTERNAL"
            },
            "payments": [
                {
                    "type": "CASH",
                    "details": {
                        "amount":"0.00",
                        "discount":"100.00"
                     }
                }
            ]
        }
    }
}

Scenario 2 – Il buono copre parte dell’acquisto Esempio: buono da 100 EUR utilizzato per un acquisto da 120 EUR → i restanti 20 EUR vengono pagati con un altro metodo di pagamento (ad es. contanti)

{
    "content": {
        "type": "TRANSACTION",
        "record": {
            "id": "{{recordIntentionIdA}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-123456",
                "total_vat": {
                    "amount": "21.63934426",
                    "exclusive": "98.36065574",
                    "inclusive": "120.00"
                }
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Product XYZ",
                        "unit": {
                            "quantity": "1",
                            "price": "120.00"
                        },
                        "value": {
                            "base": "98.36065574"
                        },
                        "vat": {
                            "type": "VAT_RATE",
                            "code": "STANDARD",
                            "percentage": "22.00",
                            "exclusive": "98.36065574",
                            "inclusive": "120",
                            "amount": "21.63934426"
                        }
                    }
                }
            ],
            "customer": {
                "type": "EXTERNAL"
            },
            "payments": [
                {
                    "type": "CASH",
                    "details": {
                        "amount":"20.00",
                        "discount":"100.00"
                     }
                }
            ]
        }
    }
}

Considerazione contabile: L’emissione di un buono multiuso non deve essere riconosciuta come ricavo, ma piuttosto come un debito nei confronti del cliente fino al momento della sua riscossione. Il ricavo viene riconosciuto solo quando il buono viene utilizzato e i relativi beni o servizi vengono effettivamente forniti. Poiché si tratta di aspetti contabili, consigliamo di verificarli con il proprio commercialista per garantire il corretto trattamento ed evitare che sia l’emissione sia il riscatto vengano registrati come ricavi.

Nota: fiskaly non è autorizzata a fornire consulenza fiscale. Per domande di natura fiscale, rivolgiti al tuo consulente fiscale, revisore o avvocato.

Posso ottenere il PDF del record generato tramite API?

Sì — a partire dalla versione SIGN IT 2025-08-12 è possibile. Puoi trovare maggiori dettagli in questo articolo: Principali cambiamenti in SIGN IT 2025-08-12

Dopo che un Record di tipo TRANSACTION è stato creato con successo (stato: COMPLETED, modalità: FINISHED), è possibile recuperare il PDF ufficiale del documento generato dall’AdE chiamando l’endpoint retrieveRecord con il parametro di query compliance-artifact:

GET {{apiBaseUrl}}/records/{{recordTransactionIdA}}**?compliance-artifact** 

La risposta include il PDF come stringa codificata in Base64 in compliance.artifact.data. Dopo la decodifica, ecco come appare nell’ambiente TEST (formato A4).

Nota: Nell’ambiente TEST viene generato solo un PDF di esempio, che non riflette i valori effettivamente inviati. I dati corretti saranno visibili esclusivamente nell’ambiente LIVE.

Quali sono le differenze rispetto alla versione 2024-10-31?

• Nella versione 2024-10-31: il PDF del record è disponibile solo per l’esercente tramite compliance.url, restituito nella risposta alla creazione, dopo aver effettuato l’accesso al portale Fatture e Corrispettivi con le credenziali Fisconline.

• Nelle versioni successive: il PDF del record è ancora disponibile su compliance.url, ma può anche essere ottenuto recuperando il record con il parametro di query compliance-artifact. Questo rende più facile archiviare, stampare o consegnare l’esatto scontrino emesso dall’AdE, senza richiedere all’esercente di accedere al portale Fatture e Corrispettivi.

Come riportare le mance

Da un punto di vista tecnico, le mance non sono soggette a IVA e non rientrano nel corrispettivo imponibile, a condizione che siano volontarie e chiaramente separate dal pagamento del bene o servizio.

Tecnicamente, mentre le mance in contanti non devono essere fiscalizzate, quelle pagate in modalità elettronica richiedono una gestione specifica per evitare che vengano erroneamente trattate come importo imponibile.

Se una mancia viene inclusa nel totale del pagamento con carta senza essere distinta dal costo del bene o servizio, l’intero importo sarà considerato corrispettivo e quindi soggetto a IVA.

Per escludere la mancia dal calcolo dell’IVA, questa distinzione deve essere riportata correttamente nel documento fiscale, tramite l’inserimento di una voce separata (entry) di tipo SALE relativa alla mancia, con:

• una descrizione chiara, ad esempio: "Mancia volontaria"

• la corretta esenzione IVA (N2 - Non soggetto): "VAT_EXEMPTION" > "NOT_SUBJECT"

Caso d’uso (al ristorante) e payload corrispondente:

• Totale servizio: 48 EUR
• Mancia elettronica: 2 EUR

{
    "content": {
        "type": "TRANSACTION",
        "record": {
            "id": "{{recordIntentionIdA}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-12345",
                "total_vat": {
                    "amount": "8.65573770",
                    "exclusive": "41.34426230",
                    "inclusive": "50.00"
                }
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "SERVICE"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Restaurant service",
                        "unit": {
                            "quantity": "1",
                            "price": "48.00"
                        },
                        "value": {
                            "base": "39.34426230"
                        },
                        "vat": {
                            "type": "VAT_RATE",
                            "code": "STANDARD",
                            "percentage": "22.00",
                            "exclusive": "39.34426230",
                            "inclusive": "48.00",
                            "amount": "8.65573770"
                        }
                    }
                },
            {
                    "type": "SALE",
                    "details": {
                        "concept": "SERVICE"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Voluntary tip",
                        "unit": {
                            "quantity": "1",
                            "price": "2.00"
                        },
                        "value": {
                            "base": "2.00"
                        },
                        "vat": {
                            "type": "VAT_EXEMPTION",
                            "code": "NOT_SUBJECT"
                        }
                    }
                }
            ],
            "customer": {
                "type": "EXTERNAL"
            },
            "payments": [
                {
                    "type": "CARD",
                    "details": {
                        "amount":"50.00"
                    },
                    "number": "****",
                    "kind": "CREDIT"
                }
            ]
        }
    }
}

Please note: fiskaly is not allowed to provide tax advice. Please contact your tax advisor, tax auditor or lawyer for tax-related questions.

Differenza tra document.number e numero progressivo AdE

Quando si crea un Record di tipo TRANSACTION, i campi operation.document.number e operation.document.series si riferiscono al sistema di numerazione interna dei documenti del contribuente. Questi valori devono essere generati dal contribuente stesso in base al proprio contesto operativo e non corrispondono al numero progressivo generato dall’Agenzia delle Entrate (AdE) e riportato nella risposta API.

Il Numero Progressivo (DCW/numero) è un identificativo univoco assegnato automaticamente dall’Agenzia delle Entrate quando un documento viene trasmesso con successo tramite il portale “Fatture e Corrispettivi”. Questo numero è incluso nella risposta positiva della creazione di un Record di tipo TRANSACTION e si trova nel campo compliance.data.

 

Quando un cliente richiede lo scontrino, è necessario indicare che è stato emesso tramite una soluzione cloud e non un Registratore Telematico (RT)?

No, non è necessario specificare il metodo di emissione sullo scontrino. Il Numero Progressivo assegnato dall’Agenzia delle Entrate (DCW/numero) è sufficiente per identificare e validare in modo univoco il documento. Tale numero conferma che lo scontrino è stato correttamente trasmesso tramite la procedura del “Documento Commerciale Online”.

Quali dati include la risposta del documento conforme?

Quando si crea con successo un record di tipo TRANSACTION utilizzando SIGN IT lite, la risposta include:

• il** numero progressivo** rilasciato dall’Agenzia delle Entrate e utilizzato per identificare univocamente il documento (DCW-numero);

• l’**URL di conformità **che permette al contribuente di visualizzare/scaricare il documento che ha emesso, dopo aver effettuato l’accesso al portale “Fatture e Corrispettivi”. 

Nota: se il cliente finale richiede uno scontrino di cortesia, è sufficiente includere il numero progressivo assegnato al documento dall’AdE (compliance.data).  

Perché ricevo un errore “401 Unauthorized” quando clicco sul link?

Questo errore si verifica perché il documento non è accessibile pubblicamente. L’accesso è limitato al contribuente che ha emesso quello specifico documento commerciale.

Per aprire correttamente il link, l’esercente deve prima accedere al portale “Fatture e Corrispettivi” utilizzando le proprie credenziali. 

Nota: con le versioni API SIGN IT 2025-08-12 e 2026-02-03 è ora possibile recuperare il documento PDF (compliance.artifact) generato nel portale “Fatture e Corrispettivi” direttamente tramite una chiamata API. Questo articolo fornisce maggiori dettagli sull’argomento: Posso ottenere il PDF del record generato tramite API?

Come rappresentare un articolo in omaggio (GIFT)

Quando un commerciante fornisce beni o servizi a titolo gratuito, le autorità fiscali richiedono solitamente che l’IVA venga calcolata sul valore originale di tali beni o servizi. Di conseguenza, anche se il cliente non effettua alcun pagamento, la transazione deve includere tutti i dettagli relativi all’IVA. 

La modalità corretta per rappresentare un articolo in omaggio in SIGN IT è la seguente:

• inserire il prezzo pieno e i relativi dettagli IVA a livello di entry, come se l’articolo fosse stato venduto a prezzo pieno;

• specificare la natura dell’articolo impostando il campo entries[].details.purpose su "GIFT".

Mentre gli sconti parziali possono essere applicati normalmente a livello di entry, un articolo scontato al 100% deve essere rappresentato come GIFT. Questo garantisce una gestione corretta dell’IVA e assicura la conformità normativa.

Di seguito è riportato un esempio di rappresentazione di un articolo offerto gratuitamente ("GIFT").

{
  "type": "SALE",
  "data": {
    "type": "ITEM",
    "text": "Product XYZ",
    "unit": {
      "quantity": "1",
      "price": "50"
    },
    "value": {
      "base": "40.983607"
    },
    "vat": {
      "type": "VAT_RATE",
      "code": "STANDARD",
      "percentage": "22.00",
      "amount": "9.016393",
      "exclusive": "40.983607",
      "inclusive": "50"
    }
  },
  "details": {
    "concept": "GOOD",
    "purpose": "GIFT",
    "number": "1",
    "description": "Product XYZ"
  }
}

Come integrare il Codice Lotteria in SIGN IT

Attualmente, in Italia coesistono due tipi di lotterie: la differita e l’istantanea. Sign IT lite supporta solo la lotteria differita, mentre la versione completa di SIGN IT supporterà entrambi i tipi. 

I consumatori possono ottenere il proprio codice lotteria sul sito ufficiale della Lotteria degli Scontrini e devono fornirlo all’esercente se desiderano partecipare alla lotteria. La partecipazione è consentita esclusivamente per gli acquisti effettuati senza contanti. 

Quando si crea un record TRANSACTION di tipo RECEIPT e CORRECTION in SIGN IT tramite l’endpoint createRecord, è possibile inserire il codice lotteria fornito dal consumatore nel campo **customer.code**. 

Per i record TRANSACTION di tipo CANCELLATION, questa informazione è derivata direttamente dallo scontrino originale a cui il documento di annullamento fa riferimento.

Quando viene trasmesso un codice lotteria, questo viene aggiunto al numero del documento commerciale (DCW) all’interno del campo compliance.data, separato da una virgola.  Esempio: "DCW2026/1234-0001,NB7A1235"

Nel PDF ufficiale dell’AdE (recuperabile tramite API), questi valori vengono visualizzati separatamente come:

• Documento N. 
• CODICE LOTTERIA DEL CLIENTE 

In una futura versione dell’API, potremmo introdurre un meccanismo migliorato di rendering della compliance.

Per maggiori informazioni, si invita a consultare la sezione “Lotteria degli Scontrini” della guida di SIGN IT.

Quali aliquote e trattamenti IVA possono essere utilizzati in Italia?

Questo articolo fornisce una mappatura dettagliata delle aliquote IVA e dei relativi trattamenti IVA applicabili in Italia quando si utilizza SIGN IT, incluse le operazioni esenti e quelle fuori campo IVA.

VAT_RATE > STANDARD = Italiano 22%

VAT_RATE > REDUCED_1 = Italiano 10%

VAT_RATE > REDUCED_2 = Italiano 5%

VAT_RATE > REDUCED_3 = Italiano 4%

VAT_EXEMPTION > NOT_SUBJECT = Italiano N2: non soggetto

VAT_EXEMPTION > NOT_TAXABLE = Italiano N3: Non imponibili

VAT_EXEMPTION > CAUSE_1 = Italiano N1: Escluse ex art 15

VAT_EXEMPTION > CAUSE_2 = Italiano N4: Esenti

VAT_EXEMPTION > CAUSE_3 = Italiano N5: Regime del margine

VAT_EXEMPTION > CAUSE_4 = Italiano N6: Altro non IVA

Cosa fare se non si hanno i dati della carta?

Se i dati della carta non sono disponibili, è possibile inserire "****" nel campo number.

Esempio:

"payments": [
    {
        "type": "CARD",
        "details": {
            "amount": "100.00"
        },
        "number": "****",
        "kind": "CREDIT"
    }
]

Generale (12)

Cos’è il limite di paginazione?

Negli endpoint di lista, il parametro di query limit viene utilizzato per gestire la paginazione, definendo quanti risultati vengono restituiti in una singola risposta. Questo consente di controllare la dimensione della risposta, ottimizzare le prestazioni e recuperare grandi volumi di dati in modo incrementale.

Esempio di richiesta GET: {{apiBaseUrl}}/assets**?limit=5**

La risposta include inoltre il campo pagination.next, che contiene l’endpoint da utilizzare nella richiesta successiva per ottenere la pagina successiva dei risultati.

Nuova terminologia delle risorse

Questo articolo illustra la struttura organizzativa e la terminologia delle risorse introdotta con SIGN IT 2026-02-03 e mantenuta in tutte le versioni successive, e come si confronta con le versioni precedenti.

Struttura organizzativa:

Cosa è cambiato in sintesi:

A partire da SIGN IT 2026-02-03, ogni riferimento nei percorsi API, negli schemi, nei parametri e nelle risposte riflette due rinominazioni principali:

Modifica	Fino a SIGN IT 2025-08-12	Da SIGN IT 2026-02-03 in poi
Asset ➜ Organization
Struttura di primo livello	Asset::TENANT rappresenta il fornitore PoS o un esercente che gestisce il proprio sistema PoS.	Organization::ACCOUNT la struttura di primo livello in fiskaly. Rappresenta la tua azienda e contiene utenti, organizzazioni, prodotti e fatturazione.
Livello intermedio	Asset::GROUP livello intermedio opzionale, utilizzato per raggruppare più risorse Asset di tipo UNIT.	Organization::GROUP livello intermedio obbligatorio all’interno di un ACCOUNT, utilizzato per organizzare più UNIT in cluster logici (ad es. un GROUP per paese). Un singolo GROUP per ACCOUNT è sufficiente se non è necessaria un’ulteriore strutturazione.
Esercente	Asset::UNIT rappresenta un esercente (organizzazione gestita, annidata sotto il TENANT o il GROUP, a seconda della struttura)	Organization::UNIT rappresenta un esercente / contribuente operante all’interno del GROUP (e del relativo ACCOUNT).
Entity ➜ Taxpayer e Location
Dati del contribuente	Entity::COMPANY / INDIVIDUAL	Taxpayer::COMPANY / INDIVIDUAL
Rappresenta una particolare UNIT con i relativi dati fiscali del contribuente.
Indirizzo operativo	Entity::LOCATION	Location::BRANCH
Rappresenta l’indirizzo operativo di un locale commerciale o di un esercizio di un soggetto giuridico.

Nota: Quando viene creato un Taxpayer, viene generata automaticamente una Location::HEAD_OFFICE con lo stesso ID. Se l’attività ha un solo indirizzo operativo e questo coincide con la sede legale del contribuente, è possibile collegare il System direttamente all’ID del Taxpayer/HEAD_OFFICE senza creare un BRANCH separato con dati identici. Per maggiori informazioni sulle altre modifiche introdotte con SIGN IT 2026-02-03 consultare: Principali cambiamenti in SIGN IT 2026-02-03

Principali cambiamenti in SIGN IT 2026-02-03

Di seguito una panoramica delle principali modifiche introdotte nell’ultima versione dell’API SIGN IT (SIGN IT 2026-02-03)  

Principali cambiamenti dalla versione 2025-08-12 alla 2026-02-03

**Nuovo header obbligatorio **X-Api-Version L’ultima versione disponibile è 2026-02-03.  

**Nuova risorsa - **Location::BRANCH

• Sostituisce la precedente risorsa Entity::LOCATION. 
• Rappresenta ciascuna sede operativa dell’attività.
• La creazione non è obbligatoria se esiste un’unica sede operativa e questa coincide con la sede legale del contribuente.

Nota: alla creazione del Taxpayer viene automaticamente generata una Location::HEAD_OFFICE, che condivide lo stesso ID del Taxpayer.

 

fiscalization.credentials.tax_id_number è ora un campo obbligatorio  

Aggiornamento della terminologia delle risorse Per migliorare chiarezza e coerenza, alcune risorse sono state rinominate: Asset::UNIT → Organization::UNIT   Entity::COMPANY/INDIVIDUAL → Taxpayer::COMPANY/INDIVIDUAL Entity::LOCATION → Location::BRANCH

Nell’ambito di questo aggiornamento, anche i relativi endpoint sono stati modificati come segue: /organizations (in precedenza /assets) /taxpayers e /locations (precedentemente raggruppati sotto la risorsa /entities e un unico endpoint, ora suddivisi in due risorse distinte con endpoint dedicati)

Per maggiori dettagli vedi questo articolo: Nuova terminologia delle risorse

Principali cambiamenti in SIGN IT 2025-08-12

Con il rilascio dell’ultima versione dell’API SIGN IT, SIGN IT 2025-08-12, sono stati introdotti alcuni cambiamenti importanti. 

La documentazione di SIGN IT 2025-08-12  fa parte della Unified API (UAPI). Nota: questa documentazione copre già sia la Francia che l’Italia. 

Principali cambiamenti dalla versione 2024-10-31 a 2025-08-12

URL di base La nuova versione utilizza il sottodominio della Unified API: TEST: test.api.fiskaly.com  LIVE: live.api.fiskaly.com   

**Header obbligatorio ****X-Api-Version** Questo header è ora obbligatorio, e l’ultima versione è 2025-08-12.  

Modifica nella struttura dei Record Il campo details nei Record è stato spostato un livello più in basso: da content.details a content.operation.details  

Recupero del PDF del Record È ora possibile ottenere il PDF ufficiale (compliance.artifact) del documento generato nel portale Fatture e Corrispettivi. Per maggiori dettagli vedi questo articolo: Posso ottenere il PDF del record generato tramite API?  

**Nuovo campo nell’Entity **– **fiscalization.credentials.tax_id_number** Questo nuovo campo tax_id_number permette agli esercenti di distinguere tra il codice fiscale dell’impresa e quello dell’utente Fisconline (la persona autorizzata a operare per conto dell’impresa e in possesso delle credenziali Fisconline). Serve a supportare i nuovi flussi di autenticazione dell’AdE che in precedenza generavano l’errore Transmission error: unsupported Agenzia delle Entrate (AdE) flow. 

Entrambi i campi sono supportati in POST /entities e PATCH /entities. 

In allegato a questo articolo troverai un PDF che fornisce una spiegazione dettagliata dei campi dell’Entity richiesti per la fiscalizzazione.

È necessario mostrare un codice QR?

No, il codice QR non è richiesto quando si utilizza SIGN IT lite.

La visualizzazione di un codice QR è obbligatoria solo se si utilizza un registratore telematico fisico (Registratore Telematico – RT).

Con SIGN IT lite, gli scontrini vengono generati direttamente tramite il portale online dell’Agenzia delle Entrate, utilizzando la procedura web “Documento commerciale online”. Questo garantisce che i dati delle transazioni vengano trasmessi immediatamente e in modo sicuro alle autorità fiscali.

La validità fiscale dello scontrino e la sua conformità sono assicurate dalla creazione digitale e dalla registrazione del documento commerciale all’interno dei sistemi dell’Agenzia delle Entrate.

Per indicazioni su come il commerciante deve procedere in caso di verifica, consulta questo articolo: SIGN IT - Come gestire un controllo fiscale con SIGN IT lite

È disponibile la dashboard per SIGN IT?

Attualmente, la Dashboard non presenta una sezione dedicata a SIGN IT. Tuttavia, stiamo lavorando a una nuova versione della Dashboard che includa i dati di SIGN IT.

Nel frattempo, questi rimangono accessibili e tracciabili tramite il portale dell’Agenzia delle Entrate, dove ogni contribuente può consultare le proprie informazioni e documenti commerciali (Record).

Per comprendere quali azioni devono essere attualmente completate nella Dashboard e quando effettuare la transizione all’API SIGN IT, si consiglia di consultare la guida passo dopo passo.

Funzionalità attualmente supportate nella Dashboard per SIGN IT

Creare l’organizzazione principale Una volta effettuata la registrazione nella Dashboard, riceverai un link di attivazione via email. Clicca sul link per verificare il tuo indirizzo email e sarai reindirizzato alla creazione della tua organizzazione.  

**Gestire l’accesso degli utenti per l’organizzazione principale **(Impostazioni → Gestione utenti) Se sei l’amministratore dell’organizzazione principale, puoi invitare o rimuovere utenti dalla tua organizzazione.  

**Creare ed eliminare chiavi API **(Impostazioni → Chiavi API → CREA CHIAVE API) Se sei l’amministratore o un utente invitato dell’organizzazione principale, puoi creare ed eliminare chiavi API. Queste sono necessarie per generare il token di accesso all’interno dell’API SIGN IT (endpoint createToken).  

Visualizzare i dettagli dell’organizzazione principale (icona “ℹ”) Se sei l’amministratore o un utente invitato dell’organizzazione principale, puoi accedere al nome, ID, indirizzo e dati fiscali dell’organizzazione principale.   

**Aggiornare i dati dell’organizzazione principale **(icona “ℹ” → Modifica) Se sei l’amministratore dell’organizzazione principale, puoi modificare l’indirizzo e i dati fiscali dell’organizzazione.  

**Visualizzare le organizzazioni gestite **(Impostazioni → Gestione organizzazione) Se sei l’amministratore o un utente invitato dell’organizzazione principale, puoi vedere i nomi e gli ID delle organizzazioni (UNIT) collegate alla tua organizzazione principale.   

Accedere alla Status Page (Stato) Visualizza aggiornamenti in tempo reale su eventuali problemi in corso e manutenzioni programmate.  

**Accedere alla pagina di supporto **(Support) Consulta gli articoli di supporto e/o contatta il nostro team di Product Education (dev-support@fiskaly.com.

Come verificare se le credenziali FISCONLINE sono valide

Nota: La validazione con dati reali avviene esclusivamente nell’ambiente LIVE. Una prima validazione delle credenziali viene eseguita quando il campo state del Taxpayer (in precedenza, Entity Company o Individual) viene aggiornato da ACQUIRED a COMMISSIONED. Se le credenziali sono valide, il campo mode del Taxpayer passerà a OPERATIVE.

Inoltre, è possibile attivare manualmente una validazione cambiando il campo mode del Taxpayer da OPERATIVE → SUSPENDED → OPERATIVE tramite l’endpoint updateTaxpayer (in precedenza, updateEntity).  Se le credenziali sono ancora valide, il campo mode del Taxpayer passerà a OPERATIVE; se invece non lo sono, resterà in SUSPENDED e sarà necessario aggiornare le credenziali FISCONLINE.

Successivamente, quando viene creato un Record, viene eseguito un ulteriore controllo delle credenziali. Se le credenziali non sono più valide, il campo mode del Record sarà impostato su FINISHED, ma il campo state sarà FAILED, con un messaggio di errore nel campo logs. 

Nota: Al momento, in caso di fallimento nella creazione del Record per credenziali invalide o scadute, il campo mode del Taxpayer non viene aggiornato automaticamente a DEGRADED. Tuttavia, in futuro è prevista l’introduzione di questo comportamento. 

Ambienti TEST e LIVE

Tutti gli Account fiskaly iniziano nell’ambiente TEST per impostazione predefinita. L’ambiente TEST offre funzionalità API complete con dati sandbox, consentendo di sviluppare e validare l’integrazione prima di passare in produzione. Qualsiasi API Key generata in questa configurazione permette la creazione di risorse esclusivamente a scopo di test.

Quando si è pronti a elaborare transazioni reali, è necessario attivare l’ambiente LIVE.

Nota: TEST e LIVE sono completamente separati: le organizzazioni e le risorse create in TEST non esistono in LIVE. È necessario creare nuove organizzazioni e risorse nell’ambiente LIVE, inclusa una nuova API Key, poiché le API Key TEST non autenticano sugli endpoint di produzione.  

Attivazione dell’ambiente LIVE nel HUB

Per abilitare l’ambiente LIVE, fare clic sull’opzione “Go LIVE” nella parte superiore della pagina nel HUB.

Il HUB richiede di confermare i dati aziendali e le informazioni di contatto prima di inviare la richiesta di attivazione. Il team Sales si metterà poi in contatto per completare il processo contrattuale.

Durante l’elaborazione della richiesta, il banner mostra un badge “LIVE access pending”. Inoltre, nell’ambiente di test viene visualizzato un gruppo denominato “AccountName-LIVE”. Questa sarà la futura organizzazione LIVE e non è richiesta alcuna azione da parte dell’utente. Una volta approvato e attivato l’account, si otterrà l’accesso all’ambiente LIVE.

 

Passaggio tra gli ambienti

Una volta attivato il LIVE, è possibile passare da TEST a LIVE in qualsiasi momento direttamente nel HUB.

Ogni ambiente è accessibile separatamente, quindi è possibile averli entrambi aperti contemporaneamente. Questo è utile per continuare lo sviluppo in TEST mentre si opera in produzione in LIVE, per riprodurre problemi prima in TEST per il debug, o per formare nuovi membri del team senza influire sui dati di produzione.

Nota: Una volta che la propria Organization opera in ambiente LIVE, non è necessario disattivare le risorse di test. L’ambiente TEST resta completamente accessibile. Il passo successivo è passare all’ambiente LIVE e creare le risorse di produzione:

• Accedere al nuovo Group “AccountName-LIVE” che rispecchia la struttura di produzione

• Generare una nuova API Key LIVE — le API Key TEST non funzionano in LIVE

Importante: I Record inviati nell’ambiente LIVE devono sempre riflettere transazioni commerciali reali.  

Se si utilizza ancora la fiskaly Dashboard

Le istruzioni seguenti si applicano all’interfaccia legacy della Dashboard.

La prima organizzazione creata nella Dashboard dispone unicamente dell’ambiente TEST. È possibile abilitare l’ambiente LIVE, come indicato dal pulsante posizionato in alto a sinistra sotto il nome dell’organizzazione:

Generando una API Key in questa configurazione, è possibile creare risorse esclusivamente per testare la nostra API.

Per impostare la prima Organization in LIVE, è necessario fornire l’Organization ID e completare l’accordo contrattuale. Una volta attivato l’ambiente LIVE, il pulsante “ENABLE LIVE” si trasforma in un toggle, che consente di passare tra l’ambiente TEST e LIVE:

Una volta che l’organizzazione dispone di un ambiente LIVE, il passo successivo consiste nel creare una API Key LIVE. Questa API Key LIVE verrà quindi utilizzata per generare risorse LIVE.

È importante sottolineare che, una volta che l’organizzazione opera in ambiente LIVE, non è necessario disattivare le risorse di test. L’ambiente TEST resta accessibile. Le risorse TEST e LIVE sono supportate in modo integrato, consentendo una transizione fluida senza la necessità di disattivare alcuna risorsa.

 

Nota: Se non è ancora stata effettuata la migrazione al HUB, è possibile seguire questi passaggi. La migrazione al HUB non richiede la ricreazione delle risorse esistenti: la configurazione TEST e LIVE attuale viene trasferita automaticamente.

Come gestire un controllo fiscale con SIGN IT lite

In caso di controllo della Guardia di Finanza è importante informare che SIGN IT lite, a differenza dei registratori di cassa tradizionali, utilizza il servizio “Documento Commerciale Online” dell’Agenzia delle Entrate, nel quale sono registrati tutti gli scontrini emessi.

A questo link è disponibile l’Interpello dell’Agenzia delle Entrate in cui viene dichiarata idonea la trasmissione degli scontrini elettronici tramite software esterni che utilizzano la funzione del Documento Commerciale Online.

 

Istruzioni per la verifica degli scontrini trasmessi all’Agenzia delle Entrate

• Cerca “Fatture e Corrispettivi Agenzia Entrate” su un motore di ricerca, oppure clicca direttamente sul seguente link: https://ivaservizi.agenziaentrate.gov.it/portale/   

• Effettua l’accesso con le tue credenziali FISCONLINE.  

• Dopo aver accettato l’informativa sul trattamento dei dati personali, verifica di essere nel Cassetto Fiscale corretto, con operatività sulla Partita IVA di riferimento.  

• Scorri verso il basso fino alla sezione “Consultazione”, quindi seleziona la voce “Fatture elettroniche e altri dati IVA”.  

• Dal menù in alto, scegli “Corrispettivi” e premi su “Invii/Aggregati giornalieri”.  

• Verifica che ci siano i totali dei corrispettivi giornalieri.  

• Cliccando sul numero degli “Invii/Aggregati giornalieri”, potrai visualizzare e stampare i dettagli di ogni invio.

Cosa fare in caso di problemi di connessione

Se un problema di connessione ti impedisce l’accesso alla nostra API o se il portale “Fatture e Corrispettivi” è temporaneamente non disponibile, le transazioni non potranno essere trasmesse all’Agenzia delle Entrate. In caso di tentativo non riuscito, la conformità può essere facilmente garantita seguendo questi passaggi:

• Fornisci al cliente un semplice documento cartaceo, come consigliato dall’Agenzia delle Entrate. Questo dovrà servire come ricevuta temporanea della transazione.

• Emetti una fattura elettronica tramite SdI (“Sistema di Interscambio”) entro 12 giorni dalla transazione al fine di garantirne la conformità. 

Procedura per l’emissione della fattura elettronica: 

• Emetti uno scontrino includendo una nota che specifichi che il portale non era accessibile al momento della transazione, ad esempio: “Portale non disponibile”.

• Registra i seguenti dati:

Data e ora di emissione

• Numero progressivo della fattura

• Nome, cognome e codice fiscale del cliente

• Partita IVA e ragione sociale dell’esercente

• Importo totale della transazione (IVA inclusa ed esclusa)

• Trasmetti i dati registrati utilizzando un sistema di fatturazione elettronica entro il termine di 12 giorni.

Seguendo questa procedura, sarà garantita la conformità alla normativa italiana anche in caso di problemi di connettività.

Note: Lo scenario offline sarà pienamente supportato in SIGN IT nella sua versione completa.

A cosa si riferisce l’X-Idempotency-Key?

L’idempotenza garantisce che richieste identiche ripetute producano lo stesso risultato, anche se vengono riproposte a causa di problemi di rete, timeout o altri problemi temporanei. Questo comportamento previene la creazione di risorse duplicate o effetti collaterali indesiderati nelle API che accettano richieste POST o PATCH.

L’intestazione HTTP X-Idempotency-Key svolge un ruolo centrale nell’implementazione dell’idempotenza. Gli integratori API utilizzano questa intestazione per identificare in modo univoco le richieste, consentendo all’API di tracciare e gestire i loro esiti attraverso i vari tentativi.

Per ulteriori informazioni, si prega di consultare la sezione dedicata all’Idempotenza nella documentazione API.

Con l’ultimo aggiornamento dell’API del 18 marzo 2026, è stato introdotto il nuovo header di risposta X-Idempotency-Replayed per tutte le richieste POST e PATCH. Questo header consente di distinguere chiaramente tra richieste ripetute ("true") e richieste elaborate come nuove ("false"), migliorando la trasparenza e semplificando le attività di debugging.

Per maggiori dettagli, consulta il nostro articolo sul blog: Unified API Update: Enhanced Idempotency Handling.

A cosa si riferisce l’X-Scope-Identifier

L’header X-Scope-Identifier riveste un ruolo fondamentale durante la creazione del Subject. Esso definisce il contesto (scope) in cui il Subject viene creato, assicurando che l’API_KEY generata sia collegata ad una specifica Organization UNIT (in precedenza, Asset UNIT).

Nota: Se questo header viene omesso, verrà visualizzato il seguente messaggio di errore:

"message": "The request functionality is not implemented yet. ['Subject::API_KEY' creation not supported for none 'Organization::UNIT' scopes]"

Altri casi d’uso

Applicabile solo alle versioni legacy. Non rilevante per la versione più recente (SIGN IT 2026-02-03). Se stai utilizzando la struttura dei GROUP (consulta l’articolo: SIGN IT - Come aggiungere un ulteriore livello a una struttura di Asset), imposta  l’X-Scope-Identifier sull’ID del relativo Asset GROUP. In questo modo, gli Asset UNIT verranno annidati sotto l’Asset GROUP corrispondente.

Nota: Se questo header viene omesso, l’Asset UNIT sarà associato di default all’organizzazione principale (Asset TENANT) tramite il token di autorizzazione.

Systems (1)

Cosa inserire nel campo “producer” se il POS è solo software?

Anche se il punto cassa (POS - Point of Sale) non include alcuna componente hardware, l’API richiede comunque la compilazione di entrambi i campi producer e software durante la creazione del System.

In questi casi, puoi semplicemente fornire informazioni relative al software anche nel campo producer: 

• Il campo type deve essere sempre indicato come "MPN".

• Il campo number può contenere un codice identificativo del software, come una SKU o un codice interno univoco, in modo da rispettare i requisiti dell’API.

• Nel campo details.name puoi inserire il nome del software POS.   

Taxpayers & Locations (2)

Quali dati fiscali devono essere forniti durante la creazione di un Taxpayer

Un Taxpayer (in precedenza “Entity”) fornisce ad una specifica Organization UNIT (in precedenza “Asset”) i dati fiscali rilevanti del contribuente, ed è composta da due parti principali:

informazioni sul contribuente (type: COMPANY / INDIVIDUAL, name e address), e

dati di fiscalizzazione specifici per il Paese (fiscalization). Per l’Italia, questi includono:

• il codice fiscale e la partita IVA dell’impresa, e

• il codice fiscale e le credenziali Fisconline dell’utente autorizzato, ossia la persona abilitata ad operare per conto dell’impresa e in possesso delle credenziali Fisconline.

Scopri di più qui: Principali cambiamenti in SIGN IT 2025-08-12 Guida ai campi del flusso di autenticazione SIGN IT lite

Per ricevere la Guida dettagliata per gli Esercenti su come richiedere le credenziali Fisconline, ti invitiamo a contattare il tuo referente commerciale di fiskaly.

Come aggiornare le credenziali FISCONLINE

Le credenziali Fisconline sul portale AdE scadono ogni 90 giorni. 

Per garantire la continuità del servizio, l’utente Fisconline autorizzato ad operare per conto dell’impresa deve aggiornare la password prima della scadenza seguendo i passaggi indicati di seguito (si consiglia di effettuare l’operazione ogni 60 giorni):

• Accedi all’Area Riservata dell’Agenzia delle Entrate utilizzando le credenziali Fisconline e vai a: Il tuo profilo / Sicurezza e Privacy / Cambio password.

• Inserisci la password attuale, una nuova password sicura e conferma l’invio del modulo.

Una volta che la password è stata aggiornata con successo sul portale AdE, inviare le credenziali aggiornate tramite API seguendo i passaggi indicati di seguito: 

• Impostare il mode di Taxpayer (in precedenza, Entity Company** **o Individual) su SUSPENDED utilizzando l’endpoint updateTaxpayer (in precedenza, updateEntity). 

• Utilizzare l’endpoint updateTaxpayer (in precedenza, updateEntity) per aggiornare le credenziali. Inviare l’intero blocco fiscalization nel corpo della richiesta, ripetendo i dati esistenti e modificando esclusivamente la password.

• Infine, impostare nuovamente il mode di Taxpayer (in precedenza, Entity Company** o Individual) **su OPERATIVE utilizzando l’endpoint updateTaxpayer (in precedenza, updateEntity).

Organizations (1)

Come aggiungere un ulteriore livello a una struttura di Asset

Questo contenuto riguarda solo le versioni legacy. Un articolo per la versione più recente (SIGN IT 2026-02-03) sarà disponibile a breve. L’integrazione con l’API deve includere la creazione della tua organizzazione principale (creata tramite la dashboard di fiskaly) e degli Asset UNIT che rappresentano ciascuno dei tuoi clienti (creati tramite l’API SIGN IT).

Tuttavia, se la tua struttura di Asset richiede maggiore flessibilità, puoi introdurre un livello intermedio opzionale chiamato **Asset ****GROUP**. Questo ti consente di organizzare più Asset UNIT in raggruppamenti logici basati sulla struttura che preferisci.

Come implementare questa nuova struttura

Scarica la collezione Postman allegata, che include gli endpoint necessari per creare e gestire gli Asset GROUP.

• Crea un Asset GROUP - otterrai il suo ID nel campo content.id della risposta. 

• Crea gli Asset UNIT, e collegali all’Asset GROUP precedentemente creato impostando l’header X-Scope-Identifier con l’ID dell’Asset GROUP.

Nota: Se l’header X-Scope-Identifier non viene fornito, l’Asset UNIT verrà associato di default all’organizzazione principale (Asset TENANT) tramite il token di autorizzazione.

Importante: Nel caso in cui l’header venga erroneamente impostato con l’ID di un altro Asset UNIT anziché con quello di un Asset GROUP, la richiesta non andrà a buon fine e la risposta indicherà chiaramente che gli Asset UNIT possono essere associati solo ad Asset GROUP.