This article describes how to use the file interface of the fiscal service.

Prerequisites

• FiskalClient as of version 1.2.11
• FiscalClient as a service (nuget implementations are not supported)

Countries supported

Currently, only the countries listed below are supported via the file interface:

• Austria
• Denmark (as of version 1.3)

Additional information

The file interface only supports a very small scope of the fiscal client's functionality to transmit the necessary data for fiscalisation. If more specific commands are desired, the service can still be integrated with tools like CURL via the REST interface. However, this is not explained in this article.

Activation

The file system interface can be enabled as follows:

• Setting the path to the monitoring in appsettings.json.
• Creating a directory under C:\ProgramData\RetailForce\Fiscal web service with name "fileSystemInterface".

appsettings.json

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

The entries before and after are not included in the example. "c:\temp\filesysteminterface" is the monitored path.

How it works

The file interface of the fiscal service monitors a directory for new files with a certain name structure. As soon as a new file corresponding to the naming conventions is created in this directory, it is processed.

Process

The procedure is as follows:

1. File is transferred in the directory and recognised (*.request)
2. File is being processed
3. *.response or *.error file is stored in the "response" directory (subdirectory of the import directory) (same file name before the extension).

Example

1. 20220308135010236.document.request is transferred
2. File is being processed
3. File response/20220308135010236.document.response is stored. 

or in case of error

1. 20220308135010236.document.request is transferred
2. File is being processed
3. File response/20220308135010236.document.error is stored. 

Responsibilities

The processed request files are moved to the subdirectory "processed" by the file interface.

The file interface will never delete any files. However, it is recommended to archive older files (recognisable by their date) after a certain period of time.

Ensuring the correct sequence

The sequence of processing is ensured by a unique sortable name of the file.

Structure of the file name

YYYYMMDDHHNNSSZZZ.{type}.request

YYYY = Year (2022), value range: 2022-3000

MM = Month (03 for March), value range: 01-12

DD = Day (02 for 2nd of the month), value range: 01-31

HH = Hour in 24h notation, value range: 00-23

NN = Minutes (04 for 4 minutes), value range: 00-59

SS = Seconds (05 for 5 seconds), value range: 00-59

ZZZ = Milliseconds (010 for 10 milliseconds), value range: 000-999

Type

{type} indicates the type of the request, there are the following types:

• document - to transmit a receipt
• validateDocument - to validate a receipt
• command - to execute a command

Type / model documentation

For more information on the document model and the corresponding responses, please refer to the Object Model Documentation and the Swagger documentation of the Fiscal Client (http://localhost:7678/swagger/index.html).

The error return is the same for all types: The exception that was thrown is returned in the return file (*.error).

Type "document" - transmitting receipts

The file content in this case is a document in the RetailForce document format (Document).

The document format can be read in the Object Model Documentation or in the Swagger documentation at the fiscal service (http://localhost:7678/swagger/index.html).

Return

The FiscalResponse of the respective country is transmitted in the return file.

Type "validateDocument" - validating a receipt

The file content in this case is, as with the type "document", a document in the RetailForce document format.

Return

In the return file, a possible list of errors (and warnings) from the validation is returned.

Type "createClient" - creating a FiscalClient

The file content in this case is a FiscalClient as json (sh. documentation).

Return

"OK" when the request has been processed successfully.

Type "createClientByCloud" - creating a FiscalClient with data from the Cloud

The file content is a json document with the following structure:

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

Return

The UniqueClientId of the created client.

Type "restoreClientByCloud" - restoring a FiscalClient with data from the Cloud

The file content is a json document with the following structure:

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

Return

The UniqueClientId of the restored client.

Type "getClientId" - Search for client and fetch id

Available from: V1.2.12

The file content is a json document with the following structure:

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

Return

The UniqueClientId of the created client.

Type "initializeClient" - initialising the FiscalClient

The file content is a json document with the following structure:

{
  "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"
  }
}

The data given are test data and are to be replaced by the correct data.

Return

Either empty or a FiscalResponse object of the respective country.

Type "cloudConnect" - initialising Cloud Connection

The file content is a json document with the following structure:

{
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}",
  "PersistDays": {days} // optional, days until credentials are stored 
}

Return

"OK" when the request has been processed successfully.

Type "auditLog" - transmitting Audit log entry

The file content is a json object with the following structure:

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

Return

Either blank or a FiscalResponse object of the respective country (if required there).

Type "digitalReceipt" - Transmit digital receipt

This file type can be used to submit a digital receipt. 

The file content is a json object with the following structure:

{
"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..."
}

The property "ReceiptMetaData" is the ReceiptMetaData object that is also to be passed when calling via the rest interface. 

In the example the PDF data stream was abbreviated by ... in the example.

Return

In the return file a QRCode link (as string) is returned for display to the customer.

Configuration

The file system interface can be activated in the client configuration by means of a value in the field FiscalClient.FileSystemInterfacePath. If this field is empty (default), the file interface is not active.