My First Cashbox

summary

After reading this, you can create a CashBox and have a functioning fiskaltrust.Middleware instance.

Introduction

Our fiskaltrust.Portal supports you as a PosDealer with two options to create your first CashBox.
We recommend Rollout plans as our deployment wizards in the fiskaltrust.Portal. With Rollout Plans, you enjoy high security when creating, buying and setting up CashBoxes and related components for your PosOperators. Additionally, you save time by being able to select several PosOperators as well as several outlets at the same time.

You use the Manual creation if you need a configuration not covered by rollout plans. Then first read the Architecture section to learn more about the components needed to create a CashBox.

Both options require legally or commercially necessary preparations. These have been described and explained previously in this documentation. In the section Prerequisites, you will find them again summarized.

tip

Please make sure you use your Sandbox account. So you avoid a bill on your account.

If you don't have one yet, please get in touch with your PosCreator for invitation details or register a new PosDealer Sandbox account yourself.

Prerequisites

Before we roll out our Middleware instance, the following prerequisites must be in place:

• A working Internet connection (please see Network Requirements)
• An active PosDealer account (either by registration or by invitation through your PosCreator) at the fiskaltrust.Portal (Sandbox). Then, as a PosDealer, you can check PosSystems too to ensure that a PosSystemId is available. Note that this menu item is not available in the account of PosOperators.
• A checked set of Master Data and at least one outlet (please see Master Data)
• A system meeting the hardware and software requirements (in this tutorial we focus on rollouts on Windows)
• Any SSCD components (hardware or SaaS credentials) required for the setup, unless created during the setup itself

Rollout Plans

Explanation

A rollout plan typically follows these five steps:

1. Select the product you'd like to roll out.
2. Select one or more PosOperators for which you plan the rollout.
3. Select one or more outlets where you want to perform the rollout.
4. Create a quote and load the quote into your shopping cart
5. Perform the checkout

Business Rollout (create SCU data)

As the first step, we will run a Business rollout which will acquire entitlements, transfer them to the PosOperators outlets, activate them and eventually create necessary backend components for the CashBox (in this case, an SCU).

Austria

For this setup, we choose a fiskaltrust.Carefree plan. The fiskaltrust.Carefree plan will create a Carefree bundle including an OnlineSignature SCU. For a quick tutorial, we refrain from choosing a PosOperator and its outlets but assign the bundle to your account and outlet.

To start the Business rollout, log into your portal account and proceed with the following steps.

1. Open your the rollout management page from Rollout Management / Plan (Sandbox link) in the left-hand navigation menu.
2. Select Business Rollout - Rolling out products.
3. Filter for Carefree and limit entries to Dealerpackage based plans.
4. Select the plan 4154-0001. This plan will create a Carefree bundle.
5. Select Perform the rollout for the current account.
6. Tick the desired outlet where you would like to roll out the Middleware.
7. Click Submit Selection.
8. Click Create quote - this will take a few seconds. Once the quote is ready, the button will change to Load quote into cart.
9. Click Load quote into cart to place the quote into your shopping cart.
10. Verify that the items in your shopping cart match the selected products.
11. Click Checkout.
12. Click binding order to complete the order.

---

At this point, should have the order listed under Shop / Orders. Finishing the order can take a couple of minutes, but once it has been completed, there should be the following items active in your account

• two new demo subscriptions under Shop / Subscriptions
• the 'Carefree' column for the selected outlet under Company Name / Outlets shows a symbol for an active Carefree subscription.

France

As Middleware instances in France are self-contained setups, there are no particular steps necessary under Business Rollout.

Germany

For this setup, we choose a fiskaltrust.Carefree plan with a Swissbit TSE. The fiskaltrust.Carefree plan will create a Carefree and TSE-as-a-Service bundle and automatically generate and assign a Swissbit TSE to your account. Using an online TSE means no further hardware provisioning steps are required from your side. For a quick tutorial, we refrain from choosing a PosOperator and its outlets but assign the bundle to your account and outlet.

To start the Business rollout, log into your portal account and proceed with the following steps.

1. Open your the rollout management page from Rollout Management / Plan (Sandbox link) in the left-hand navigation menu.
2. Select Business Rollout - Rolling out products.
3. Filter for swissbit cloud and limit entries to Dealerpackage based plans.
4. Select the plan 4445-0008. This plan will create an SCU with a Swissbit Cloud TSE.
5. Select Perform the rollout for the current account.
6. Tick the desired outlet where you would like to roll out the Middleware.
7. Click Submit Selection.
8. Click Create quote - this will take a few seconds. Once the quote is ready, the button will change to Load quote into cart.
9. Click Load quote into cart to place the quote into your shopping cart.
10. Verify that the items in your shopping cart match the selected products.
11. Click Checkout.
12. Click binding order to complete the order.

---

At this point, should have the order listed under Shop / Orders. Finishing the order can take a couple of minutes, but once it has been completed, there should be the following items active in your account

• two new demo subscriptions under Shop / Subscriptions
• a new SCU for a Swissbit Cloud TSE under Configuration / Signature Creation Unit

Review successful completion

Select Company Name / Outlets. Filter the outlet table by entering a search term or sort the outlets by clicking on one of the table headings. For example, in the Carefree and AKO columns, you can check whether these products are activated. The following image shows an example of activating the fiskaltrust.CarefreeBundle for the selected location:

Technical Rollout (generate the CashBox)

The second step is the Technical rollout which will use a template to create a new CashBox and a new Queue. It will also link the previously created SCU (from the Business rollout) to the new Queue.

France

For this setup, we choose a rollout plan based on TBD. This plan will create a brand-new CashBox with a new queue and a new SCU.

To start the Technical rollout log into your portal account and proceed with the following steps.

caution

Please ensure the outlet selected in step 6 has a valid SIRET code configured before you create the CashBox.

1. Open your the rollout management page from Rollout Management / Plan (Sandbox link) in the left-hand navigation menu.
2. Select Technical Rollout - Creating cashboxes at scale.
3. Filter for REST CashBox.
4. Select the plan REST CashBox.
5. Select Perform the rollout for the current account.
6. Tick the desired outletwhere you would like to roll out the Middleware.
7. Click Submit Selection.
8. Click Create quote - this will take a few seconds. Once the quote is ready, the button will change to Load quote into cart.
9. Click Load quote into cart to place the quote into your shopping cart.
10. Verify that the items in your shopping cart match the selected products.
11. Click Checkout.
12. Click binding order to complete the order.

---

At this point, should have the order listed under Shop / Orders. Finishing the order can take a couple of minutes, but once it has been completed, you should have

• a new queue under Configuration / Queue
• a new SCU under Configuration / Signature creation unit
• a new CashBox under Configuration / CashBox

Germany

We choose a rollout plan based on a Swissbit template for this setup. This plan will create a new queue, a new CashBox, and link the previously created SCU.

To start the Technical rollout log into your portal account and proceed with the following steps.

1. Open your the rollout management page from Rollout Management / Plan (Sandbox link) in the left-hand navigation menu.
2. Select Technical Rollout - Creating cashboxes at scale.
3. Filter for fiskaltrust Middleware für Swissbit Cloud TSE.
4. Select the plan fiskaltrust Middleware für Swissbit Cloud TSE.
5. Select Perform the rollout for the current account.
6. Tick the same outlet you chose before during the Business rollout.
7. Click Submit Selection.
8. Click Create quote - this will take a few seconds. Once the quote is ready, the button will change to Load quote into cart.
9. Click Load quote into cart to place the quote into your shopping cart.
10. Verify that the items in your shopping cart match the selected products.
11. Click Checkout.
12. Click binding order to complete the order.

---

At this point, should have the order listed under Shop / Orders. Finishing the order can take a couple of minutes, but once it has been completed, you should have

• a new queue under Configuration / Queue
• a new CashBox under Configuration / CashBox

Manual Creation

Explanation

The Configuration of a CashBox follows these steps:

1. Choose PosOperator / Overview to switch to the account of the desired PosOperator.
2. Select Configuration / Signature Creation Unit.
3. Add a Signature Creation Unit or enter the data of your hardware in use.
4. Optionally add a helper.
5. Add and connect a Queue.
6. Add and connect a CashBox.

SCU

steps	description
	Select Configuration / Signature Creation Unit and check the List of Signature Creation Units.
...	To expand your SCUs, please choose +Add.
	You must add a Description.
	At Package name, you can select the desired option.
	At Package version, you can choose the desired option.
	You must select an Outlet at Outlet.
	At Package name, you can select the desired option.
	After you have selected Save, you will be directed to Configuration / Signature Creation Unit / Configuration. Add the necessary details for the selection you have made there.

Helper

Helpers are optional and vary depending on national laws and the needed functionality. Read the section Helper for further information.

Queue

A Queue is defined here, find more details at our interface description.

steps	description
	Select Configuration / Queue and check the List of Queues.
...	To expand your Queues, please choose +Add.
	You must add a Description.
	At Package name, you can select the desired option.
	At Package version, you can choose the desired option.
	At Timeout, you can specify a millisecond value for the timeout of the Queue.
	The Country Code depends on the chosen fiskaltrust.Portal and cannot be changed, see reference tables for details.
	Enter the desired CashBox Identification but note that this value cannot be changed again after saving your Queue.
	At Outlet, you can choose the desired option but note that this value cannot be changed again afer saving your Queue.
	After you have selected Save, you will be directed to Configuration / Queue / Configuration. Add there the necessary details for the selection you have made.

CashBox

steps	description
	Select Configuration / CashBox and check the List of CashBoxes.
...	To expand your CashBoxes, please choose +Add.
	You must add a Description.
	At IP Address, you can enter a value.
	At Oulet, you can choose the desired option but note that this value cannot be changed again afer saving your Queue.
	After you have selected Save, you will be directed to your List of CashBoxes at Configuration / CashBox. Add the necessary details for the selection you have made there.
	Select Drag & Drop to edit or edit by list to add the necessary details.

Deploying the CashBox

You should now have a working CashBox and be able to download its package and deploy it on your machine.

Download

To download the Middleware package for your newly created CashBox, go to your list of CashBoxes in the portal (at Configuration / CashBox) and click the download button for the Online Launcher.

The downloaded Middleware package assembles the appropriate binary packages for your CashBox and may take a while. Once your browser prompts you for the file download, save the file to your hard disk.

Deployment

Unzip the archive you downloaded into the directory where you'd like to deploy the Middleware. Once that is complete, you can start your Middleware instance with the test script test.cmd (please make sure to launch it with administrative privileges).

info

As we downloaded the Online Launcher, the archive only comes with the launcher stub, and the Middleware will fetch all additionally required packages upon the first start. The download of additionally required packages may delay the first start by a few seconds.

Running a test request

Once the Middleware has been deployed and started, it is advisable to perform a quick check if the Middleware is generally available on the network and responds to requests.

For that purpose, the Middleware features an echo/ping request type that responds with the received data. If you successfully get a response, the Middleware should also be ready to accept your signing requests.

postman collection

For Postman, you can download a request collection from the Github repository.

Request details

Austria

To perform an "echo" request, you will need to send a POST request to the configured Middleware URL, with the path /json/Echo. That request takes a JSON string in its request body, containing the message string you'd like to receive back from the Middleware.

For example, to send Hello fiskaltrust.Middleware! as a request string, we'd be sending the following request body along with the POST request.

"Hello fiskaltrust.Middleware!"

The following HTTP request example would send the above's string to the Middleware.

POST /json/Echo HTTP/1.1
Host: localhost
Content-Length: 31
Content-Type: application/json

"Hello fiskaltrust.Middleware!"

The response to your request should have a status code of 200 and contain the exact string you sent in the request in the response body.

info

You can find the full details on the request and its parameters (along with a curl example) here.

France

caution

This example uses REST as a communication protocol and requires your CashBox to have a REST helper enabled.

To perform an "echo" request, you will need to send a POST request to the configured Middleware URL, with the path /json/Echo. That request takes a JSON string in its request body, containing the message string you'd like to receive back from the Middleware.

For example, to send Hello fiskaltrust.Middleware! as a request string, we'd be sending the following request body along with the POST request.

"Hello fiskaltrust.Middleware!"

The following HTTP request example would send the above's string to the Middleware.

POST /json/Echo HTTP/1.1
Host: localhost
Content-Length: 31
Content-Type: application/json

"Hello fiskaltrust.Middleware!"

The response to your request should have a status code of 200 and contain the exact string you sent in the request in the response body.

info

You can find the full details on the request and its parameters (along with a curl example) here.

Germany

caution

This example uses REST as a communication protocol and requires your queue to have a configured rest:// URL.

To perform an "echo" request, you will need to send a POST request to the configured Middleware URL, with the path /json/v1/Echo. That request takes a JSON object in its request body, with one single string field named Message, containing the message string you'd like to receive back from the Middleware.

{
    "Message": "Hello fiskaltrust.Middleware!"
}

The following HTTP request example would take the (minified) JSON object from above and send Hello fiskaltrust.Middleware! to the Middleware.

POST /json/v1/Echo HTTP/1.1
Host: localhost
Content-Length: 46
Content-Type: application/json

{ "Message": "Hello fiskaltrust.Middleware!" }

The response to your request should have a status code of 200 and contain the same object and the exact string you sent in the request in the response body.

info

You can find the full details on the request and its parameters (along with a curl example) here.