Ovaj članak opisuje kako koristiti sučelje datoteka fiskalne usluge.

Preduvjeti

• FiskalClient od verzije 1.2.11
• FiscalClient kao usluga (nuget implementacije nisu podržane)

Podržane zemlje

Trenutno su putem sučelja za datoteke podržane samo zemlje navedene u nastavku:

• Austrija
• Danska (od verzije 1.3)

Dodatne informacije

Sučelje za datoteke podržava samo vrlo mali dio funkcionalnosti fiskalnog klijenta za slanje potrebnih podataka za fiskalizaciju. Ako su željene specifičnije naredbe, usluga se i dalje može integrirati s alatima poput CURL-a putem REST sučelja. Međutim, to nije objašnjeno u ovom članku.

Aktivacija

Sučelje datotečnog sustava može se omogućiti na sljedeći način:

• Postavljanje puta do nadzora u datoteci appsettings.json.
• Stvaranje direktorija pod C:\ProgramData\RetailForce\Fiscal web service s nazivom "fileSystemInterface".

appsettings.json

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

Unosi prije i poslije nisu uključeni u primjer. "c:\temp\filesysteminterface" je nadzirana putanja.

Kako radi

Interfejs datoteka fiskalne službe nadzire direktorij za nove datoteke s određenom strukturom imena. Čim se u tom direktoriju stvori nova datoteka koja odgovara konvencijama imenovanja, ona se obrađuje.

Obrada

Postupak je sljedeći:

1. Datoteka se prenosi u direktorij i prepoznaje (*.request)
2. Datoteka se obrađuje
3. Datoteka *.response ili *.error pohranjuje se u direktorij "response" (poddirektorij direktorija za uvoz) (isti naziv datoteke prije ekstenzije).

Primjer

1. 20220308135010236.document.request je prenesen
2. Datoteka se obrađuje
3. Datoteka response/20220308135010236.document.response je spremljena. 

ili u slučaju pogreške

1. 20220308135010236.document.request is transferred
2. Datoteka se obrađuje
3. Datoteka response/20220308135010236.document.error je spremljena. 

Odgovornosti

Obrađene datoteke zahtjeva premještaju se u poddirektorij "processed" putem sučelja za datoteke.

Sučelje za datoteke nikada neće izbrisati nijednu datoteku. Međutim, preporučuje se arhivirati starije datoteke (prepoznatljive po datumu) nakon određenog vremenskog razdoblja.

Osiguravanje ispravnog redoslijeda

Redoslijed obrade osigurava jedinstveno sortirano ime datoteke.

Struktura naziva datoteke

YYYYMMDDHHNNSSZZZ.{type}.request

GGGG = Godina (2022), raspon vrijednosti: 2022-3000

MM = Mjesec (03 za ožujak), raspon vrijednosti: 01-12

DD = Dan (02 za 2. u mjesecu), raspon vrijednosti: 01-31

HH = Sat u 24-satnom sustavu, raspon vrijednosti: 00-23

NN = minute (04 za 4 minute), raspon vrijednosti: 00-59

SS = Sekunde (05 za 5 sekundi), raspon vrijednosti: 00-59

ZZZ = milisekunde (010 za 10 milisekundi), raspon vrijednosti: 000-999

Tip

{type} označava vrstu zahtjeva, postoje sljedeće vrste:

• document - za slanje potvrde
• validateDocument - za provjeru potvrde
• command - za izvršavanje naredbe

Dokumentacija tipa / modela

Za više informacija o modelu dokumenata i odgovarajućim odgovorima pogledajte dokumentaciju modela objekata i Swagger dokumentaciju fiskalnog klijenta (http://localhost:7678/swagger/index.html).

Povrat pogreške je isti za sve tipove: Izuzetak koji je bačen vraća se u datoteku s povratom (*.error).

Tip "document" - prijenos računa

Sadržaj datoteke u ovom je slučaju dokument u formatu RetailForce (Document).

Format dokumenta može se pročitati u dokumentaciji modela objekata ili u Swagger dokumentaciji na fiskalnoj usluzi (http://localhost:7678/swagger/index.html).

Povrat

FiscalResponse dotične zemlje prenosi se u povratnoj datoteci.

Tip "validateDocument" - provjera valjanosti računa

Sadržaj datoteke u ovom je slučaju, kao i kod tipa "document", dokument u RetailForce formatu dokumenata.

Povrat

U povratnoj datoteci vraća se mogući popis pogrešaka (i upozorenja) iz validacije.

Tip "createClient" - stvaranje FiscalClienta

Sadržaj datoteke u ovom je slučaju FiscalClient u JSON formatu (vidi dokumentaciju).

Povrat

"OK" kada je zahtjev uspješno obrađen.

Tip "createClientByCloud" - stvaranje FiscalClient-a s podacima iz oblaka

Sadržaj datoteke je JSON dokument sa sljedećom strukturom:

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

Vratite

Jedinstveni ID klijenta koji je stvoren.

Tip "restoreClientByCloud" - obnavljanje FiscalClient-a s podacima iz oblaka

Sadržaj datoteke je JSON dokument sa sljedećom strukturom:

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

VraćaJedinstveni ID klijenta koji je stvoren.Tip "restoreClientByCloud

Jedinstveni ID klijenta (UniqueClientId) vraćenog klijenta.

Tip "getClientId" - pretraži klijenta i dohvati ID

Dostupno od: V1.2.12

Sadržaj datoteke je JSON dokument sa sljedećom strukturom:

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

Vraćanje

Jedinstveni ID klijenta (UniqueClientId) stvorenog klijenta.

Tip "initializeClient" - inicijalizacija FiscalClient-a

Sadržaj datoteke je JSON dokument sa sljedećom strukturom:

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

Navedeni podaci su testni i trebaju se zamijeniti ispravnim podacima.

Vraćanje

Bilo prazan ili objekt FiscalResponse odgovarajuće zemlje.

Tip "cloudConnect" - inicijalizacija Cloud veze

Sadržaj datoteke je JSON dokument sa sljedećom strukturom:

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

Vraćanje

"OK" kada je zahtjev uspješno obrađen.

Tip "auditLog" - prijenos unosa u evidenciji revizije

Sadržaj datoteke je JSON objekt sa sljedećom strukturom:

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

Vraćanje

Bilo prazno ili objekt FiscalResponse odgovarajuće zemlje (ako je tamo potrebno).

Tip "digitalReceipt" - Pošalji digitalni račun

Ova vrsta datoteke može se koristiti za slanje digitalne potvrde o kupnji. 

Sadržaj datoteke je JSON objekt sa sljedećom strukturom:

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

Svojstvo "ReceiptMetaData" je objekt ReceiptMetaData koji se također mora proslijediti pri pozivu putem REST sučelja. 

U primjeru je PDF tok podataka skraćen s ... u primjeru.

Povrat

U povratnoj datoteci vraća se QRCode poveznica (kao niz) za prikaz kupcu.

Konfiguracija

Sučelje datotečnog sustava može se aktivirati u konfiguraciji klijenta pomoću vrijednosti u polju FiscalClient.FileSystemInterfacePath. Ako je ovo polje prazno (zadano), sučelje datoteka nije aktivno.

Ovaj je članak automatski preveden.