diff --git a/poscreators/getting-started/get-started.md b/poscreators/getting-started/get-started.md index d6b0dc4..2b9a5a4 100644 --- a/poscreators/getting-started/get-started.md +++ b/poscreators/getting-started/get-started.md @@ -5,24 +5,34 @@ title: Introduction # Introduction -This guide provides a technical overview of the integration and onboarding workflow for PosCreators. It outlines the key stages required to successfully integrate **fiskaltrust.Middleware** into a POS system and to progress to pilot installations. +This page provides an overview of the steps required to get started as a PosCreator with fiskaltrust. -Successful completion of these stages ensures a reliable and compliant deployment of fiskaltrust solutions in your POS environment. +It outlines the key stages from initial setup and onboarding to the technical integration of **fiskaltrust.Middleware** into your POS system and preparation for pilot installations. + +Following these stages ensures a reliable and compliant deployment of fiskaltrust solutions. ## Integration Workflow -The integration process is divided into discrete stages, each with specific objectives and deliverables as follows: +The integration workflow focuses on the technical implementation of **fiskaltrust.Middleware** and is divided into discrete stages, each with specific objectives and deliverables. + +![integration phases](images/pos-creator-integration-phases.svg) + +:::info + +The [Onboarding Process](./onboarding-process.md) is described separately and is not part of the middleware integration itself. + +::: -![integration phases](images/pos-creator-integration-phases.png) +## Additional Resources -Before proceeding with this guide, review the following resources: +The following resources provide a high-level walkthrough of the overall process for PosCreators. -### Video Tutorial +### Tutorial video -A technical walkthrough covering the complete PosCreator onboarding process can be viewed as follows: +A technical introduction to fiskaltrust.Middleware, including onboarding concepts, integration phases, and rollout preparation: ### Presentation Slides -Download the slides corresponding to the video tutorial [here](presentations/technical-onboarding-poscreators.pdf). +Download the corresponding slides for a structured overview of the onboarding and integration process [here](presentations/technical-onboarding-poscreators.pdf). diff --git a/poscreators/getting-started/images/cashbox-config-cashbox-creation-01.png b/poscreators/getting-started/images/cashbox-config-cashbox-creation-01.png index 8983e09..741e106 100644 Binary files a/poscreators/getting-started/images/cashbox-config-cashbox-creation-01.png and b/poscreators/getting-started/images/cashbox-config-cashbox-creation-01.png differ diff --git a/poscreators/getting-started/images/cashbox-config-queue-creation-01.png b/poscreators/getting-started/images/cashbox-config-queue-creation-01.png index 4c979fa..7e9016b 100644 Binary files a/poscreators/getting-started/images/cashbox-config-queue-creation-01.png and b/poscreators/getting-started/images/cashbox-config-queue-creation-01.png differ diff --git a/poscreators/getting-started/images/cashbox-config-scu-creation-01.png b/poscreators/getting-started/images/cashbox-config-scu-creation-01.png index 000c959..bc86700 100644 Binary files a/poscreators/getting-started/images/cashbox-config-scu-creation-01.png and b/poscreators/getting-started/images/cashbox-config-scu-creation-01.png differ diff --git a/poscreators/getting-started/images/icon-download-launcher.png b/poscreators/getting-started/images/icon-download-launcher.png index b6e2602..44687d4 100644 Binary files a/poscreators/getting-started/images/icon-download-launcher.png and b/poscreators/getting-started/images/icon-download-launcher.png differ diff --git a/poscreators/getting-started/images/middleware.svg b/poscreators/getting-started/images/middleware.svg new file mode 100644 index 0000000..0f83668 --- /dev/null +++ b/poscreators/getting-started/images/middleware.svg @@ -0,0 +1,4 @@ + + + +
Queue
Queue
SCU
SCU
SSCD
SSCD
SSCD
SSCD
SSCD
SSCD
Cashbox
Cashbox
IPOS
IPOSText is not SVG - cannot display \ No newline at end of file diff --git a/poscreators/getting-started/images/pos-creator-integration-phases.svg b/poscreators/getting-started/images/pos-creator-integration-phases.svg new file mode 100644 index 0000000..5672007 --- /dev/null +++ b/poscreators/getting-started/images/pos-creator-integration-phases.svg @@ -0,0 +1,4 @@ + + + +PortalRegistrationft.MiddlewareIntegrationBusiness CaseAnalysisPOS DealerOnboardingPilotInstallationHandoverfor Rollout \ No newline at end of file diff --git a/poscreators/getting-started/middleware-integration.md b/poscreators/getting-started/middleware-integration.md index 11c0a5b..280ebdf 100644 --- a/poscreators/getting-started/middleware-integration.md +++ b/poscreators/getting-started/middleware-integration.md @@ -17,91 +17,99 @@ The following steps describe how to configure and test the integration of **ft.M ### 1.1 Overview -As a POS creator, your first goal is to be able to send requests to our free ft.Middleware from your POS-System, and to be able to test your integration. The following sections summarize the configuration of a CashBox and its components, which are required to achieve this goal. +As a POS creator, your first goal is to send requests from your POS system to our free ft.Middleware and test the integration. The following sections summarize the CashBox configuration and its components, which are required to achieve this goal. -**Note:** All steps which are described in this document are for testing purposes, and, unless specifically stated otherwise, should be carried out in the Sandbox instance of the fiskaltrust.Portal. +:::note + +All steps in this document are intended for testing purposes and should be performed in the Sandbox environment of the fiskaltrust Portal, unless otherwise specified. + +::: ### 1.2 CashBox -A so-called CashBox is a configuration container that connects (links) the configurations of individual components of the fiskaltrust.Middleware which can be configured in the fiskaltrust.Portal. The fiskaltrust.Portal can contain the configurations of Queues, SCUs, and various Helpers - and a CashBox connects them with each other. Next, we will configure an SCU and a Queue needed for testing, and then connect them together in the CashBox. +A CashBox is a configuration container that connects (links) the configurations of individual components of the fiskaltrust.Middleware which can be configured in the fiskaltrust.Portal. The fiskaltrust.Portal can contain the configurations of Queues, SCUs, and various Helpers. A CashBox links them together to form a complete Middleware configuration. -![cashbox](images/middleware.png) +In the next steps, an SCU and a Queue will be created for testing purposes and connected via a CashBox. -The steps for the creation and configuration of the CashBox are covered in the [further part of this document](#15-cashbox-creation). +![cashbox](images/middleware.svg) + +The steps for the creation and configuration of the CashBox are described in the [1.5 CashBox creation](#15-cashbox-creation) section. ### 1.3 Configuration of the SCU -The SCU (Signature Creation Unit) is a component of the ft.Middleware, which is responsible for the communication with the TSE. Depending on which TSE you plan to use, the SCU will have to be configured accordingly. +The SCU (Signature Creation Unit) is a component of the ft.Middleware responsible for the communication with the TSE. The configuration of an SCU depends on the specific TSE you intend to use. -To create an SCU configuration in the fiskaltrust.Portal, select the menu item ``Configuration -> Signature creation unit`` and press the button "Create". Enter a short description (name) and select the package for your TSE at "Package Name". Then select the latest version under "Package Version" and press the button "Save". +To create an SCU configuration in the fiskaltrust.Portal, select the menu item `Configuration` / `Signature creation unit` and click "Create". Enter a short description (name) for the SCU, then select the package for your TSE under "Package Name". Next, choose the latest version under "Package Version" and select the appropriate "Outlet". Click "Save" to create the SCU configuration. ![cashbox-config-scu-creation-01](images/cashbox-config-scu-creation-01.png) -Further configuration information is now required, and it may vary depending on the previously selected TSE package. In general, you specify here how the SCU can reach the TSE, and the endpoint via which the Queue will communicate with the SCU. - -In the upper section of this form you can specify how the SCU can reach the selected TSE (the fields depend on the selected TSE type): +After saving, additional configuration information are required. These depend on the selected TSE package. Typically, you define how the SCU connects to the TSE, as well as the endpoint through which the Queue communicates with the SCU. -- **Cryptovision** - Enter the device path, the drive letter followed by the colon to which you have connected the TSE. For example ``E:`` +In the upper section of the form, you can configure how the SCU connects to the selected TSE. The available fields depend on the chosen TSE type: -- **Swissbit** - Enter the device path, the drive letter followed by the colon to which you have connected the TSE. For example ``E:`` +- **Cryptovision** - Enter the device path (drive letter followed by a colon) where the TSE is connected, for example `E:`. +- **Swissbit** - Enter the device path (drive letter followed by a colon) where the TSE is connected, for example `E:`. +- **Diebold - Nixdorf** - Enter the COM port to which the TSE is connected, for example `COM6`. +- **Epson** - Under revision. +- **fiskaly Cloud-TSE** - Enter the TSS ID, API key and the "Secret" key. One can obtain them for testing purposes from the official fiskaly website and fiskaly dashboard. Alternatively, you can purchase a free trial fiskaly Cloud-TSE in the sandbox fiskaltrust.Portal shop. This will automatically create an SCU with the corresponding data. -- **Diebold - Nixdorf** - Enter the com port to which you have connected the TSE. For example ``COM6`` +:::note -- **Epson** - Under revision. +Select the outlet in the shop before you add the fiskaly Cloud-TSE test to your shopping cart (via the outlet dropdown in the upper area). -- **fiskaly Cloud-TSE** - Enter the TSS ID, API key and the "Secret" key. One can obtain them for testing purposes from the official fiskaly website and fiskaly dashboard. Alternatively, you can purchase a free trial fiskaly Cloud-TSE in our sandbox fiskaltrust.Portal shop. This will automatically create a SCU with the corresponding data for you. Note: Select the outlet in the shop before you add the test fiskaly Cloud-TSE to your shopping cart (outlet drop-down in the upper area). +::: -To specify the communication endpoint for reaching the SCU, select, for example, the "gRPC" by pressing the corresponding button in the lower part of the form . The input field is filled in automatically and can be edited further if necessary. For the goal of this document, the automatically filled gRPC endpoint is sufficient. +To specify the communication endpoint for the SCU, select, for example, the "gRPC" by pressing the corresponding button in the lower part of the form . The input field is filled automatically and can be edited if necessary. For the purposes of this guide, the automatically filled gRPC endpoint is sufficient. ![cashbox-config-scu-creation-02](images/cashbox-config-scu-creation-02.png) -Save the configuration of your SCU after entering the required data. In the next step we will configure the Queue. +Save the configuration of your SCU after entering the required data. In the next step, we will configure the Queue. ### 1.4 Configuration of the Queue -The Queue is a component of the fiskaltrust.Middleware which collects the received data from the POS-System and is responsible for creating the request chain. It is the component of the fiskaltrust.Middleware with which your POS-System communicates. You send your data to it and receive signatures (and other data) back. +The Queue is a component of the fiskaltrust.Middleware that collects the received data from the POS system and is responsible for creating the request chain. It is the component of the fiskaltrust.Middleware with which your POS system communicates. You send your data to it and receive signatures (and other data) in return. -Under the menu item ``Configuration -> Queue`` you will find the button for creating a new Queue. Press this button to get to the input form. Enter a short description (name) and the CashBoxIdentification. The CashBoxIdentification will later be used by the SCU as clientID for the TSE. It is therefore important to enter a ["printable string"](https://en.wikipedia.org/wiki/PrintableString) with a maximum of 20 characters and that the **used value is unique**. +Under the menu item `Configuration` / `Queue`, click the "Add" button to create a new Queue. This opens the input form. Enter a short description (name) and the CashBoxIdentification. The CashBoxIdentification is later used by the SCU as clientID for the TSE. It must therefore be a **unique value**, formatted as a ["printable string"](https://en.wikipedia.org/wiki/PrintableString) with a maximum length of 20 characters. ![cashbox-config-queue-creation-01](images/cashbox-config-queue-creation-01.png) -After saving, a form appears in which you can specify the communication endpoint. We will use this later for the communication with the queue. For our example we can choose http(REST) by pressing the corresponding button. +After saving, a form appears where you can specify the communication endpoint. This endpoint will later be used for communication with the Queue. For our example, we will choose http(REST) by clicking the corresponding button. ![cashbox-config-queue-creation-02](images/cashbox-config-queue-creation-02.png) -After saving, we are done with the configuration of the Queue and can now create the CashBox (our configuration container) in the next step. +Once saved, the Queue configuration is complete. In the next step, we will create the CashBox (our configuration container). ### 1.5 CashBox creation -Under the menu item ``Configuration -> CashBox`` you will find the button to create a new CashBox. Press this button to get to the input form. After entering a short description (name) press the "Save" button. The CashBox has been created and now appears in the list. +Under the menu item `Configuration` / `CashBox,`click the "Add" button to create a new CashBox. This opens the input form. After entering a short description (name), click "Save". The CashBox is now created and appears in the list. ![cashbox-config-cashbox-creation-01](images/cashbox-config-cashbox-creation-01.png) #### 1.5.1 Connecting CashBox with Queue and SCU -Next, we want to put the configuration of the Queue and SCU into the created CashBox and connect them to each other. To do this, press the button with list symbol assigned to the CashBox. +Next, we will add the configuration of the Queue and SCU to the created CashBox and connect them. To do this, click the button with the list icon assigned to the CashBox. ![icon-list-config](images/icon-list-config.png) -Here you can now select the previously created Queue and SCU using the corresponding checkboxes and then save your selection. In the following we will connect the Queue with the SCU. To do this, expand the list entry of the new CashBox in the overview of the CashBoxes. The detail area shows the contained configurations. Two buttons are assigned to the Queue configuration on the right. Press the first button (box and arrow symbol) to assign the new SCU to the Queue. +Select the previously created Queue and SCU using the corresponding checkboxes, then click "Save". After saving, we will connect the Queue with the SCU. To do this, expand the list entry of the new CashBox in the overview of the CashBoxes. The detail area shows the contained configurations. Two buttons are assigned to the Queue configuration on the right side. Click the first button (box-and-arrow icon) to assign the new SCU to the Queue. ![icon-box-and-arrow](images/icon-box-and-arrow.png) -A popup appears in which you can select the SCU. After assigning and saving we are done with the configuration of our CashBox. +A popup appears where you can select the SCU. After assigning and saving, the CashBox configuration is complete. ![queue-to-scu-assignment](images/queue-to-scu-assignment.png) ## 2. Middleware Launcher -The ft.Middleware Launcher starts the required services on the local machine, and exposes the endpoint configured for the Queue to the communication with your POS-System. +The ft.Middleware Launcher starts the required services on the local machine and exposes the endpoint configured for the Queue for the communication with your POS system. ### 2.1 Downloading the launcher -Before downloading the launcher **it is important that you "rebuild" the CashBox**. To do this, press the "Rebuild configuration" button (first grey button with reload symbol) in the CashBox line. **This action must be performed every time you change the configuration of the CashBox or one of its components**. +Before downloading the launcher, **it is important to "rebuild" the CashBox**. To do this, click the "Rebuild configuration" button (first grey button with the reload icon) in the CashBox line. **This action must be repeated whenever the CashBox configuration or any of its components is changed.**. ![icon-rebuild-cashbox](images/icon-rebuild-cashbox.png) -After rebuild you can now download the launcher. The download of the launcher is initiated by clicking the button "Download .NET Launcher" (globe symbol). +After rebuild, you can now download the launcher by clicking the "Download" button. ![icon-download-launcher](images/icon-download-launcher.png) @@ -109,48 +117,53 @@ After rebuild you can now download the launcher. The download of the launcher is :::info Note -The debug mode is not available for launcher version 1.2. When using AT queues, a [debug launcher](https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc/france/installation#fiskaltrustmiddleware) is available. However, it only provides additional logging for AT-specific scenarios. +The debug mode is not available in launcher version 1.2. For AT queues, a [debug launcher](https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc/france/installation#fiskaltrustmiddleware) is available, but it only provides additional logging for AT-specific scenarios. ::: -When the download is completed, you will receive a zip file containing the launcher, its corresponding configuration, and other required files. Now, unpack the zip file and in the newly unzipped folder locate a ``test.cmd`` file, which we will edit. Open it with an editor of your choice and add the argument `` -verbosity=Debug`` at the end of the second line (which starts with ``fiskaltrust.exe``). This will give us more detailed log output later. Now save and close the ``test.cmd`` file. +After the download is complete, you will receive a ZIP file containing the launcher, its corresponding configuration, and other required files. Extract the ZIP file and open the extracted folder. Locate the `test.cmd` fileand open it in a text editor of your choice. Add the argument `-verbosity=Debug` at the end of the second line (which starts with `fiskaltrust.exe`). This enables more detailed logging output.Save and close the `test.cmd` file. ### 2.3 Starting the launcher -The launcher must be started in the Administrator mode. You can start the launcher by right-clicking on the ``test.cmd`` file, and selecting "Run as Administrator". A terminal will appear where you can follow the start of the local middleware via log messages. This window remains open and visualizes log messages for further progress. Do not click into the inner area of the window, because this will pause the service (Windows feature). If this happens to you by mistake, click again and press "Enter" to cancel the interruption. +The launcher must be started in Administrator mode. To do this, right-click the `test.cmd` file and select "Run as Administrator". A terminal window will open where you can follow the start of the local middleware via log messages. This window remains open, as it displays log messages for further progress. Do not click inside the terminal window, as this may pause the service (Windows feature). If this happens accidentally, click the window again and press "Enter" to cancel the interruption. **Known issues / recommendations:** -- To prevent folder access issues during the start of the Launcher, it's best to extract the files to a "neutral" location, e.g. ``C:\Launcher\``. Starting the Launcher from one of the current user's folders may result in ``Access denied`` error. -- To prevent system permission issues when starting the Launcher, it's best to start the command prompt as Administrator, navigate to the folder containing Launcher's files, and start it from there. -- In case of a failed launch due to the port being used by another process, you may be required to change the port of the Queue's endpoint. In such case you'll have to rebuild the CashBox, download the Launcher again, and then retry the start it. If that fails a system restart may help. +- To avoid folder access issues during startup, extract the files to a "neutral" directory, e.g. `C:\Launcher\`. Running it from user-specific folders may result in **Access denied** errors. +- To avoid system permission issues when starting the Launcher, start a command prompt as Administrator, navigate to the folder containing Launcher's files, and start it from there. +- If the launcher fails because the port is already in use, you may need to change the Queue endpoint port. In that case, rebuild the CashBox, download the launcher again, and retry. If the issue persists, a system restart may help. ## 3. Middleware Communication ### 3.1 Initialization with an initial operation receipt -After starting the launcher, the local middleware is available. Next, we will initialize the launcher using an initial operation receipt. To help you understand this (and other) operations, we have prepared a Postman collection with several examples of simple requests and complex business cases. You can start our Postman collection directly from our fiskaltrust [middleware-demo-postman](https://github.com/fiskaltrust/middleware-demo-postman) github repo. +After starting the launcher, the local middleware is available. The next step is to initialize it using an initial operation receipt. To help you understand this and other operations, we provide a Postman collection with several examples of simple requests and complex business cases. You can access and use the collection directly from the fiskaltrust [middleware-demo-postman](https://github.com/fiskaltrust/middleware-demo-postman) GitHub repository. #### 3.1.1 Configuration of the Postman collection -Once the Postman collection loads, it must still be configured to send requests to the previously started local middleware. To do this, select the "fiskaltrust Middleware" collection, go to "Edit", and select the "Variables" tab. Here we find the two variables that are important for us: ``base_url`` and ``cashbox_id``. We need to modify those values as follows: - -- **base_url** - here we specify the URL of the previously created http(REST) endpoint of the Queue. The required value can be found in the fiskaltrust.Portal under the menu item ``Configuration -> Queue`` . Expand the detail area of the list entry of our Queue and copy the URL from there. For example ``rest://localhost:1500/f84bf516-a17b-4432-afa6-8c1050e2854d`` . Now replace ``rest://`` with ``http://`` in the URL to get the value for the Postman ``base_url`` variable. Example ``http://localhost:1500/f84bf516-a17b-4432-afa6-8c1050e2854d``. Now enter this value in Postman for the variable ``base_url`` as ``CURRENT_VALUE``. +After the Postman collection loads, it must still be configured to send requests to the previously started local Middleware. To do this, select the "fiskaltrust Middleware" collection, click "Edit", and select the "Variables" tab. Here you will find two relevant variables: `base_url` and `cashbox_id`. Configure them as follows: -- **cashbox_id** - here we must specify the ID of our configuration container (not to be confused with the CashBoxIdentification). We can find the value for the ``cashbox_id`` in the fiskaltrust.Portal under the menu item ``Configuration -> CashBox``. To do so, expand the detail area of the list entry of our CashBox and copy the value of **CashBoxId**. For example ``90682627-f707-45ab-84df-f855118bba97``. Now enter this as the value of the variable ``cashbox_id`` under ``CURRENT_VALUE`` in the Postman collection. +- **base_url** - Specifies the URL of the previously created http(REST) endpoint of the Queue. You can find the required value in the fiskaltrust.Portal under the menu item `Configuration` / `Queue`. Expand the detail area of the list entry of the Queue and copy the URL. For example, `rest://localhost:1500/f84bf516-a17b-4432-afa6-8c1050e2854d`. Replace `rest://` with `http://` in the URL to obtain the value for the Postman `base_url` variable. For example, `http://localhost:1500/f84bf516-a17b-4432-afa6-8c1050e2854d`. Now enter this value in Postman for the variable `base_url` as `CURRENT_VALUE`. +- **cashbox_id** - Specifies the ID of the configuration container (not to be confused with the CashBoxIdentification). You can find this value for the `cashbox_id` in the fiskaltrust.Portal under the menu item `Configuration` / `CashBox`. Expand the detail area of the list entry of the CashBox and copy the value of **CashBoxId**. For example, `90682627-f707-45ab-84df-f855118bba97`. Now enter this value in Postman for the variable `cashbox_id` under `CURRENT_VALUE`. -Press ``Update`` to save your changes. +Once both variables are configured, click `Update` to save your changes. #### 3.1.2 Send a request with the initial operation receipt -In our Postman collection you will find an entry with the name ``Initial Operation Receipt``. Click on it and select the ``Body`` tab to view its contents. You can now send the request by pressing the ``Send`` button. The request will be sent to the local middleware and you will get the response of the middleware back, which is displayed in Postman. In the terminal you can view the corresponding log messages. The ft.SecurityMechanism of the middleware and the TSE are now initialized and wait for further requests. +In our Postman collection, locate an entry with the name `Initial Operation Receipt`. Click on it and select the `Body` tab to view its contents. You can now send the request by clicking `Send`. The request will be sent to the local Middleware, and the response will be displayed in Postman. You can view the corresponding log messages in the terminal. The ft.SecurityMechanism of the Middleware and the TSE are now initialized and ready to process further requests. ### 3.2 Sending further requests -### 3.2.1 Interface doc +### 3.2.1 Compliance Middleware documentation -The interface to the middleware is described in our [interface-doc](https://github.com/fiskaltrust/interface-doc/) Github repository. The fiskaltrust interface-doc repo contains important information and descriptions about the communication with the middleware. The [doc](https://github.com/fiskaltrust/interface-doc/tree/master/doc) folder contains a general part (directory ``general``) and country specific parts that specify the general part in more detail depending on the country. It is important that you read this interface description in order to be able to make further steps. +The Compliance Middleware is described in our [Documentation](https://github.com/fiskaltrust/docs/tree/main/poscreators/middleware-doc) GitHub repository. This repository contains important information about communication with the Middleware. + +The [middleware-doc](https://github.com/fiskaltrust/docs/tree/main/poscreators/middleware-doc) folder includes a general section (directory `general`) and country-specific sections that extend the general specification with localized requirements. + +It is important to review this documentation before continuing with further steps. ### 3.2.2 Postman collection -In the Postman collection mentioned above there are many more examples of requests that you can analyze and execute. After you have familiarized yourself with the interface description [interface-doc](https://github.com/fiskaltrust/interface-doc/) we recommend our [webinar video](https://www.youtube.com/watch?v=mq1hHL8ezOg&t=15s) on the middleware in which we explain the examples and have collected and demonstrated further important information for you. +The Postman collection referenced above contains additional request examples that you can explore and execute. + +After familiarizing yourself with the Compliance Middleware documentation, we also recommend watching our [Middleware webinar video](https://www.youtube.com/watch?v=mq1hHL8ezOg&t=15s), which explains the examples in detail and provides additional context.