RetailForce Fiscal Service – Descrierea API-ului – RetailForce

Acest articol oferă o prezentare generală a funcțiilor api ale serviciului fiscal RetailForce (stare: release 1.6.3). Parametrii necesari pentru fiecare punct de interfață pot fi consultați prin swagger (de exemplu, http://localhost:7678/swagger/index.html) după instalarea RetailForce Middleware.

API-ul este împărțit în diferite domenii, care sunt utilizate pentru scopuri și produse diferite.

Informații din coloana „Tip”:

O ... opțional
M ... obligatoriu / necesar
M* ... obligatoriu / necesar în anumite țări sau în anumite condiții
R ... recomandat

Titlurile se referă la secțiunea corespunzătoare din swagger. Pentru unele puncte finale veți găsi linkuri către informații suplimentare.

Arhivă

Scurtă descriere: Funcția de arhivare a datelor deja fiscalizate.

Punctele finale din această secțiune sunt utilizate pentru a transfera date către Arhiva RetailForce.

Vă rugăm să rețineți: această secțiune NU este necesară atunci când utilizați middleware-ul pentru fiscalizare! Arhivarea datelor fiscale se realizează automat și depinde de licența selectată.

Punct de acces	Tip	Descriere
POST /api/v1/archive/de/{clientId}	O	Această metodă este utilizată pentru a încărca mai multe fișiere în arhiva Cloud.
GET /api/v1/archive/de/{clientId}	O	Se utilizează pentru a descărca date (fișiere) arhivate anterior din arhiva Cloud.

Backup

Descriere succintă: Funcție de arhivare pentru date POS arbitrare

Punctele finale din această secțiune sunt destinate încărcării datelor arbitrare în arhiva Cloud – pentru serviciul/produsul: „Arhiva POS”. Pentru a utiliza acest serviciu este necesară o licență de backup.

Punct de acces	Tip	Descriere
POST /api/v1/backup/{clientId}	O	Această metodă realizează o copie de rezervă a unui anumit folder în arhiva din Cloud.
POST /api/v1/backup/{clientId}/restore	O	Restabilește un fișier arhivat anterior (copie de rezervă) într-o locație specifică.
GET /api/v1/backup/{clientId}/restore	O	Returnează o adresă URL de descărcare, care poate fi utilizată pentru a descărca fișierul de backup solicitat din arhiva din Cloud.

Închidere

Scurtă descriere: Funcții de închidere pentru casele de marcat.

Această secțiune oferă diverse funcții administrative pentru contabilitatea unei case de marcat. Pentru mai multe informații despre înregistrările de închidere de la sfârșitul zilei, consultați articolul: Închiderea zilnică a casei de marcat,

Punct final	Tip	Descriere
POST /api/v1/closing/{clientId}/book/ openingStock	O	Înregistrează stocul inițial pentru un raport de închidere a casei de marcat. Înregistrează doar o *încasare, nu reajustează stocul de numerar. Alternativă:* Ca alternativă, casa de marcat poate înregistra și un document: documentType [11] = PayIn.
PUT /api/v1/closing/{clientId}/book/ cashDifference	O	Înregistrează o diferență de numerar în sistemul de fiscalizare. Alternativă: Ca alternativă, casa de marcat poate, de asemenea, să înregistreze un document cu BusinessTransactionType [91] = CashDifference.
PUT /api/v1/closing/{clientId}/book/ cashLift	O	Înregistrează un *transfer de bani* din sistemul casei de marcat către bancă (sau orice altă destinație).
GET /api/v1/closing/{clientId}/ actualStock	O	Returnează stocul real de plăți al unui anumit client. Acesta se calculează pe baza documentelor transmise (pe lângă bonurile de vânzare și de returnare, depuneri și retrageri etc.).
POST /api/v1/closing/{clientId}/ cashpointCheck	O	Verifică stocul real al plăților pentru această casă de marcat și returnează o listă a plăților cu diferență (sau o listă goală dacă nu există nicio diferență).
POST /api/v1/closing/{clientId}/ cashpointClose	O	Închide ziua curentă cu un raport de închidere. Închiderea se efectuează pe baza documentelor trimise clientului de la ultima închidere. Sistemul casei de marcat nu primește înapoi raportul de închidere!
GET /api/v1/closing/{clientId}/ endofdayDocument	O	Returnează documentul de sfârșit de zi pentru ziua curentă. Documentul returnat trebuie stocat (storeDocument > documentType 99)
GET /api/v1/closing/{clientId}/ lastClosing	O	Returnează data și ora ultimei închideri pentru un anumit client (terminal)
GET /api/v1/closing/{clientId}/ closingNecessary	O	Returnează informații cu privire la faptul dacă se efectuează sau nu o închidere zilnică la un anumit terminal. (În funcție de RetailForce.Fiscalisation.Implementation. IFiscalCountryProperties. MaximumHourIntervalForClosing).

Informații

Descriere succintă: utilizat pentru a interoga informații speciale

Punct de interfață	Tip	Descriere
GET /api/v1/information/version	O	Returnează versiunea actuală (SW) a software-ului (middleware fiscal).
GET /api/v1/information/version/{clientId}	O	Returnează versiunea modulului de țară al clientului specificat.
GET /api/v1/information/countryProperties	O	Returnează fiscalCountryProperties pentru țara solicitată.
GET /api/v1/information/client/{clientId}/ countryProperties	O	Returnează proprietățile fiscale ale țării (fiscalCountryProperties) pentru clientul specificat.
GET /api/v1/information/client/{clientId}/ UniqueCashRegisterId	O	Returnează ID-ul unic al casei de marcat (storeNumber/terminalNumber).
GET /api/v1/information/client/{clientId}/ status	O	Returnează starea clientului fiscal solicitat.
GET /api/v1/information/client/{clientId}/ accessLicenses	O	Returnează o listă a licențelor de acces pentru clientul solicitat.
GET /api/v1/information/client/{clientId}/ licenses	O	Returnează cererea de licență pentru clientul solicitat.
GET /api/v1/information/client/{clientId}/ getVatIdentification	R	Returnează codul de identificare Vat corespunzător procentului și datei/orei solicitate.
GET /api/v1/information/client/{clientId}/ documentMandatoryFields/{typeName}	O	Returnează câmpurile obligatorii pentru tipul specificat prin typeName, pentru implementarea țării respective.
POST /api/v1/information/client/{clientId}/ storeErrorDocumentsToDisk	R	Dacă este setat la „true”, orice document de eroare va fi stocat în directorul clientului fiscal.
GET /api/v1/information/client/{clientId}/ storeErrorDocumentsToDisk	R	Returnează dacă opțiunea RetailForce.Fiscalisation.TrustedFiscalModule. StoreErrorDocumentsToDisk este activată.
GET /api/v1/information/performance/ {clientId}	O	Returnează toate ID-urile contoarelor de performanță pentru clientul specificat
DELETE /api/v1/information/performance/ {clientId}	O	Resetează toate datele medii pentru clientul specificat.
GET /api/v1/information/performance {clientId}/{performanceCounterId}	O	Returnează datele medii ale ID-ului contorului de performanță solicitat.
DELETE /api/v1/information/performance/ {clientId}/{performanceCounterId}	O	Resetează datele medii pentru clientul specificat și contorul de performanță specificat.
PUT /api/v1/information/performance/ {clientId}/file	O	Activează sau dezactivează urmărirea fișierului de performanță. Urmărirea fișierului de performanță este dezactivată în mod implicit.
GET /api/v1/information/progress/ {clientId}	O	Returnează toate etichetele cu informații privind progresul pentru clientul specificat.
GET /api/v1/information/progress/{clientId}/ {label}	O	Returnează informațiile privind progresul pentru clientul și eticheta specificate.

Gestionare

Descriere scurtă: Funcții de gestionare, punere în funcțiune și scoatere din funcțiune

Punct final	Tip	Descriere
PUT /api/v1/management/clients	O/M	Creează un client nou în magazinul de configurații. Obiectul de configurație trebuie pregătit de sistemul POS. Configurarea unui client este necesară pentru funcționare. Utilizați fie acest punct final, fie: PUT /api/v1/management/clients, sau PUT /api/v1/management/clients/ byCloud/ID.
POST /api/v1/management/clients	O	Actualizează o configurație a clientului creată de sistemul de casă de marcat în magazinul de configurații.
GET /api/v1/management/clients	O	Returnează toți clienții enumerați în magazinul de configurații. Poate fi utilizat și în cazul utilizării configurației în Cloud.
PUT /api/v1/management/clients/ byCloud	O/M	Creează un client nou cu o configurație pregătită în Cloud / sau încarcă un client existent. Configurarea unui client este necesară pentru funcționare. Utilizați fie: acest punct final, fie PUT /api/v1/management/clients, sau PUT /api/v1/management/clients/ byCloud/ID.
PUT /api/v1/management/clients/ byCloud/ID	O	Creează un client încărcând datele de configurare din Cloud. Alternativă: punct de capăt alternativ pentru PUT /api/v1/management/clients și PUT /api/v1/management/clients/byCloud.
PUT /api/v1/management/clients/ byCloud/{clientId}	R	Actualizează configurația clientului prin preluarea acesteia din Cloud. Se utilizează atunci când configurația pregătită în Cloud a fost actualizată și trebuie descărcată din nou de către clientul fiscal (actualizare).
POST /api/v1/management/clients/withCloud	O/M	Creează un client nou în modulul de gestionare fiscală și adaugă acest client la configurația din Cloud. Clientul este creat în magazinul local de configurații, iar obiectul de configurare este apoi încărcat în sistemul Cloud. Notă: Distribuitorul trebuie să fie setat în datele clientului, iar distribuitorul trebuie să aibă permisiunea de a crea clienți noi.
POST /api/v1/management/cloud/ connect	M*	Stabilește conexiunea la Cloud pentru clientul specific și încarcă modulul fiscal de încredere în cache. Necesar pentru sistemele care utilizează funcții Cloud. Necesar după fiecare repornire a sistemului POS.
POST /api/v1/management/Cloud/ updateLicense	O	Actualizează cheia de licență curentă din configurația clientului fiscal (inclusiv pe disc). Necesar dacă licențele din configurația Cloud au fost modificate.
HEAD /api/v1/management/Cloud/queue	R	Metodă pentru a porni sau opri procesarea cozii din Cloud (pentru toți clienții). Comanda „Stop” oprește procesarea după finalizarea încărcării curente. Comanda „Start” pornește imediat procesarea cozii. Dacă procesarea cozii din Cloud este oprită, trebuie să o reporniți, cu excepția cazului în care serviciul este repornit (caz în care procesarea în Cloud este activată din nou).
GET /api/v1/management/clients/ {clientId}	O	Returnează configurația unui client specific.
DELETE /api/v1/management/clients/ {clientId}	O	Șterge un client specific Atenție: utilizați cu precauție!
GET /api/v1/management/clients/ID	O	Returnează ID-ul unic al clientului pentru parametrii solicitați. Se pot utiliza diferiți parametri pentru a solicita uniqueClientId.
GET /api/v1/management/clients/ LicenseConsumerId	O	Returnează ID-ul consumatorului de licență pentru identificatorul companiei specificat. Sunt returnate numai LicenseConsumerId-urile care sunt deja stocate în magazinul de configurare.
GET /api/v1/management/clients/ validate	O	Validează informațiile clientului specificat pentru a îndeplini configurația necesară specifică țării. Se utilizează pentru a valida o configurație creată de sistemul de casă de marcat înainte de a utiliza /api/v1/management/clients. Validarea configurației cloud este asigurată de sistemul cloud.
POST /api/v1/management/clients/ initialize	M	Inițializează unitatea de fiscalizare (precum și eventualul hardware și eventuala declarație către autoritățile fiscale). Inițializarea se realizează prin intermediul bonului de pornire (bonul inițial), care poate fi fie interogat folosind punctul final GET /api/v1/transactions/document/ {clientId}/start, fie creat de sistemul de casă de marcat.
POST /api/v1/management/clients/ migrate/{clientId}	O	Migrează un client de la un alt furnizor de servicii de fiscalizare. Se utilizează la trecerea de la un alt furnizor de middleware fiscal la RetailForce Vă rugăm să luați în considerare sistemele acceptate.
POST /api/v1/management/clients/ migrate/{clientId}/file	O	Migrează un client de la un alt furnizor de servicii de fiscalizare și efectuează un import de fișiere. Vă rugăm să luați în considerare sistemele acceptate!
POST /api/v1/management/clients/ decommission	R	Dezactivarea clientului fiscal (și, eventual, a echipamentului hardware, precum și eventuala declarare către autoritățile fiscale).
PUT /api/v1/management/clients/ {clientId}/supportPackage	R	Încarcă un Support Package (fișiere jurnal) în Cloud pentru clientul respectiv. Acest punct final este necesar pentru a utiliza funcția „Încărcare Support Package” din sistemul Cloud.
GET /api/v1/management/clients/recovery/ {clientId}/backup	R	Efectuează o copie de rezervă a unui client cu numele de fișier specificat (copie de rezervă sub formă de fișier zip). Dacă se utilizează încărcarea în Cloud, procesarea cozii din Cloud va fi oprită și repornită (iar coada din Cloud va fi reinitializată). Atenție: Vă rugăm să rețineți că, dacă clientul nu este eliminat, procesul cozii din Cloud va fi reluat după realizarea copiei de rezervă. Dacă există fișiere care nu au fost incluse înainte de realizarea copiei de rezervă, acestea fac parte din copie și vor fi încărcate de două ori în cazul în care clientul este restaurat.
POST /api/v1/management/clients/ recovery/restore	R	Restaurează un client (cu toate datele) din fișierul ZIP de backup specificat.
POST /api/v1/management/clients/recovery/restoreByCloud	R	Creează un client nou cu configurația din Cloud sau încarcă un client existent.
POST /api/v1/management/clients/recovery/restoreByCloud/ID	O	Creează un client nou cu configurația din Cloud / sau încarcă un client existent.
POST /api/v1/management/clients/ {clientId}/GlobalShortId	O	Generează un ID nou sau returnează unul existent, unic la nivel global, pentru clientul respectiv. În plus, se activează emiterea retailForceReceiptId pentru clientul respectiv.
POST /api/v1/management/clients/ {clientId}/certificate	O/M	Stochează un certificat extern în magazinul de certificate al modulului fiscal. Necesar pentru sistemele care NU utilizează funcțiile RetailForce Cloud în țările cu regim fiscal în care se utilizează certificate software în contextul fiscalizării (Slovenia, Croația, Spania,…)
GET /api/v1/management/clients/ {clientId}/licenses/accessLicense	O	Returnează dacă clientul solicitat deține licența de acces solicitată.
GET /api/v1/management/clients/ {clientId}/licenses/license	O	Returnează dacă clientul solicitat deține licența solicitată.

ManagementController_Austria

Descriere succintă: Funcții de gestionare pentru fiscalizarea din Austria.

Punct de interfață	Tip	Descriere
POST /api/v1/management/austria/ {clientId}/aes	O	Creează o cheie de utilizator AES pentru acest client și o returnează. Cheia AES va fi, de asemenea, stocată în configurația clientului. Notă: Cheia de utilizator AES va fi creată automat de clientul fiscal. Punctul de interfață este necesar doar dacă cheia AES trebuie creată manual.
GET /api/v1/management/austria/ {clientId}/aes	O	Returnează cheia AES pentru clientul specificat.
GET /api/v1/management/austria/ {clientId}/dep	O/M	Exportă toate liniile de chitanțe din jurnalul local de colectare a datelor (DEP §7 RKSV). Necesar pentru sistemele offline (sistemele care NU utilizează arhivarea în Cloud a datelor fiscale).
GET /api/v1/management/austria/ {clientId}/dep131	O	Exportă toate datele solicitate pentru protocolul DEP131 (DEP §131 BAO) din datele stocate local.
GET /api/v1/management/austria/ {clientId}/DEP/startReceipt	R	Returnează chitanța de început pentru acest client. Sistemul de casă de marcat trebuie să poată furniza chitanța inițială (chitanța de început) la cerere în timpul unui audit fiscal; dacă sistemul POS nu a stocat chitanța inițială, aceasta poate fi solicitată folosind acest punct final.
GET /api/v1/management/austria/ {clientId}/dep/monthReceipts	R	Returnează toate chitanțele lunare din intervalul de date solicitat. Sistemul de casă de marcat trebuie să poată furniza chitanțele lunare la cerere în timpul unui audit fiscal; dacă sistemul POS nu a stocat aceste documente, ele pot fi solicitate folosind acest punct de interfață.
GET /api/v1/management/austria/ {clientId}/fon/certificate	O	Returnează toate dispozitivele de semnătură și indică dacă acestea sunt activate sau nu în FinanzOnline (Fon).
POST /api/v1/management/austria/ {clientId}/Fon/certificate	O	Înregistrează dispozitivul de semnătură configurat la Fon (dacă este configurat unul) sau dispozitivul de semnătură identificat prin certificateSerial. Notă: Dacă se utilizează serviciile RetailForce Cloud, certificatele sunt înregistrate automat în portalul FinanzOnline (Fon) (à sunt necesare datele de autentificare pentru utilizatorul serviciului web al casei de marcat!); punctul de interfață este necesar doar dacă înregistrarea trebuie efectuată manual.
DELETE /api/v1/management/austria/ {clientId}/Fon/certificate	O	Anulează înregistrarea dispozitivului de semnătură configurat la Fon (dacă este configurat unul) sau a dispozitivului de semnătură identificat prin certificateSerial. Atenție: utilizați cu precauție!
GET /api/v1/management/austria/ {clientId}/fon/document	R	Validează ultimul document semnat în DEP la FinanzOnline (FON).
GET /api/v1/management/austria/ {clientId}/Fon/document/{depDocument}	R	Validează documentul DEP specificat (cod QR) la Fon.
GET /api/v1/management/austria/ {clientId}/fon/cashregister	O	Returnează informația dacă casa de marcat a clientului respectiv este activată la Fon. Necesar pentru sistemele offline.
POST /api/v1/management/austria/ {clientId}/fon/cashregister	O	Înregistrarea sistemului de casă la Fon pentru clientul curent. Necesar pentru sistemele offline.
DELETE /api/v1/management/austria/ {clientId}/Fon/cashregister	O	Anularea înregistrării casei de marcat la Fon pentru clientul respectiv. Necesar pentru sistemele offline. Atenție: a se utiliza cu precauție!

ManagementController_Bulgaria

Descriere scurtă: Funcții de gestionare pentru fiscalizarea din Bulgaria.

Punct final	Tip	Descriere
POST /api/v1/management/bulgaria/ {clientId}/commands/closing	M	Trimite comanda de închidere (Z) către imprimanta fiscală.
POST /api/v1/management/bulgaria/ {clientId}/commands/synchronizeTime	M	Trimite comanda de sincronizare a orei (L) către imprimanta fiscală.
GET /api/v1/management/bulgaria/ {clientId}/reports/KLEN	R	Această funcție poate fi utilizată pentru a genera un așa-numit raport KLEN. (începând cu v1.8.3)
GET /api/v1/management/bulgaria/ {clientId}/reports/zreport	R	Această funcție este utilizată pentru a afișa rapoarte detaliate și sintetice pe o anumită perioadă. (începând cu v1.8.3)
GET /api/v1/management/bulgaria/ {clientId}/reports/block	R	Această funcție este utilizată pentru a genera un așa-numit raport BLOCK. (începând cu v1.8.3)

ManagementController_Danemarca

Descriere succintă: Funcții de gestionare pentru fiscalizarea daneză.

Punct final	Tip	Descriere
GET /api/v1/management/denmark/ {clientId}/saft	M	Exportă formatul SAF-T pentru Danemarca în stream-ul specificat.

ManagementController_France

Descriere scurtă: Funcții de gestionare pentru fiscalizarea franceză.

Punct de capăt	Tip	Descriere
GET /api/v1/management/france/eventlog/ {clientId}	M	Returnează toate intrările din jurnalul de audit solicitate după dată.
GET /api/v1/management/france/ archive/{clientId}	M	Returnează arhivele stocate local pentru închidere.
POST /api/v1/management/france/archive/ {clientId}/verify	M	Metodă de verificare a arhivei franceze.

ManagementController_Germany

Descriere scurtă: Funcții de gestionare pentru fiscalizarea germană.

Punct de acces	Tip	Descriere
GET /api/v1/management/germany/TSE	R	Returnează un array cu dispozitivele TSE locale conectate și starea acestora.
POST /api/v1/management/germany/ TSE/{TseSerial}/selftest	R	Efectuează un autotest sincron pentru casa de marcat specificată pe dispozitivul TSE (casa de marcat este opțională).
PUT /api/v1/management/germany/ {clientId}/TSE/connectTest	R	Efectuează o conexiune de test la TSE-ul specificat.
GET /api/v1/management/germany/ {clientId}/TSE/listClients	O	Returnează toți clienții înregistrați pe TSE-ul clientului specificat.
GET /api/v1/management/germany/ {clientId}/TSE/status	R	Returnează starea TSE-ului. Dacă nu se găsește niciun modul fiscal, se returnează starea RetailForce.Fiscalisation.Implementation. Germany.Tse.TseStatus.Critical.
PUT /api/v1/management/germany/ {clientId}/TSE/updateTime	M	Actualizează ora de pe TSE la ora reală a computerului.
GET /api/v1/management/germany/ {clientId}/TSE/tar	O	Exportă fișierele tar din TSE-ul principal. Necesar pentru sistemele offline.
GET /api/v1/management/germany/ {clientId}/taxonomy	O	Exportă taxonomia (DSFinV-K export) și o returnează sub forma unui fișier de descărcat (în format zip). Necesar pentru sistemele offline.
GET /api/v1/management/germany/ {clientId}/TSE/listTransactions	R	Returnează toate tranzacțiile active (începute) pe TSE. Recomandat pentru urmărirea tranzacțiilor deschise (toate tranzacțiile inițiate trebuie stocate sau anulate).
DELETE /api/v1/management/germany/ {clientId}/TSE/listTransactions	O	Anulează tranzacțiile active (inițiate) pe TSE.
GET /api/v1/management/germany/ {clientId}/TSE/openOfflineSignatures/count	O	Returnează numărul de tranzacții offline (= tranzacții care nu au fost trimise către TSE din cauza faptului că TSE este offline – defect sau indisponibil).
GET /api/v1/management/germany/ {clientId}/TSE/openOfflineSignatures	O	Returnează toate semnăturile offline deschise stocate pentru TSE-ul actual.
PUT /api/v1/management/germany/ {clientId}/TSE/openOfflineSignatures	O	Procesează semnăturile offline deschise.
PUT /api/v1/management/germany/ {clientId}/TSE/replace	R	Înlocuiește un TSE actual pentru clientul dat cu unul nou (de exemplu, dacă vechiul TSE este deteriorat sau certificatul a expirat).
POST /api/v1/management/germany/ {clientId}/TSE/selftest	R	Efectuează un autotest sincron pentru casa de marcat specificată pe TSE (casa de marcat este opțională).
POST /api/v1/management/germany/ {clientId}/TSE/updateFirmware	R	Actualizează firmware-ul dispozitivului hardware TSE de la swissbit.

ManagementController_Spania

Descriere scurtă: Funcții de gestionare pentru fiscalizarea din Spania.

Punct de acces	Tip	Descriere
GET /api/v1/management/spain/ {clientId}/ticketBai	R	Returnează fișierele TicketBAI stocate (fișiere trimise, fișiere de răspuns, fișiere de eroare) sub formă de fișier zip.
GET /api/v1/management/spain/ {clientId}/TicketBAI/{DocumentNumber}	R	Returnează fișierele TicketBAI stocate pentru numărul de document solicitat (fișiere trimise, fișiere de răspuns, fișiere de eroare) sub forma unui fișier zip.

Chitanțe

Descriere scurtă: utilizat pentru a trimite chitanțe digitale către RetailForce Cloud prin intermediul Middleware-ului.

Punctele finale din această secțiune sunt utilizate pentru a trimite documente de chitanță digitală către sistemul Cloud (sunt necesare licențe pentru chitanțe digitale pentru a utiliza acest serviciu!).

Punct de acces

Tip

Descriere

POST /api/v1/receipts/{clientId}

O/M

Încarcă un fișier cu chitanțe digitale în sistemul Cloud.

Alternativă: Utilizați fie acest punct final, fie cel alternativ din această secțiune pentru a trimite date privind chitanțele digitale.

POST /api/v1/receipts/
{clientId}/{DocumentGuid}

O/M

Încarcă un fișier digital în sistemul Cloud. Utilizând Metadata-ul de fiscalizare.