Przegląd kroków niezbędnych do uruchomienia klienta:

1. Tworzenie struktury organizacyjnej
2. Konfiguracja
3. Nawiązanie połączenia z Cloud
4. Inicjalizacja klienta

1. Utworzenie struktury organizacyjnej

Pierwszym krokiem przed uruchomieniem systemu jest utworzenie struktury organizacyjnej firmy obsługującej kasy fiskalne w RetailForce Cloud. Szczegółowe informacje na ten temat można znaleźć w artykule, do którego link znajduje się poniżej.

Krok ten można pominąć w przypadku systemów, które mają działać całkowicie w trybie offline i nie nawiązują w żadnym momencie połączenia z RetailForce Cloud.

2. Konfiguracja

Konfigurację klienta middleware można zasadniczo przeprowadzić na dwa różne sposoby (w zależności od ustawień i ustaleń dokonanych przez producenta oprogramowania kasowego oraz firmę obsługującą kasy):

1. Konfiguracja za pośrednictwem RetailForce Cloud lub alternatywnie
2. Konfiguracja za pośrednictwem oprogramowania POS (system kasowy, elektroniczny system rejestracji)

1. Konfiguracja za pośrednictwem RetailForce Cloud

W tym wariancie client pobiera lokalnie obiekt konfiguracyjny przygotowany w RetailForce Cloud. Można to uznać za konfigurację automatyczną. Sposób tworzenia obiektów konfiguracyjnych opisano w artykule, do którego prowadzi link.

Podczas konfiguracji jednostki fiskalnej za pośrednictwem Cloud wszystkie dane wymagane przez system są już skonfigurowane w Cloud (instrukcje i ogólne informacje dotyczące tworzenia konfiguracji). Dane te są pobierane z Cloud za pomocą wywołania z poziomu klienta fiskalnego (CreateClientByCloud).

Parametry wywołania to:

• Identyfikator firmy (companyIdentification), zazwyczaj numer identyfikacyjny VAT (VatNumber). W zależności od kraju, w którym obowiązują przepisy podatkowe, może być konieczne wprowadzenie alternatywnych lub dodatkowych identyfikatorów (!). Na początek zaleca się jednak użycie numeru identyfikacyjnego VAT.
• Numer sklepu / oddziału
• Numer kasy fiskalnej
• cloudApiKey
• cloudApiSecret

Jeśli funkcja PUT api/v1/management/clients/byCloud zostanie wykonana bez błędów, konfiguracja klienta fiskalnego zostanie zakończona. Jako wartość zwracana przekazywany jest identyfikator GUID modułu fiskalnego (=clientId).

2. Konfiguracja za pośrednictwem oprogramowania POS

Jako alternatywę dla automatycznej konfiguracji klienta za pośrednictwem RetailForce Cloud systemu obiekt konfiguracyjny można również przygotować w oprogramowaniu kasowym. Ten rodzaj konfiguracji stosuje się w systemach, które nie posiadają połączenia z RetailForce Cloud. W tym celu wykorzystuje się punkt końcowy PUT /api/v1/management/clients.

Podczas konfiguracji oprogramowania kasowego istnieją dwa sposoby prawidłowego uruchomienia modułu:

1. Moduł bez połączenia z Cloud, z lokalnym przechowywaniem danych i eksportem
2. Moduł z połączeniem z Cloud, z lokalnym i chmurowym przechowywaniem danych oraz eksportem

W każdym przypadku konieczne jest prawidłowe ustawienie niezbędnych parametrów konfiguracyjnych zgodnie z dokumentacją.

Wariant 2 (z połączeniem z Cloud) można również aktywować w późniejszym terminie, tzn. możliwe jest utworzenie konfiguracji fiskalnej bez połączenia z Cloud, a następnie zsynchronizowanie jej z Cloud.

Należy pamiętać, że utworzenie klienta w Cloud musi zostać umożliwione przez producenta oprogramowania POS i/lub organizację w ustawieniach Cloud. Standardową procedurą jest najpierw utworzenie obiektu konfiguracyjnego w Cloud.

3. Nawiązywanie połączenia z Cloud

Kolejnym krokiem jest połączenie klienta z RetailForce Cloud (w przypadku systemów działających w trybie offline, bez połączenia z RetailForce Cloud, krok ten można pominąć). Odbywa się to za pomocą funkcji:

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

Parametry wywołania:

• clientId – unikalny ID klienta (Guid) został zwrócony kasie podczas konfiguracji za pośrednictwem RetailForce Cloud.
• cloudApiKey
• cloudApiSecret

4. Inicjalizacja klienta

Wywołanie funkcji InitializeClient (POST /api/v1/management/clients/initialize) wraz z parametrem (dokument startowy) powoduje wywołanie procedury inicjalizacji właściwej dla danego kraju; w ramach tego procesu inicjalizowane są również wszelkie komponenty zabezpieczeń (w razie potrzeby).
W kwestiach dotyczących konkretnego kraju lub sprzętu prosimy zapoznać się z odpowiednią dokumentacją.

Dokument początkowy można uzyskać od serwisu poprzez wykonanie funkcji:

• GET /api/v1/transactions/document/{clientId}/start
  (parameter: clientId, optional: BookDate).

Jeśli moduł FiscalClient jest używany bez fiskalizacji (NoFiscalisation), na przykład w przypadku przesyłania do klienta wyłącznie cyfrowych paragonów lub danych archiwalnych, inicjalizacja nie jest konieczna.

• Wywołanie funkcji inicjalizacji (InitializeClient – POST /api/v1/management/clients/initialize)

Inicjalizacja urządzenia fiskalnego odbywa się następnie za pomocą wywołania InitializeClient.

Do funkcji InitializeClient przekazywany jest obiekt NullReceipt; przykład znajduje się poniżej:

{
    "modelVersion": "1.5.2",
    "uniqueClientId": "c1062c55-57c4-4ed2-9c53-aff1762326a4",
    "additionalFields": {},
    "documentGuid": "5efa5306-fe53-452d-9c81-68329475eee0",
    "documentId": "1",
    "createDate": "2025-05-02T07:08:17.8334419+02:00",
    "bookDate": "2025-05-02T07:08:17.8335535+02:00",
    "documentNumber": "1",
    "documentType": 1000,
    "documentTypeCaption": "Startbeleg",
    "user": {
        "id": "1",
        "caption": "User 1",
        "firstName": "1",
        "lastName": "User",
        "dateOfEntry": "2025-05-02T07:08:17.833596+02:00"
    },
    "allocationGroups": [],
    "positionCount": 0,
    "fiscalDocumentNumber": 1,            
    "fiscalDocumentRevision": 1,          
    "positions": [],
    "Payments": [],
    "additionalHeader": [],
    "additionalFooter": [],
    "fiscalAdditionalFields": {}
}

Proces inicjalizacji jest zasadniczo specyficzny dla danego kraju, jednak wywołanie pozostaje takie samo dla wszystkich krajów. Szczegółowe informacje na temat inicjalizacji specyficznych dla poszczególnych krajów można znaleźć w dokumentacji danego kraju.

Uruchomienie w skrócie

W celu uruchomienia klienta wywoływane są następujące funkcje w podanej kolejności:

Powiązane artykuły

Inicjalizacja w Niemczech

Obsługa błędów

Błąd: Nie znaleziono GetConfiguration dla klienta <CLIENTID>

Ten artykuł został przetłumaczony automatycznie.