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 dell 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, consultare il nostro articolo sull'ambiente TEST e LIVE.

Step 4: MANAGEMENT - Crea token

Iniziare a utilizzare l'API SIGN IT attraverso l'endpoint createToken. In seguito, sarà necessario creare un token per autenticarsi per ogni operazione.

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

Continua creando un asset di tipo UNIT attraverso l'endpoint createAsset. È necessario creare una risorsa UNIT per ciascuna delle rappresentazioni degli esercenti.

Quando create il primo Assetdi tipo UNIT, assicuratevi che sia associato all' UUID della Main Organization creata in precedenza tramite il Cruscotto. Per questo motivo, è necessario utilizzare il token generato dalle chiavi API create nella Main Organization. Questo riflette la struttura gerarchica dove la UNIT appartiene alla Main Organization.

Step 6: MANAGEMENT - Crea un Subject

Crea un subject del tipo API_KEY attraverso l’endpoint createSubjectc. La connessione tra l’Asset Unit e la chiave API è stabilita dallo 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 entità (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'entità di tipo Società (impresa) o Individuo (lavoratore autonomo). In ogni caso, è necessario indicare la legal entity (ragione sociale) e legal address(indirizzo legale).
• Nell'ambito delle informazioni richieste dalla legge italiana, devono essere forniti i seguenti dati dei contribuenti:
  • tax_id_number: il Codice fiscale,
  • vat_id_number: Numero di Partita IVA,
  • credentials: pin e password necessarie per accedere ai servizi di Ade. Per ulteriori informazioni, consultare la sezione Credenziali.

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 una location entity

Per ogni business location operativa deve essere introdotto l'entity type Location attraverso l’endpoint CreateEntity.

Step 10: OPERAZIONE - Crea un sistema (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 Azienda o Individuo, 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.

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 acquisto
• Parte B) Transazione (Transaction) - 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 sistema che eseguirà una transazione
• Tipo di operazione Transazione: significa che l'operazione che il sistema intende eseguire è la registrazione di una transazione.
• Le informazioni dettagliate, se applicabili, se si tratta di un record ditraining (a scopo di test e istruttivo) e la possibilità di indicare le informazioni della persona che esegue l'operazione.

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 tipo di record 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 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 ogni voce o articolo venduto:
    • Identificazione di una vendita
    • 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 tipo RECEIPT e in più:

  • 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 ogni caso, una volta che la transazione è stata correttamente registrata e le informazioni sul documento commerciale sono state trasmesse con successo al portale web di AdE, la risposta conforme 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).