act’o-soft Logo

    Documentation

    Fiscal service environment

     

    The "fiscal4brand" service acts as an intermediary between the cash register system and the financial administration. The service processes the data from the POS system and ensures that it is formatted according to the requirements of the financial administration. 

    In addition, the "fiscal4brand" service offers additional functions such as storing data, creating reports and managing certificates.

    Below you'll find schematics in how the clients works via middleware and a signature unit. There are three examples shown here. First the initialization of the API and the fiscal service. Next ist the creation and processing of a fiscal transaction und last but not least, the execution of an exported function is shown.

     

    Initialization of the fiscal API

     

    Processing of transactions

     

    Exported functions

     

     

     

    Supported countries

    Country Fiscal device type
    Fiscal data transmission
    Bulgaria Fiscal printer
    Online 
    Germany Signature unit
    Offline 
    Austria Signature unit Online 
    France -  Offline 
    Greece Fiscal printer Online 
    Italy Fiscal printer Online 
    Poland Fiscal printer Online 
    Romania Fiscal printer Online 
    Serbia Signature unit Online 
    Slovakia Fiscal printer Online 
    Croatia Local service
    Online 
    Slovenia Local service
    Online 

     

    General Settings

    The Fiskalservice has a configuration file (config.sofia) which is located next to the executing file of the Fiskalservice. The configuration allows several options of the fiscal service to be switched on or off and connected hardware to be configured.

    It is planned to switch off HTTP operation from 01.01.2024. From this date, there will be a new switch that allows legacy operation with HTTP, but is excluded from any warranty.

     

    Config file (“config.sofia”)

    Property

    Value

    Description

    Port

    String (e.g. “1121”)

    The port that is set for control when the fiscal service is started.

    HTTPSEnabled

    Boolean (true / false)

    This property activates HTTPs.

    Hardware config

    Property

    Value

    Description

    Typ

    String

    Hardware Typ (e.g. LineDisplay)

    Interface

    String

    Hardware Interface (e.g. OPOS)

    Name

    String

    Name of the device

    Address

    String

    Address

    SpoolerUse

    Boolean

    Use spooler for device? (POS Printer, Fiscal Printer, ...)

    SpoolerRetryTime

    Integer

    Time until a new printing attempt is made

    SpoolerMaxReceiptStore

    Integer

    Maximum number of receipts to be saved

    HTTPS Konfiguration

    The "HTTPSEnabled" switch activates the HTTPS connection for Fiskalservice 3.X. Currently, the connected client must confirm a standard certificate. At a later date, the connection should be extended so that there is either a separate certificate that must be confirmed or the service should be extended so that a separate authentication is required.

    Country-specific information

    Germany [DE]

    StartTransaction

    The german fiscal laws require to mark the starting point of a sale transaction. With retail stores this is done, when a new shopping cart is created by the client, as well as when the first PLU item is scanned by the cashier. In our solution this has to be called explicit by the client. The result of calling this function, will result in a transaction ID which is to be used by the client. Date and time of this execution is the used in the fiscal unit mit mark the start of a sale.

    For further information, please check out our development guide here:

    Technical docu

     

    EndTransaction

    When the cashier finishes a sales transaction, let's say by receiving the payment from the customer, the transaction is sent to the fiscal service. Our service then verifies the contents of the transaction, processes it and the relevant fiscal data is sent to the fiscal unit. With a successful processing within the fiscal unit, the transaction is finished and there is no need to call EndTransaction explicitly.

     

    Available exported functions

    In the german fiscal solution, there are several exported functions available, which can be called remotely by the client application. We differentiate between country and device specific functions. These are the available functions for germany:

    • Country specific
      • Data export (DSFinV-k)
        Export of the fiscal data stored by the fiscal service as CSV files
    • Device specific
      • TAR export
        Exports all available TAR files from the fiscal unit
      • TAR export by period
        Exports all avaliable TAR files from date, to date
      • TAR export by transaction
        Exports all avalable TAR files from transaction no. to transaction no.
      • TSE checkout
        Checkout of a TSE fiscal unit, for store closings
      • TSE self test
        Technical self check of the fiscal unit
      • TSE unlock
        Unlocks a locked fiscal unit

    For further information, please check out our development guide here:

    Technical docu

     

    Available trigger functions

    In the german fiscal solution, there are several trigger functions available, which can be called remotely by the client application. These are the available trigger for germany:

    • Start transaction
      This function opens the new Transaction.

     

    Minimal receipt information

    In Germany, a minimal amount of information is required for a sales-receipt. The following properties are required:

    • Transaction-Type
      That type defines the type of the receipt.
    • TransactionID
      The unique ID of the transaction.
    • TransactionNumber
      Consecutive transaction number.
    • Currencies
      List of currencies used for the sale receipt.
    • Items
      List of items sold. Including currency iso & vat id.
    • CashItems
      List of payments for the sale receipt. Including type like "Cash", "Card" and more.

    (More details in the technical documentation)
    Technical docu

     

    Delimitation

    UpdateTransaction 

    Our fiscal service solution is mainly written for retail purposes like selling goods in a store (like fashion retail). If you want to use this solution in gastronomy or hotel industry, additional changes are needed. 

    In Germany it is mandatory to call StartTransaction on the fiscal device, when you create a new transaction in the  cash register software. When you finish the sale of goods, the transaction is sent to the fiscal device (TSE), which automatically finishes the transaction. 

    In gastronomy or the hotel industry, the transaction is finished when the customer has payed for the service and leaves the location. So it is necessary to update the transaction with the command UpdateTransaction, whenever new services are requested by the customer. This is needed when, for example new food or drinks are ordered. This feature is not yet available in the fiscal service and will be added later. 

    Transaction splitting 

    Transaction splitting is regularily used in the gastronomy sector, therefore it is necessary for a fiscal solution to provide transaction splitting, when multiple customers want to pay for a transaction separately. This feature ist not yet available in the fiscal service and will be added later.

    Location Group 

    The location group feature for fiscalization is used in gastronomy, when several restaurant tables are grouped together. This enables transactions to be assigned to a certain location group. This feature ist not yet available in the fiscal service and will be added later. 

     

    Hungary [HU]

    Installation guide

    Since January 1, 2014, a change in the law has come into force that only allows cash register systems that support receipt printers with an installed fiscal unit.

    It should be noted that communication between the tax office and the fiscal printer takes place via an interface (telecommunications network - GSM) and not via the public Internet. As a result, no further network settings need to be taken.

    Used Hardware

    Fiscal-Printer: Epson TM-T810F'
    Note: The print line is limited to max. 40 characters.

    POS Settings

    The regional and language settings must be set to the country. Please note that these settings must be set for ALL users of the PC, especially for systems where the character set settings differ from the Western European character set.

    Regional and language Options (Windows 10)

    Driver Settings

    The system expects the driver required for the fiscal printer to be installed and set up. The Fiscal Service Setup already contains all the necessary components including the fiscal printer driver.

    The driver installation package expects the printer to be connected to COM4. Any necessary changes to the COM port can be ensured by configuration. The cash drawer is not controlled via the fiscal printer.

     

    Integration Requirements

    In Hungary, financial transactions must be accompanied by a "reason". The following reasons are given:

    Pay In:

    Reason

    Description

    SDKTransactionType
    TransactionSubType

    01

    Change pay-in

    02

    Cashier pay-in

    03

    Fee collection

    04

    Lottery ticket selling

    05

    Deposit

    06

    Cash shortage

    07

    Tip

    08

    Other pay-in

     

    Pay Out:

    Reason

    Description

    SDKTransactionType
    TransactionSubType

    31

    SKIM

    32

    Cashier log-out

    33

    voucher out

    34

    gift card out

    35

    salary payout

    36

    wages payout

    37

    post fee payout

    38

    other costs

    39

    buy goods

    40

    closure amount payout

    41

    other payout

     

    API documentation

    You can find a detailed developemnt documentation of our fiscal API under the following link. Please note, that the documentation ist still preliminary and is subject to change.

    Technical docu

     

    Hard- and Software requirements

    There are several requirements for our fiscal service, that should be considered. While the SDK NuGet package works in every Visual Studio 2017 (and higher), the fiscal service itself has some requirements for hard- and software.

     

    Hardware

     

    Minimum

    Recommended

    CPU Dual Core @ 2,0 Ghz
    AMD Athlon / Intel Celeron 
    Quad Core @ 2,0 Ghz
    AMD Ryzen / Intel Core 
    Architecture 64-Bit (x64)  64-Bit (x64) 
    Memory 2 GByte  8 GByte 
    Storage *
    HDD SSD

    * the required storage depends on the used fiscal solution and the amount of transactions generated by the client application.

     

    Software

    Microsoft Windows 10 (or higher) with installed Microsoft .NET 6 Hosting Bundle
    Debian Linux support is given but needs to be officially approved by act'o-soft

     

    Glossary

    Fiscal API  This is the API interface for the Fiscal Service by act'o-soft. 
    Exported Function  This is a function provided by the fiscal service, which can be run remotely by the client application. 
    Text Index  This represents a number which will be converted to a specified text template. This is used by act'o-soft internally with its cash register application. 
    OID  The short form of "Object ID". This is used in our fiscal database and it is basically a GUID. 
    Reaction Advice  Depending on the outcome of a transaction processing, the fiscal service tells the client what to do next. The Reaction Advice could be OK (all fine), Warning (The client should show the error message to the user), Rollback (The last transaction should be undone), RollbackClose (The last transaction should be undone and the client needs to shut down) 
    Print Data  In some cases, the fiscal service provides the printed receipt in text form. 
    Symbology  This term is used in regards to barcode printing. The symbology represents a type of barcode, like QR-Codes.