Salt la conținutul principal

Interfața sistemului de fișiere

DEVELOPMENT
  • Actualizat

Acest articol descrie modul de utilizare a interfeței de fișiere a serviciului fiscal.

Cerințe preliminare

  • FiskalClient începând cu versiunea 1.2.11
  • FiscalClient ca serviciu (implementările nuget nu sunt acceptate)

Țări acceptate

În prezent, doar țările enumerate mai jos sunt acceptate prin intermediul interfeței de fișiere:

  • Austria
  • Danemarca (începând cu versiunea 1.3)

Informații suplimentare

Interfața de fișiere acceptă doar o gamă foarte restrânsă de funcționalități ale clientului fiscal pentru a transmite datele necesare fiscalizării. Dacă se doresc comenzi mai specifice, serviciul poate fi totuși integrat cu instrumente precum CURL prin intermediul interfeței REST. Totuși, acest aspect nu este explicat în acest articol.

Activare

Interfața de sistem de fișiere poate fi activată după cum urmează:

  • Setarea căii către monitorizare în appsettings.json.
  • Crearea unui director în C:\ProgramData\RetailForce\Fiscal web service cu numele „fileSystemInterface”.

Atenție: Pentru a activa sistemul, serviciul trebuie repornit după efectuarea acestor setări.

appsettings.json

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

Intrările de dinainte și de după nu sunt incluse în exemplu. „c:\temp\filesysteminterface” este calea monitorizată.

Notă: Dosarul monitorizat trebuie să fie un dosar local. Unitățile de rețea nu sunt acceptate, deoarece sistemele de monitorizare a fișierelor adesea nu funcționează fiabil în acest caz.

Cum funcționează

Interfața de fișiere a serviciului fiscal monitorizează un director pentru fișiere noi cu o anumită structură de denumire. Imediat ce un fișier nou care corespunde convențiilor de denumire este creat în acest director, acesta este procesat.

Atenție: Pentru fișierele mai mari, se recomandă să scrieți mai întâi fișierul în director ca fișier temporar și apoi să-l redenumiți cu numele corect folosind comanda RENAME.

Procedură

Procedura este următoarea:

  1. Fișierul este transferat în director și recunoscut (*.request)
  2. Fișierul este procesat
  3. Fișierul *.response sau *.error este stocat în directorul „response” (subdirector al directorului de import) (același nume de fișier înainte de extensie).

Exemplu

  1. 20220308135010236.document.request este transferat
  2. Fișierul este în curs de procesare
  3. Fișierul response/20220308135010236.document.response este stocat. 

sau, în caz de eroare

  1. 20220308135010236.document.request este transferat
  2. Fișierul este în curs de procesare
  3. Fișierul response/20220308135010236.document.error este stocat. 

Responsabilități

Fișierele de solicitare procesate sunt mutate în subdirectorul „processed” de către interfața de fișiere.

Interfața de fișiere nu va șterge niciodată niciun fișier. Cu toate acestea, se recomandă arhivarea fișierelor mai vechi (recunoscute după dată) după o anumită perioadă de timp.

Asigurarea secvenței corecte

Ordinea de procesare este asigurată de un nume unic al fișierului, care poate fi sortat.

Structura numelui fișierului

AAAALLZZHHNNSSZZZ.{tip}.request

AAAA = An (2022), interval de valori: 2022-3000

MM = Luna (03 pentru martie), interval de valori: 01-12

DD = Zi (02 pentru data de 2 a lunii), interval de valori: 01-31

HH = Ora în format de 24 de ore, interval de valori: 00-23

NN = Minute (04 pentru 4 minute), interval de valori: 00-59

SS = Secunde (05 pentru 5 secunde), interval de valori: 00-59

ZZZ = Milisecunde (010 pentru 10 milisecunde), interval de valori: 000-999

Tipul

{tip} indică tipul cererii; există următoarele tipuri:

  • document – pentru a transmite o chitanță
  • validateDocument – pentru validarea unei chitanțe
  • command – pentru a executa o comandă

Documentația privind tipul/modelul

Pentru mai multe informații despre modelul documentului și răspunsurile corespunzătoare, vă rugăm să consultați Documentația modelului de obiect și documentația swagger a Clientului fiscal (http://localhost:7678/swagger/index.html).

Răspunsul de eroare este același pentru toate tipurile: excepția generată este returnată în fișierul de răspuns (*.error).

Tipul „document” – transmiterea chitanțelor

Conținutul fișierului în acest caz este un document în formatul de document RetailForce (Document).

Formatul documentului poate fi consultat în Documentația modelului de obiecte sau în documentația swagger a serviciului fiscal (http://localhost:7678/swagger/index.html).

Răspuns

FiscalResponse-ul țării respective este transmis în fișierul de răspuns.

Tipul „validateDocument” – validarea unei chitanțe

Conținutul fișierului în acest caz este, la fel ca în cazul tipului „document”, un document în formatul RetailForce.

Răspuns

În fișierul de returnare este returnată o listă posibilă de erori (și avertismente) rezultate din validare.

Tipul „createClient” – crearea unui FiscalClient

Conținutul fișierului în acest caz este un FiscalClient în format JSON (vezi documentația).

Răspuns

„OK” atunci când solicitarea a fost procesată cu succes.

Tipul „createClientByCloud” – crearea unui FiscalClient cu date din Cloud

Conținutul fișierului este un document JSON cu următoarea structură:

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

Retur

UniqueClientId-ul clientului creat.

Tipul „restoreClientByCloud” – restaurarea unui FiscalClient cu date din Cloud

Conținutul fișierului este un document JSON cu următoarea structură:

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

Rezultat

UniqueClientId-ul clientului restaurat.

Tipul „getClientId” – Căutarea clientului și preluarea ID-ului

Disponibil începând cu: V1.2.12

Conținutul fișierului este un document JSON cu următoarea structură:

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

Rezultat

UniqueClientId-ul clientului creat.

Tastați „InitializeClient” – inițializarea FiscalClient

Conținutul fișierului este un document JSON cu următoarea structură:

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

Datele furnizate sunt date de test și trebuie înlocuite cu datele corecte.

Rezultat

Fie gol, fie un obiect fiscalResponse al țării respective.

Tipul „CloudConnect” – inițializarea conexiunii la cloud

Conținutul fișierului este un document JSON cu următoarea structură:

{
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}",
  "PersistDays": {days} // optional, days until credentials are stored 
}
Atenție: Datele de autentificare sunt stocate criptate pe disc. Păstrarea datelor de autentificare reprezintă un potențial risc de securitate.

Returnează

„OK” atunci când solicitarea a fost procesată cu succes.

Tipul „AuditLog” – transmiterea unei intrări din jurnalul de audit

Conținutul fișierului este un obiect JSON cu următoarea structură:

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

Returnează

Fie se lasă necompletat, fie se returnează un obiect fiscalResponse corespunzător țării respective (dacă este necesar acolo).

Tipul „digitalReceipt” – Transmiterea chitanței digitale

Acest tip de fișier poate fi utilizat pentru a transmite o chitanță digitală. 

Conținutul fișierului este un obiect JSON cu următoarea structură:

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

Proprietatea „ReceiptMetaData” este obiectul ReceiptMetaData care trebuie transmis și atunci când se efectuează apelul prin intermediul interfeței REST. 

În exemplu, stream-ul de date PDF a fost prescurtat cu ...

Rezultat

În fișierul de răspuns este returnat un link QrCode (sub formă de string) pentru a fi afișat clientului.

Configurare

Interfața sistemului de fișiere poate fi activată în configurația clientului prin setarea unei valori în câmpul „FiscalClient.FileSystemInterfacePath”. Dacă acest câmp este gol (implicit), interfața de fișiere nu este activă.

Acest articol a fost tradus automat.

Articole conexe

Comentarii

0 comentarii

Vă rugăm să vă autentificați pentru a lăsa un comentariu.

Susținut de Zendesk