My First Cashbox
After reading this, you can create a CashBox and have a functioning fiskaltrust.Middleware instance.
Unfortunately, this tutorial is not yet applicable to the Austrian market as rollout plans are not active there. However, while we are working on enabling rollout plans in Austria, you still use the shop to create a SignatureCloud cashbox.
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)
- 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β
Rollout plans are guided deployment wizards in the fiskaltrust.Portal, which assists you in buying, reselling and setting up CashBoxes and their components for your PosOperators. A rollout plan typically follows these five steps:
- Select the product you'd like to roll out.
- Select one or more PosOperators for which you plan the rollout.
- Select one or more outlets where you want to perform the rollout.
- Create a quote and load the quote into your shopping cart
- Perform the checkout
Business Rollout (getting the SCU)β
As the first step, we will be running a Business rollout which will acquire entitlements, transfer them to the PosOperators outlets and activate them and eventually create necessary backend components for the CashBox (in this case, an SCU).
- France
- Germany
As Middleware instances in France are self-contained setups, there are no particular steps necessary under Business Rollout.
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.
- Open your the rollout management page from
Rollout Management
/Plan
(Sandbox link) in the left-hand navigation menu. - Select
Business Rollout - Rolling out products
. - Filter for
swissbit cloud
and limit entries toDealerpackage based plans
. - Select the plan 4445-0008. This plan will create an SCU with a Swissbit Cloud TSE.
- Select
Perform the rollout for the current account
. - Tick the desired outlet where you would like to roll out the Middleware.
- Click
Submit Selection
. - Click
Create quote
- this will take a few seconds. Once the quote is ready, the button will change toLoad quote into cart
. - Click
Load quote into cart
to place the quote into your shopping cart. - Verify that the items in your shopping cart match the selected products.
- Click
Checkout
. - 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β
You can check the successful completion of the order by surrogating into the PosOperator's account.
In the PosOperator's account, now select PosOperator's 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 in the PosOperator's account for the selected location:
Technical Rollout (creating 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
- Germany
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.
Please ensure the outlet selected in step 6 has a valid SIRET code configured before you create the CashBox.
- Open your the rollout management page from
Rollout Management
/Plan
(Sandbox link) in the left-hand navigation menu. - Select
Technical Rollout - Creating cashboxes at scale
. - Filter for
REST CashBox
. - Select the plan
REST CashBox
. - Select
Perform the rollout for the current account
. - Tick the desired outletwhere you would like to roll out the Middleware.
- Click
Submit Selection
. - Click
Create quote
- this will take a few seconds. Once the quote is ready, the button will change toLoad quote into cart
. - Click
Load quote into cart
to place the quote into your shopping cart. - Verify that the items in your shopping cart match the selected products.
- Click
Checkout
. - 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
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.
- Open your the rollout management page from
Rollout Management
/Plan
(Sandbox link) in the left-hand navigation menu. - Select
Technical Rollout - Creating cashboxes at scale
. - Filter for
fiskaltrust Middleware fΓΌr Swissbit Cloud TSE
. - Select the plan
fiskaltrust Middleware fΓΌr Swissbit Cloud TSE
. - Select
Perform the rollout for the current account
. - Tick the same outlet you chose before during the Business rollout.
- Click
Submit Selection
. - Click
Create quote
- this will take a few seconds. Once the quote is ready, the button will change toLoad quote into cart
. - Click
Load quote into cart
to place the quote into your shopping cart. - Verify that the items in your shopping cart match the selected products.
- Click
Checkout
. - 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
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).
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 couple of 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 data it received. If you successfully get a response, the Middleware should also be ready to accept your signing requests.
For Postman, you can download a request collection from the Github repository.
Request detailsβ
- France
- Germany
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.
You can find the full details on the request and its parameters (along with a curl example) here.
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.
You can find the full details on the request and its parameters (along with a curl example) here.