Dieser Artikel beschreibt, wie die Dateischnittstelle des Fiskalservice verwendet werden kann.

Voraussetzungen

• FiskalClient ab der Version 1.2.11
• FiskalClient als Service (nuget Implementierungen sind nicht unterstützt)

Unterstützte Länder

Aktuell werden nur die nachfolgend aufgelisteten Länder über die Dateischnittstelle unterstützt:

• Österreich
• Dänemark (ab der Version 1.3)

Zusatzinformationen

Die Dateischnittstelle unterstützt nur einen sehr geringen Umfang des Fiskalclients um die notwendigen Daten zur Fiskalisierung zu übermitteln. Wenn spezifischere Kommandos gewünscht werden, kann der Service noch mit Tools wie CURL über die REST Schnittstelle integriert werden. Dies wird allerdings nicht in diesem Artikel erläutert.

Aktivierung

Die Dateischnittstelle kann folgendermaßen aktiviert werden:

• Setzen des Pfades zur Überwachung in der appsettings.json
• Erstellen eines Verzeichnisses unter C:\ProgramData\RetailForce\Fiscal Webservice mit Namen "fileSystemInterface"

appsettings.json

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

Die Einträge vorher und nachher sind im Beispiel nicht enthalten. "c:\temp\filesysteminterface" ist der überwachte Pfad.

Funktionsweise

Die Dateischnittstelle des Fiskalservices überwacht ein Verzeichnis auf neue Dateien mit einem bestimmten Namensaufbau. Sobald eine neue Datei, die den Namenskonventionen entspricht in diesem Verzeichnis angelegt wird, wird diese verarbeitet.

Ablauf

Der Ablauf ist folgendermaßen:

1. Datei wird im Verzeichnis übergeben und erkannt (*.request)
2. Datei wird verarbeitet
3. Im Verzeichnis "response" (Unterverzeichnis des Importverzeichnisses) wird eine *.response oder eine *.error Datei abgelegt (selber Dateiname vor der Extension)

Beispiel

1. 20220308135010236.document.request wird übergeben
2. Datei wird verarbeitet
3. Datei response/20220308135010236.document.response wird abgelegt.

oder im Fehlerfall

1. 20220308135010236.document.request wird übergeben
2. Datei wird verarbeitet
3. Datei response/20220308135010236.document.error wird abgelegt.

Verantwortlichkeiten

Die verarbeiteten Request Dateien werden von der Dateischnittstelle in das Unterverzeichnis "processed" verschoben.

Von der Dateischnittstelle werden niemals Dateien gelöscht. Es empfiehlt sich aber ältere Dateien (erkennbar am Datum) nach einer bestimmten Zeit zu archivieren.

Sicherstellung der richtigen Reihenfolge

Die Reihenfolder der Verarbeitung. Dies wird durch einen eindeutig-sortierbaren Namen der Datei sichergestellt.

Aufbau des Dateinamens

YYYYMMDDHHNNSSZZZ.{type}.request

YYYY = Jahr (2022), Wertbereich: 2022-3000

MM = Monat (03 für März), Wertebereich: 01-12

DD = Tag (02 für 2. des Monats), Wertebereich: 01-31

HH = Stunden in 24h Schreibweise, Wertebereich: 00-23

NN = Minuten (04 für 4 Minuten), Wertebereich: 00-59

SS = Sekunden (05 für 5 Sekunden), Wertebereich: 00-59

ZZZ = Millisekunden (010 für 10 Millisekunden), Wertebereich: 000-999

Type

{type} gibt den Typ des Requests an, es gibt folgende Typen:

• document - Zur Übermittlung eines Beleges
• validateDocument - Zur Validierung eines Beleges
• command - Zur Ausführung eines Kommandos

Typendokumentation

Nähere Informationen bezüglich dem Dokumentenmodell und den entsprechenden Antworten finden Sie in der Object Model Documentation sowie in der Swagger Dokumentation des Fiskalclients (http://localhost:7678/swagger/index.html).

Die Fehlerrückgabe ist bei allen Typen gleich: Es wird die Exception, welche ausgelöst wurde in der Rückgabedatei (*.error) rückübermittelt.

Typ "document" - Übermittlung Beleg

Der Dateiinhalt in diesem Fall ist ein Beleg im RetailForce Dokument Format (Document).

Das Dokumentenformat kann in der Object Model Documentation oder in der Swagger Dokumentation am Fiskalservice ausgelesen werden (http://localhost:7678/swagger/index.html).

Rückgabe

In der Rückgabe Datei wird die FiscalResponse des jeweiligen Landes übermittelt.

Typ "validateDocument" - Validierung eines Beleges

Der Dateiinhalt in diesem Fall ist wie beim Typ "document" ein Beleg im RetailForce Dokument Format.

Rückgabe

In der Rückgabe Datei wird eine mögliches Liste von Fehlern (und Warnungen) von der Validierung zurückgegeben.

Typ "createClient" - Anlegen eines FiskalClients

Der Dateiinhalt in diesem Fall ist ein FiscalClient als json (sh. Dokumentation).

Rückgabe

"OK" wenn die Anforderung erfolgreich verarbeitet wurde.

Typ "createClientByCloud" - Anlegen FiskalClient mit Cloud-Daten

Der Dateiinhalt ist ein json Dokument mit folgendem Aufbau:

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

Rückgabe

Die UniqueClientId des angelegten Clients.

Typ "restoreClientByCloud" - Wiederherstellung FiskalClient mit Cloud-Daten

Der Dateiinhalt ist ein json Dokument mit folgendem Aufbau:

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

Rückgabe

Die UniqueClientId des wiederherstgestellten Clients.

Typ "getClientId" - Nach Client suchen und Id zurückgeben

Verfügbar: Ab V1.2.12.

Der Dateiinhalt ist ein json Dokument mit folgendem Aufbau:

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

Rückgabe

Die UniqueClientId des angelegten Clients.

Typ "initializeClient" - Initialisierung des FiskalClients

Der Dateiinhalt ist ein json Dokument mit folgenden Aufbau:

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

Die angegebenen Daten sind Testdaten und sind durch die richtigen Daten zu ersetzen.

Rückgabe

Entweder leer oder ein FiscalResponse Objekt des jeweiligen Landes.

Typ "cloudConnect" - Cloud-Verbindung initialisieren

Der Dateiinhalt ist ein json Dokument mit folgenden Aufbau:

{
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}",
  "PersistDays": {Tage} //optional, die Anzahl der Tage zum Speichern der Credentials
}

Rückgabe

"OK" wenn die Anforderung erfolgreich verarbeitet wurde.

Typ "auditLog" - Audit log eintragen übermitteln

Der Dateiinhalt ist ein json Objekt mit folgenden Aufbau:

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

Rückgabe

Entweder leer oder ein FiscalResponse Objekt des jeweiligen Landes (wenn dort erforderlich).

Typ "digitalReceipt" - Digitalen Beleg übermitteln

Mit diesem Dateityp kann ein digitaler Beleg übermittelt werden. 

Der Dateiinhalt ist ein json Objekt mit folgendem Aufbau:

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

Die Property "ReceiptMetaData" ist das ReceiptMetaData-Objekt dass auch beim Aufruf über die Restschnittstelle zu übergeben ist. 

Im Beispiel wurde der PDF Datenstrom durch ... abgekürzt.

Rückgabe

In der Rückgabedatei wird ein QRCode-Link (als String) zur Anzeige für den Kunden zurückgegeben.

Konfiguration

Die Dateisystem Schnittstelle kann in der Client Konfiguration mittels einem Wert im Feld FiscalClient.FileSystemInterfacePath aktiviert werden. Ist dieses Feld leer (default), dann ist die Dateischnittstelle auch nicht aktiv.