Integrazione Passo dopo Passo

⚠️ Stai visualizzando la documentazione per la versione API 2024-10-31. 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, consulta le istruzioni dettagliate passo dopo passo fornite qui.

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

Passaggio 1: Registrarsi sul Dashboard

Inizia registrandoti sul Dashboard.

La creazione di un account fiskaly è il primo passo, dopodiché puoi procedere con la configurazione della prima struttura organizzativa per la tua azienda e la generazione della chiave API.

📘video tutorial

Guarda il nostro video per una spiegazione passo dopo passo su come configurare il tuo account e la tua prima organizzazione.

Passaggio 2: Creare la prima organizzazione

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

Passaggio 3: Creare la chiave API

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

Tieni presente che le chiavi API generate nell’ambiente TEST creeranno risorse TEST, mentre quelle dell’ambiente LIVE creeranno risorse LIVE. Per ulteriori dettagli, consulta il nostro articolo sugli ambienti TEST e LIVE.

A partire dal passo successivo, utilizzerai la nostra API SIGN IT. Puoi scaricare la nostra collezione Postman per SIGN IT, che potrebbe facilitare la tua integrazione nei passaggi successivi.

Passaggio 4: MANAGEMENT - Creare Token

Inizia a utilizzare l’API SIGN IT tramite l’endpoint createToken. Dovrai creare un token per autenticarti nei passaggi successivi.

Passaggio 5: MANAGEMENT - Creare Asset UNIT

Continua creando un Asset di tipo UNIT tramite l’endpoint createAsset. Dovrai creare un Asset UNIT per ciascuna delle tue rappresentazioni di contribuente.

Quando crei il tuo primo Asset di tipo UNIT, assicurati che sia associato all’UUID della prima organizzazione che hai creato tramite il Dashboard. Per farlo, utilizza il token generato dalle chiavi API create nella prima organizzazione. Questo riflette la struttura gerarchica in cui la UNIT è annidata sotto la prima organizzazione.

Passaggio 6: MANAGEMENT - Creare Subject (Chiave API)

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

Passaggio 7: MANAGEMENT - Creare nuovo Token

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

Passaggio 8: OPERATION - Creare Entity COMPANY o INDIVIDUAL

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

• Dovrai impostare il Contribuente come Entity di tipo Company (entità giuridica) o Individual (persona fisica). In entrambi i casi, devono essere forniti name e address.
• All’interno delle informazioni di fiscalization italiane, devono essere forniti 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 dell’AdE. Per ulteriori informazioni, consulta la nostra sezione Credenziali.

Una volta creata una Entity di tipo Company o Individual, il suo state verrà impostato su ACQUIRED. Per essere 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.

📘important

Il contribuente deve effettuare manualmente un primo accesso al portale web dell’Agenzia delle Entrate per verificare che le credenziali funzionino correttamente e per accettare i termini, le condizioni e le clausole aggiuntive previste.

Passaggio 9: OPERATION - Creare Entity LOCATION

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

Quando crei una Entity di tipo Location, il suo state è inizialmente impostato su ACQUIRED. Per procedere, devi cambiare lo stato a 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. Per questo, deve essere selezionato il tipo di System FISCAL_DEVICE.

• Un System verrà connesso a una Entity già creata (che sia di tipo Company o Individual, o una specifica Location 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 monitoraggio di quale dispositivo esegue le transazioni fiscali.

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

Passaggio 11: OPERATION - Creare Record

💡Tip

La creazione di un Record nell’API SIGN IT richiederà sempre due chiamate successive: Parte A) INTENTION (subito 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 nel 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.

Un Record di tipo Intention conterrà le seguenti informazioni:

• Associazione a 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 un Record di tipo Transaction.

Qualsiasi documento Transaction verrà associato all’identificatore interno di un Record di tipo Intention già creato, e può contenere dettagli per scopi di formazione (documenti emessi in modalità di addestramento o test).

La Transaction può essere utilizzata per effettuare 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 (comprensivi ed esclusivi di IVA)
  • Informazioni di ciascuna voce o riga articolo venduta 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 annullare un’intera transazione. Per questo, è necessario fornire l’id di un record creato in precedenza.

In tutti i casi, una volta che la transazione è correttamente registrata e le informazioni del documento commerciale sono state trasmesse con successo al portale web dell’AdE, la risposta conforme alla creazione del record indicherà il numero progressivo assegnato dall’AdE al documento commerciale e il Codice Lotteria del consumatore (se fornito nel payload trasmesso).

📘Note

Tutti i record creati nell’ambiente LIVE vengono trasmessi alle Autorità Fiscali e generano documenti commerciali validi. Pertanto, questi documenti devono sempre riflettere transazioni reali.