Panoramica delle fasi necessarie per la messa in servizio di un client:

1. Creazione della struttura organizzativa
2. Configurazione
3. Stabilimento della connessione al Cloud
4. Inizializzazione del client

1. Creazione della struttura organizzativa

Come primo passo verso la messa in funzione, è necessario creare la struttura organizzativa dell’azienda che gestisce i registratori di cassa nel RetailForce Cloud. Potete trovare ulteriori dettagli al riguardo nell’articolo collegato.

Tale passaggio può essere omesso per i sistemi che devono operare completamente offline e che non stabiliscono in alcun momento una connessione con il RetailForce Cloud.

2. Configurazione

La configurazione di un client di middleware può essere effettuata fondamentalmente in due modi diversi (a seconda delle impostazioni e degli accordi stipulati dal produttore del software per registratori di cassa e dalla società che gestisce i registratori di cassa):

1. Configurazione tramite RetailForce Cloud, oppure
2. Configurazione tramite software POS (sistema di cassa, sistema di registrazione elettronica)

1. Configurazione tramite RetailForce Cloud

In questa variante, il client scarica localmente un oggetto di configurazione predisposto nel RetailForce Cloud. Tale approccio può essere considerato una configurazione automatica. La creazione degli oggetti di configurazione è descritta nell’articolo collegato.

Quando si configura un’unità fiscale tramite il cloud, tutti i dati richiesti dal sistema sono già preconfigurati nel cloud (istruzioni e informazioni generali sulla creazione di una configurazione). Tali dati vengono recuperati dal cloud tramite una chiamata dal client fiscale (CreateClientByCloud).

I parametri per la chiamata sono:

• Identificativo aziendale (companyIdentification), solitamente il numero di partita IVA (VatNumber). A seconda del paese di riferimento fiscale, potrebbe essere necessario inserire in alternativa o in aggiunta altre caratteristiche identificative (!). Tuttavia, per la fase iniziale si raccomanda l’utilizzo del numero di partita IVA.
• Numero del punto vendita / della filiale
• Numero del registratore di cassa
• cloudApiKey
• cloudApiSecret

Se l’endpoint PUT api/v1/management/clients/byCloud viene eseguito senza errori, la configurazione del cliente fiscale è completata. Il GUID del modulo fiscale (=clientId) viene restituito come valore di ritorno.

2. Configurazione tramite software POS

In alternativa alla configurazione automatica del client tramite il RetailForce Cloud system, l’oggetto di configurazione può essere preparato anche dal software POS. Tale modalità di configurazione viene adottata per i sistemi privi di connettività verso RetailForce Cloud. A tal fine si utilizza l’endpoint PUT /api/v1/management/clients.

Durante la configurazione del software del registratore di cassa, sono disponibili due modalità per avviare correttamente il modulo:

1. Modulo senza connessione al Cloud con archiviazione ed esportazione dei dati in locale
2. Modulo con connessione al Cloud, con archiviazione ed esportazione dei dati sia in locale che nel Cloud

In ogni caso, è necessario che i parametri di configurazione richiesti siano impostati correttamente secondo la documentazione.

La variante 2 (con connessione al Cloud) può essere attivata anche in un secondo momento, ovvero è possibile creare una configurazione fiscale senza connessione al Cloud e successivamente sincronizzarla con il Cloud.

Si noti che la creazione di un client nel cloud deve essere abilitata dal produttore del software POS e/o dall’organizzazione nelle impostazioni del cloud. La procedura standard prevede di creare innanzitutto un oggetto di configurazione nel cloud.

3. Stabilire la connessione al Cloud

Il passo successivo consiste nel collegare il client al RetailForce Cloud (per i sistemi offline, privi di connessione al cloud, questo passaggio può essere saltato). Ciò avviene tramite la funzione:

• POST /api/v1/management/cloud/connect .

Parametri per la chiamata:

• clientId – l’ID cliente univoco (GUID) restituito al registratore di cassa al momento della configurazione tramite RetailForce Cloud.
• cloudApiKey
• cloudApiSecret

4. Inizializzazione del client

Richiamando la funzione InitializeClient (POST /api/v1/management/clients/initialize), con il parametro (documento di avvio), viene richiamata la routine di inizializzazione del rispettivo Paese; in questo processo vengono inizializzati anche eventuali componenti di sicurezza (se necessario).
Per argomenti specifici relativi al Paese e/o all’hardware, si prega di fare riferimento alla documentazione pertinente.

Il documento iniziale può essere richiesto al servizio eseguendo la funzione:

• GET /api/v1/transactions/document/{clientId}/start
  (parametro: clientId, opzionale: BookDate).

Se FiscalClient viene utilizzato senza fiscalizzazione (NoFiscalisation), ad esempio qualora al client vengano trasmesse solo ricevute digitali o dati di archivio, l’inizializzazione non è necessaria.

• Chiamata della funzione di inizializzazione (InitializeClient - POST /api/v1/management/clients/initialize)

L’inizializzazione dell’unità fiscale viene quindi eseguita tramite la chiamata InitializeClient.

Alla funzione InitializeClient viene passato un NullReceipt; di seguito è riportato un esempio:

{
    "modelVersion": "1.5.2",
    "uniqueClientId": "c1062c55-57c4-4ed2-9c53-aff1762326a4",
    "additionalFields": {},
    "documentGuid": "5efa5306-fe53-452d-9c81-68329475eee0",
    "documentId": "1",
    "createDate": "2025-05-02T07:08:17.8334419+02:00",
    "bookDate": "2025-05-02T07:08:17.8335535+02:00",
    "documentNumber": "1",
    "documentType": 1000,
    "documentTypeCaption": "Startbeleg",
    "user": {
        "id": "1",
        "caption": "User 1",
        "firstName": "1",
        "lastName": "User",
        "dateOfEntry": "2025-05-02T07:08:17.833596+02:00"
    },
    "allocationGroups": [],
    "positionCount": 0,
    "fiscalDocumentNumber": 1,            
    "fiscalDocumentRevision": 1,          
    "positions": [],
    "Payments": [],
    "additionalHeader": [],
    "additionalFooter": [],
    "fiscalAdditionalFields": {}
}

Il processo di inizializzazione è fondamentalmente specifico per ogni paese, ma la chiamata rimane la stessa per tutti i paesi. Per i dettagli sulle inizializzazioni specifiche per paese, si prega di fare riferimento alla documentazione relativa al paese in questione.

Panoramica sulla messa in servizio

Per mettere in servizio un client vengono richiamate le seguenti funzioni nell’ordine indicato:

Articoli correlati

Inizializzazione in Germania

Gestione degli errori

Errore: GetConfiguration per il client <clientid> non trovato</clientid>

Questo articolo è stato tradotto automaticamente.