Integrazione step-by-step

Per iniziare l'integrazione, consulta le istruzioni dettagliate passo-passo fornite qui.

Il diagramma di accompagnamento illustra il flusso di lavoro ed evidenzia i passaggi essenziali necessari per completare con successo l'integrazione, per la quale è necessario utilizzare la nostra API SIGN IT.

Step 1: Registrati

Inizia registrandoti sulla Dashboard.

La creazione di un account fiskaly è il primo passo, dopodiché si può procedere con l'impostazione della prima struttura organizzativa per la propria azienda e la richiesta della chiave API.

video tutorial

Guarda il nostro video che spiega passo dopo passo come configurare il proprio account e la prima organizzazione.

Step 2: Crea la prima organizzazione

Continua creando la prima organizzazione utilizzando la Dashboard. Questa organizzazione rappresenterà il fornitore di software di cassa o l'esercente che ha sviluppato il proprio sistema di cassa.

Step 3: Genera la chiave API

Il passo successivo consiste nel generare una chiave API per la propria organizzazione tramite la Dashboard. Questa coppia di chiavi API (Chiave API e Chiave API Segreta) è necessaria per generare il primo Asset di tipo UNIT (Step 5).

Si noti 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 sull'ambiente TEST e LIVE.

A partire dallo step successivo, dovrai utilizzare la nostra API SIGN IT. Puoi scaricare la collezione Postman per SIGN IT, che potrebbe semplificare l'integrazione nelle fasi successive.

Step 4: MANAGEMENT - Crea token

Inizia a utilizzare l'API SIGN IT tramite l'endpoint createToken. Sarà necessario creare un token per autenticarsi negli step successivi.

Step 5: MANAGEMENT - Crea un Asset (Struttura organizzativa)

Prosegui creando un Asset di tipo UNIT tramite l'endpoint createAsset. Dovrai creare una risorsa Asset UNIT per ciascuna entità fiscale rappresentata (esercente).

Durante la creazione del primo Asset di tipo UNIT, assicurati di associarlo allo UUID della prima organizzazione precedentemente creata tramite la Dashboard. Per farlo, è necessario utilizzare il token generato a partire dalle chiavi API create per la prima organizzazione. Questo rispecchia la struttura gerarchica, in cui l'Asset UNIT appartiene alla prima organizzazione.

Step 6: MANAGEMENT - Crea un Subject

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

Step 7: MANAGEMENT - Crea un nuovo token

In seguito, crea un token che sarà utilizzato per creare le risorse all’interno dell’Asset UNIT corrispondente.

Step 8: OPERAZIONE - Crea un'Entity (Rappresentazione di un esercente)

Ora puoi iniziare a creare le parti operative necessarie per la fiscalità in Italia. Per farlo, utilizza l'endpoint createEntity per creare la rappresentazione di un esercente come segue:

• È necessario impostare il contribuente come un'Entity (entità) di tipo COMPANY (Società) o INDIVIDUAL (Persona fisica). In entrambi i casi, è necessario indicare il name (ragione sociale) e address(indirizzo legale).
• Nell'ambito delle informazioni fiscali richieste dalla legge italiana (fiscalization), devono essere forniti i seguenti dati dei contribuenti:
  • tax_id_number: Codice Fiscale
  • vat_id_number: Partita IVA
  • credentials: pin e password necessarie per accedere ai servizi dell'Agenzia delle Entrate. Per ulteriori informazioni, consulta la sezione Credenziali

Una volta creata un'Entity, di tipo Company o Individual, il suo state sarà ACQUIRED. Per essere funzionante, lo stato deve essere cambiato in COMMISSIONED tramite 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 verificare che le credenziali funzionino correttamente e per accettare i termini, le condizioni e le clausole aggiuntive previste.

Step 9: OPERAZIONE - Crea un'Entity Location

Per ciascuna sede operativa dell'attività, è necessario creare un'Entity di tipo Location tramite l’endpoint createEntity.

Una volta creata un'Entity di tipo Location, il suo state sarà ACQUIRED. Per poter procedere, lo stato deve essere cambiato in COMMISSIONED tramite l'endpoint updateEntity.

Step 10: OPERAZIONE - Crea un System (Rappresentazione di una cassa)

L’endpoint createSystem consente di creare un'astrazione di ogni dispositivo utilizzato per emettere documenti commerciali. Ciò significa che ogni registratore di cassa o punto vendita deve essere indicato come un nuovo System (sistema) nell'API SIGN IT. A tal fine, è necessario selezionare il tipo di sistema: FISCAL_DEVICE.

• Un sistema sarà collegato a un'entità già creata (sia essa di tipo Company o Individual, o una sede specifica se diversa dall'indirizzo legale).
• Per ogni dispositivo, è necessario fornire informazioni sul prodotto, come MPN, marca e data di inizio dell'utilizzo, nonché nome e versione del software installato sul dispositivo. Queste informazioni consentono di tracciare correttamente il dispositivo che esegue le transazioni fiscali.

Quando viene creato un System, il suo stato iniziale sarà ACQUIRED. Per poter creare dei Record, il suo state deve essere cambiato in COMMISSIONED tramite l'endpoint updateSystem.

Step 11: OPERAZIONE - Crea un Record

suggerimento

La creazione di un Record nell'API SIGN IT richiede sempre due chiamate consecutive:

• Parte A) INTENTION (Intenzione) - all'inizio del processo di vendita
• Parte B) TRANSACTION (Transazione) - al termine del processo di pagamento

Parte A) Intenzione

Per ogni operazione commerciale effettuata sul registratore di cassa, l'uso dell'endpoint createRecord di SIGN IT API sarà utilizzato in due chiamate: una prima chiamata per registrare l'intenzione di avviare una transazione, e una seconda chiamata in cui si forniscono i dati della transazione.

Un Record di tipo Intenzione contiene le seguenti informazioni:

• Associazione a un System (sistema) che eseguirà una transazione
• Tipo di operazione TRANSACTION: significa che l'operazione che il sistema intende eseguire è la registrazione di una transazione.

Parte B) Transazione

L'ultimo passo per emettere una scontrino conforme in Italia è quello di effettuare una chiamata all'endpoint createRecord indicando un record di tipo Transazione.

Ogni documento di tipo Transazione sarà associato all'identificativo interno creato per il Record di tipo Intenzione e potrà contenere dettagli a scopo formativo (documenti emessi in modalità training o test).

La Transazione 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/prestazione:
  • Informazioni sul documento come numero, codice attività (se applicabile), data della transazione e importi totali del documento (IVA inclusa ed esclusa).
  • Informazioni su ogni voce o articolo venduto:
    • Identificazione di una vendita/prestazione
    • Descrizione
    • Indicazione se si tratta di un bene o di un 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, oltre a:
  • id di riferimento di uno scontrino già creato (documento commerciale originale)
• CANCELLATION: questa operazione viene utilizzata per annullare un'intera transazione. A tal fine, è necessario fornire l'id di un Record creato in precedenza.

In tutti i casi, una volta che la transazione è stata correttamente registrata e le informazioni del documento commerciale sono state trasmesse con successo al portale web dell'Agenzia delle Entrate, la risposta conforme generata al momento della creazione del Record riporterà il numero progressivo assegnato da AdE al documento commerciale e il codice lotteria del consumatore (se fornito nel payload trasmesso).

attenzione

Tutti i dati inseriti nell'ambiente LIVE vengono trasmessi alle autorità fiscali e generano documenti commerciali ufficiali. Per questo motivo, tali documenti devono sempre corrispondere a transazioni realmente avvenute.