fiskaltrust.Middleware demo (Node)

A demo application that demonstrates how to call the fiskaltrust.Middleware from Node.js using gRPC.

Getting Started

Prerequisites

In order to use this demo application, the following prerequisites are required:

• The demo application: The easiest way to retrieve this is to clone this repository.
• The fiskaltrust.Middleware running on your machine, which can be configured and downloaded via the fiskaltrust.Portal (AT, DE, FR). Start it (either by running it as a service, or with the test.cmd file), and let it run in the background to handle your requests.
• Your Cashbox Id is visible in the portal. It is also displayed in the startup console log of the Middleware.

This example uses the .proto files of the fiskaltrust Middleware interface to automatically generate the client and the contracts at runtime via the officially suggested gRPC packages (a comprehensive tutorial and overview can be found here). The proto files are available in our interface-doc repository, and will automatically be downloaded in this sample (as described below).

To run the demo, Node.js and NPM need to be installed. Follow the following steps:

Running the Demo

After cloning the repository, run the following commands to setup and start the application. npm install will automatically pull the latest .proto files, and put them into the /proto folder.

npm install   # This will also download the .proto files
node app.js   # You will be prompted for the middleware URL and the cashbox ID

1. The demo will show up a list of available demo receipts, pulled from the receipt-examples folder. Before executing any receipt, make sure that the SCU is initialized, by calling the initial-operation-receipt.
2. To execute a receipt against the middleware, select it by its leading number and press Enter.
3. This will print the example to the command line and send it to the Sign endpoint of the Middleware. After the receipt is processed, the Middleware will return the result back to the demo app, which again prints it to the console.
4. Alternatively, a Journal request can also be executed. This is used to export different types of data from the middleware - system information, processed receipts, etc.
5. To go back to the command list, press enter

Additional information

The fiskaltrust.Middleware is written in C# and uses some language-specific functionalities that a user needs to take care of when connecting via gRPC:

Due to the binary serialization in Protobuf, DateTime and decimal (which are native types in C#) need to be converted when used outside of .NET. Thus, the bcl.proto is referenced in the IPOS.proto file. An example how to deal with these types is shown in proto-helpers.js.

Minimal sample

This minmial sample code can be used to connect to the Middleware via gRPC and Node. It sends an Echo request, which can be used to test the connection without altering any data.

const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');

const packageDefinition = protoLoader.loadSync(
    'IPOS.proto',
    { keepCase: true, longs: String, enums: String, defaults: true, oneofs: true});

const grpcProxyObject = grpc.loadPackageDefinition(packageDefinition).fiskaltrust.ifPOS.v1;
const pos = new grpcProxyObject.POS(url, grpc.credentials.createInsecure());

client.Echo({ Message: "Hello World!" }, function (err, response) {
    if (err) {
        console.error(err);
        return;
    }
    console.log('Echo response:', response.Message);
});

Documentation

The full documentation for the interface can be found on https://docs.fiskaltrust.cloud. It is activeliy maintained and developed in our interface-doc repository.

More information is also available after logging into the portal with a user that has the PosCreator role assigned.

Communication

The fiskaltrust.Middleware supports different communication protocols, effectively giving our customers the possibility to use it on all platforms. Hence, different protocols are recommended for different platforms. For non-windows environments, we recommend the usage of gRPC. Please have a look into our other demo repositories for alternatives, e.g. HTTP/REST or SOAP.

User specific protocols

With the helper topology, it is possible to solve every scenario. Please contact our support if you required assistance for a special case scenario.

Contributions

We welcome all kinds of contributions and feedback, e.g. via Issues or Pull Requests.

Related resources

Our latest samples are available in the following languages:

                                               

Additionally, other samples (including legacy ones) can be found in our demo repository.