Section navigation

FAQ

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

Taxpayers & Locations (4)

Posso aggiornare i dati del Taxpayer?

address** e **fiscalization L’address e la fiscalization (credentials incluse) di un Taxpayer possono essere aggiornate finché la risorsa si trova nello stato ACQUIRED, oppure nello stato COMMISSIONED con modalità SUSPENDED.

Se il Taxpayer è nello stato ACQUIRED, è sufficiente chiamare updateTaxpayer con i dati aggiornati
Se il Taxpayer è nello stato COMMISSIONED, sospendi prima la risorsa (mode: "SUSPENDED"), esegui l’aggiornamento, quindi riattivala (mode: "OPERATIVE").

Per maggiori dettagli su come aggiornare specificamente le credentials, consulta questo articolo: SIGN IT - Come aggiornare le credenziali FISCONLINE

type** e **name A differenza degli altri campi, il type e il name di un Taxpayer possono essere modificati solo mentre la risorsa si trova nello stato ACQUIRED. Una volta che lo stato passa a COMMISSIONED, questi campi non possono più essere aggiornati.

In questo caso, puoi procedere come segue:

Crea un nuovo Taxpayer nella stessa Organization UNIT. La risorsa sarà per impostazione predefinita nello stato ACQUIRED.
Se sono presenti Location esistenti assegnate al vecchio Taxpayer:

Se sono nello stato COMMISSIONED, aggiornale alla modalità SUSPENDED tramite updateLocation

Se sono nello stato ACQUIRED, passa direttamente al punto 3
Assegna le Location esistenti (se presenti) al nuovo Taxpayer ID tramite updateLocation.

{
    "content": {
        "taxpayer": {
            "id": "{{taxpayerId}}"
        }
    }
}

Aggiorna il vecchio Taxpayer dallo stato COMMISSIONED a DECOMMISSIONED tramite updateTaxpayer.
Aggiorna il nuovo Taxpayer dallo stato ACQUIRED a COMMISSIONED tramite updateTaxpayer.
Aggiorna le Location esistenti (se presenti) alla modalità OPERATIVE:

Se erano state aggiornate a SUSPENDED al punto 2, riportale alla modalità OPERATIVE tramite updateLocation

Se sono ancora nello stato ACQUIRED, basterà aggiornarle allo stato COMMISSIONED quando sarai pronto.

Nota: se hai dei System nello stato COMMISSIONED, resteranno inutilizzabili finché la/le Location e/o il Taxpayer associati non saranno rispettivamente nello stato COMMISSIONED con modalità OPERATIVE. Non è necessaria alcuna azione sul System stesso, poiché punta già all’ID della Location corretta — basta attendere che i passaggi sopra indicati vengano completati correttamente.

Metadata

I metadata di un Taxpayer restano sempre completamente aggiornabili, indipendentemente dallo stato e dalla modalità della risorsa.

Cos’è la modalità DEGRADED e come intervenire

Cos’è la modalità DEGRADED?

Quando la trasmissione di un record fallisce a causa di un **errore persistente nelle credenziali Fisconline **nell’ambiente LIVE, la modalità del Taxpayer passa automaticamente da OPERATIVE a DEGRADED.

Tutte le trasmissioni successive vengono immediatamente bloccate fino a quando le credenziali Fisconline non vengono corrette e il Taxpayer viene ripristinato manualmente in modalità OPERATIVE.

Nota: per ora, questa modifica si applica esclusivamente a SIGN IT 2026-06-01, con effetto dal 19 giugno.

Verrà estesa a tutte le versioni API precedenti nel corso dei prossimi 3 mesi. Per aiutarti a prepararti, a partire dal 19 giugno sarà possibile simulare lo scenario di credenziali scadute nell’ambiente TEST per tutte le versioni API — incluse quelle precedenti alla 2026-06-01. Scopri come alla fine di questo articolo.

Cosa la innesca?La prima trasmissione di record che fallisce nell’ambiente LIVE con uno dei seguenti 3 errori di autenticazione:


Errore	Causa
`Authentication error: Fisconline credentials expired`	La password ha superato il ciclo di vita di 90 giorni
`Authentication error: Invalid credentials`	Username, PIN o password errati
`Authentication error: authentication failed due to multiple failed intents with wrong credentials - please reset and update them`	Account bloccato dopo ripetuti tentativi di accesso falliti

Il record che innesca l’errore restituisce lo stato FAILED, con l’errore di autenticazione scatenante nei logs.
La modalità del Taxpayer passa automaticamente da OPERATIVE a DEGRADED
Tutte le trasmissioni successive restituiscono immediatamente un errore 405 Method not allowed error — "record operation invalid: cannot create new record of '<TYPE>::<OPERATION>', legal entity is not in mode 'OPERATIVE'".

Come ripristinareIl flusso di ripristino è il seguente:

PATCH Taxpayer → Aggiornare la modalità del Taxpayer a SUSPENDED
Aggiornare o ripristinare le credenziali nel portale AdE, in base allo scenario
PATCH Taxpayer → Fornire credenziali valide
PATCH Taxpayer → Aggiornare la modalità del Taxpayer a OPERATIVE

#### Come simulare la modalità DEGRADED nell’ambiente TEST

Per simulare lo scenario di credenziali scadute nell’ambiente TEST, invia il record con l’header: X-Taxpayer-Credentials-Expired: true

Questo header fa sì che il record si comporti come quello che innesca l’errore, forzando il percorso di scadenza delle credenziali, così da poter osservare il comportamento completo della modalità DEGRADED descritto sopra — utile per testare la propria integrazione prima che la funzionalità sia disponibile nella propria versione.

Scopri tutte le novità di SIGN IT 2026-06-01.

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

Un Taxpayer (in precedenza “Entity COMPANY / INDIVIDUAL”) 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
le credenziali Fisconline (codice fiscale personale, pin e password) dell’utente autorizzato ad operare per conto dell’impresa e in possesso delle credenziali Fisconline.

Taxpayer details.png **Nota: **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. La validità di 90 giorni della password Fisconline decorre dal momento in cui è stata aggiornata l’ultima volta sul portale AdE, che non necessariamente coincide con il momento in cui è stata comunicata a fiskaly tramite API.

Per garantire la continuità del servizio, l’utente Fisconline autorizzato ad operare per conto dell’impresa deve aggiornare la password sul portale AdE 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.

Nota: Se non si ricorda la password attuale, sarà necessario reimpostarla sul portale AdE. Una volta aggiornata con successo la password sul portale AdE, inviare le credenziali aggiornate tramite API seguendo i passaggi indicati di seguito:

Impostare il mode del Taxpayer 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 del Taxpayer su OPERATIVE utilizzando l’endpoint updateTaxpayer (in precedenza, updateEntity).

**Aggiornamento importante: **Questo flusso si applica anche quando la modalità di partenza è DEGRADED e non OPERATIVE. La modalità DEGRADED viene attivata automaticamente quando l’invio di un record fallisce a causa di credenziali scadute, non valide o di un account bloccato. Viene introdotta nella versione 2026-06-01 il 19 giugno, e sarà disponibile per tutte le versioni precedenti nei prossimi 3 mesi. Per saperne di più: Cos’è la modalità DEGRADED e come intervenire Nota: I passaggi API descritti in questo articolo si applicano ai Taxpayer in stato COMMISSIONED — come mostrato nel diagramma, la modalità del Taxpayer (sia OPERATIVE che DEGRADED) deve essere impostata su SUSPENDED prima di aggiornare qualsiasi informazione. Se il Taxpayer è ancora in stato ACQUIRED, non è ancora stato attivato, quindi è possibile aggiornarne le informazioni direttamente tramite l’endpoint updateTaxpayer senza modificarne la modalità.

Generale (13)

Principali cambiamenti in SIGN IT 2026-06-01

Di seguito una panoramica delle principali modifiche introdotte in SIGN IT 2026-06-01.

**Nuovo header **X-Api-Version obbligatorio L’ultima versione disponibile è la 2026-06-01.
Introdotta la modalità DEGRADED **per i Taxpayer **(dal 19 giugno) Quando viene rilevato un errore persistente nelle credenziali Fisconline durante la trasmissione di un record, il Taxpayer passa automaticamente da OPERATIVE a DEGRADED e le trasmissioni successive vengono bloccate fino alla risoluzione del problema. Per saperne di più: Cos’è la modalità DEGRADED e come intervenire
**Modifica strutturale per RECEIPT e CORRECTION **
Nuovo campo obbligatorio totals.vat (a livello di operation) in sostituzione del vecchio total_vat (a livello di document). La semantica rimane invariata: contiene l’importo IVA aggregato, il subtotale IVA esclusa e il totale IVA inclusa.

Versioni precedenti

"operation": {
  "type": "RECEIPT",
  "document": {
    "number": "REC-001",
    "total_vat": {
      "amount": "4.45454545",
      "exclusive": "20.54545455",
      "inclusive": "25.00"
    }
  },
  "entries": [...],
  "payments": [...]
}

Dalla versione 2026-06-01

"operation": {
  "type": "RECEIPT",
  "document": {
    "number": "REC-001"
  },
  "totals": {
    "vat": {
      "amount": "4.45454545",
      "exclusive": "20.54545455",
      "inclusive": "25.00"
    }
  },
  "entries": [...]
  "payments": [...]
}

-** Nuovo campo obbligatorio **breakdown. Contiene gli stessi valori IVA di totals.vat, ma suddivisi per aliquota IVA. Particolarmente utile quando una transazione include articoli con aliquote IVA diverse.

"operation": {
  "type": "RECEIPT",
  "breakdown": [
  {
    "type": "VAT_RATE",
    "code": "STANDARD",
    "percentage": "22.00",
    "amount": "4.40",
    "exclusive": "20.00",
    "inclusive": "24.40"
  },
  {
    "type": "VAT_RATE",
    "code": "REDUCED_1",
    "percentage": "10.00",
    "amount": "0.05454545",
    "exclusive": "0.54545455",
    "inclusive": "0.60"
  }
]
}

unit.price è ora un **oggetto con due campi **— inclusive e exclusive — invece di un singolo valore stringa (solo IVA inclusa)

Versioni precedenti

"entries": [
  {
    "type": "SALE",
    "data": {
      "type": "ITEM",
      "text": "Margherita pizza",
      "unit": {
        "quantity": "2",
        "price": "12.20"
      }

Dalla versione 2026-06-01

"entries": [
  {
    "type": "SALE",
    "data": {
      "type": "ITEM",
      "text": "Margherita pizza",
      "unit": {
        "quantity": "2",
        "price": {
          "inclusive": "12.20",
          "exclusive": "10.00"
        }
      }

Nuovo valore INVOICE aggiunto al campo concept per i pagamenti non riscossi (OUTSTANDING). Impostare questo valore nel caso di prestazione di servizi continuativi con emissione di fattura a fine periodo.

"payments": [
        {
          "type": "OUTSTANDING",
          "details": {
            "amount": "2.00"
          },
          "concept": "INVOICE"
        }
      ]

E-INVOICE per l’Italia è ora disponibile (invio e ricezione di fatture elettroniche B2B, invio di fatture elettroniche B2C). Ulteriori dettagli sono disponibili qui: E-INVOICE IT per clienti SIGN IT

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}}/records**?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 in 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

Il rilascio di SIGN IT 2025-08-12 introduce cambiamenti importanti e segna il debutto della nostra Unified API.

La documentazione di questa versione è ora valida sia per la Francia che per 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: 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

HUB, la nuova dashboard

fiskaly HUB è la nuova interfaccia web che sostituisce il precedente fiskaly Dashboard ed è ora il punto centrale per la gestione della tua integrazione SIGN IT.

Questo articolo spiega cosa viene gestito in HUB e cosa rimane invece gestito tramite API, dal punto di vista di SIGN IT. Per HUB stesso, manteniamo una guida HUB completa: ogni sezione qui sotto rimanda all’argomento corrispondente, dove troverai tutti i dettagli e gli screenshot.

Per comprendere l’intero flusso di integrazione e quando eseguire ciascun passaggio, ti consigliamo di consultare la guida all’integrazione di SIGN IT.

Nota: se in precedenza utilizzavi il fiskaly Dashboard, HUB ne è il successore. Offre una struttura unificata per Account, Group e Unit, insieme a una navigazione migliorata, alla gestione dell’Organization, alla gestione delle API Key e all’accesso ai servizi fiskaly sia in ambiente TEST che LIVE. Questo articolo spiega le principali differenze tra la terminologia utilizzata su Dashboard e quella utilizzata su HUB: SIGN IT - Nuova terminologia delle risorse

Dove trovare cosa


Configurazione dell’Account, gestione utenti, API Key	HUB
Monitoraggio di Taxpayer, Location, System e Record	HUB (sezione SIGN IT)
Passaggio all’ambiente LIVE	HUB (Go LIVE)
Creazione e gestione delle Unit (Taxpayer)	SIGN IT API
Nota: tutti i corrispettivi trasmessi con successo restano inoltre accessibili e tracciabili dal Taxpayer tramite il portale dell’Agenzia delle Entrate, dove ogni contribuente può consultare autonomamente i propri dati fiscali.

Cosa puoi fare in HUB per SIGN IT

Account e accesso

Registrati su hub.fiskaly.com per ricevere l’email di attivazione: il link è valido per 5 minuti. Se disponi già di un account su Dashboard, ti basta accedere a HUB con le stesse credenziali. Una volta effettuato l’accesso, potrai creare il tuo Account, invitare utenti, assegnare ruoli e generare API Key.

→ Primi passi · Glossario

Selezione dell’ambito (Pannello di navigazione → Organizations → Select)

Tutto ciò che vedi in HUB dipende dall’organizzazione che stai visualizzando in quel momento. La scheda dell’organizzazione nella parte superiore della barra laterale mostra sempre dove ti trovi; puoi cliccarci sopra per aprire la pagina di dettaglio di quell’organizzazione, oppure utilizzare Organizations nel pannello di navigazione per aprire il selettore delle organizzazioni e cambiarla.

Ciò che è disponibile dipende dal livello selezionato:

Account — i dati aziendali e la sezione “What’s New” con avvisi di manutenzione e aggiornamenti sulle release. In arrivo: informazioni su piani e fatturazione.
Group — gestione delle Unit sottostanti, invito degli utenti e generazione delle API Key
Unit — i dati SIGN IT relativi a quel Taxpayer, oltre alle relative API Key, agli utenti e alla panoramica dei prodotti disponibili.

→ Menu HUB · Cambio organizzazione

Gestione degli utenti (Pannello di navigazione → Users)

Invita o rimuovi utenti a livello di Account, Group o Unit, a seconda di dove l’utente deve avere accesso. A livello di Account puoi anche assegnare i ruoli — Owner, Admin, Billing e Regular user — tramite policy, opzionalmente con una data di scadenza per l’accesso temporaneo.

→ Gestione utenti · Ruoli e assegnazione dei ruoli

API Key (Pannello di navigazione → API Keys)

Vengono create a livello di Group o Unit a seconda della tua integrazione, e sono necessarie per generare access token all’interno della SIGN IT API (endpoint createToken). Le API Key sono specifiche per ambiente: una Key di TEST crea solo risorse di test; una Key di LIVE crea solo risorse di produzione.

→ Gestione delle API Key

Gestione dell’Organization (Pannello di navigazione → Organizations)

Una pagina dedicata mostra l’intera gerarchia di Group e Unit appartenenti al tuo Account. Se utilizzi i Group, le Unit vengono mostrate all’interno della struttura del Group.

Ogni Group e Unit dispone inoltre di una pagina di dettaglio in cui puoi visualizzare e modificare nome, indirizzo e logo dell’organizzazione.

→ Dettagli dell’organizzazione

Monitoraggio di SIGN IT

Una volta creata e configurata tramite API, un’Organization UNIT compare nella sezione SIGN IT di HUB, che segue la stessa gerarchia di un drill-down a partire dal Taxpayer:

La Overview ti offre una lettura immediata dello stato operativo del Taxpayer: il suo stato e la modalità correnti e quanti System sono commissioned al suo interno. Da qui,
Locations ti permette di vedere dove quei System sono fisicamente installati e verificare che ogni Location funzioni come previsto. Cliccando su una Location, la vista si restringe ai relativi
Systems, dove puoi monitorare l’attività di ciascun System, incluso il numero di Record emessi e i relativi dettagli software.
I Records si trovano al livello più granulare e forniscono un registro di stato di ogni transazione fiscale in tutte le Location e i System appartenenti all’Organization UNIT.

→ Panoramica del servizio SIGN IT

Le tue risorse SIGN IT vengono sempre mostrate a livello di Unit, poiché ogni Unit corrisponde a un Taxpayer. Se stai cercando Location, System o Record e la sezione SIGN IT appare vuota, verifica di aver selezionato la Unit corretta e non l’Account o un Group.

Per il recupero tramite API, puoi comunque elencare tutti gli Asset tramite l’endpoint SIGN IT ListAssets. Per recuperare le Unit appartenenti a un Group specifico, includi l’header:

X-Scope-Identifier: {GROUP_ID}

Passaggio a LIVE

Quando sei pronto a elaborare transazioni reali, l’Account Owner clicca su “Go Live” nel banner Test Mode nella parte superiore di HUB. Dopo aver confermato i dati della tua azienda, il nostro team Sales ti contatterà per completare l’iter contrattuale. Una volta attivato LIVE, potrai passare dall’ambiente TEST all’ambiente LIVE direttamente in HUB.

→ Passaggio all’ambiente LIVE & SIGN IT - Ambienti TEST e LIVE

Guida e stato

La barra di navigazione superiore include un menu Help con accesso diretto alla nostra documentazione per sviluppatori, al centro assistenza e al contatto con il supporto. Da lì puoi anche cambiare la lingua dell’interfaccia di HUB — HUB è disponibile in inglese, tedesco, spagnolo, italiano e francese.

Riepilogo

HUB sostituisce il vecchio Dashboard e supporta tutte le funzioni di configurazione relative a SIGN IT.
Struttura organizzativa, accesso degli utenti e API Key sono oggi interamente gestiti all’interno di HUB.
Taxpayer, Location, System e Record vengono monitorati in HUB; il contenuto fiscale dei record viene consultato sul portale dell’AdE.
Le Unit (Taxpayer) continuano a essere create e gestite tramite la SIGN IT API.

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 lo state del Taxpayer viene aggiornato da ACQUIRED a COMMISSIONED nell’ambiente LIVE. Se le credenziali sono valide, il mode del Taxpayer cambierà a OPERATIVE.
Inoltre, è possibile avviare manualmente una validazione cambiando il mode del Taxpayer da OPERATIVE → SUSPENDED → OPERATIVE nell’ambiente LIVE tramite l’endpoint updateTaxpayer (in precedenza, updateEntity). Se le credenziali sono ancora valide, il mode del Taxpayer cambierà a OPERATIVE; in caso contrario, resterà in SUSPENDED e sarà necessario aggiornare le credenziali FISCONLINE.
Successivamente, quando viene creato un Record TRANSACTION nell’ambiente LIVE, viene eseguita un’ulteriore verifica delle credenziali. Se l’autenticazione al portale AdE non va a buon fine a causa di credenziali scadute, non valide o di un account bloccato, il Record restituirà modalità FINISHED / stato FAILED, e un messaggio Authentication Error apparirà nei logs indicando la causa esatta. In tal caso, la modalità del Taxpayer passerà automaticamente a DEGRADED, bloccando ulteriori trasmissioni di record fino a quando le credenziali Fisconline non vengono corrette e il Taxpayer viene ripristinato manualmente in modalità OPERATIVE.

Nota: La modalità DEGRADED viene introdotta nella versione 2026-06-01 in data 19 giugno, e sarà disponibile per tutte le versioni precedenti nei prossimi 3 mesi. Se si decide di rimanere sulla propria versione, è già possibile simularne il comportamento inviando un record con l’header X-Taxpayer-Credentials-Expired: true nell’ambiente di TEST. Per maggiori dettagli: Cos’è la modalità DEGRADED e come intervenire

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, viene richiesta l’attivazione dell’ambiente LIVE.

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

Attivazione dell’ambiente LIVE in HUB

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

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 “Accesso LIVE in attesa”.

Inoltre, nell’ambiente TEST viene visualizzato un Group placeholder denominato “AccountName-LIVE”. Rappresenta il primo Group selezionato per l’attivazione LIVE e non richiede alcuna azione da parte dell’utente.

Una volta che l’Account è stato approvato e attivato:

il banner di attivazione scompare
l’ambiente LIVE diventa accessibile e
il Group AccountName-LIVE appare nell’ambiente LIVE.

Passaggio tra gli ambienti

TEST e LIVE sono ambienti indipendenti, ciascuno accessibile tramite il proprio URL. Una volta attivato il LIVE, i pulsanti TEST/LIVE in alto a sinistra di HUB consentono di passare tra i due ambienti in qualsiasi momento.

Ogni ambiente viene aperto 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 facendo clic sul pulsante LIVE e creare le risorse di produzione.

Creazione delle risorse LIVE

Accedere al nuovo Group “AccountName-LIVE” in LIVE.
Generare una nuova API Key LIVE — le API Key TEST non funzionano in LIVE.
Ricreare le risorse successive in LIVE tramite l’API SIGN IT, seguendo la sequenza di configurazione descritta nella guida di integrazione SIGN IT. Le risorse di TEST non vengono trasferite in LIVE.

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

Se utilizzi ancora la fiskaly Dashboard

È possibile continuare a utilizzare la nostra interfaccia legacy Dashboard in TEST, ma si consiglia di migrare a HUB, poiché offre una visione unificata di Account, Group e risorse di tutte le soluzioni fiskaly, una navigazione più chiara tra gli ambienti TEST e LIVE e l’accesso alle ultime funzionalità e migliorie, mentre la Dashboard non è più in sviluppo attivo.

Per impostare la prima Organization in LIVE, si completa il processo di attivazione descritto sopra in HUB. La nostra Guida all’Attivazione dell’Accesso LIVE fornisce ulteriori dettagli sui passaggi previsti.

La Dashboard legacy non supporta più l’attivazione LIVE — questo passaggio viene completato tramite HUB.

Nota: Se non è ancora stata effettuata la migrazione a HUB, è possibile seguire questi passaggi. La migrazione a 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.

Per la ricerca di uno specifico Documento Commerciale all’interno del portale Fatture e Corrispettivi, ti invitiamo a consultare il seguente articolo: Come individuare un documento commerciale nel portale AdE

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 entro 12 giorni dalla transazione al fine di garantirne la conformità. La fattura può essere emessa tramite E-INVOICE IT, tramite un sistema di fatturazione elettronica già a tua disposizione oppure direttamente tramite SdI “Sistema di Interscambio”).

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’header X-Idempotency-Key svolge un ruolo centrale nell’implementazione dell’idempotenza.

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.

Gli integratori API utilizzano l’header X-Idempotency-Key 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’aggiornamento API del 18 marzo 2026, è stato introdotto il nuovo header di risposta X-Idempotency-Replayed per 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 **per una Organization UNIT (in precedenza, Asset UNIT).

Definisce lo scope in cui il Subject viene creato, garantendo che l’API_KEY generata sia associata a una specifica Organization 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 Consulta l’articolo Come aggiungere un ulteriore livello alla tua struttura

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.

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"
          }
        }
      ]

Nota: La procedura web “Documento Commerciale Online” su cui si basa SIGN IT lite tollera tecnicamente una discrepanza massima di €0.02 tra il totale del documento e il totale dei pagamenti. Sebbene sarebbe quindi tecnicamente possibile rappresentare solo 23,00 nell’esempio sopra, includere lo sconto risulta più coerente con l’approccio definito nelle specifiche tecniche RT tradizionali.

**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 “Fatture e Corrispettivi” dell’Agenzia delle Entrate in due modi:

**Utilizzando la ****compliance.url** Se la trasmissione del Record::TRANSACTION ha restituito stato COMPLETED e mode FINISHED, la risposta dell’API include una compliance.url. Aprendo questo link e autenticandosi con le proprie credenziali, l’esercente viene indirizzato al PDF corrispondente generato nel portale AdE.
Ricerca manuale nel portale Fatture e Corrispettivi

Accedere al portale Fatture e Corrispettivi.
Scorrere fino alla sezione “Corrispettivi” e selezionare “Documento Commerciale Online”.
Nella pagina successiva, cliccare su “Cerca il tuo documento”.
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": {
                    "inclusive": "9.00",
                    "exclusive": "8.18181818"
                }
            },
            "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: Questo payload riflette la struttura di *entries* introdotta nella versione API 2026-06-01. Se stai integrando una versione precedente, usa il formato semplice *unit.price* come stringa (es. “price”: “9.00”) invece dell’oggetto { *inclusive*, *exclusive* } mostrato qui.

Importane: 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": "{{cancellationIntentionId}}"
        },
        "operation": {
            "type": "CANCELLATION",
          "record": {
              "id": "{{cancelReceiptId}}"
          }
        }
    }
}

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

La CANCELLATION è un’operazione diversa dalla CORRECTION, che viene utilizzata in caso di resi. Non sai quale delle due utilizzare? Consulta il nostro articolo: Come gestire un reso (CORRECTION)

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.

Questa operazione si differenzia da una CANCELLATION, che viene utilizzata per invalidare una RECEIPT esistente. Non sai quale delle due utilizzare? Consulta il nostro articolo: Quando va usata la CANCELLATION?

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

Nota*: i seguenti payload riflettono le modifiche alla struttura introdotte con la versione API 2026-06-01. Se stai integrando una versione precedente: sostituisci il campo totals.vat (a livello di operation) con il vecchio total_vat (a livello di document), rimuovi il campo breakdown e usa il formato semplice unit.price come stringa (solo inclusive, es. “price”: “50.00”) al posto dell’oggetto { inclusive, exclusive } mostrato qui.*

Esempio

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

{
    "content": {
        "type": "TRANSACTION",
        "record": {
            "id": "{{intentionId}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-12345"
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Jacket",
                        "unit": {
                            "quantity": "1",
                            "price": {
                                "inclusive": "50.00",
                                "exclusive": "40.98360656"
                            }
                        },
                        "value": {
                            "base": "40.98360656",
                            "discount": "0.00"
                        },
                        "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": {
                                "inclusive": "25.00",
                                "exclusive": "20.49180328"
                            }
                        },
                        "value": {
                            "base": "40.98360655"
                        },
                        "vat": {
                            "type": "VAT_RATE",
                            "code": "STANDARD",
                            "percentage": "22.00",
                            "exclusive": "40.98360655",
                            "inclusive": "50.00",
                            "amount": "9.01639344"
                        }
                    }
                }
            ],
            "breakdown": [
                {
                    "type": "VAT_RATE",
                    "code": "STANDARD",
                    "percentage": "22.00",
                    "exclusive": "81.96721311",
                    "inclusive": "100.00",
                    "amount": "18.03278688"
                }
            ],
            "totals": {
                "vat": {
                    "amount": "18.03278688",
                    "exclusive": "81.96721311",
                    "inclusive": "100.00"
                }
            },
            "customer": {
                "type": "EXTERNAL"
            },
            "payments": [
                {
                    "type": "CASH",
                    "details": {
                        "amount": "100.00"
                    }
                }
            ]
        }
    }
}

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": "{{correctionIntentionId}}"
    },
    "operation": {
      "type": "CORRECTION",
      "record": {
        "id": "{{correctReceiptId}}"
      },
      "data": {
        "type": "RECEIPT",
        "document": {
          "number": "INV-16789",
          "series": "C"
        },
        "entries": [
          {
            "type": "RETURN",
            "details": {
              "concept": "GOOD",
              "number": "2"
            },
            "data": {
              "type": "ITEM",
              "text": "T-shirt",
              "unit": {
                "quantity": "1",
                "price": {
                  "inclusive": "25.00",
                  "exclusive": "20.49180327"
                }
              },
              "value": {
                "base": "20.49180327"
              },
              "vat": {
                "type": "VAT_RATE",
                "code": "STANDARD",
                "percentage": "22.00",
                "exclusive": "20.49180327",
                "inclusive": "25.00",
                "amount": "4.50819672"
              }
            }
          }
        ],
        "breakdown": [
          {
            "type": "VAT_RATE",
            "code": "STANDARD",
            "percentage": "22.00",
            "exclusive": "20.49180327",
            "inclusive": "25.00",
            "amount": "4.50819672"
          }
        ],
        "totals": {
          "vat": {
            "amount": "4.50819672",
            "exclusive": "20.49180327",
            "inclusive": "25.00"
          }
        },
        "customer": {
          "type": "EXTERNAL"
        },
        "payments": [
          {
            "type": "CASH",
            "details": {
              "amount": "25.00"
            }
          }
        ]
      }
    }
  }
}

Scenario di rimborso totale in un unico documento Per un rimborso completo, tutte le voci del documento commerciale originale devono essere elencate con i rispettivi valori.

Scenario di scambio merce: reso dell’articolo A e acquisto dell’articolo B Non è possibile emettere un unico “Documento Commerciale” che contenga sia voci di tipo SALE che RETURN. Dal punto di vista tecnico, l’approccio corretto è il seguente:

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

Scenario: reso dell’articolo A ed emissione di un buono acquisto Dal punto di vista tecnico, l’approccio corretto è il seguente:

Emettere una transazione di tipo CORRECTION per certificare il reso dell’articolo A
Emettere 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 il “Totale non riscosso” nel documento commerciale:

indica payments[].type: "OUTSTANDING";
aggiungi payments[].concept e specifica se riguarda: un bene (GOOD - “Credito per cessione di bene consegnato”), un servizio (SERVICE - “Prestazioni di servizi”) o, dalla versione 2026-06-01, una prestazione di servizi continuativa con fattura emessa a fine periodo (INVOICE - flag nel box “Emissione fattura”).

Esempio di pagamento non riscosso per un bene

{
  "content": {
    "type": "TRANSACTION",
    "record": {
      "id": "{{intentionId}}"
    },
    "operation": {
      "type": "RECEIPT",
      "document": {
        "number": "INV-12345"
      },
      "entries": [
        {
          "type": "SALE",
          "details": {
            "concept": "GOOD"
          },
          "data": {
            "type": "ITEM",
            "text": "Product A",
            "unit": {
              "quantity": "1",
              "price": {
                "inclusive": "40.00",
                "exclusive": "32.78688525"
              }
            },
            "value": {
              "base": "32.78688525"
            },
            "vat": {
              "type": "VAT_RATE",
              "code": "STANDARD",
              "percentage": "22.00",
              "exclusive": "32.78688525",
              "inclusive": "40.00",
              "amount": "7.21311475"
            }
          }
        }
      ],
      "breakdown": [
        {
          "type": "VAT_RATE",
          "code": "STANDARD",
          "percentage": "22.00",
          "exclusive": "32.78688525",
          "inclusive": "40.00",
          "amount": "7.21311475"
        }
      ],
      "totals": {
        "vat": {
          "amount": "7.21311475",
          "exclusive": "32.78688525",
          "inclusive": "40.00"
        }
      },
      "customer": {
        "type": "EXTERNAL"
      },
      "payments": [
        {
          "type": "OUTSTANDING",
          "details": {
            "amount": "40.00"
          },
          "concept": "GOOD"
        }
      ]
    }
  }
}

Nota: il payload qui sopra riflette le modifiche alla struttura introdotte con la versione API 2026-06-01. Se stai integrando una versione precedente: sostituisci il campo totals.vat (a livello di operation) con il vecchio total_vat (a livello di document), rimuovi il campo breakdown e usa il formato semplice unit.price come stringa (solo inclusive, es. “price”: “40.00”) al posto dell’oggetto { inclusive, exclusive } mostrato qui.

Come viene rappresentato nella procedura web del Documento Commerciale Online

Cosa fare al momento dell’incasso? Per i beni (GOOD), il documento commerciale iniziale — emesso con pagamento OUTSTANDING (non riscosso) — è sufficiente: il momento impositivo si perfeziona già alla consegna, quindi alla riscossione non serve un ulteriore documento, ma basta conservare o fare riferimento alla relativa prova di pagamento. Per i servizi (SERVICE), invece, poiché il momento impositivo si perfeziona solo con l’incasso, 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

SIGN IT lite si basa sulla procedura web “Documento Commerciale Online” (DCO) dell’Agenzia delle Entrate. Questo articolo descrive come l’AdE calcola i valori del documento commerciale in questa procedura.

L’Agenzia delle Entrate si basa sui seguenti valori per calcolare tutti gli altri:

unit.quantity
unit.price
vat.percentage
value.discount
details.purpose, solo per le righe in omaggio ("GIFT"). L’AdE esclude le righe in omaggio dall’importo complessivo da saldare (Totale complessivo), ma queste concorrono comunque all’imponibile e all’IVA.

**Valori a livello di riga (entry) **

unit.quantity: per questo valore sono ammessi solo 2 decimali.
vat.amount e vat.inclusive sono arrotondati all’ottava cifra decimale.
value.base e vat.exclusive non sono mappati sul portale AdE, ma consigliamo di calcolarli con lo stesso arrotondamento descritto qui sopra.


Campo API	Definizione	Formula
`value.base`	Importo totale della riga (IVA esclusa) prima degli sconti, se presenti	`(unit.price.inclusive × unit.quantity) ÷ (1 + (vat.percentage ÷ 100))` Nota: se stai utilizzando una versione legacy, `unit.price` è IVA inclusa
`vat.inclusive`	Importo totale della riga (IVA inclusa) dopo gli sconti, se presenti	`(unit.price.inclusive x unit.quantity)` `- value.discount` Nota: se stai utilizzando una versione legacy, `unit.price` è IVA inclusa
`vat.exclusive`	Importo totale della riga (IVA esclusa) dopo gli sconti, se presenti	`vat.inclusive ÷ (1 + (vat.percentage ÷ 100))`
`vat.amount`	Importo IVA	`vat.inclusive - vat.exclusive`

Valori a livello di totali del documento

total_vat.amount / totals.vat.amount (a seconda della versione utilizzata): il portale AdE ricalcola il valore inviato e lo sovrascrive con la somma degli importi IVA di tutte le entries, righe in omaggio incluse. L’AdE arrotonda questo valore (in background) all’ottava cifra decimale.
total_vat.inclusive / totals.vat.inclusive e total_vat.exclusive / totals.vat.exclusive (a seconda della versione utilizzata): questi campi non vengono inoltrati all’AdE, che calcola i propri totali del documento direttamente dai valori di riga elencati all’inizio dell’articolo.
payments[].details.amount e payments[].details.discount: per questi valori sono ammessi solo 2 decimali.

Warning ed errori più comuni

**WARNING **di validazione "Validation checks failed.. Reasons: Received total VAT amount XXX is not equal to Tax Agency computed total VAT amount XXX" Cosa significa: l’importo IVA totale inviato non coincide con la somma degli importi IVA di riga calcolata dall’AdE. Il warning non è bloccante: il documento commerciale viene accettato con il valore ricalcolato dall’AdE (mostrato nel PDF arrotondato a 2 decimali).
Errori di trasmissione del record con ERROR di validazione "Validation checks failed.. Reasons: La somma delle tipologie di pagamento non risulta uguale al Totale complessivo" Cosa significa: l’AdE verifica che la somma di tutti i pagamenti (Σ payments[].details.amount + Σ payments[].details.discount) coincida con l’importo complessivo da saldare (Totale complessivo), che l’AdE calcola a partire dalle righe (Σ [(unit.price.inclusive × unit.quantity) − value.discount]), escluse le righe in omaggio.

Esempio di payload

{
  "content": {
    "type": "TRANSACTION",
    "record": {
      "id": "{{intentionId}}"
    },
    "operation": {
      "type": "RECEIPT",
      "document": {
        "number": "INV-12346"
      },
      "entries": [
        {
          "type": "SALE",
          "details": {
            "concept": "GOOD"
          },
          "data": {
            "type": "ITEM",
            "text": "Prod A",
            "unit": {
              "quantity": "1.00",
              "price": {
                "inclusive": "9.00",
                "exclusive": "8.18181818"
              }
            },
            "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": {
                "inclusive": "1.20",
                "exclusive": "0.98360656"
              }
            },
            "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"
            }
          }
        }
      ],
      "breakdown": [
        {
          "type": "VAT_RATE",
          "code": "REDUCED_1",
          "percentage": "10.00",
          "exclusive": "7.27272727",
          "inclusive": "8.00",
          "amount": "0.72727273"
        },
        {
          "type": "VAT_RATE",
          "code": "STANDARD",
          "percentage": "22.00",
          "exclusive": "1.92622951",
          "inclusive": "2.35",
          "amount": "0.42377049"
        }
      ],
      "totals": {
        "vat": {
          "amount": "1.15104322",
          "exclusive": "9.19895678",
          "inclusive": "10.35"
        }
      },
      "customer": {
        "type": "EXTERNAL"
      },
      "payments": [
        {
          "type": "CASH",
          "details": {
            "amount": "10.35"
          }
        }
      ]
    }
  }
}

Nota: il payload qui sopra riflette le modifiche alla struttura introdotte con la versione API 2026-06-01. Se stai integrando una versione precedente: sostituisci il campo totals.vat (a livello di operation) con il vecchio total_vat (a livello di document), rimuovi il campo breakdown e usa il formato semplice unit.price come stringa (solo inclusive, es. “price”: “9.00”) al posto dell’oggetto { inclusive, exclusive } mostrato qui.

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.

Nota*: i seguenti payload riflettono le modifiche alla struttura introdotte con la versione API 2026-06-01. Se stai integrando una versione precedente: sostituisci il campo totals.vat (a livello di operation) con il vecchio total_vat (a livello di document), rimuovi il campo breakdown e usa il formato semplice unit.price come stringa (solo inclusive, es. “price”: “100.00”) al posto dell’oggetto { inclusive, exclusive } mostrato qui.*

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": "{{intentionId}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-123456"
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Voucher for service XYZ - Nr. 2345",
                        "unit": {
                            "quantity": "1",
                            "price": {
                                "inclusive": "100.00",
                                "exclusive": "81.96721311"
                            }
                        },
                        "value": {
                            "base": "81.96721311"
                        },
                        "vat": {
                            "type": "VAT_RATE",
                            "code": "STANDARD",
                            "percentage": "22.00",
                            "exclusive": "81.96721311",
                            "inclusive": "100.00",
                            "amount": "18.03278689"
                        }
                    }
                }
            ],
            "breakdown": [
                {
                    "type": "VAT_RATE",
                    "code": "STANDARD",
                    "percentage": "22.00",
                    "exclusive": "81.96721311",
                    "inclusive": "100.00",
                    "amount": "18.03278689"
                }
            ],
            "totals": {
                "vat": {
                    "amount": "18.03278689",
                    "exclusive": "81.96721311",
                    "inclusive": "100.00"
                }
            },
            "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"
           },
           "entries": [
               {
                   "type": "SALE",
                   "details": {
                       "concept": "GOOD"
                   },
                   "data": {
                       "type": "ITEM",
                       "text": "Product XYZ",
                       "unit": {
                           "quantity": "1",
                           "price": {
                               "inclusive": "200.00",
                               "exclusive": "163.93442623"
                           }
                       },
                       "value": {
                           "base": "163.93442623",
                           "discount": "100.00"
                       },
                       "vat": {
                           "type": "VAT_RATE",
                           "code": "STANDARD",
                           "percentage": "22.00",
                           "exclusive": "81.96721311",
                           "inclusive": "100.00",
                           "amount": "18.03278689"
                       }
                   }
               }
           ],
           "breakdown": [
               {
                   "type": "VAT_RATE",
                   "code": "STANDARD",
                   "percentage": "22.00",
                   "exclusive": "81.96721311",
                   "inclusive": "100.00",
                   "amount": "18.03278689"
               }
           ],
           "totals": {
               "vat": {
                   "amount": "18.03278689",
                   "exclusive": "81.96721311",
                   "inclusive": "100.00"
               }
           },
           "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"
           },
           "entries": [
               {
                   "type": "SALE",
                   "details": {
                       "concept": "GOOD"
                   },
                   "data": {
                       "type": "ITEM",
                       "text": "Product A",
                       "unit": {
                           "quantity": "1",
                           "price": {
                               "inclusive": "90.00",
                               "exclusive": "73.77049180"
                           }
                       },
                       "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": "Product B",
                       "unit": {
                           "quantity": "1",
                           "price": {
                               "inclusive": "20.00",
                               "exclusive": "16.39344262"
                           }
                       },
                       "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"
                       }
                   }
               }
           ],
           "breakdown": [
               {
                   "type": "VAT_RATE",
                   "code": "STANDARD",
                   "percentage": "22.00",
                   "exclusive": "8.19672131",
                   "inclusive": "10.00",
                   "amount": "1.80327869"
               }
           ],
           "totals": {
               "vat": {
                   "amount": "1.80327869",
                   "exclusive": "8.19672131",
                   "inclusive": "10.00"
               }
           },
           "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"
           },
           "entries": [
               {
                   "type": "SALE",
                   "details": {
                       "concept": "GOOD"
                   },
                   "data": {
                       "type": "ITEM",
                       "text": "Product XYZ",
                       "unit": {
                           "quantity": "1",
                           "price": {
                               "inclusive": "100.01",
                               "exclusive": "81.97540984"
                           }
                       },
                       "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"
                       }
                   }
               }
           ],
           "breakdown": [
               {
                   "type": "VAT_RATE",
                   "code": "STANDARD",
                   "percentage": "22.00",
                   "exclusive": "0.00819672",
                   "inclusive": "0.01",
                   "amount": "0.00180328"
               }
           ],
           "totals": {
               "vat": {
                   "amount": "0.00180328",
                   "exclusive": "0.00819672",
                   "inclusive": "0.01"
               }
           },
           "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.

Nota*: i seguenti payload riflettono le modifiche alla struttura introdotte con la versione API 2026-06-01. Se stai integrando una versione precedente: sostituisci il campo totals.vat (a livello di operation) con il vecchio total_vat (a livello di document), rimuovi il campo breakdown e usa il formato semplice unit.price come stringa (solo inclusive, es. “price”: “100.00”) al posto dell’oggetto { inclusive, exclusive } mostrato qui.*

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": "{{intentionId}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-12345"
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Voucher XYZ",
                        "unit": {
                            "quantity": "1",
                            "price": {
                                "inclusive": "100.00",
                                "exclusive": "100.00"
                            }
                        },
                        "value": {
                            "base": "100.00"
                        },
                        "vat": {
                            "type": "VAT_EXEMPTION",
                            "code": "NOT_SUBJECT"
                        }
                    }
                }
            ],
            "breakdown": [
                {
                    "type": "VAT_EXEMPTION",
                    "code": "NOT_SUBJECT",
                    "exclusive": "100.00"
                }
            ],
            "totals": {
                "vat": {
                    "amount": "0.00",
                    "exclusive": "100.00",
                    "inclusive": "100.00"
                }
            },
            "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": "{{intentionId}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-123456"
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Product XYZ",
                        "unit": {
                            "quantity": "1",
                            "price": {
                                "inclusive": "100.00",
                                "exclusive": "81.96721311"
                            }
                        },
                        "value": {
                            "base": "81.96721311"
                        },
                        "vat": {
                            "type": "VAT_RATE",
                            "code": "STANDARD",
                            "percentage": "22.00",
                            "exclusive": "81.96721311",
                            "inclusive": "100.00",
                            "amount": "18.03278689"
                        }
                    }
                }
            ],
            "breakdown": [
                {
                    "type": "VAT_RATE",
                    "code": "STANDARD",
                    "percentage": "22.00",
                    "exclusive": "81.96721311",
                    "inclusive": "100.00",
                    "amount": "18.03278689"
                }
            ],
            "totals": {
                "vat": {
                    "amount": "18.03278689",
                    "exclusive": "81.96721311",
                    "inclusive": "100.00"
                }
            },
            "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": "{{intentionId}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-123456"
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Product XYZ",
                        "unit": {
                            "quantity": "1",
                            "price": {
                                "inclusive": "120.00",
                                "exclusive": "98.36065574"
                            }
                        },
                        "value": {
                            "base": "98.36065574"
                        },
                        "vat": {
                            "type": "VAT_RATE",
                            "code": "STANDARD",
                            "percentage": "22.00",
                            "exclusive": "98.36065574",
                            "inclusive": "120.00",
                            "amount": "21.63934426"
                        }
                    }
                }
            ],
            "breakdown": [
                {
                    "type": "VAT_RATE",
                    "code": "STANDARD",
                    "percentage": "22.00",
                    "exclusive": "98.36065574",
                    "inclusive": "120.00",
                    "amount": "21.63934426"
                }
            ],
            "totals": {
                "vat": {
                    "amount": "21.63934426",
                    "exclusive": "98.36065574",
                    "inclusive": "120.00"
                }
            },
            "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.

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/{{recordTransactionId}}**?compliance-artifact**

La risposta include il PDF come stringa codificata in Base64 in compliance.artifact.data. Una volta decodificato, il documento viene visualizzato nel formato originale A4.

Nota: Nell’ambiente TEST viene generato solo un PDF di esempio (vedi sotto), che non rispecchia i valori effettivamente inviati. I dati reali saranno visibili esclusivamente nell’ambiente LIVE.

Suggerimento: Se hai bisogno di convertirlo in formato 80mm per stampante termica, dovrai gestire la conversione autonomamente — alcuni integratori lo fanno tramite modelli AI (es. Claude).

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 il documento commerciale 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": "{{intentionId}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "INV-12345"
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "SERVICE"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Restaurant service",
                        "unit": {
                            "quantity": "1",
                            "price": {
                                "inclusive": "48.00",
                                "exclusive": "39.34426230"
                            }
                        },
                        "value": {
                            "base": "39.34426230",
                            "discount": "0.00"
                        },
                        "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": {
                                "inclusive": "2.00",
                                "exclusive": "2.00"
                            }
                        },
                        "value": {
                            "base": "2.00",
                            "discount": "0.00"
                        },
                        "vat": {
                            "type": "VAT_EXEMPTION",
                            "code": "NOT_SUBJECT"
                        }
                    }
                }
            ],
            "breakdown": [
                {
                    "type": "VAT_RATE",
                    "code": "STANDARD",
                    "percentage": "22.00",
                    "exclusive": "39.34426230",
                    "inclusive": "48.00",
                    "amount": "8.65573770"
                },
                {
                    "type": "VAT_EXEMPTION",
                    "code": "NOT_SUBJECT",
                    "exclusive": "2.00"
                }
            ],
            "totals": {
                "vat": {
                    "amount": "8.65573770",
                    "exclusive": "41.34426230",
                    "inclusive": "50.00"
                }
            },
            "customer": {
                "type": "EXTERNAL"
            },
            "payments": [
                {
                    "type": "CARD",
                    "details": {
                        "amount": "50.00"
                    },
                    "number": "****",
                    "kind": "CREDIT"
                }
            ]
        }
    }
}

Nota*: il payload qui sopra riflette le modifiche alla struttura introdotte con la versione API 2026-06-01. Se stai integrando una versione precedente: sostituisci il campo totals.vat (a livello di operation) con il vecchio total_vat (a livello di document), rimuovi il campo breakdown e usa il formato semplice unit.price come stringa (solo inclusive, es. “price”: “48.00”) al posto dell’oggetto { inclusive, exclusive } mostrato qui.*

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:

compliance.data: il numero progressivo (DCW-numero), generato dall’Agenzia delle Entrate e utilizzato per identificare univocamente il documento. Nota: se viene trasmesso un codice lotteria, questo viene aggiunto al numero progressivo, separato da una virgola. Esempio: “DCW2026/1234-0001,NB7A1235”
compliance.url: un link che consente al contribuente di visualizzare e scaricare il documento PDF emesso, dopo aver effettuato l’accesso con le proprie credenziali al portale “Fatture e Corrispettivi” dell’AdE. Nota: si tratta di un link privato che non deve essere condiviso con il cliente finale.

Nota: nell’ambiente di TEST, i valori compliance restituiti sono placeholder e non si riferiscono a un documento fiscale reale.

È possibile recuperare il PDF tramite API?

Sì. A partire dalla versione 2025-08-12 di SIGN IT API, il documento PDF ufficiale generato nel portale “Fatture e Corrispettivi” è disponibile tramite API in compliance.artifact, senza bisogno di accedere al portale. Per maggiori dettagli, consulta: 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").

{
    "content": {
        "type": "TRANSACTION",
        "record": {
            "id": "{{intentionId}}"
        },
        "operation": {
            "type": "RECEIPT",
            "document": {
                "number": "0001"
            },
            "entries": [
                {
                    "type": "SALE",
                    "details": {
                        "concept": "GOOD",
                        "purpose": "GIFT"
                    },
                    "data": {
                        "type": "ITEM",
                        "text": "Caffè",
                        "unit": {
                            "quantity": "1.00",
                            "price": {
                                "inclusive": "1.20",
                                "exclusive": "1.0909091"
                            }
                        },
                        "value": {
                            "base": "1.0909091",
                            "discount": "0.00"
                        },
                        "vat": {
                            "type": "VAT_RATE",
                            "code": "REDUCED_1",
                            "percentage": "10.00",
                            "exclusive": "1.0909091",
                            "inclusive": "1.20",
                            "amount": "0.10909091"
                        }
                    }
                }
            ],
            "breakdown": [
                {
                    "type": "VAT_RATE",
                    "code": "REDUCED_1",
                    "percentage": "10.00",
                    "exclusive": "1.0909091",
                    "inclusive": "1.20",
                    "amount": "0.10909091"
                }
            ],
            "totals": {
                "vat": {
                    "amount": "0.10909091",
                    "exclusive": "1.0909091",
                    "inclusive": "1.20"
                }
            },
            "payments": [
                {
                    "type": "CASH",
                    "details": {
                        "amount": "0.00"
                    }
                }
            ]
        }
    }
}

Nota*: l’esempio qui sopra riflette le modifiche alla struttura introdotte con la versione API 2026-06-01. Se stai integrando una versione precedente: usa il formato semplice unit.price come stringa (solo inclusive, es. “price”: “1.20”) al posto dell’oggetto { inclusive, exclusive } mostrato qui.*

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?

Questo articolo fornisce una mappatura dettagliata dei trattamenti IVA applicabili in Italia quando si utilizza SIGN IT.

`VAT_RATE`

`vat.code`	`vat.percentage`	Casi d’uso tipici
`STANDARD`	22%	Aliquota di default per tutto ciò che non è espressamente ridotto
`REDUCED_1`	10%	Turismo/ospitalità, ristorazione, lavori edili, energia domestica, alcuni alimenti e prodotti farmaceutici
`REDUCED_2`	5%	Alcuni servizi sociali/assistenziali, alcuni beni essenziali, opere d’arte
`REDUCED_3`	4%	Alimenti di prima necessità, libri e giornali, prima casa, ausili per disabili

Nota: Il valore del campo percentage viene pre-validato internamente insieme al valore del campo code. In caso di discrepanza tra il valore fornito e il valore atteso (es. “STANDARD” con “10%” anziché “22%”), il record ottiene lo stato “REJECTED” con un errore di validazione. Esempio: Validation error: invalid entries. Reasons: invalid rate percentage '10.00%' for code STANDARD, expected '22.00%'

VAT_EXEMPTION

`vat.code`	Codice Natura	Natura operazione
`CAUSE_1`	N1	Escluse ex art. 15 DPR 633/72
`NOT_SUBJECT`	N2	Non soggette
`NOT_TAXABLE`	N3	Non imponibili
`CAUSE_2`	N4	Esenti
`CAUSE_3`	N5	Regime del margine
`CAUSE_4`	N6	Altro non IVA

Nota: La procedura web “Documento Commerciale Online” dell’AdE su cui si basa SIGN IT lite accetta esclusivamente i codici Natura generici (N1, N2, N3, N4, N5, N6) e non supporta i sotto-codici (N2.1, N2.2, N3.1, ecc.). Per ogni entry con VAT_EXEMPTION dovrà pertanto essere indicato il codice Natura generico di riferimento (es. N2, N3).

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"
    }
]

Se il kind della carta non è noto, è possibile utilizzare CREDIT o DEBIT come valore predefinito. La distinzione non ha rilevanza fiscale: l’AdE registra entrambi semplicemente come pagamento con strumenti elettronici.

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.

Organizations (1)

Come aggiungere un ulteriore livello alla tua struttura

Quale versione dell’API SIGN IT stai usando?

Da SIGN IT 2026-02-03 in poi, la struttura è: Organization::ACCOUNT → Organization::GROUP (obbligatorio) → Organization::UNIT.

Fino a SIGN IT 2025-08-12, la struttura è: Asset::TENANT → Asset::GROUP (opzionale) → Asset::UNIT.

Scorri fino alla sezione che corrisponde alla tua integrazione.

Da SIGN IT 2026-02-03 in poi Di default, la tua integrazione richiede il tuo Organization::ACCOUNT e un Organization::GROUP (obbligatorio) — entrambi creati tramite la fiskaly HUB — e Organization::UNIT che rappresentano ciascuno dei tuoi clienti, creati tramite l’API SIGN IT.

Nella maggior parte dei casi, un singolo Group per Paese è sufficiente (ad es. se intendi supportare la fiscalizzazione in Italia e Francia, puoi creare un Organization::GROUP per l’Italia e uno per la Francia).

Tuttavia, se la tua organizzazione interna richiede un ulteriore livello di strutturazione all’interno di un Paese — ad esempio, separando i contribuenti per paese e poi ulteriormente per brand, regione o criteri simili — puoi aggiungere un livello aggiuntivo creando un sotto-gruppo (un Group annidato all’interno di un altro Group).

Account (organizzazione principale)
  |
  +-- Group ("Francia")
  |     |
  |     +-- Unit ("contribuente 1")
  |
  +-- Group ("Italia")
        |
        +-- Sub-group ("Brand A")
        |     |
        |     +-- Unit ("contribuente 2")
        |     +-- Unit ("contribuente 3")
        |
        +-- Sub-group ("Brand B")
              |
              +-- Unit ("contribuente 4")

**Nota: **Attualmente, i sotto-gruppi possono essere creati solo tramite API. Il supporto per crearli direttamente dalla fiskaly HUB potrebbe essere introdotto in futuri rilasci. Tuttavia, una volta creati, i sotto-gruppi sono già visibili nella HUB.

Importante: Una volta creata un’Organization, il suo posizionamento nella struttura non può più essere modificato. Ad esempio, una Unit creata direttamente sotto il Group principale non può essere spostato in un secondo momento sotto un Sub-group, e viceversa.

Guida passo-passo

Chiama createOrganization con type: GROUP, autenticandoti con il bearer token del Group principale (quello creato tramite la fiskaly HUB). L’ID del Group viene restituito in content.id

{
 "content": {
   "type": "GROUP",
   "name": "name-your-sub-group-here"
 }
}

Chiama createOrganization con type: UNIT, assicurandoti di impostare l’ID del Sub-Group (dal passaggio 1) come header X-Scope-Identifier. Questo garantisce che lo Unit venga creato direttamente sotto il Sub-group.

**Nota: **Se X-Scope-Identifier non viene fornito, l’Organization::UNIT viene creato direttamente sotto il Group principale (quello creato tramite la fiskaly HUB) per default, tramite il bearer token utilizzato.

Fino a SIGN IT 2025-08-12

Di default, la tua integrazione richiede solo la tua organizzazione principale (creata tramite la fiskaly dashboard) e degli Asset::UNIT che rappresentano ciascuno dei tuoi clienti (creati tramite l’API SIGN IT).

Se la tua struttura richiede maggiore flessibilità, puoi introdurre un livello intermedio opzionale, Asset::GROUP, per organizzare più Asset::UNIT in raggruppamenti logici.

Tenant (organizzazione principale)
  |
  +-- Group (livello opzionale)
  |     |
  |     +-- Unit ("contribuente 1")
  |     +-- Unit ("contribuente 2")
  |
  +-- Unit ("contribuente 3")
  |
  +-- Unit ("contribuente 4")

Importante: Una volta creato un Asset, il suo posizionamento nella struttura non può più essere modificato. Ad esempio, una Unit creata direttamente sotto l’organizzazione principale (Tenant) non può essere spostato in un secondo momento sotto un Group, e viceversa.

Guida passo-passo

Chiama createAsset con type: GROUP, autenticandoti con il bearer token dell’organizzazione principale (quella creata tramite la fiskaly Dashboard). L’ID del Group viene restituito in content.id

{
 "content": {
   "type": "GROUP",
   "name": "name-your-asset-group-here"
 }
}

Chiama createAsset con type: UNIT, assicurandoti di impostare l’ID dell’Asset::GROUP (dal passaggio 1) come header X-Scope-Identifier. Questo garantisce che lo Unit venga creato direttamente sotto il Group.

**Nota: **Se X-Scope-Identifier non viene fornito, l’Asset::UNIT viene annidato direttamente sotto l’organizzazione principale (Asset::TENANT) per default, tramite il bearer token utilizzato.

Per saperne di più sulla terminologia e sui cambiamenti di struttura tra le versioni, vedi: SIGN IT: Nuova terminologia delle risorse.