Vai al contenuto principale

Linee guida per l’implementazione

Harald Krondorfer
  • Aggiornato

RetailForce sviluppa software per garantire la conformità alle normative relative alla fiscalizzazione dei sistemi di registrazione elettronica in diversi paesi. Questo software è denominato «Fiscal Middleware».

Il presente documento fornisce una panoramica su come integrare il RetailForce Middleware. L’architettura del sistema a monte che invia e riceve dati dal RetailForce Middleware, nonché i requisiti e le funzioni specifiche di tale sistema, potrebbero rendere necessario discostarsi dalla presente descrizione.

1. Nozioni di base

Di seguito sono elencati i singoli passaggi da eseguire prima di avviare l’integrazione. Tali passaggi vengono inoltre illustrati in dettaglio durante la sessione di onboarding.

1.1 Panoramica delle varianti di integrazione

Prima di procedere con l’integrazione, si consiglia di acquisire una visione d’insieme delle diverse varianti di integrazione disponibili. Tali varianti sono descritte nel seguente articolo: Panoramica sulla fiscalizzazione con RetailForce – RetailForce Software GmbH (= articolo di panoramica).

Nell’articolo collegato sono inoltre riportate le fonti da cui è possibile scaricare il RetailForce Middleware nelle diverse varianti.

Dopo aver scaricato il Fiscal Middleware, proceda all’installazione. Una descrizione delle modalità di installazione delle diverse varianti è disponibile nell’articolo di panoramica.

1.1.1 Online vs. Offline

Il RetailForce Fiscal Middleware è fondamentalmente un sistema software autonomo. Tuttavia, diverse funzioni sono disponibili solo quando il middleware è connesso al RetailForce Cloud.

Il RetailForce Cloud fornisce diverse funzioni di gestione, quali la configurazione automatica da remoto del middleware, compresa l’assegnazione delle licenze, nonché funzioni di archiviazione sicura a lungo termine.

Per poter utilizzare le funzioni del RetailForce Cloud, il Fiscal Middleware o il client specifico all’interno dell’installazione (client = singola istanza del sistema di registrazione elettronica) deve essere collegato a un terminal nel RetailForce Cloud.

Se si intende utilizzare il middleware senza stabilire una connessione al Cloud (sistema offline), è possibile saltare i passaggi seguenti. Proseguire con il punto 1.5.

Nota: si consiglia di stabilire una connessione al Cloud (= sistema online), poiché ciò semplifica notevolmente la messa in servizio di un client e consente l’automazione nell’inizializzazione dell’hardware necessario.

1.2 Accesso al RetailForce Portal

Tutte le funzioni del RetailForce Cloud sono accessibili tramite

Per motivi di sicurezza, non è consentita l’autenticazione autonoma al RetailForce Portal. Per ottenere l’accesso, è necessario ricevere un link di invito da un utente già autorizzato. La procedura di onboarding successiva è descritta nell’articolo seguente: Registrazione nel RetailForce Portal – RetailForce Software GmbH.

1.3 Struttura organizzativa

È necessario innanzitutto creare una struttura organizzativa nel portale. L’articolo Creazione della struttura organizzativa in RetailForce Cloud – RetailForce Software GmbH fornisce una panoramica delle funzioni disponibili a tale scopo.

1.4 Configurazione

Dopo aver creato la struttura organizzativa, almeno un’organizzazione (= cliente), un punto vendita (= filiale) e un terminal (= cassa), è necessario preparare un oggetto di configurazione nel Cloud e assegnarlo a un’entità (organizzazione, azienda, punto vendita o terminale). È possibile trovare una descrizione di questa procedura alla voce: Informazioni generali sulla configurazione – RetailForce Software GmbH.

1.5 Inizializzazione

Se i passaggi precedenti sono stati eseguiti con successo, è possibile mettere in funzione il Fiscal Middleware. I passaggi necessari per la messa in funzione (con e senza stabilimento della connessione al cloud) sono spiegati in modo più dettagliato nell’articolo Inizializzazione (informazioni generali) – RetailForce Software GmbH.

Nota: si prega di tenere presente che nell’articolo sopra citato vengono descritti nuovamente anche i processi «Creazione della struttura organizzativa » e «Creazione della configurazione ».

A seguito del processo di messa in funzione/inizializzazione, il Fiscal Client dovrebbe

  • essere completamente configurato,
    • sia tramite un oggetto di configurazione predisposto nel Cloud, sia
    • «manualmente» dal sistema di registrazione elettronica,
  • e disporre di un ID Cliente univoco.

2. Integrazione

Una volta completata con successo la messa in servizio di un client («registratore di cassa»), è possibile avviare l’integrazione.

La presente sezione fornisce indicazioni sul processo di trasferimento dei documenti tra il registratore di cassa (sistema di registrazione elettronica) e il client specifico.

2.1 Servizio web REST

Il seguente articolo fornisce indicazioni per iniziare l’integrazione dell’interfaccia del servizio web REST, utilizzata sia per

  • sia il servizio Windows che
  • il container Docker.

Primi passi con il servizio fiscale – RetailForce Software GmbH

2.2 Implementazione NuGet

Per assistenza nell’implementazione NuGet (DLL) del middleware, si rimanda al seguente articolo: Primi passi nell’implementazione NuGet – RetailForce Software GmbH.

2.3 Interfaccia del file system

Oltre alle due varianti di implementazione sopra menzionate, ovvero il servizio web REST e NuGet, è possibile accedere al middleware anche tramite un’interfaccia file. Per ulteriori informazioni al riguardo, si rimanda all’articolo: Interfaccia del file system – RetailForce Software GmbH.

Nota: si prega di tenere presente che l’interfaccia file non è disponibile in tutti i paesi! Inoltre, si consiglia di utilizzare l’interfaccia file solo qualora, per motivi tecnici, non fosse possibile l’implementazione tramite servizio web REST e nuget.

2.4 Processo di trasmissione dei documenti

Una volta installato il Fiscal Middleware su un computer, in forma analoga a un servizio Windows, è possibile accedere alla descrizione dell’API all’indirizzo http://localhost:7678/swagger/index.html.

In caso di installazione su un host remoto (ad es. in rete LAN), utilizzare l’indirizzo IP del sistema su cui è stato installato il middleware al posto di «localhost».

Tutti gli endpoint del middleware sono documentati in Swagger. Per la trasmissione dei documenti (ad es. le ricevute di cassa) sono rilevanti gli endpoint della sezione «Transazioni».

La trasmissione dei documenti avviene sempre tramite un processo a due fasi, avviato con

  1. "createDocument" e si conclude con
  2. "storeDocument" oppure con "cancelDocument", in caso di annullamento del documento.

API-transactions.png

Il processo di trasmissione dei documenti è illustrato in dettaglio nella sezione: Processo di base per il trasferimento dei documenti – RetailForce Software GmbH.

2.5 Fiscal Service Client Sample

RetailForce mette a disposizione un programma di esempio, denominato «Fiscal Service Client Sample». Esso fornisce indicazioni su come creare la struttura JSON con cui i documenti vengono inviati al servizio fiscale.

Il Fiscal Service Client Sample può essere utilizzato per generare esempi di diversi tipi di documenti e casi aziendali.

Una descrizione del programma è disponibile all’indirizzo: Fiscal Service Client Sample – RetailForce Software GmbH.

Esempi di documenti e casi d’uso sono inoltre disponibili nel Solution Center, alla pagina: Transazioni commerciali – RetailForce Software GmbH.

Nota: si prega di tenere presente che i casi d’uso qui elencati potrebbero basarsi su un modello di documento precedente. Si raccomanda l’utilizzo del Fiscal Service Client Sample.

2.6 Elenco degli endpoint

Di seguito vengono descritti gli endpoint che devono essere implementati in ogni caso.

Endpoint Descrizione
PUT /api/va/management/clients necessario solo se la configurazione del client deve essere effettuata dal software POS e non dal sistema Cloud. Alternativa: PUT /api/v1/management/clients/byCloud
PUT /api/v1/management/clients/byCloud necessario se la configurazione del client deve essere effettuata dal sistema cloud. Alternativa: PUT /api/va/management/clients
POST /api/v1/management/cloud/connect stabilisce la connessione cloud di un client. Deve essere eseguito dopo ogni riavvio del computer (sistema). I dati necessari per stabilire la connessione cloud (API Key e API Secret) devono essere memorizzati dal sistema di registrazione elettronica.
POST /api/v1/management/clients/initialize Inizializza il client o qualsiasi hardware fiscale necessario (dispositivo tecnico di sicurezza, unità di creazione della firma, stampante, ecc.). Per l’inizializzazione è necessario un documento di avvio. Questo può essere generato dal sistema di registrazione elettronica oppure automaticamente tramite il middleware con l’endpoint GET /api/v1/transactions/document/{clientId}/start.
GET /api/v1/transactions/document/{clientId}/start Consigliato. Crea un cosiddetto documento di avvio per il client specifico, ai fini dell’inizializzazione.
PUT /api/v1/transactions/createDocument Questo metodo non genera direttamente un documento, ma avvia il processo, ad esempio sul TSE (Dispositivo Tecnico di Sicurezza) in Germania. (Obbligatorio in ogni paese!)
POST /api/v1/transactions/storeDocument Salva il documento corrispondente
POST /api/v1/transactions/cancelDocument Annulla un documento sull’unità di fiscalizzazione.

 

 

Questo articolo è stato tradotto automaticamente.

Articoli correlati

Commenti

0 commenti

Accedi per aggiungere un commento.

Powered by Zendesk