Tento článok popisuje, ako používať súborové rozhranie daňovej služby.

Predpoklady

• FiskalClient vo verzii 1.2.11 alebo novšej
• FiscalClient ako služba (implementácie cez nuget nie sú podporované)

Podporované krajiny

V súčasnosti sú prostredníctvom súborového rozhrania podporované len nižšie uvedené krajiny:

• Rakúsko
• Dánsko (od verzie 1.3)

Ďalšie informácie

Súborové rozhranie podporuje len veľmi obmedzený rozsah funkcií daňového klienta na odosielanie údajov potrebných na daňovú evidenciu. Ak potrebujete špecifickejšie príkazy, službu je možné integrovať s nástrojmi ako CURL prostredníctvom rozhrania REST. To však nie je vysvetlené v tomto článku.

Aktivácia

Rozhranie súborového systému je možné aktivovať nasledovne:

• Nastavením cesty k monitorovaniu v súbore appsettings.json.
• Vytvorením adresára v umiestnení C:\ProgramData\RetailForce\Fiscal web service s názvom „fileSystemInterface“.

appsettings.json

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

Záznamy pred a za týmto riadkom nie sú v príklade uvedené. „c:\temp\filesysteminterface“ je monitorovaná cesta.

Ako to funguje

Súborové rozhranie daňovej služby monitoruje adresár na prítomnosť nových súborov s určitou štruktúrou názvov. Akonáhle sa v tomto adresári vytvorí nový súbor zodpovedajúci konvenciám pomenovania, je spracovaný.

Postup

Postup je nasledovný:

1. Súbor sa prenesie do adresára a rozpozná (*.request)
2. Súbor sa spracúva
3. Súbor *.response alebo *.error sa uloží do adresára „response“ (podadresár adresára importu) (rovnaký názov súboru pred príponou).

Príklad

1. Prenáša sa súbor 20220308135010236.document.request
2. Súbor sa spracúva
3. Súbor response/20220308135010236.document.response je uložený. 

alebo v prípade chyby

1. 20220308135010236.document.request je odoslaný
2. Súbor sa spracúva
3. Súbor response/20220308135010236.document.error je uložený. 

Zodpovednosti

Spracované súbory žiadostí sú prostredníctvom súborového rozhrania presunuté do podadresára „processed“.

Súborové rozhranie nikdy nevymaže žiadne súbory. Odporúča sa však po uplynutí určitého času archivovať staršie súbory (rozpoznateľné podľa dátumu).

Zabezpečenie správneho poradia

Poradie spracovania je zabezpečené jedinečným názvom súboru, ktorý je možné zoradiť.

Štruktúra názvu súboru

RRRRMMDDHHNNSSZZZ.{typ}.request

RRRR = rok (2022), rozsah hodnôt: 2022–3000

MM = mesiac (03 pre marec), rozsah hodnôt: 01–12

DD = deň (02 pre 2. deň v mesiaci), rozsah hodnôt: 01–31

HH = hodina v 24-hodinovom formáte, rozsah hodnôt: 00–23

NN = Minúty (04 pre 4 minúty), rozsah hodnôt: 00–59

SS = sekundy (05 pre 5 sekúnd), rozsah hodnôt: 00–59

ZZZ = milisekundy (010 pre 10 milisekúnd), rozsah hodnôt: 000–999

Typ

{type} označuje typ požiadavky, existujú nasledujúce typy:

• document – na odoslanie potvrdenia
• validateDocument – na overenie potvrdenia
• command – na vykonanie príkazu

Dokumentácia typu / modelu

Ďalšie informácie o modeli dokumentu a príslušných odpovediach nájdete v dokumentácii k objektovému modelu a v dokumentácii swagger k aplikácii Fiscal Client (http://localhost:7678/swagger/index.html).

Vrátená chyba je pre všetky typy rovnaká: Vyvolaná výnimka sa vráti v súbore (*.error).

Typ „document“ – odosielanie potvrdeniek

Obsahom súboru je v tomto prípade dokument vo formáte RetailForce (Document).

Formát dokumentu si môžete prečítať v dokumentácii objektového modelu alebo v dokumentácii swagger na stránke daňovej služby (http://localhost:7678/swagger/index.html).

Odpoveď

V súbore s odpoveďou sa odosiela fiscalResponse príslušnej krajiny.

Typ „validateDocument“ – overovanie dokladu

Obsahom súboru je v tomto prípade, rovnako ako pri type „document“, dokument vo formáte RetailForce.

Odpoveď

V súbore s odpoveďou sa vráti prípadný zoznam chýb (a varovaní) z overovania.

Typ „createClient“ – vytvorenie FiscalClient

Obsahom súboru je v tomto prípade objekt FiscalClient vo formáte JSON (pozri dokumentáciu).

Návrat

„OK“, ak bola požiadavka úspešne spracovaná.

Typ „createClientByCloud“ – vytvorenie objektu FiscalClient s údajmi z Cloudu

Obsahom súboru je dokument vo formáte JSON s nasledujúcou štruktúrou:

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

Vráti

UniqueClientId vytvoreného klienta.

Typ „restoreClientByCloud“ – obnovenie FiscalClient s údajmi z Cloudu

Obsah súboru je dokument JSON s nasledujúcou štruktúrou:

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

Výsledok

UniqueClientId obnoveného klienta.

Typ „getClientId“ – vyhľadanie klienta a získanie ID

Dostupné od verzie: V1.2.12

Obsah súboru je dokument JSON s nasledujúcou štruktúrou:

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

Vrátená hodnota

UniqueClientId vytvoreného klienta.

Typ „InitializeClient“ – inicializácia FiscalClient

Obsah súboru je dokument vo formáte JSON s nasledujúcou štruktúrou:

{
  "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é údaje sú testovacie a je potrebné ich nahradiť správnymi údajmi.

Vrátená hodnota

Buď prázdna, alebo objekt fiscalResponse príslušnej krajiny.

Typ „CloudConnect“ – inicializácia pripojenia k cloudu

Obsah súboru je dokument JSON s nasledujúcou štruktúrou:

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

Vrátená hodnota

„OK“, ak bola požiadavka úspešne spracovaná.

Typ „AuditLog“ – odosielanie záznamu v audítorskom protokole

Obsah súboru je objekt JSON s nasledujúcou štruktúrou:

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

Vráti

Buď prázdne, alebo objekt fiscalResponse príslušnej krajiny (ak je to tam vyžadované).

Typ „digitalReceipt“ – odoslanie digitálnej účtenky

Tento typ súboru sa môže použiť na odoslanie digitálnej účtenky. 

Obsah súboru je objekt JSON s nasledujúcou štruktúrou:

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

Vlastnosť „ReceiptMetaData“ je objekt ReceiptMetaData, ktorý sa má odoslať aj pri volaní cez rozhranie REST. 

V príklade bol dátový stream PDF skrátený znakmi „...“.

Výstup

V návratovom súbore sa vráti odkaz QrCode (ako string) na zobrazenie zákazníkovi.

Konfigurácia

Rozhranie súborového systému je možné aktivovať v konfigurácii klienta pomocou hodnoty v poli FiscalClient.FileSystemInterfacePath. Ak je toto pole prázdne (predvolené nastavenie), rozhranie súborového systému nie je aktívne.

Tento článok bol preložený automaticky.