Überblick über die zur Inbetriebnahme eines Clients erforderlichen Schritte:

1. Anlage Organisationsstruktur
2. Konfiguration
3. Herstellung Cloud Verbindung
4. Client-Initialisierung

1. Anlage Organisationsstruktur

Als ersten Schritt zur Inbetriebnahme, muss zunächst die Organisationsstruktur des Kassenbetreibenden Unternehmen in der RetailForce Cloud angelegt werden. Details dazu finden Sie im verlinkten Artikel.

Bei Systemen, welche vollständig offline arbeiten und zu keinem Zeitpunkt eine Verbindung zur RetailForce Cloud aufbauen, kann dieser Schritt übersprungen werden.

2. Konfiguration

Die Konfiguration eines Clients der Fiskal Middleware kann grundsätzlich auf zwei unterschiedliche Arten erfolgen (abhängig von den Einstellungen und Vereinbarungen, die der Kassensoftwarehersteller und das Kassen-betreibende Unternehmen getroffen haben):

1. Konfiguration über RetailForce Cloud, oder alternativ:
2. Konfiguration durch Kassensoftware

1. Konfiguration über RetailForce Cloud

Bei dieser Variante lädt der Client ein in der RetailForce Cloud vorbereitetes Konfigurations-Objekt lokal herunter. Dies kann als automatische Konfiguration angesehen werden. Die Erstellung von Konfigurationsobjekten wird im verlinkten Artikel beschrieben.

Bei der Konfiguration einer Fiskaleinheit durch die Cloud, sind alle Daten die das System benötigt bereits in der Cloud konfiguriert (Anleitung und allgemeine Informationen zur Erstellung einer Konfiguration). Diese Daten werden mittels eines Aufrufs vom Fiskalclient (CreateClientByCloud) aus der Cloud geladen.

Die Parameter für den Aufruf sind:

• Unternehmensidentifikation (CompanyIdentification), zumeist die Umsatzsteuer-Identifikations-Nr. (Ust-Id-Nr. = VatNumber). In Abhängigkeit vom Fiskalland, kann es notwendig sein, alternativ, oder zusätzlich (!) noch weitere ID-Merkmale anzugeben. Im Rahmen der Inbetriebnahme wird allerdings die USt.Id-Nr. empfohlen.
• Filialnummer
• Kassennummer
• cloudApiKey
• cloudApiSecret

Wird die Funktion PUT api/v1/management/clients/byCloud ohne Fehler abgeschlossen, dann ist die Konfiguration des Fiskalclients abgeschlossen. Die Guid des Fiskalmoduls (=clientId) wird als Rückgabewert übermittelt.

2. Konfiguration durch Kassensoftware

Alternativ zur automatischen Client-Konfiguration über das RetailForce Cloud-System, kann das Konfigurationsobjekt auch von der Kassensoftware vorbereitet werden. Diese Art der Konfiguration wird bei Systemen eingesetzt, welche keine Anbindung an die RetailForce Cloud besitzen. Hierfür wird der Endpunkt PUT /api/v1/management/clients verwendet.

Bei der Konfiguration durch die Kassensoftware, gibt es 2 Möglichkeiten das Modul korrekt in Betrieb zu nehmen:

1. Modul ohne Cloud-Anbindung mit lokaler Datenspeicherung und -export
2. Modul mit Cloud-Anbindung mit lokaler und Cloud-Datenspeicherung und -export

Es ist jedenfalls erforderlich, dass die notwendigen Konfigurationsparameter entsprechend der Dokumentation korrekt gesetzt werden.

Variante 2 (mit Cloud-Anbindung) kann auch später aktiviert werden, d.h. es ist möglich eine Fiskalkonfiguration ohne Cloud-Anbindung anzulegen und diese dann mit der Cloud zu synchronisieren. 

Es ist zu beachten, dass die Anlage eines Clients in der Cloud durch den Kassensoftwarehersteller und/oder die Organisation in den Cloud-Einstellungen freigeschaltet sein muss. Der Standardweg ist, zuerst ein Konfigurationsobjekt in der Cloud anzulegen.

3. Herstellung Cloud Verbindung

Als nächsten Schritt muss der Client mit der RetailForce Cloud verbunden werden (bei Offline-Systemen, ohne Cloud-Verbindung kann dieser Schritt übersprungen werden). Dies erfolgt über die Funktion:

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

Parameter für den Aufruf:

• clientId - die eindeutige Client-ID (Guid) wurde der Kasse bei Konfiguration über RetailForce Cloud zurückgegeben.
• cloudApiKey
• cloudApiSecret

4. Client-Initialisierung

Durch Aufruf der Funktion InitializeClient (POST /api/v1/management/clients/initialize), mit Parameter (Startdokument), wird die Initialisierungsroutine des jeweiligen Landes aufgerufen, etwaige Sicherheitskomponenten werden in diesem Zug ebenfalls initialisiert (wenn notwendig).
Für länder- und oder Hardwarespezifische Themen entnehmen Sie diese bitte aus der entsprechenden Dokumentation.

Das Startdokument kann durch Ausführen der Funktion:

• GET /api/v1/transactions/document/{clientId}/start
  (Parameter: clientId, optional: bookDate)

vom Dienst angefragt werden.

Wird der FiskalClient ohne Fiskalisierung verwendet (NoFiscalisation), wenn etwa nur digitale Belege oder Archivdaten an den Client übermittelt werden, ist eine Initialisierung nicht notwendig.

• Aufruf der Funktion Initialisierung (InitializeClient - POST /api/v1/management/clients/initialize)

Die Initialisierung der Fiskaleinheit erfolgt dann mittels dem Aufruf InitializeClient.

Der Funktion InitializeClient wird ein NullReceipt übergeben, anbei ein Beispiel:

{
    "UniqueClientId": "c1062c55-57c4-4ed2-9c53-aff1762326a4",
    "DocumentGuid": "5efa5306-fe53-452d-9c81-68329475eee0",
    "DocumentId": "5efa5306-fe53-452d-9c81-68329475eee0",
    "CreateDate": "2021-02-02T05:31:08.9450964+01:00",
    "BookDate": "2021-02-02T05:31:08.9450964+01:00",
    "DocumentNumber": null,
    "CancellationDocument": false,
    "DocumentReference": null,
    "IsTraining": false,
    "DocumentType": 1000,
    "DocumentTypeCaption": null,
    "User": {
        "Id": "1234",
        "Caption": "Testuser"
    },
    "AllocationGroups": [],
    "Partner": null,
    "FiscalResponse": null,               
    "FiscalDocumentNumber": 1,            
    "FiscalDocumentRevision": 1,          
    "Positions": [],
    "Payments": []
}

Der Initialisierungsvorgang ist grundsätzlich länderspezifisch, der Aufruf bleibt aber für alle Länder gleich. Details zu den länderspezifischen Initialisierungen entnehmen Sie bitte aus der jeweiligen Länderdokumentation.

Inbetriebnahme im Überblick

Folgende Funktionen werden in der vorliegenden Reihenfolge, zur Inbetriebnahme eines Clients, aufgerufen:

Weiterführende Artikel

Initialisierung Deutschland

Fehlerbehandlung

Fehler: GetConfiguration for client <ClientId> not found