Przejdź do głównej zawartości

Interfejs systemu plików

DEVELOPMENT
  • Zaktualizowano

W niniejszym artykule opisano sposób korzystania z interfejsu plikowego usługi fiskalnej.

Wymagania wstępne

  • FiskalClient w wersji 1.2.11 lub nowszej
  • FiscalClient jako usługa (implementacje z pakietu nuget nie są obsługiwane)

Obsługiwane kraje

Obecnie za pośrednictwem interfejsu plikowego obsługiwane są wyłącznie kraje wymienione poniżej:

  • Austria
  • Dania (od wersji 1.3)

Dodatkowe informacje

Interfejs plików obsługuje jedynie bardzo wąski zakres funkcji klienta fiskalnego, niezbędny do przesyłania danych wymaganych do celów fiskalnych. Jeśli potrzebne są bardziej szczegółowe polecenia, usługę można nadal zintegrować z narzędziami takimi jak CURL za pośrednictwem interfejsu REST. Nie zostało to jednak omówione w niniejszym artykule.

Aktywacja

Interfejs plikowy można włączyć w następujący sposób:

  • Ustawienie ścieżki do monitorowania w pliku appsettings.json.
  • Utworzenie katalogu o nazwie „fileSystemInterface” w lokalizacji C:\ProgramData\RetailForce\Fiscal web service.

Uwaga: Aby aktywować system, po wprowadzeniu tych ustawień należy ponownie uruchomić usługę.

appsettings.json

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

W przykładzie nie uwzględniono wpisów znajdujących się przed i po tej sekcji. „c:\temp\filesysteminterface” to ścieżka podlegająca monitorowaniu.

Uwaga: Monitorowany folder musi być folderem lokalnym. Dyski sieciowe nie są obsługiwane, ponieważ systemy monitorowania plików często nie działają w tym przypadku niezawodnie.

Jak to działa

Interfejs plików usługi fiskalnej monitoruje katalog pod kątem nowych plików o określonej strukturze nazw. Gdy tylko w tym katalogu zostanie utworzony nowy plik zgodny z konwencjami nazewniczymi, jest on przetwarzany.

Uwaga: W przypadku większych plików zaleca się najpierw zapisanie pliku w katalogu jako plik tymczasowy, a następnie zmianę jego nazwy na prawidłową za pomocą funkcji RENAME.

Procedura

Procedura przebiega następująco:

  1. Plik zostaje przeniesiony do katalogu i rozpoznany (*.request)
  2. Plik jest przetwarzany
  3. Plik *.response lub *.error jest zapisywany w katalogu „response” (podkatalogu katalogu importu) (ta sama nazwa pliku przed rozszerzeniem).

Przykład

  1. Przesyłany jest plik 20220308135010236.document.request
  2. Plik jest przetwarzany
  3. Plik response/20220308135010236.document.response został zapisany. 

lub w przypadku błędu

  1. Plik 20220308135010236.document.request został przesłany
  2. Plik jest przetwarzany
  3. Plik response/20220308135010236.document.error został zapisany. 

Obowiązki

Przetworzone pliki żądań są przenoszone przez interfejs plików do podkatalogu „processed”.

Interfejs plików nigdy nie usuwa żadnych plików. Zaleca się jednak archiwizowanie starszych plików (rozpoznawalnych po dacie) po upływie określonego czasu.

Zapewnienie prawidłowej kolejności

Kolejność przetwarzania jest zapewniona dzięki unikalnej, sortowalnej nazwie pliku.

Struktura nazwy pliku

RRRRMMDDHHNNSSZZZ.{typ}.request

RRRR = rok (2022), zakres wartości: 2022–3000

MM = miesiąc (03 dla marca), zakres wartości: 01–12

DD = dzień miesiąca (02 oznacza 2. dzień miesiąca), zakres wartości: 01–31

HH = godzina w formacie 24-godzinnym, zakres wartości: 00–23

NN = minuty (04 oznacza 4 minuty), zakres wartości: 00–59

SS = sekundy (05 oznacza 5 sekund), zakres wartości: 00–59

ZZZ = milisekundy (010 oznacza 10 milisekund), zakres wartości: 000–999

Typ

{type} określa typ żądania; dostępne są następujące typy:

  • document – w celu przesłania pokwitowania
  • validateDocument – w celu weryfikacji potwierdzenia
  • command – w celu wykonania polecenia

Dokumentacja typu / modelu

Więcej informacji na temat modelu dokumentu oraz odpowiadających mu odpowiedzi można znaleźć w dokumentacji modelu obiektowego oraz dokumentacji swagger klienta Fiscal (http://localhost:7678/swagger/index.html).

Sposób zwracania błędów jest taki sam dla wszystkich typów: wyrzucony wyjątek jest zwracany w pliku zwrotnym (*.error).

Typ „document” – przesyłanie paragonów

W tym przypadku zawartość pliku stanowi dokument w formacie RetailForce (Document).

Format dokumentu można sprawdzić w dokumentacji modelu obiektowego lub w dokumentacji swagger w serwisie Fiscal Client (http://localhost:7678/swagger/index.html).

Odpowiedź

W pliku zwrotnym przekazywana jest odpowiednia dla danego kraju odpowiedź fiscalResponse.

Typ „validateDocument” – weryfikacja paragonu

Zawartością pliku w tym przypadku jest, podobnie jak w przypadku typu „document”, dokument w formacie RetailForce.

Odpowiedź

W pliku zwrotnym zwracana jest ewentualna lista błędów (i ostrzeżeń) wynikających z walidacji.

Typ „createClient” – utworzenie obiektu FiscalClient

W tym przypadku zawartością pliku jest obiekt FiscalClient w formacie JSON (zob. dokumentacja).

Odpowiedź

„OK”, jeśli żądanie zostało pomyślnie przetworzone.

Typ „createClientByCloud” – tworzenie obiektu FiscalClient na podstawie danych z Cloud

Zawartość pliku stanowi dokument JSON o następującej strukturze:

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

Wartość zwracana

Unikalny identyfikator klienta (uniqueClientId) utworzonego klienta.

Typ „restoreClientByCloud” – przywracanie obiektu FiscalClient na podstawie danych z Cloud

Zawartość pliku stanowi dokument JSON o następującej strukturze:

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

Wynik

Unikalny identyfikator klienta (uniqueClientId) przywróconego klienta.

Typ „getClientId” – wyszukiwanie klienta i pobieranie ID

Dostępne od wersji: V1.2.12

Zawartość pliku stanowi dokument JSON o następującej strukturze:

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

Zwraca

Unikalny identyfikator klienta (uniqueClientId) utworzonego klienta.

Wpisz „InitializeClient” – inicjalizacja FiscalClient

Zawartość pliku stanowi dokument JSON o następującej strukturze:

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

Podane dane mają charakter testowy i należy je zastąpić prawidłowymi danymi.

Wartość zwracana

Albo albo obiekt fiscalResponse dla danego kraju.

Typ „CloudConnect” – inicjalizacja połączenia z chmurą

Zawartość pliku stanowi dokument JSON o następującej strukturze:

{
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}",
  "PersistDays": {days} // optional, days until credentials are stored 
}
Uwaga: Dane uwierzytelniające są przechowywane w postaci zaszyfrowanej na dysku. Trwałe przechowywanie danych uwierzytelniających stanowi potencjalne zagrożenie dla bezpieczeństwa.

Zwraca

„OK”, jeśli żądanie zostało pomyślnie przetworzone.

Typ „AuditLog” – przesyłanie wpisu do dziennika audytowego

Zawartość pliku stanowi obiekt JSON o następującej strukturze:

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

Zwróć

Puste pole lub obiekt „fiscalResponse” odpowiedniego kraju (jeśli jest to wymagane w danym kraju).

Typ „digitalReceipt” – przesłanie cyfrowego paragonu

Ten typ pliku może służyć do przesłania cyfrowego paragonu. 

Zawartość pliku stanowi obiekt JSON o następującej strukturze:

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

Właściwość „ReceiptMetaData” to obiekt ReceiptMetaData, który należy również przekazać podczas wywołania za pośrednictwem interfejsu REST. 

W przykładzie stream danych PDF został skrócony za pomocą znaków „...”.

Odpowiedź

W pliku zwrotnym zwracany jest link w postaci kodu QrCode (jako string) przeznaczony do wyświetlenia klientowi.

Konfiguracja

Interfejs systemu plików można aktywować w konfiguracji klienta poprzez wprowadzenie wartości w polu „FiscalClient.FileSystemInterfacePath”. Jeśli pole to jest puste (ustawienie domyślne), interfejs plików nie jest aktywny.

Ten artykuł został przetłumaczony automatycznie.

Powiązane artykuły

Komentarze

Komentarze: 0

Zaloguj się, aby dodać komentarz.

Oparte na technologii Zendesk