Tento článek popisuje, jak používat souborové rozhraní fiskální služby.

Předpoklady

• FiskalClient od verze 1.2.11
• FiscalClient jako služba (implementace přes NuGet nejsou podporovány)

Podporované země

V současné době jsou prostřednictvím souborového rozhraní podporovány pouze níže uvedené země:

• Rakousko
• Dánsko (od verze 1.3)

Další informace

Souborové rozhraní podporuje pouze velmi omezený rozsah funkcí fiskálního klienta pro přenos dat nezbytných pro fiskalizaci. Pokud jsou požadovány specifičtější příkazy, lze službu stále integrovat s nástroji jako CURL prostřednictvím rozhraní REST. To však není v tomto článku vysvětleno.

Aktivace

Rozhraní souborového systému lze aktivovat následujícím způsobem:

• Nastavením cesty k monitorování v souboru appsettings.json.
• Vytvořením adresáře pod C:\ProgramData\RetailForce\Fiscal web service s názvem „fileSystemInterface“.

appsettings.json

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

Zápisy před a za tímto příkladem nejsou v příkladu uvedeny. „c:\temp\filesysteminterface“ je sledovaná cesta.

Jak to funguje

Souborové rozhraní fiskální služby sleduje adresář, zda se v něm neobjeví nové soubory s určitou strukturou názvů. Jakmile je v tomto adresáři vytvořen nový soubor odpovídající konvencím pojmenování, je zpracován.

Postup

Postup je následující:

1. Soubor je přenesen do adresáře a rozpoznán (*.request)
2. Soubor se zpracovává
3. Soubor *.response nebo *.error se uloží do adresáře „response“ (podadresář adresáře importu) (stejný název souboru před příponou).

Příklad

1. Přenesen je soubor 20220308135010236.document.request
2. Soubor se zpracovává
3. Soubor response/20220308135010236.document.response je uložen. 

nebo v případě chyby

1. 20220308135010236.document.request je přenášeno
2. Soubor se zpracovává
3. Soubor response/20220308135010236.document.error je uložen. 

Odpovědnosti

Zpracované soubory požadavků jsou přesunuty do podadresáře „processed“ prostřednictvím rozhraní pro práci se soubory.

Souborové rozhraní nikdy žádné soubory nemaže. Doporučuje se však starší soubory (rozpoznatelné podle data) po určité době archivovat.

Zajištění správného pořadí

Pořadí zpracování je zajištěno jedinečným, tříditelným názvem souboru.

Struktura názvu souboru

YYYYMMDDHHNNSSZZZ.{type}.request

YYYY = rok (2022), rozsah hodnot: 2022–3000

MM = měsíc (03 pro březen), rozsah hodnot: 01–12

DD = den (02 pro 2. den v měsíci), rozsah hodnot: 01–31

HH = hodina v 24hodinovém formátu, rozsah hodnot: 00–23

NN = minuty (04 pro 4 minuty), rozsah hodnot: 00–59

SS = sekundy (05 pro 5 sekund), rozsah hodnot: 00–59

ZZZ = milisekundy (010 pro 10 milisekund), rozsah hodnot: 000–999

Typ

{type} označuje typ požadavku, existují následující typy:

• document – pro odeslání potvrzení
• validateDocument – k ověření potvrzení
• command – k provedení příkazu

Dokumentace typu / modelu

Další informace o modelu dokumentu a odpovídajících odpovědích naleznete v dokumentaci k objektovému modelu a v dokumentaci Swagger k fiskálnímu klientovi (http://localhost:7678/swagger/index.html).

Vrácení chyb je u všech typů stejné: Vyvolaná výjimka je vrácena v souboru (*.error).

Typ „document“ – přenos účtenek

Obsahem souboru je v tomto případě dokument ve formátu RetailForce (Document).

Formát dokumentu lze najít v dokumentaci k objektovému modelu nebo v dokumentaci Swagger na stránkách fiskální služby (http://localhost:7678/swagger/index.html).

Odpověď

V souboru s odpovědí je odeslána FiscalResponse příslušné země.

Typ „validateDocument“ – ověření účtenky

Obsahem souboru je v tomto případě, stejně jako u typu „document“, dokument ve formátu RetailForce.

Odpověď

V souboru s odpovědí je vrácen případný seznam chyb (a varování) z ověření.

Typ „createClient“ – vytvoření FiscalClient

Obsahem souboru je v tomto případě objekt FiscalClient ve formátu JSON (viz dokumentace).

Návrat

„OK“, pokud byl požadavek úspěšně zpracován.

Typ „createClientByCloud“ – vytvoření objektu FiscalClient s daty z Cloudu

Obsah souboru je dokument ve formátu JSON s následující strukturou:

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

Vrátí

UniqueClientId vytvořeného klienta.

Typ „restoreClientByCloud“ – obnovení objektu FiscalClient s daty z Cloudu

Obsah souboru je dokument JSON s následující strukturou:

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

Návrat

UniqueClientId obnoveného klienta.

Typ „getClientId“ – vyhledání klienta a načtení ID

K dispozici od verze: V1.2.12

Obsah souboru je dokument ve formátu JSON s následující strukturou:

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

Návrat

Jedinečné ID klienta (UniqueClientId) vytvořeného klienta.

Typ „initializeClient“ – inicializace FiscalClient

Obsah souboru tvoří dokument JSON s následující strukturou:

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

Uvedená data jsou testovací a je třeba je nahradit správnými údaji.

Návrat

Buď prázdná hodnota, nebo objekt FiscalResponse příslušné země.

Typ „cloudConnect“ – inicializace připojení k Cloud

Obsah souboru je dokument ve formátu JSON s následující strukturou:

{
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}",
  "PersistDays": {days} // optional, days until credentials are stored 
}

Návrat

„OK“, pokud byl požadavek úspěšně zpracován.

Typ „auditLog“ – přenos záznamu v auditovém protokolu

Obsah souboru je objekt JSON s následující strukturou:

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

Vrátí

Buď prázdné, nebo objekt „FiscalResponse“ příslušné země (je-li to v dané zemi vyžadováno).

Typ „digitalReceipt“ – odeslání digitální účtenky

Tento typ souboru lze použít k odeslání digitální účtenky. 

Obsahem souboru je objekt JSON s následující strukturou:

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

Vlastnost „ReceiptMetaData“ představuje objekt ReceiptMetaData, který je třeba předat i při volání přes rozhraní REST. 

V příkladu byl datový tok PDF zkrácen pomocí znaků „...“.

Návrat

Ve vráceném souboru je vrácen odkaz na QR kód (ve formě řetězce) pro zobrazení zákazníkovi.

Konfigurace

Rozhraní souborového systému lze aktivovat v konfiguraci klienta zadáním hodnoty do pole „FiscalClient.FileSystemInterfacePath“. Je-li toto pole prázdné (výchozí nastavení), rozhraní souborového systému není aktivní.

Tento článek byl přeložen automaticky.