Vai al contenuto principale

Interfaccia del file system

DEVELOPMENT
  • Aggiornato

Il presente articolo illustra come utilizzare l’interfaccia file del servizio fiscale.

Prerequisiti

  • FiskalClient a partire dalla versione 1.2.11
  • FiscalClient come servizio (le implementazioni nuget non sono supportate)

Paesi supportati

Attualmente, tramite l’interfaccia file sono supportati solo i paesi elencati di seguito:

  • Austria
  • Danimarca (a partire dalla versione 1.3)

Ulteriori informazioni

L’interfaccia file supporta solo una parte molto limitata delle funzionalità del client fiscale per la trasmissione dei dati necessari alla fiscalizzazione. Qualora si desiderino comandi più specifici, è comunque possibile integrare il servizio con strumenti quali CURL tramite l’interfaccia REST. Tuttavia, tale aspetto non viene trattato nel presente articolo.

Attivazione

L’interfaccia del file system può essere abilitata come segue:

  • Impostando il percorso di monitoraggio nel file appsettings.json.
  • Creando una directory in C:\ProgramData\RetailForce\Fiscal web service con il nome "fileSystemInterface".

Attenzione: per attivare il sistema, è necessario riavviare il servizio dopo aver effettuato queste impostazioni.

appsettings.json

"AppSettings": {
  ...,
  "FileSystemInterfacePath": "c:/temp/filesysteminterface",
  ...
}

Le voci che precedono e seguono non sono incluse nell’esempio. "c:\temp\filesysteminterface" è il percorso monitorato.

Nota: la cartella monitorata deve essere una cartella locale. Le unità di rete non sono supportate, poiché in questi casi i sistemi di monitoraggio dei file spesso non funzionano in modo affidabile.

Funzionamento

L’interfaccia file del servizio fiscale monitora una directory alla ricerca di nuovi file con una determinata struttura di denominazione. Non appena in questa directory viene creato un nuovo file conforme alle convenzioni di denominazione, esso viene elaborato.

Attenzione: per i file di grandi dimensioni, si consiglia di salvare innanzitutto il file nella directory come file temporaneo e successivamente rinominarlo con il nome corretto utilizzando il comando RENAME.

Procedura

La procedura è la seguente:

  1. Il file viene trasferito nella directory e riconosciuto (*.request)
  2. Il file viene elaborato
  3. Il file *.response o *.error viene salvato nella directory "response" (sottodirectory della directory di importazione) con lo stesso nome del file prima dell’estensione.

Esempio

  1. Viene trasferito il file 20220308135010236.document.request
  2. Il file è in fase di elaborazione
  3. Il file response/20220308135010236.document.response è stato salvato. 

oppure, in caso di errore

  1. 20220308135010236.document.request è stato trasferito
  2. Il file è in fase di elaborazione
  3. Il file response/20220308135010236.document.error è stato archiviato. 

Responsabilità

I file delle richieste elaborate vengono spostati dall’interfaccia file nella sottodirectory “processed”.

L’interfaccia file non eliminerà mai alcun file. Tuttavia, si raccomanda di archiviare i file più vecchi (riconoscibili dalla data) dopo un certo periodo di tempo.

Garanzia della corretta sequenza

La sequenza di elaborazione è garantita da un nome univoco e ordinabile del file.

Struttura del nome del file

YYYYMMDDHHNNSSZZZ.{type}.request

AAAA = Anno (2022), intervallo di valori: 2022-3000

MM = Mese (03 per marzo), intervallo di valori: 01-12

DD = Giorno (02 per il 2 del mese), intervallo di valori: 01-31

HH = Ora nel formato 24 ore, intervallo di valori: 00-23

NN = Minuti (04 per 4 minuti), intervallo di valori: 00-59

SS = Secondi (05 per 5 secondi), intervallo di valori: 00-59

ZZZ = Millisecondi (010 per 10 millisecondi), intervallo di valori: 000-999

Tipo

{type} indica il tipo di richiesta; sono disponibili i seguenti tipi:

  • Document - per trasmettere una ricevuta
  • validateDocument – per convalidare una ricevuta
  • command - per eseguire un comando

Documentazione relativa al tipo/modello

Per ulteriori dettagli sul modello del documento e sulle risposte corrispondenti, si prega di fare riferimento alla Documentazione sul modello a oggetti e alla documentazione Swagger del Fiscal Client (http://localhost:7678/swagger/index.html).

Il messaggio di errore è uniforme per tutti i tipi: l’eccezione generata viene restituita nel file di ritorno (*.error).

Tipo "document" - trasmissione delle ricevute

Il contenuto del file in questo caso è un documento nel formato RetailForce (Document).

Il formato del documento è consultabile nella documentazione sul modello a oggetti o nella documentazione Swagger del servizio fiscale (http://localhost:7678/swagger/index.html).

Risposta

Nel file di risposta viene trasmessa la fiscalResponse del rispettivo Paese.

Tipo "validateDocument" - convalida di una ricevuta

Il contenuto del file in questo caso è, come per il tipo "document", un documento nel formato RetailForce.

Risposta

Nel file di restituzione viene restituito un eventuale elenco di errori (e avvisi) emersi dalla convalida.

Tipo "createClient" - creazione di un FiscalClient

Il contenuto del file in questo caso è un FiscalClient in formato JSON (vedi documentazione).

Risposta

"OK" quando la richiesta è stata elaborata con successo.

Tipo "createClientByCloud" - creazione di un FiscalClient con dati provenienti dal Cloud

Il contenuto del file è un documento JSON con la seguente struttura:

{
  "CompanyIdentification": 
  {
    "Type": 0, 
    "Identification": "UID"
  },
  "StoreNumber": "001",
  "TerminalNumber": "01",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}"
}

Restituisce

L'uniqueClientId del client creato.

Tipo "restoreClientByCloud" - ripristino di un FiscalClient con dati provenienti dal Cloud

Il contenuto del file è un documento JSON con la seguente struttura:

{
  "CompanyIdentification": 
  {
    "Type": 0, 
    "Identification": "UID"
  },
  "StoreNumber": "001",
  "TerminalNumber": "01",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}"
}

Risultato

Il UniqueClientId del cliente ripristinato.

Tipo "getClientId" - Ricerca di un client e recupero dell'ID

Disponibile a partire dalla versione V1.2.12

Il contenuto del file è un documento JSON con la seguente struttura:

{
  "CompanyIdentification": 
  {
    "Type": 0, 
    "Identification": "UID"
  },
  "StoreNumber": "001",
  "TerminalNumber": "01"
}

Risultato

L'uniqueClientId del client creato.

Digitare "InitializeClient" - Inizializzazione del FiscalClient

Il contenuto del file è un documento JSON con la seguente struttura:

{
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "BookDate": "2022-03-10T08:52:33.3556282Z",
   "User": 
   {
     "Id": "1",
     "Caption": "Test",
     "LastName": "Test",
     "FirstName": "Test",
     "DateOfEntry": "2022-03-10T08:52:33.3556282Z"
  }
}

I dati riportati sono dati di prova e devono essere sostituiti con quelli corretti.

Ritorno

Null oppure un oggetto fiscalResponse relativo al paese in questione.

Tipo "CloudConnect" - inizializzazione della connessione cloud

Il contenuto del file è un documento JSON con la seguente struttura:

{
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}",
  "PersistDays": {days} // optional, days until credentials are stored 
}
Attenzione: le credenziali vengono memorizzate su disco in forma crittografata. La persistenza delle credenziali rappresenta un potenziale rischio per la sicurezza.

Restituisce

"OK" quando la richiesta è stata elaborata con successo.

Tipo "AuditLog" - trasmissione di una voce del registro di audit

Il contenuto del file è un oggetto JSON con la seguente struttura:

{
  "RecordDateTime": "2022-03-11T15:17:57.9859527",
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "LogEntryType": 200,
  "Message": "OpenDrawer",
  "DocumentGuid": null,
  "User": null
}

Restituisce

Null oppure un oggetto fiscalResponse del rispettivo Paese (se richiesto in tale Paese).

Tipo "digitalReceipt" - Invio della ricevuta digitale

Questo tipo di file può essere utilizzato per trasmettere una ricevuta digitale. 

Il contenuto del file è un oggetto JSON con la seguente struttura:

{
"UniqueClientId": "d5ecc344-e37a-40c6-bed4-a6b1e60e68c8",
"ReceiptMetaData": {
"DocumentType": 0,
"CustomDocumentType": null,
"DocumentGuid": "2394fef4-2339-459a-817e-e4cd86ce23f6",
"DocumentNumber": "1",
"DocumentId": "CS_01_01_1",
"BookDate": "2021-11-17T06:45:03.8203317",
"Amount": 141.0,
"Partner": null,
"Users": null,
"ProcessId": null,
"CancelledDocumentGuid": null,
"ItemIdArray": [
"1231",
"SW4471"
],
"ItemCodeArray": null
},
"PdfDataBase64": "JVBERi0xLjcKJeLjz9MKMSAwIG9iaiAKPDwKL0NvbG9yU3Bh..."
}

La proprietà «ReceiptMetaData» corrisponde all’oggetto ReceiptMetaData che deve essere trasmesso anche in caso di chiamata tramite l’interfaccia REST. 

Nell’esempio, il flusso di dati PDF è stato abbreviato con «...».

Restituzione

Nel file di risposta viene restituito un link QrCode (sotto forma di stringa) da mostrare al cliente.

Configurazione

L’interfaccia del file system può essere attivata nella configurazione del client impostando un valore nel campo FiscalClient.FileSystemInterfacePath. Se questo campo è vuoto (impostazione predefinita), l’interfaccia file non è attiva.

Questo articolo è stato tradotto automaticamente.

Articoli correlati

Commenti

0 commenti

Accedi per aggiungere un commento.

Powered by Zendesk