Integrazione Passo per Passo

⚠️ Stai visualizzando la documentazione per la versione API 2025-08-12. La versione più recente è 2026-05-04. Le modifiche principali includono una terminologia aggiornata (Asset → Organization, Entity → Taxpayer/Location).

Per iniziare il processo di integrazione, fare riferimento alle istruzioni dettagliate passo per passo fornite qui.

Il diagramma allegato illustra il flusso di lavoro e mette in evidenza i passaggi essenziali necessari per completare con successo l’integrazione, per la quale sarà necessario utilizzare la nostra SIGN IT.

Passaggio 1: Registrarsi sul Dashboard

Iniziare registrandosi sul Dashboard.

La creazione di un account fiskaly è il primo passaggio, dopo il quale è possibile procedere con la configurazione della prima struttura organizzativa per la propria attività e la generazione della chiave API.

📘video tutorial

Guarda il nostro video per una spiegazione passo per passo su come configurare l’account e la prima organizzazione.

Passaggio 2: Creare la prima organizzazione

Continuare creando la prima organizzazione tramite il Dashboard. Questa organizzazione rappresenterà il fornitore di POS o il rivenditore con il proprio sistema POS.

Passaggio 3: Creare una chiave API

Il passaggio successivo consiste nel generare una chiave API per la propria organizzazione tramite il Dashboard. Questa coppia chiave API e segreto è necessaria per creare il primo Asset di tipo UNIT (Passaggio 5).

Notare che le chiavi API generate nell’ambiente TEST creeranno risorse TEST, mentre quelle dell’ambiente LIVE creeranno risorse LIVE. Per ulteriori dettagli, fare riferimento all’articolo sugli ambienti TEST e LIVE.

A partire dal passaggio successivo, si utilizzerà l’API SIGN IT. È possibile scaricare la nostra collezione Postman per SIGN IT, che può facilitare l’integrazione nei passaggi successivi.

Passaggio 4: MANAGEMENT - Creare Token

Iniziare a utilizzare l’API SIGN IT tramite l’endpoint createToken. Sarà necessario creare un token per autenticarsi nei passaggi successivi.

Passaggio 5: MANAGEMENT - Creare Asset UNIT

Continuare creando un Asset di tipo UNIT tramite l’endpoint createAsset. Sarà necessario creare un Asset UNIT per ciascuna delle rappresentazioni dei contribuenti.

Quando si crea il primo Asset di tipo UNIT, assicurarsi che sia associato all’UUID della prima organizzazione creata tramite il Dashboard. Per farlo, utilizzare il token generato dalle chiavi API create nella prima organizzazione. Questo riflette la struttura gerarchica in cui il UNIT è annidato sotto la prima organizzazione.

Passaggio 6: MANAGEMENT - Creare Subject (Chiave API)

Creare un Subject di tipo API_KEY tramite l’endpoint createSubject. La connessione tra l’Asset UNIT e la chiave API viene stabilita tramite l’X-Scope-Identifier (utilizzando l’id dell’Asset appena creato).

Passaggio 7: MANAGEMENT - Creare nuovo Token

Successivamente, creare un token che verrà utilizzato per creare risorse all’interno dell’Asset UNIT corrispondente.

Passaggio 8: OPERATION - Creare Entity COMPANY o INDIVIDUAL

Ora si è pronti per iniziare a creare le parti operative necessarie per la fiscalizzazione in Italia. Per farlo, utilizzare l’endpoint createEntity per creare la rappresentazione di un Contribuente come segue:

• Sarà necessario impostare il Contribuente come Entity di tipo Company (persona giuridica) o Individual (persona fisica). In entrambi i casi, è necessario fornire name e address.
• All’interno delle informazioni fiscalization italiane, è necessario fornire i seguenti dati del contribuente:
  • tax_id_number: Codice Fiscale italiano,
  • vat_id_number: Partita IVA italiana,
  • credentials: pin e password necessari per accedere ai servizi di AdE. Per ulteriori informazioni, fare riferimento alla nostra sezione Credenziali.

Una volta creata una Entity, sia di tipo Company che Individual, il suo state verrà impostato su ACQUIRED. Affinché sia pienamente funzionale, lo stato deve essere aggiornato a COMMISSIONED utilizzando l’endpoint updateEntity.

📘Note

Solo le credenziali Fisconline sono valide per l’utilizzo di SIGN IT lite. Le credenziali devono essere aggiornate ogni 60 giorni.

📘importante

Il contribuente deve effettuare manualmente un primo accesso al portale web dell’Agenzia delle Entrate per garantire il corretto funzionamento delle credenziali e accettare i termini, le condizioni e le clausole aggiuntive fornite.

Passaggio 9: OPERATION - Creare Entity LOCATION

Per ciascuna sede operativa, è necessario creare una Entity di tipo Location tramite l’endpoint createEntity.

Quando si crea una Entity di tipo Location, il suo state viene inizialmente impostato su ACQUIRED. Per procedere, è necessario modificare lo stato in COMMISSIONED utilizzando l’endpoint updateEntity.

Passaggio 10: OPERATION - Creare System

L’endpoint createSystem consente di creare un’astrazione di ogni dispositivo utilizzato per emettere ricevute. Ciò significa che ogni registratore di cassa o punto vendita deve essere fornito come nuovo System nell’API SIGN IT. A tal fine, è necessario selezionare il tipo di Sistema FISCAL_DEVICE.

• Un System sarà connesso a una Entity già creata (sia essa di tipo Company o Individual, o una Location specifica se diversa dall’indirizzo legale).
• Per ogni dispositivo, sarà necessario fornire informazioni sul prodotto come MPN, marca e data di inizio utilizzo, insieme al nome e alla versione del software installato sul dispositivo. Queste informazioni garantiscono il corretto tracciamento del dispositivo che esegue le transazioni fiscali.

Quando si crea un System, il suo stato iniziale è impostato su ACQUIRED. Per creare Registrazioni, il suo state deve essere aggiornato a COMMISSIONED utilizzando l’endpoint updateSystem.

Passaggio 11: OPERATION - Creare Registrazione

💡Tip

La creazione di una Registrazione nell’API SIGN IT richiederà sempre due chiamate successive: Parte A) INTENTION (all’inizio del processo di vendita) e Parte B) TRANSACTION (direttamente dopo il processo di pagamento).

PARTE A) Intention

Per ogni operazione commerciale effettuata nel registratore di cassa o POS, l’endpoint createRecord dell’API SIGN IT verrà utilizzato in due chiamate: la prima per registrare l’intenzione di avviare una transazione, e la seconda per fornire i dati della transazione.

Una Registrazione di tipo Intention conterrà le seguenti informazioni:

• Associazione con un System che effettuerà la transazione.
• Operazione di tipo Transaction: Ciò significa che l’operazione che il System intende eseguire è la registrazione di una transazione.

Parte B) Transaction

Il passaggio finale per emettere una ricevuta conforme in Italia è effettuare un’altra chiamata all’endpoint createRecord, indicando una Registrazione di tipo Transaction.

Qualsiasi documento Transaction sarà associato all’identificatore interno di una Registrazione di tipo Intention già creata, e può contenere dettagli per scopi formativi (documenti emessi in modalità formativa o di test).

La Transaction può essere utilizzata per eseguire una delle seguenti operazioni in Italia:

• RECEIPT: Questa operazione contiene tutte le informazioni necessarie per la creazione di un Documento commerciale di vendita in Italia:
  • Informazioni sul documento come numero, codice attività (se applicabile), data della transazione e importi totali del documento (IVA inclusa ed esclusa)
  • Informazioni su ciascuna voce o riga articolo venduto nell’operazione:
    • Identificazione di una Vendita
    • Descrizione
    • Indicazione se si tratta di un bene o servizio
• CORRECTION: Questo tipo di operazione viene utilizzato per rappresentare qualsiasi processo di reso effettuato. Contiene gli stessi dati di un’operazione di tipo RECEIPT, e in aggiunta:
  • id di riferimento a una ricevuta già creata (documento di transazione originale)
• CANCELLATION: Questa operazione viene utilizzata per invalidare un’intera transazione. A tal fine, è necessario fornire l’id di una registrazione precedentemente creata.

In tutti i casi, una volta che la transazione è correttamente registrata e le informazioni del documento commerciale vengono trasmesse con successo al portale web di AdE, la risposta conforme della creazione della registrazione indicherà il numero progressivo assegnato da AdE al documento commerciale e il Codice Lotteria del consumatore (se fornito nel payload trasmesso).

📘Note

Tutte le registrazioni create nell’ambiente LIVE vengono trasmesse alle Autorità Fiscali e generano documenti commerciali validi. Pertanto, questi documenti devono sempre riflettere transazioni reali.