Firma RetailForce opracowuje oprogramowanie zapewniające zgodność z przepisami dotyczącymi fiskalizacji elektronicznych systemów rejestracji w różnych krajach. Oprogramowanie to nosi nazwę „Fiscal Middleware”.
Niniejszy dokument zawiera przegląd sposobu integracji oprogramowania RetailForce Fiscal Middleware. Architektura systemu nadrzędnego, który wysyła dane do oprogramowania Fiscal Middleware i odbiera dane z niego, a także szczególne wymagania i funkcje tego systemu mogą wymagać odstępstwa od niniejszego opisu.
1. Podstawy
Poniżej wymieniono poszczególne kroki, które należy wykonać przed rozpoczęciem integracji. Kroki te są również szczegółowo omawiane podczas sesji wdrożeniowej.
1.1 Przegląd wariantów integracji
Przed rozpoczęciem integracji prosimy zapoznać się z dostępnymi wariantami integracji. Warianty te opisano w poniższym artykule: Przegląd fiskalizacji z RetailForce – RetailForce Software GmbH (=artykuł przeglądowy).
W artykule, do którego prowadzi link, znajdują się również źródła, z których można pobrać oprogramowanie RetailForce Middleware w różnych wariantach.
Po pobraniu oprogramowania Fiscal Middleware należy przeprowadzić instalację. Opis sposobu instalacji poszczególnych wariantów znajduje się w artykule przeglądowym.
1.1.1 Tryb online a tryb offline
Oprogramowanie RetailForce Middleware jest zasadniczo samodzielnym systemem. Jednak niektóre funkcje są dostępne wyłącznie wtedy, gdy oprogramowanie jest połączone z RetailForce Cloud.
RetailForce Cloud zapewnia różne funkcje zarządzania, takie jak automatyczna zdalna konfiguracja middleware, w tym przydzielanie licencji, a także funkcje bezpiecznej długoterminowej archiwizacji.
Aby móc korzystać z funkcji RetailForce Cloud, oprogramowanie Fiscal Middleware lub konkretny klient w ramach instalacji (klient = pojedyncza instancja elektronicznego systemu rejestracji) musi być podłączony do terminala w RetailForce Cloud.
Jeśli middleware ma działać bez nawiązywania połączenia z Cloud (system offline), poniższe kroki można pominąć. Proszę przejść do punktu 1.5.
1.2 Dostęp do RetailForce portalu
Wszystkie funkcje RetailForce Cloud są udostępniane za pośrednictwem
- RetailForce Cloud Portal (https://portal.retailforce.cloud), a także za pośrednictwem
- Cloud API (https://api.retailforce.cloud/swagger)
Samodzielna rejestracja w portalu RetailForce nie jest możliwa ze względów bezpieczeństwa. Aby uzyskać dostęp do portalu, należy otrzymać link z zaproszeniem od użytkownika, który posiada już uprawnienia. Dalszy proces rejestracji opisano w poniższym artykule: Rejestracja w portalu RetailForce – RetailForce Software GmbH.
1.3 Struktura organizacyjna
W portalu należy najpierw utworzyć strukturę organizacyjną. Artykuł „Tworzenie struktury organizacyjnej w RetailForce Cloud – RetailForce Software GmbH” zawiera przegląd funkcji udostępnionych w tym celu.
1.4 Konfiguracja
Po utworzeniu struktury organizacyjnej, co najmniej jednej organizacji (=klienta), jednego sklepu (=oddziału) oraz jednego terminala (=kasy), należy przygotować obiekt konfiguracyjny w Cloud i przypisać go do podmiotu (organizacji, firmy, sklepu lub terminala). Opis tego procesu można znaleźć w artykule: Ogólne informacje na temat konfiguracji – RetailForce Software GmbH.
1.5 Inicjalizacja
Jeśli poprzednie kroki zostały pomyślnie wykonane, można uruchomić oprogramowanie Fiscal Middleware. Kroki niezbędne do uruchomienia (z nawiązaniem połączenia z chmurą oraz bez niego) zostały szczegółowo wyjaśnione w artykule Inicjalizacja (ogólne) – RetailForce Software GmbH.
W wyniku procesu uruchomienia/inicjalizacji oprogramowanie Fiscal Client powinno
- być w pełni skonfigurowany,
- albo za pomocą obiektu konfiguracyjnego przygotowanego w Cloud, albo
- „ręcznie” przez system elektronicznej ewidencji,
- oraz posiadać unikalny ID klienta.
2. Integracja
Po pomyślnym zakończeniu uruchomienia klienta („kasy fiskalnej”) można rozpocząć integrację.
W niniejszym rozdziale przedstawiono wytyczne dotyczące procesu przekazywania dokumentów między kasą fiskalną (systemem elektronicznej ewidencji) a konkretnym klientem.
2.1 Usługa internetowa REST
Poniższy artykuł pomoże Państwu rozpocząć integrację interfejsu usługi internetowej REST, który służy do
- usługi systemu Windows, jak i
- kontener Docker.
Pierwsze kroki z usługą fiskalną – RetailForce Software GmbH
2.2 Wdrożenie w Nuget
Pomoc dotycząca implementacji middleware za pomocą nuget (DLL) znajduje się w poniższym artykule: Pierwsze kroki w implementacji nuget – RetailForce Software GmbH.
2.3 Interfejs systemu plików
Oprócz dwóch wyżej wymienionych wariantów wdrożenia – usługi internetowej REST oraz nuget – dostęp do oprogramowania middleware można uzyskać również za pośrednictwem interfejsu plikowego. Więcej informacji na ten temat można znaleźć w artykule: Interfejs systemu plików – RetailForce Software GmbH.
2.4 Proces przesyłania dokumentów
Po zainstalowaniu oprogramowania pośredniczącego Fiscal Middleware na komputerze, działającego w formie usługi systemu Windows, dostęp do opisu interfejsu api można uzyskać pod adresem http://localhost:7678/swagger/index.html.
W przypadku instalacji na komputerze zdalnym (np. w sieci LAN) należy użyć adresu IP systemu, na którym zainstalowano middleware, zamiast „localhost”.
Wszystkie punkty końcowe middleware są opisane w dokumentacji swagger. Dla przesyłania dokumentów (np. dowodów kasowych) istotne są punkty końcowe z sekcji „Transakcje”.
Przesyłanie dokumentów jest zawsze procesem dwuetapowym, który rozpoczyna się od wywołania
- „createDocument”, a kończy się albo
- „storeDocument”, albo „cancelDocument” – w przypadku anulowania dokumentu.
Proces przesyłania dokumentów został szczegółowo wyjaśniony tutaj: Podstawowy proces przesyłania dokumentów – RetailForce Software GmbH.
2.5 Fiscal Service Client Sample
Firma RetailForce udostępnia przykładowy program o nazwie „Fiscal Service Client Sample”. Zawiera on wskazówki dotyczące tworzenia struktury JSON, w której dokumenty są przesyłane do serwisu Fiscal Service.
Przykładowy program „Fiscal Service Client Sample” można wykorzystać do generowania przykładów różnych typów dokumentów i scenariuszy biznesowych.
Opis programu można znaleźć pod adresem: Fiscal Service Client Sample – RetailForce Software GmbH.
Przykłady różnych dokumentów i przypadków biznesowych można również znaleźć w Centrum Rozwiązań pod adresem: Transakcje biznesowe – RetailForce Software GmbH.
2.6 Lista punktów końcowych
Poniżej opisano punkty końcowe, które należy w każdym przypadku zaimplementować.
| Punkt końcowy | Opis |
| PUT /api/va/management/clients | konieczne wyłącznie w przypadku, gdy konfiguracja klienta ma być przeprowadzona z poziomu oprogramowania POS, a nie z poziomu systemu w chmurze. Alternatywa: PUT /api/v1/management/clients/byCloud |
| PUT /api/v1/management/clients/byCloud | Konieczne, jeśli konfiguracja klienta ma zostać przeprowadzona z poziomu systemu w chmurze. Alternatywa: PUT /api/va/management/clients |
| POST /api/v1/management/cloud/connect | ustanawia połączenie klienta z chmurą. Należy to wykonać po każdym ponownym uruchomieniu komputera (systemu). Dane wymagane do ustanowienia połączenia z chmurą (klucz API i API Secret) muszą być przechowywane przez elektroniczny system rejestracji. |
| POST /api/v1/management/clients/initialize | Inicjuje klienta lub wszelki niezbędny sprzęt fiskalny (techniczne urządzenie zabezpieczające, moduł generowania podpisu, drukarkę itp.). Do inicjalizacji wymagany jest dokument startowy. Można go wygenerować za pomocą elektronicznego systemu rejestracji lub automatycznie poprzez middleware, korzystając z punktu końcowego GET /api/v1/transactions/document/{clientId}/start. |
| GET /api/v1/transactions/document/{clientId}/start | Zalecane. Tworzy tzw. dokument startowy dla konkretnego klienta w celu jego inicjalizacji. |
| PUT /api/v1/transactions/createDocument | Metoda ta sama w sobie nie tworzy dokumentu, a jedynie uruchamia proces, na przykład na urządzeniu TSE (Technical Security Device) w Niemczech. (Wymagane w każdym kraju!) |
| POST /api/v1/transactions/storeDocument | Zapisuje dany dokument |
| POST /api/v1/transactions/cancelDocument | Anuluje dokument w jednostce fiskalnej. |
Ten artykuł został przetłumaczony automatycznie.
Komentarze
Komentarze: 0
Zaloguj się, aby dodać komentarz.