Šiame straipsnyje aprašoma, kaip galima naudoti Fiskaliojo tarnybos failų sąsają.

Reikalavimai

• „FiskalClient“ nuo versijos 1.2.11
• „FiskalClient“ kaip paslauga (Nuget įgyvendinimai nepalaikomi)

Palaikomos šalys

Šiuo metu per failų sąsają palaikomos tik toliau išvardytos šalys:

• Austrija
• Danija (nuo versijos 1.3)

Papildoma informacija

Failų sąsaja palaiko tik labai nedidelę fiskalinio kliento funkciją, skirtą perduoti reikiamus fiskalizavimo duomenis. Jei reikalingos konkretesnės komandos, paslaugą galima integruoti naudojant tokias priemones kaip CURL per REST sąsają. Tačiau tai šiame straipsnyje neaptariama.

Aktyvavimas

Failų sąsają galima aktyvuoti taip:

• Nustatykite stebėjimo kelią failo „appsettings.json“
• Sukurti katalogą C:\ProgramData\RetailForce\Fiscal Webservice su pavadinimu „fileSystemInterface“

appsettings.json

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

Pavyzdyje nėra pateikti įrašai prieš ir po. „c:\temp\filesysteminterface“ yra stebimas kelias.

Veikimo principas

Fiskalinės paslaugos failų sąsaja stebi katalogą, ieškodama naujų failų su tam tikra pavadinimo struktūra. Kai tik šiame kataloge sukuriama nauja failas, atitinkantis pavadinimo taisykles, jis apdorojamas.

Eiga

Eiga yra tokia:

1. Failas perduodamas į katalogą ir atpažįstamas (*.request)
2. Failas apdorojamas
3. Kataloge „response“ (importo katalogo pakatalogis) įrašomas *.response arba *.error failas (tas pats failo pavadinimas prieš plėtinį)

Pavyzdys

1. Perkeliamas failas 20220308135010236.document.request
2. Failas apdorojamas
3. Įrašomas failas response/20220308135010236.document.response.

arba, jei įvyksta klaida

1. 20220308135010236.document.request perduodamas
2. Failas apdorojamas
3. Failas „response/20220308135010236.document.error“ yra išsaugomas.

Atsakomybė

Apdoroti užklausos failai iš failų sąsajos perkeliami į pakatalogį „processed“.

Failų sąsaja niekada neištrina failų. Tačiau rekomenduojama senesnius failus (atpažįstamus pagal datą) po tam tikro laiko archyvuoti.

Teisingos tvarkos užtikrinimas

Apdorojimo eiliškumas. Tai užtikrinama naudojant aiškiai rūšiuojamą failo pavadinimą.

Failo pavadinimo struktūra

YYYYMMDDHHNNSSZZZ.{type}.request

YYYY = metai (2022), verčių diapazonas: 2022–3000

MM = mėnuo (03 – kovo mėn.), verčių diapazonas: 01–12

DD = diena (02 reiškia 2-ą mėnesio dieną), reikšmių diapazonas: 01–31

HH = valandos 24 valandų formatu, verčių diapazonas: 00–23

NN = minutės (04 reiškia 4 minutes), verčių diapazonas: 00–59

SS = sekundės (05 reiškia 5 sekundes), reikšmių diapazonas: 00–59

ZZZ = milisekundės (010 reiškia 10 milisekundžių), reikšmių diapazonas: 000–999

Type

{type} nurodo užklausos tipą, yra šie tipai:

• document – dokumento perdavimui
• validateDocument – dokumento patvirtinimui
• command – komandos vykdymui

Tipų dokumentacija

Išsamesnę informaciją apie dokumentų modelį ir atitinkamus atsakymus rasite objektų modelio dokumentacijoje bei fiskalinio kliento „Swagger“ dokumentacijoje (http://localhost:7678/swagger/index.html).

Klaidų grąžinimas visų tipų atveju yra vienodas: iššaukta išimtis grąžinama grąžinimo faile (*.error).

Tipas „document“ – dokumento perdavimas

Šiuo atveju failo turinys yra dokumentas „RetailForce“ dokumento formatu (Document).

Dokumentų formatą galima rasti „Object Model Documentation“ arba „Swagger Documentation“ fiskalinėje tarnyboje (http://localhost:7678/swagger/index.html).

Grąžinimas

Grąžinamajame faile perduodamas atitinkamos šalies „FiscalResponse“.

Tipas „validateDocument“ – kvito patvirtinimas

Šiuo atveju failo turinys, kaip ir tipo „document“ atveju, yra kvitas „RetailForce“ dokumento formatu.

Grąžinimas

Grąžinimo faile pateikiamas galimas patikrinimo klaidų (ir įspėjimų) sąrašas.

Tipas „createClient“ – „FiscalClient“ sukūrimas

Šiuo atveju failo turinys yra „FiscalClient“ kaip json (žr. dokumentaciją).

Grąžinimas

„OK“, jei užklausa buvo sėkmingai apdorota.

Tipas „createClientByCloud“ – FiskalCliento sukūrimas naudojant debesies duomenis

Failo turinys yra json dokumentas, kurio struktūra yra tokia:

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

Grąžinimas

Sukurto kliento „UniqueClientId“.

Tipas „restoreClientByCloud“ – FiskalClient atkūrimas naudojant debesies duomenis

Failo turinys yra JSON dokumentas, kurio struktūra yra tokia:

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

Grąžinimas

Atkurto kliento unikalus identifikatorius (UniqueClientId).

Tipas „getClientId“ – kliento paieška ir ID grąžinimas

Galima naudoti nuo V1.2.12 versijos.

Failo turinys yra JSON dokumentas, kurio struktūra yra tokia:

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

Grąžinimas

Sukurto kliento unikalus identifikatorius (UniqueClientId).

Tipas „initializeClient“ – FiskalClients inicijavimas

Failo turinys yra JSON dokumentas, kurio struktūra yra tokia:

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

Nurodyti duomenys yra bandomieji ir turi būti pakeisti tikraisiais duomenimis.

Grąžinimas

Tuščias arba atitinkamos šalies „FiscalResponse“ objektas.

Tipas „cloudConnect“ – debesies ryšio inicijavimas

Failo turinys yra JSON dokumentas, kurio struktūra yra tokia:

{
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}",
  "PersistDays": {Tage} //optional, die Anzahl der Tage zum Speichern der Credentials
}

Grąžinimas

„OK“, jei užklausa buvo sėkmingai apdorota.

Tipas „auditLog“ – audito žurnalo įrašo perdavimas

Failo turinys yra JSON objektas, kurio struktūra yra tokia:

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

Grąžinimas

Tuščias arba atitinkamos šalies „FiscalResponse“ objektas (jei ten reikalaujama).

Tipas „digitalReceipt“ – perduoti skaitmeninį kvitą

Naudojant šį failo tipą galima perduoti skaitmeninį kvitą. 

Failo turinys yra JSON objektas, kurio struktūra yra tokia:

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

Savybė „ReceiptMetaData“ yra „ReceiptMetaData“ objektas, kuris taip pat turi būti perduotas, kai kreipiamasi per REST sąsają. 

Pavyzdyje PDF duomenų srautas buvo sutrumpintas simboliais ...

Grąžinimas

Grąžinamajame faile grąžinama QRCode nuoroda (kaip eilutė), skirta rodyti klientui.

Konfigūracija

Failų sistemos sąsaja gali būti aktyvuota kliento konfigūracijoje, įvedant reikšmę laukelyje „FiscalClient.FileSystemInterfacePath“. Jei šis laukelis yra tuščias (numatyta reikšmė), failų sąsaja taip pat nėra aktyvi.