RetailForce Fiscal Service – api-beskrivelse – RetailForce

Denne artikel giver et overblik over api-funktionerne i RetailForce Fiscal Service (status: release 1.6.3). De påkrævede parametre for hvert endpoint kan ses via swagger (f.eks. http://localhost:7678/swagger/index.html) efter installation af Fiscal Middleware.

Api'et er opdelt i forskellige områder, der anvendes til forskellige formål og produkter.

Oplysninger i kolonnen »Type«:

O ... valgfrit
M ... obligatorisk / påkrævet
M* ... obligatorisk / påkrævet i visse lande eller under visse betingelser
R ... anbefalet

Overskrifterne henviser til det respektive afsnit i swagger. For nogle endpoints finder du links til yderligere oplysninger.

Arkiv

Kort beskrivelse: Arkiveringsfunktion for allerede skattebehandlede data.

Endpunkterne i dette afsnit bruges til at overføre data til Secure RetailForce Archive.

Bemærk: Dette afsnit er IKKE påkrævet, når du bruger middleware til fiskalisering! Arkivering af fiskalisationsdata sker automatisk og afhænger af den valgte licens.

Endpoint	Type	Beskrivelse
POST /api/v1/archive/de/{clientId}	O	Denne metode bruges til at uploade flere filer til Cloud-arkivet.
GET /api/v1/archive/de/{clientId}	O	Bruges til at downloade tidligere arkiverede data (filer) fra Cloud-arkivet.

Sikkerhedskopiering

Kort beskrivelse: Arkiveringsfunktion til vilkårlige POS-data

Endpunkterne i dette afsnit bruges til at uploade vilkårlige data til Cloud-arkivet – for tjenesten/produktet: “POS-arkiv”. Der kræves en backup-licens for at kunne benytte denne tjeneste.

Endpoint	Type	Beskrivelse
POST /api/v1/backup/{clientId}	O	Denne metode sikkerhedskopierer en given mappe til Cloud-arkivet.
POST /api/v1/backup/{clientId}/restore	O	Gendanner en tidligere arkiveret (backup) fil til en bestemt placering.
GET /api/v1/backup/{clientId}/restore	O	Returnerer en download-URL, som kan bruges til at downloade den anmodede backup-fil fra Cloud-arkivet.

Afslutning

Kort beskrivelse: Afslutningsfunktioner til kasseapparater.

Dette afsnit indeholder forskellige administrative funktioner til bogføring af et kasseapparat. For yderligere oplysninger om afslutningsposteringer ved dagens afslutning, se artiklen: Daglig afslutning af kasseapparatet,

Endepunkt	Type	Beskrivelse
POST /api/v1/closing/{clientId}/book/ openingStock	O	Bogfører startbeholdningen til en kasseafslutning. Bogfører kun en *indbetaling, justerer ikke kassebeholdningen. Alternativ:* Som alternativ kan kasseapparatet også bogføre et dokument: documentType [11] = PayIn.
PUT /api/v1/closing/{clientId}/book/ cashDifference	O	Bogfører en kontantforskel til skattesystemet. Alternativ: Som alternativ kan kasseapparatet også bogføre et dokument med BusinessTransactionType [91] = CashDifference.
PUT /api/v1/closing/{clientId}/book/ cashLift	O	Bogfører en *pengeoverførsel* fra kassesystemet til banken (eller en anden destination).
GET /api/v1/closing/{clientId}/ actualStock	O	Returnerer den faktiske saldo for betalinger for en bestemt client. Dette beregnes på baggrund af de overførte dokumenter (ud over salgs- og returkvitteringer, indskud og udbetalinger osv.).
POST /api/v1/closing/{clientId}/ cashpointCheck	O	Kontrollerer den faktiske saldo for betalingerne for denne kasse og returnerer en liste over betalinger med afvigelse (eller en tom liste, hvis der ikke er nogen afvigelse).
POST /api/v1/closing/{clientId}/ cashpointClose	O	Afslutter den aktuelle dag med en afslutningsopgørelse. Afslutningen foretages på baggrund af de dokumenter, der er sendt til klienten siden sidste afslutning. Kassesystemet modtager ikke en afslutningsopgørelse som svar!
GET /api/v1/closing/{clientId}/ endofdayDocument	O	Returnerer dagafslutningsdokumentet for den aktuelle dag. Det returnerede dokument skal gemmes (storeDocument > documentType 99)
GET /api/v1/closing/{clientId}/ lastClosing	O	Returnerer dato og klokkeslæt for den seneste afslutning for en bestemt klient (terminal)
GET /api/v1/closing/{clientId}/ closingNecessary	O	Returnerer oplysninger om, hvorvidt der skal foretages en daglig afslutning på en bestemt terminal. (Afhængigt af RetailForce.Fiscalisation.Implementation. IFiscalCountryProperties. MaximumHourIntervalForClosing).

Oplysninger

Kort beskrivelse: bruges til at hente specifikke oplysninger

Endpoint	Type	Beskrivelse
GET /api/v1/information/version	O	Returnerer den aktuelle version (SW) af softwaren (fiscal middleware).
GET /api/v1/information/version/{clientId}	O	Returnerer versionen af landemodulet for den angivne client.
GET /api/v1/information/countryProperties	O	Returnerer fiscalCountryProperties for det anmodede land.
GET /api/v1/information/client/{clientId}/ countryProperties	O	Returnerer fiscalCountryProperties for den angivne client.
GET /api/v1/information/client/{clientId}/ UniqueCashRegisterId	O	Returnerer det unikke kasseapparat-ID (storeNumber/terminalNumber).
GET /api/v1/information/client/{clientId}/ status	O	Returnerer status for den anmodede skattepligtige client.
GET /api/v1/information/client/{clientId}/ accessLicenses	O	Returnerer en liste over adgangslicenser for den anmodede client.
GET /api/v1/information/client/{clientId}/ licenses	O	Returnerer licenskravet for den anmodede client.
GET /api/v1/information/client/{clientId}/ getVatIdentification	R	Returnerer det relevante Vat-nummer for den anmodede procentdel og dato/tidspunkt.
GET /api/v1/information/client/{clientId}/ documentMandatoryFields/{typeName}	O	Returnerer de obligatoriske felter for den type, der er angivet ved typeName, for den givne landimplementering.
POST /api/v1/information/client/{clientId}/ storeErrorDocumentsToDisk	R	Hvis indstillet til true, gemmes eventuelle fejldokumenter i den skattemæssige klientmappe.
GET /api/v1/information/client/{clientId}/ storeErrorDocumentsToDisk	R	Returnerer, om indstillingen RetailForce.Fiscalisation.TrustedFiscalModule. StoreErrorDocumentsToDisk er aktiveret.
GET /api/v1/information/performance/ {clientId}	O	Returnerer alle ydeevnemåler-ID'er for den angivne client
DELETE /api/v1/information/performance/ {clientId}	O	Nulstiller alle gennemsnitsdata for den angivne client.
GET /api/v1/information/performance {clientId}/{performanceCounterId}	O	Returnerer gennemsnitsdataene for den anmodede ydeevnemåler-ID.
DELETE /api/v1/information/performance/ {clientId}/{performanceCounterId}	O	Nulstiller gennemsnitsdataene for den angivne client og den angivne præstationsmåler.
PUT /api/v1/information/performance/ {clientId}/file	O	Aktiverer eller deaktiverer sporing af ydeevnefiler. Sporing af ydeevnefiler er som standard deaktiveret.
GET /api/v1/information/progress/ {clientId}	O	Returnerer alle etiketter med fremskridtsoplysninger for den angivne client.
GET /api/v1/information/progress/{clientId}/ {label}	O	Returnerer statusoplysningerne for den angivne client og etiket.

Administration

Kort beskrivelse: Administrationsfunktioner, idriftsættelse og nedlukning

Endpoint	Type	Beskrivelse
PUT /api/v1/management/clients	O/M	Opretter en ny client i konfigurationslageret. Konfigurationsobjektet skal forberedes af POS-systemet. Konfiguration af en client er påkrævet for drift. Brug enten dette endpoint eller: PUT /api/v1/management/clients, eller PUT /api/v1/management/clients/byCloud/ID.
POST /api/v1/management/clients	O	Opdaterer en clientkonfiguration, der er oprettet af kassesystemet, i konfigurationslageret.
GET /api/v1/management/clients	O	Returnerer alle klienter, der er opført i konfigurationslageret. Kan også bruges ved brug af Cloud-konfiguration.
PUT /api/v1/management/clients/ byCloud	O/M	Opretter en ny client med en konfiguration, der er forberedt i Cloud, eller indlæser en eksisterende client. Konfiguration af en client er påkrævet for at kunne udføre handlingen. Brug enten: dette endpoint eller PUT /api/v1/management/clients, eller PUT /api/v1/management/clients/ byCloud/ID.
PUT /api/v1/management/clients/ byCloud/ID	O	Opretter en client ved at hente konfigurationsdataene fra Cloud. Alternativ: alternativt endpoint til PUT /api/v1/management/clients og PUT /api/v1/management/clients/byCloud.
PUT /api/v1/management/clients/ byCloud/{clientId}	R	Opdaterer klientkonfigurationen ved at hente klientkonfigurationen fra Cloud. Anvendes, når den konfiguration, der er forberedt i Cloud, er blevet opdateret og skal downloades på ny af den skattemæssige client (opdatering).
POST /api/v1/management/clients/withCloud	O/M	Opretter en ny client i skattemodulets administration og tilføjer denne client til Cloud-konfigurationen. Clienten oprettes i det lokale konfigurationslager, og konfigurationsobjektet uploades derefter til Cloud-systemet. Bemærk: Distributoren skal være angivet i klientdataene, og distributoren skal have tilladelse til at oprette nye klienter.
POST /api/v1/management/cloud/ connect	M*	Etablerer en Cloud-forbindelse for den specifikke client og indlæser det betroede skatte- og afgiftsmodul i cachen. Påkrævet for systemer, der bruger cloud-funktioner. Nødvendigt efter hver genstart af POS-systemet.
POST /api/v1/management/cloud/ updateLicense	O	Opdaterer den aktuelle licensnøgle i skatteclientkonfigurationen (også på disken). Påkrævet, hvis licenserne i Cloud-konfigurationen er blevet ændret.
HEAD /api/v1/management/cloud/queue	R	Metode til at starte eller stoppe behandlingen af cloud-køen (for alle klienter). Stop-kommandoen stopper behandlingen, når den aktuelle upload er afsluttet. Start starter købehandlingen med det samme. Hvis behandlingen af cloud-køen er stoppet, skal du genstarte den, medmindre tjenesten genstartes (i hvilket tilfælde cloud-behandlingen aktiveres igen).
GET /api/v1/management/clients/ {clientId}	O	Returnerer klientkonfigurationen for en bestemt klient.
DELETE /api/v1/management/clients/ {clientId}	O	Sletter en bestemt client OBS: Brug med forsigtighed!
GET /api/v1/management/clients/ID	O	Returnerer det unikke client-ID for de anmodede parametre. Der kan bruges forskellige parametre til at anmode om uniqueClientId.
GET /api/v1/management/clients/ LicenseConsumerId	O	Returnerer licensforbruger-ID'et for den angivne virksomhedsidentifikation. Kun LicenseConsumerId'er, der allerede er gemt i konfigurationslageret, returneres.
GET /api/v1/management/clients/ validate	O	Validerer de angivne clientoplysninger for at opfylde de nødvendige landespecifikke konfigurationskrav. Bruges til at validere en konfiguration oprettet af kassesystemet, før /api/v1/management/clients anvendes. Validering af cloud-konfigurationen foregår i cloud-systemet.
POST /api/v1/management/clients/ initialize	M	Initialiserer afregningsenheden (samt eventuel hardware og eventuel indberetning til skattemyndighederne). Initialiseringen sker via en startkvittering (første kvittering), som enten kan hentes ved hjælp af endpointet GET /api/v1/transactions/document/ {clientId}/start, eller oprettes af kassesystemet.
POST /api/v1/management/clients/ migrate/{clientId}	O	Overfører en client fra en anden leverandør af skatteovervågning. Anvendes ved skift fra en anden leverandør af skatteovervågnings-middleware til RetailForce Bemærk venligst de understøttede systemer.
POST /api/v1/management/clients/ migrate/{clientId}/file	O	Overfører en client fra en anden leverandør af skattehåndteringsløsninger og udfører en filimport. Bemærk de understøttede systemer!
POST /api/v1/management/clients/ decommission	R	Nedlukning af skattepligtig client (og eventuel hardware samt eventuel indberetning til skattemyndighederne).
PUT /api/v1/management/clients/ {clientId}/supportPackage	R	Uploader en Support Package (logfiler) til Clouden for den angivne client. Dette endpoint er nødvendigt for at kunne bruge funktionen "Upload Support Package" i Cloud-systemet.
GET /api/v1/management/clients/recovery/ {clientId}/backup	R	Sikkerhedskopierer en client til det angivne filename (sikkerhedskopi i zip-fil). Hvis cloud-upload er i brug, vil behandlingen af cloud-køen blive stoppet og startet (og cloud-køen vil blive reinitialiseret). OBS: Bemærk, at hvis clienten ikke fjernes, vil behandlingen af cloud-køen genoptages efter sikkerhedskopieringen. Hvis der er filer, der ikke var til stede før sikkerhedskopieringen, indgår de også i sikkerhedskopien og vil muligvis blive uploadet to gange, hvis clienten gendannes.
POST /api/v1/management/clients/ recovery/restore	R	Gendanner en client (med alle data) fra den angivne backup-zip-fil.
POST /api/v1/management/clients/recovery/restoreByCloud	R	Opretter en ny client med konfiguration fra Cloud / eller indlæser en eksisterende client.
POST /api/v1/management/clients/recovery/restoreByCloud/ID	O	Opretter en ny client med konfiguration fra Cloud / eller indlæser en eksisterende client.
POST /api/v1/management/clients/ {clientId}/GlobalShortId	O	Genererer et nyt eller returnerer et eksisterende, globalt unikt ID for den pågældende klient. Derudover aktiveres udstedelsen af retailForceReceiptId for den pågældende klient.
POST /api/v1/management/clients/ {clientId}/certificate	O/M	Gemmer et eksternt certifikat i skattemodulets certifikatlager. Påkrævet for systemer, der IKKE bruger RetailForce Cloud-funktioner i skattepligtige lande, hvor softwarecertifikater anvendes i forbindelse med skattehåndtering (Slovenien, Kroatien, Spanien,…)
GET /api/v1/management/clients/ {clientId}/licenses/accessLicense	O	Returnerer, om den anmodede client har den anmodede adgangslicens.
GET /api/v1/management/clients/ {clientId}/licenses/license	O	Returnerer, om den anmodede client har den anmodede licens.

ManagementController_Austria

Kort beskrivelse: Administrationsfunktioner til østrigsk fiskalisering.

Endpoint	Type	Beskrivelse
POST /api/v1/management/austria/ {clientId}/aes	O	Opretter en AES-bruger-nøgle til denne client og returnerer den. AES-nøglen gemmes også i client-konfigurationen. Bemærk: AES-bruger-nøglen oprettes automatisk af den skattemæssige client. Endpointet er kun nødvendigt, hvis AES-nøglen skal oprettes manuelt.
GET /api/v1/management/austria/ {clientId}/aes	O	Returnerer AES-nøglen for den angivne client.
GET /api/v1/management/austria/ {clientId}/dep	O/M	Eksporterer alle kvitteringslinjer fra den lokale dataindsamlingslog (DEP §7 RKSV) med lagrede data. Påkrævet for offline-systemer (systemer, der IKKE anvender cloud-arkivering af regnskabsdata).
GET /api/v1/management/austria/ {clientId}/dep131	O	Eksporterer alle data, der kræves til DEP131-protokollen (DEP §131 BAO), fra de lokalt lagrede data.
GET /api/v1/management/austria/ {clientId}/dep/startReceipt	R	Returnerer startkvitteringen for denne client. Kassesystemet skal kunne levere startkvitteringen på anmodning under en regnskabsrevision. Hvis POS-systemet ikke har gemt startkvitteringen, kan den anmodes via dette endpoint.
GET /api/v1/management/austria/ {clientId}/DEP/monthReceipts	R	Returnerer alle månedskvitteringer inden for den anmodede datointerval. Kassesystemet skal kunne levere månedskvitteringer på anmodning under en regnskabsrevision. Hvis POS-systemet ikke har gemt disse dokumenter, kan de anmodes om via dette endpoint.
GET /api/v1/management/austria/ {clientId}/fon/certificate	O	Returnerer alle signaturenheder og angiver, om de er aktiveret på FinanzOnline (Fon) eller ej.
POST /api/v1/management/austria/ {clientId}/fon/certificate	O	Registrerer den konfigurerede signaturenhed hos Fon (hvis der er konfigureret en) eller den signaturenhed, der er identificeret med certificateSerial. Bemærk: Hvis RetailForce Cloud Services anvendes, registreres certifikater automatisk i FinanzOnline-portalen (Fon) (à brugeroplysninger for kasseapparatets webservice-bruger er nødvendige!); endpoint er kun nødvendigt, hvis registreringen skal foretages manuelt.
DELETE /api/v1/management/austria/ {clientId}/fon/certificate	O	Afregistrerer den konfigurerede signaturenhed hos Fon (hvis en sådan er konfigureret) eller den signaturenhed, der er identificeret med certificateSerial. OBS: Brug med forsigtighed!
GET /api/v1/management/austria/ {clientId}/fon/document	R	Validerer det senest signerede dokument i DEP hos FinanzOnline (FON).
GET /api/v1/management/austria/ {clientId}/Fon/document/{depDocument}	R	Validerer det angivne DEP-dokument (QR-kode) hos Fon.
GET /api/v1/management/austria/ {clientId}/fon/cashregister	O	Returnerer, om den aktuelle clients kasseapparat er aktiveret hos Fon. Påkrævet for offline-systemer.
POST /api/v1/management/austria/ {clientId}/fon/cashregister	O	Registrering af kassesystemet hos Fon for den aktuelle client. Påkrævet for offline-systemer.
DELETE /api/v1/management/austria/ {clientId}/fon/cashregister	O	Afregistrer kasseapparat hos Fon for den aktuelle client. Kræves til offline-systemer. OBS: Brug med forsigtighed!

ManagementController_Bulgaria

Kort beskrivelse: Administrationsfunktioner til bulgarsk fiskalisering.

Endpoint	Type	Beskrivelse
POST /api/v1/management/bulgaria/ {clientId}/commands/closing	M	Sender lukningskommando (Z) til den skattepligtige printer.
POST /api/v1/management/bulgaria/ {clientId}/commands/synchronizeTime	M	Sender kommandoen til tidssynkronisering (L) til den finansielle printer.
GET /api/v1/management/bulgaria/ {clientId}/reports/KLEN	R	Denne funktion kan bruges til at generere en såkaldt KLEN-rapport. (fra v1.8.3)
GET /api/v1/management/bulgaria/ {clientId}/reports/zreport	R	Denne funktion bruges til at udskrive detaljerede og opsummerede perioderapporter. (fra v1.8.3)
GET /api/v1/management/bulgaria/ {clientId}/reports/block	R	Denne funktion bruges til at udskrive en såkaldt BLOCK-rapport. (fra v1.8.3)

ManagementController_Danmark

Kort beskrivelse: Administrationsfunktioner til den danske fiskalisering.

Endpoint	Type	Beskrivelse
GET /api/v1/management/denmark/ {clientId}/saft	M	Eksporterer SAF-T-formatet for Danmark til den angivne stream.

ManagementController_France

Kort beskrivelse: Administrationsfunktioner til fransk skatteindberetning.

Endpoint	Type	Beskrivelse
GET /api/v1/management/france/eventlog/ {clientId}	M	Returnerer alle de anmodede revisionslogposter sorteret efter dato.
GET /api/v1/management/france/ archive/{clientId}	M	Returnerer de lokalt lagrede arkiver til lukning.
POST /api/v1/management/france/archive/ {clientId}/verify	M	Metode til verifikation af det franske arkiv.

ManagementController_Germany

Kort beskrivelse: Administrationsfunktioner til tysk fiskalisering.

Endpoint	Type	Beskrivelse
GET /api/v1/management/germany/TSE	R	Returnerer en række tilkoblede lokale TSE-enheder og deres status.
POST /api/v1/management/germany/ TSE/{TseSerial}/selftest	R	Kører en synkron selvtest for den angivne kasseapparat på TSE'en (kasseapparatet er valgfrit).
PUT /api/v1/management/germany/ {clientId}/TSE/connectTest	R	Foretager en testforbindelse til den angivne TSE.
GET /api/v1/management/germany/ {clientId}/TSE/listClients	O	Returnerer alle klienter, der er opført på den angivne klients TSE.
GET /api/v1/management/germany/ {clientId}/TSE/status	R	Returnerer status for TSE'en. Hvis der ikke findes noget skattemodul, returneres status RetailForce.Fiscalisation.Implementation. Germany.Tse.TseStatus.Critical.
PUT /api/v1/management/germany/ {clientId}/TSE/updateTime	M	Opdaterer klokkeslættet på TSE'en til den aktuelle computertid.
GET /api/v1/management/germany/ {clientId}/TSE/tar	O	Eksporterer tar-filerne fra den primære TSE. Påkrævet for offline-systemer.
GET /api/v1/management/germany/ {clientId}/taxonomy	O	Eksporterer taksonomi (DSFinV-K export) og returnerer den som en downloadfil (zip-filformat). Påkrævet for offline-systemer.
GET /api/v1/management/germany/ {clientId}/TSE/listTransactions	R	Returnerer alle aktive (påbegyndte) transaktioner på TSE. Anbefales til sporing af åbne transaktioner (alle påbegyndte transaktioner skal gemmes eller annulleres).
DELETE /api/v1/management/germany/ {clientId}/TSE/listTransactions	O	Annullerer aktive (påbegyndte) transaktioner på TSE.
GET /api/v1/management/germany/ {clientId}/TSE/openOfflineSignatures/count	O	Returnerer antallet af offline-transaktioner (= transaktioner, der ikke er blevet sendt til TSE på grund af, at TSE er offline – nede eller utilgængelig).
GET /api/v1/management/germany/ {clientId}/TSE/openOfflineSignatures	O	Returnerer alle åbne offline-signaturer, der er gemt for den aktuelle TSE.
PUT /api/v1/management/germany/ {clientId}/TSE/openOfflineSignatures	O	Behandler åbne offline-signaturer.
PUT /api/v1/management/germany/ {clientId}/TSE/replace	R	Erstat en eksisterende TSE for den angivne client med en ny (f.eks. hvis den gamle TSE er beskadiget, eller certifikatet er udløbet).
POST /api/v1/management/germany/ {clientId}/TSE/selftest	R	Kører en synkron selvtest for den angivne kasseapparat på TSE'en (kasseapparatet er valgfrit).
POST /api/v1/management/germany/ {clientId}/TSE/updateFirmware	R	Opdaterer firmwaren på swissbit-hardware-TSE-enheden.

ManagementController_Spain

Kort beskrivelse: Administrationsfunktioner til spansk skatteovervågning.

Endpoint	Type	Beskrivelse
GET /api/v1/management/spain/ {clientId}/TicketBAI	R	Returnerer de gemte TicketBAI-filer (sendte filer, svarfiler, fejlfiler) som en zip-fil.
GET /api/v1/management/spain/ {clientId}/TicketBAI/{DocumentNumber}	R	Returnerer de gemte TicketBAI-filer for det anmodede dokumentnummer (sendte filer, svarfiler, fejlfiler) som en zip-fil.

Kvitteringer

Kort beskrivelse: bruges til at sende digitale kvitteringer til RetailForce Cloud via middleware.

Endpunkterne i dette afsnit bruges til at sende digitale kvitteringsdokumenter til Cloud-systemet (der kræves licenser til digitale kvitteringer for at kunne benytte denne tjeneste!).

Endpoint

Type

Beskrivelse

POST /api/v1/receipts/{clientId}

O/M

Uploader en digital kvitteringsfil til Cloud-systemet.

Alternativ: Brug enten dette eller det alternative endpoint i dette afsnit til at sende data om digitale kvitteringer.

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

O/M

Uploader en digital fil til Cloud-systemet. Bruger metadata fra fiscalisation.