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".
Attention: To activate the system the service must be restarted after these settings.
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.
Attention: For larger files, it is advisable to first write the file into the directory as a temp file and then rename it to the correct file name using RENAME.
Process
The procedure is as follows:
- File is transferred in the directory and recognised (*.request)
- File is being processed
- *.response or *.error file is stored in the "response" directory (subdirectory of the import directory) (same file name before the extension).
Example
- 20220308135010236.document.request is transferred
- File is being processed
- File response/20220308135010236.document.response is stored.
or in case of error
- 20220308135010236.document.request is transferred
- File is being processed
- 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.
Comments
0 comments
Please sign in to leave a comment.