Ta članek opisuje, kako uporabljati datotečni vmesnik fiskalne storitve.

Predpogoji

• FiskalClient, različica 1.2.11 ali novejša
• FiscalClient kot storitev (izvedbe iz nuget niso podprte)

Podprte države

Trenutno so prek vmesnika za datoteke podprte le spodaj navedene države:

• Avstrija
• Danska (od različice 1.3)

Dodatne informacije

Datotečni vmesnik podpira le zelo omejen obseg funkcionalnosti fiskalnega klienta za prenos podatkov, potrebnih za fiskalizacijo. Če so potrebni bolj specifični ukazi, je storitev mogoče integrirati z orodji, kot je CURL, prek vmesnika REST. Vendar to v tem članku ni pojasnjeno.

Aktivacija

Datotečni vmesnik lahko omogočite na naslednji način:

• Nastavite pot do spremljanja v datoteki appsettings.json.
• Ustvarite mapo v C:\ProgramData\RetailForce\Fiscal web service z imenom »fileSystemInterface«.

appsettings.json

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

Vnosi pred in po tem niso vključeni v primer. »c:\temp\filesysteminterface« je nadzorovana pot.

Kako deluje

Datotečni vmesnik fiskalne storitve spremlja mapo za nove datoteke z določeno strukturo imen. Takoj ko se v tej mapi ustvari nova datoteka, ki ustreza konvencijam poimenovanja, se ta obdela.

Postopek

Postopek je naslednji:

1. Datoteka se prenese v imenik in prepozna (*.request)
2. Datoteka se obdeluje
3. Datoteka *.response ali *.error se shrani v imenik »response« (podimenik uvoznega imenika) (isto ime datoteke pred končnico).

Primer

1. Prenesena je datoteka 20220308135010236.document.request
2. Datoteka se obdeluje
3. Datoteka response/20220308135010236.document.response je shranjena. 

ali v primeru napake

1. 20220308135010236.document.request je prenesen
2. Datoteka se obdeluje
3. Datoteka response/20220308135010236.document.error je shranjena. 

Odgovornosti

Obdelane datoteke zahtevkov se prek vmesnika za datoteke premaknejo v podmapo »processed«.

Datotečni vmesnik nikoli ne bo izbrisal nobene datoteke. Vendar se priporoča, da se starejše datoteke (prepoznavne po datumu) po določenem času arhivirajo.

Zagotavljanje pravilnega zaporedja

Zaporedje obdelave je zagotovljeno z edinstvenim imenom datoteke, po katerem je mogoče datoteke razvrstiti.

Struktura imena datoteke

YYYYMMDDHHNNSSZZZ.{type}.request

LLLL = leto (2022), obseg vrednosti: 2022–3000

MM = mesec (03 za marec), obseg vrednosti: 01–12

DD = dan (02 za 2. v mesecu), območje vrednosti: 01–31

HH = ura v 24-urnem zapisu, obseg vrednosti: 00–23

NN = minute (04 za 4 minute), obseg vrednosti: 00–59

SS = sekunde (05 za 5 sekund), območje vrednosti: 00–59

ZZZ = milisekunde (010 za 10 milisekund), obseg vrednosti: 000–999

Tip

{type} označuje vrsto zahtevka, na voljo so naslednje vrste:

• document – za pošiljanje potrdila
• validateDocument – za preverjanje veljavnosti potrdila
• command – za izvedbo ukaza

Dokumentacija o tipih/modelih

Za več informacij o modelu dokumenta in ustreznih odgovorih si oglejte dokumentacijo o objektnem modelu ter dokumentacijo swagger za Fiscal Client (http://localhost:7678/swagger/index.html).

Vrnitev napake je enaka za vse tipe: izjema, ki je bila sprožena, se vrne v datoteki (*.error).

Tip »document« – pošiljanje potrdil

Vsebina datoteke je v tem primeru dokument v formatu RetailForce (Document).

Obliko dokumenta si lahko ogledate v dokumentaciji o objektnem modelu ali v dokumentaciji swagger na spletni strani fiskalne storitve (http://localhost:7678/swagger/index.html).

Odgovor

V datoteki z odgovori se prenese fiscalResponse zadevne države.

Tip »validateDocument« – preverjanje veljavnosti potrdila

Vsebina datoteke je v tem primeru, tako kot pri tipu »document«, dokument v formatu RetailForce.

Povratni odgovor

V datoteki z odgovorom se vrne morebitni seznam napak (in opozoril) iz preverjanja veljavnosti.

Tip »createClient« – ustvarjanje FiscalClient

Vsebina datoteke je v tem primeru FiscalClient v formatu JSON (glej dokumentacijo).

Vrnitev

»OK«, če je bila zahteva uspešno obdelana.

Tip »createClientByCloud« – ustvarjanje objekta FiscalClient s podatki iz Cloud

Vsebina datoteke je dokument v formatu JSON z naslednjo strukturo:

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

Vrni

UniqueClientId ustvarjenega klienta.

Tip »restoreClientByCloud« – obnovitev FiscalClient s podatki iz Cloud

Vsebina datoteke je dokument v formatu JSON z naslednjo strukturo:

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

Vrnjena vrednost

UniqueClientId obnovljene stranke.

Tip »getClientId« – iskanje stranke in pridobivanje ID-ja

Na voljo od: V1.2.12

Vsebina datoteke je dokument v formatu JSON z naslednjo strukturo:

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

Vrnjeno

UniqueClientId ustvarjene stranke.

Vnesite »InitializeClient« – inicializacija FiscalClient

Vsebina datoteke je dokument v formatu JSON z naslednjo strukturo:

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

Podatki so testni in jih je treba nadomestiti s pravimi podatki.

Vrnitev

Prazno ali objekt »fiscalResponse« za zadevno državo.

Tip »CloudConnect« – inicializacija povezave s Cloudom

Vsebina datoteke je dokument v formatu JSON z naslednjo strukturo:

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

Vrne

»OK«, če je bila zahteva uspešno obdelana.

Tip »AuditLog« – pošiljanje vnosa v revizijski dnevnik

Vsebina datoteke je JSON-objekt z naslednjo strukturo:

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

Vrni

Prazno ali objekt fiscalResponse zadevne države (če je to tam zahtevano).

Tip »digitalReceipt« – pošiljanje digitalnega računa

Ta tip datoteke se lahko uporabi za oddajo digitalnega računa. 

Vsebina datoteke je JSON-objekt z naslednjo strukturo:

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

Lastnost »ReceiptMetaData« je objekt ReceiptMetaData, ki ga je treba posredovati tudi pri klicu prek vmesnika REST. 

V primeru je bil stream podatkov PDF v primeru skrajšan z ...

Vrnitev

V vrnjeni datoteki se vrne povezava QrCode (kot string) za prikaz stranki.

Konfiguracija

Vmesnik datotečnega sistema se lahko aktivira v konfiguraciji odjemalca z vrednostjo v polju »FiscalClient.FileSystemInterfacePath«. Če je to polje prazno (privzeto), vmesnik datotečnega sistema ni aktiven.

Ta članek je bil samodejno preveden.