diff --git a/posdealers/technical-operations/middleware/helper-possystemapi.md b/posdealers/technical-operations/middleware/helper-possystemapi.md deleted file mode 100644 index 6bb3d0f..0000000 --- a/posdealers/technical-operations/middleware/helper-possystemapi.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -slug: /posdealers/technical-operations/middleware/helper-possystemapi -title: Local PosSystem API Helper ---- -# How to Configure the Local PosSystem API Helper with Launcher 2.0 - -:::caution - -The local PosSystem API Helper is currently in preview. - -::: - -:::info summary - -After reading this, you can set up and configure the local PosSystem API Helper within a Launcher 2.0 deployment. - -## Introduction - -The local PosSystem API Helper is a Middleware component that exposes a local endpoint through which the POS System communicates with the fiskaltrust Middleware. It acts as a bridge between the POS System and the underlying Queue, and is required for Launcher 2.0 deployments. - -:::caution - -The PosSystem API Helper must be part of the **same [CashBox](cashbox.md)** as the Queue it is intended to serve. - -::: - -:::caution - -As the local PosSystem API Helper is currently only supported on the Launcher 2.0 this setup does not work for France. If you're interested in running this in Austria reach out to us as the launcher 2.0 is not enabled per default there. - -::: -## Add a Helper Local PosSystem API - -To add the local PosSystem API Helper, navigate to `Configuration` / `Helper` in the fiskaltrust Portal and follow the steps below. -Note that the following figures and steps are exemplary. - -![possystemapihelper1.png](images/possystemapihelper1.png) - -| steps | description | -|:----------------------:|---------------------------------------------------------------------------------------------------------------------------------------------| -|![Number 1](../../images/numbers/circle-1o.png) | _Choose `Configuration`/ `Helper` to get to the Helper configuration._ | -|![Number 2](../../images/numbers/circle-2o.png) | _Click on `+Add` for creating a new Helper._ | -|![Number 3](../../images/numbers/circle-3o.png) | Add or edit a **name** for your Helper at `Description`. | -|![Number 4](../../images/numbers/circle-4o.png) | Select `fiskaltrust.Middleware.Helper.LocalPosSystemApi` from the **`Package name`** drop-down. Note that this selection **cannot be changed later**. | -|![Number 5](../../images/numbers/circle-5o.png) | Select the latest `Package version` using the drop-down menu. | -|![Number 6](../../images/numbers/circle-6o.png) | You can select one of the available outlets with the drop-down menu. | -|![Number 7](../../images/numbers/circle-7o.png) | `Save` your changes. | - -Once saved, a **success** notification will appear confirming that the Helper has been created. The configuration window for the new Helper will then open automatically, allowing you to proceed with the setup. - -## Configure a PosSystem API Helper -![posystemapiconfiguration.png](images/posystemapiconfiguration.png) - -| steps | description | -|:----------------------:|---------------------------------------------------------------------------------------------------------------------------------------------| -|![Number 1](../../images/numbers/circle-1o.png) | Click `http` to generate a URL through which the POS-System can access the Helper. You may also rename the URL to one of your own choosing. | -|![Number 2](../../images/numbers/circle-2o.png) | `Save` your changes to return to `Configuration`/ `Helper`. | - -## Use a PosSystem API Helper - -![assignposysstemapi.png](images/assignposysstemapi.png) - -| steps | description | -|:----------------------------------------------:|----------------------------------------------------------------------------------------| -|![Number 1](../../images/numbers/circle-1o.png) | Navigate to `Configuration` / `CashBox` and search for the desired CashBox. | -|![Number 2](../../images/numbers/circle-2o.png) | Click `Edit` to open the CashBox configuration. | - -![selecthelper.png](images/selecthelper.png) - -| steps | description | -|:-----------------------------------------------:|-----------------------------------------| -| ![Number 3](../../images/numbers/circle-3o.png) | Scroll down to the **Helpers** section and locate the PosSystem API Helper. | -| ![Number 4](../../images/numbers/circle-4o.png) | Activate the Helper by selecting its checkbox. | - -![savecashboxconfig.png](images/savecashboxconfig.png) - -:::info - -The same LocalPosSystemApi Helper can be used in multiple cashboxes. - -::: - -| steps | description | -|:-----------------------------------------------:|-----------| -| ![Number 5](../../images/numbers/circle-5o.png) | Scroll back to the top of the page. | -| ![Number 6](../../images/numbers/circle-6o.png) | `Save` your configuration. | - -## Download Launcher - -:::caution - -The minimum required Launcher version is **2.0.0-rc.25**. When downloading a launcher the latest version is automatically downloaded. - -::: - -![downloadlauncher.png](images/downloadlauncher.png) - -| steps | description | -|:----------------------:|-------------| -|![Number 1](../../images/numbers/circle-1o.png) | Return to the `Configuration` / `CashBox` page. You should see the Helper URL you configured in the previous step. | -|![Number 2](../../images/numbers/circle-2o.png) | Click `Rebuild configuration` and wait for the success confirmation. | -|![Number 3](../../images/numbers/circle-3o.png) | Click `Download` and select the correct Version 2 Launcher architecture for your system. | - -## Deploy the CashBox - -Once the Launcher package is downloaded, extract it and run `launcher-test.cmd` (or `launcher-test.sh` on unix based systems) to start the Middleware. For detailed instructions on starting the Launcher and installing it as a service, see [Launcher 2.0 Getting Started](https://github.com/fiskaltrust/middleware-launcher?tab=readme-ov-file#getting-started). - -## Test the PosSystem API Helper - -Once the Middleware is running, verify that the PosSystem API Helper is working correctly by sending a test request. The easiest way to do this is to use the [fiskaltrust Developer Portal](https://developer.fiskaltrust.eu/), which provides an interactive interface for sending requests to the Middleware and inspecting the responses. - -![fiskaltrustfordevpage.png](images/fiskaltrustfordevpage.png) - -Select **POS System API** from the available options. - -![fiskaltrustfordev_selectmarket.png](images/fiskaltrustfordev_selectmarket.png) - -Select your market. - -![fiskaltrustfordev_settings.png](images/fiskaltrustfordev_settings.png) - -Click **Settings** in the top-right corner. - -![fiskaltrustfordev_setsettings.png](images/fiskaltrustfordev_setsettings.png) - -| steps | description | -|:----------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|![Number 1](../../images/numbers/circle-1o.png) | In the `Environment` section, select `Local Middleware`. | -|![Number 2](../../images/numbers/circle-2o.png) | In the `Middleware Endpoint` field, enter the Helper URL found on the `Configuration` / `CashBox` page. | -|![Number 3](../../images/numbers/circle-3o.png) | Copy the PIN from the `Configuration` / `CashBox` page, enter it in the field below, then click `Pair`. A confirmation message should appear as shown below. | - -![pairedpin.png](images/pairedpin.png) - -| steps | description | -|:-----------------------------------------------:|-------------------------------------------------------------------------| -| ![Number 4](../../images/numbers/circle-4o.png) | The `CashBox ID` and `Access Token` fields will be populated automatically. | -| ![Number 5](../../images/numbers/circle-5o.png) | Click `Test Connection` — a green **201** response confirms the Helper is working correctly. | - -Close **Settings**. You can now use the available endpoints to send requests to the Middleware and verify the Helper's functionality. - -![fiskaltrustfordev_endpoints.png](images/fiskaltrustfordev_endpoints.png) \ No newline at end of file diff --git a/posdealers/technical-operations/middleware/images/connect-helper-1.png b/posdealers/technical-operations/middleware/images/connect-helper-1.png new file mode 100644 index 0000000..6654409 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/connect-helper-1.png differ diff --git a/posdealers/technical-operations/middleware/images/connect-helper-2.png b/posdealers/technical-operations/middleware/images/connect-helper-2.png new file mode 100644 index 0000000..5475530 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/connect-helper-2.png differ diff --git a/posdealers/technical-operations/middleware/images/connect-helper-3.png b/posdealers/technical-operations/middleware/images/connect-helper-3.png new file mode 100644 index 0000000..65601f2 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/connect-helper-3.png differ diff --git a/posdealers/technical-operations/middleware/images/connect-helper-4.png b/posdealers/technical-operations/middleware/images/connect-helper-4.png new file mode 100644 index 0000000..a3766d3 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/connect-helper-4.png differ diff --git a/posdealers/technical-operations/middleware/images/connect-helper-5.png b/posdealers/technical-operations/middleware/images/connect-helper-5.png new file mode 100644 index 0000000..7139230 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/connect-helper-5.png differ diff --git a/posdealers/technical-operations/middleware/images/download-launcher-12.png b/posdealers/technical-operations/middleware/images/download-launcher-12.png new file mode 100644 index 0000000..d576ad3 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/download-launcher-12.png differ diff --git a/posdealers/technical-operations/middleware/images/existing-cashbox-1.png b/posdealers/technical-operations/middleware/images/existing-cashbox-1.png new file mode 100644 index 0000000..ae88397 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/existing-cashbox-1.png differ diff --git a/posdealers/technical-operations/middleware/images/fiskaltrustfordev_setsettings_fr.png b/posdealers/technical-operations/middleware/images/fiskaltrustfordev_setsettings_fr.png new file mode 100644 index 0000000..960bf31 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/fiskaltrustfordev_setsettings_fr.png differ diff --git a/posdealers/technical-operations/middleware/images/helper-url-1.png b/posdealers/technical-operations/middleware/images/helper-url-1.png new file mode 100644 index 0000000..6654409 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/helper-url-1.png differ diff --git a/posdealers/technical-operations/middleware/images/new-cashbox-1.png b/posdealers/technical-operations/middleware/images/new-cashbox-1.png new file mode 100644 index 0000000..9fed4c7 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/new-cashbox-1.png differ diff --git a/posdealers/technical-operations/middleware/images/new-cashbox-2.png b/posdealers/technical-operations/middleware/images/new-cashbox-2.png new file mode 100644 index 0000000..f43fda1 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/new-cashbox-2.png differ diff --git a/posdealers/technical-operations/middleware/images/new-cashbox-3.png b/posdealers/technical-operations/middleware/images/new-cashbox-3.png new file mode 100644 index 0000000..ab38ad9 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/new-cashbox-3.png differ diff --git a/posdealers/technical-operations/middleware/images/settings_fr.png b/posdealers/technical-operations/middleware/images/settings_fr.png new file mode 100644 index 0000000..ee17f15 Binary files /dev/null and b/posdealers/technical-operations/middleware/images/settings_fr.png differ diff --git a/posdealers/technical-operations/middleware/localpossystemapi-helper-1-2.md b/posdealers/technical-operations/middleware/localpossystemapi-helper-1-2.md new file mode 100644 index 0000000..2399421 --- /dev/null +++ b/posdealers/technical-operations/middleware/localpossystemapi-helper-1-2.md @@ -0,0 +1,241 @@ +--- +slug: /posdealers/technical-operations/middleware/helper-existing-cashbox +title: Local PosSystem API Helper with Existing 1.2 CashBox +--- +# How to use LocalPosSystemApi helper with an existing 1.2 cashbox + +:::info summary + +After reading this, you can configure the LocalPosSystemApi Helper and use it with an existing Middleware 1.2 CashBox by setting up a new Middleware 1.3 CashBox alongside it. + +::: + +## Introduction + +This guide describes how to use the LocalPosSystemApi Helper when you already have a running Middleware 1.2 CashBox. + +The LocalPosSystemApi Helper needs to run inside a Middleware 1.3 CashBox. + +For that reason we need to setup a second cashbox that contains only the LocalPosSystemApi Helper which is connecting to the queue running in the existing 1.2 CashBox. + +:::tip + +The packages starting with `fiskaltrust.service`, `fiskaltrust.signing` are part of the Middeleware 1.2 stack and packages starting with `fiskaltrust.Middleware` are part of the Middleware 1.3 stack. + +The Middleware 1.2 only supports the AT and FR markets. For new cashboxes in AT the Middleware 1.3 is also supported and should be preferred. + +::: + +The process consists of the following main steps: + +1. Prepare the 1.2 cashbox with a rest helper (if not already done). +2. Create and configure a new LocalPosSystemApi Helper. +2. Create a new 1.3 CashBox and assign the LocalPosSystemApi helper. + +## Navigate to the existing 1.2 CashBox + +To locate your existing Middleware 1.2 CashBox, navigate to `Configuration` / `CashBox` in the fiskaltrust Portal. + +![existing-cashbox-1.png](images/existing-cashbox-1.png) + +| steps | description | +|-------------------------------------------------|-------------------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | Navigate to `Configuration` / `CashBox`. | +| ![Number 2](../../images/numbers/circle-2o.png) | Use the search field to filter CashBoxes by name or ID to locate the existing one. | +| ![Number 3](../../images/numbers/circle-3o.png) | Identify the CashBox running Launcher 1.2 by checking the version displayed in the list. | +| ![Number 4](../../images/numbers/circle-4o.png) | Click the expand arrow to reveal the CashBox configuration inline. | +| ![Number 5](../../images/numbers/circle-5o.png) | Verify if a `fiskaltrust.service.helper.rest` is present. If it is present you can skip the next step | + +You can verify that the packages are running version 1.2 for example, the Queue will show a package such as `fiskaltrust.service.sqlite` in version 1.2. + +## Add a rest helper for the 1.2 CashBox + +:::info + +You can skip this step if a rest helper is already present in the 1.2 CashBox. + +::: + +To add the local rest Helper, navigate to `Configuration` / `Helper` in the fiskaltrust Portal and follow the steps below. +Note that the following figures and steps are exemplary. + + +![possystemapihelper1.png](images/possystemapihelper1.png) + +| steps | description | +|-------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | _Choose `Configuration`/ `Helper` to get to the Helper configuration._ | +| ![Number 2](../../images/numbers/circle-2o.png) | _Click on `+Add` for creating a new Helper._ | +| ![Number 3](../../images/numbers/circle-3o.png) | Add or edit a **name** for your Helper at `Description`. | +| ![Number 4](../../images/numbers/circle-4o.png) | Select `fiskaltrust.service.helper.rest` from the **`Package name`** drop-down. Note that this selection **cannot be changed later**. | +| ![Number 5](../../images/numbers/circle-5o.png) | Select the latest `Package version` using the drop-down menu. | +| ![Number 6](../../images/numbers/circle-6o.png) | You can select one of the available outlets with the drop-down menu. | +| ![Number 7](../../images/numbers/circle-7o.png) | `Save` your changes. | + +Once saved, a **success** notification will appear confirming that the Helper has been created. The configuration window for the new Helper will then open automatically, allowing you to proceed with the setup. + +### Use the rest Helper in the 1.2 CashBox + + +![assignposysstemapi.png](images/assignposysstemapi.png) + +| steps | description | +|-------------------------------------------------|-------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | Navigate to `Configuration` / `CashBox` and search for the 1.2 CashBox. | +| ![Number 2](../../images/numbers/circle-2o.png) | Click `Edit` to open the CashBox configuration. | + + +![selecthelper.png](images/selecthelper.png) + +| steps | description | +|-------------------------------------------------|---------------------------------------------------------------------------------| +| ![Number 3](../../images/numbers/circle-3o.png) | Scroll down to the **Helpers** section and locate the just created rest Helper. | +| ![Number 4](../../images/numbers/circle-4o.png) | Activate the Helper by selecting its checkbox. | + + +![savecashboxconfig.png](images/savecashboxconfig.png) + +| steps | description | +|-------------------------------------------------|-------------------------------------| +| ![Number 5](../../images/numbers/circle-5o.png) | Scroll back to the top of the page. | +| ![Number 6](../../images/numbers/circle-6o.png) | `Save` your configuration. | + + +## Add a LocalPosSystemApi Helper + +To add the LocalPosSystemApi Helper, navigate to `Configuration` / `Helper` in the fiskaltrust Portal and follow the steps below. +Note that the following figures and steps are exemplary. + +![possystemapihelper1.png](images/possystemapihelper1.png) + +| steps | description | +|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | _Choose `Configuration`/ `Helper` to get to the Helper configuration._ | +| ![Number 2](../../images/numbers/circle-2o.png) | _Click on `+Add` for creating a new Helper._ | +| ![Number 3](../../images/numbers/circle-3o.png) | Add or edit a **name** for your Helper at `Description`. | +| ![Number 4](../../images/numbers/circle-4o.png) | Select `fiskaltrust.Middleware.Helper.LocalPosSystemApi` from the **`Package name`** drop-down. Note that this selection **cannot be changed later**. | +| ![Number 5](../../images/numbers/circle-5o.png) | Select the latest `Package version` using the drop-down menu. | +| ![Number 6](../../images/numbers/circle-6o.png) | You can select one of the available outlets with the drop-down menu. | +| ![Number 7](../../images/numbers/circle-7o.png) | `Save` your changes. | + +Once saved, a **success** notification will appear confirming that the Helper has been created. The configuration window for the new Helper will then open automatically, allowing you to proceed with the setup. + +## Configure the LocalPosSystemApi Helper + + +![connect-helper-5.png](images/connect-helper-5.png) + +| steps | description | +|-------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | Click `http` to generate a URL through which the POS-System can access the Helper. You may also rename the URL to one of your own choosing. | +| ![Number 2](../../images/numbers/circle-2o.png) | In the configuration window, click `Add custom configuration` to reveal the Key and Value input fields. | +| ![Number 3](../../images/numbers/circle-3o.png) | Enter the parameters specified below one by one. Use the `+` button next to each row to add the next entry. | +| ![Number 4](../../images/numbers/circle-4o.png) | `Save` your changes to return to `Configuration`/ `Helper`. | + +| Key | Value | +|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `middlewareaccesstoken` | The **AccessToken** of the existing 1.2 CashBox. | +| `middlewarecashboxid` | The **CashBox ID** of the existing 1.2 CashBox. | +| `middlewareservicefolder` | `C:/ProgramData/fiskaltrust` _(optional, only required if the service folder of the 1.2 CashBox has been changed from the default. Set this to the custom path so the Helper knows where to find the Middleware data.)_ | + +The LocalPosSystemApi helper is now connected to the 1.2 CashBox. + +## Create a new 1.3 CashBox for the LocalPosSystemApi Helper + +To create a new CashBox, navigate to `Configuration` / `CashBox` and follow the steps below. + +![new-cashbox-1.png](images/new-cashbox-1.png) + +| steps | description | +|-------------------------------------------------|----------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | Navigate to `Configuration` / `CashBox`. | +| ![Number 2](../../images/numbers/circle-2o.png) | Click `Add` to create a new CashBox. | +| ![Number 3](../../images/numbers/circle-3o.png) | Enter a **description** for the new CashBox. | +| ![Number 4](../../images/numbers/circle-4o.png) | Select the appropriate **outlet**. | +| ![Number 5](../../images/numbers/circle-5o.png) | `Save` the new CashBox. | + +Once saved, click `Edit by list` to configure the components of the new CashBox. Note that for this setup, only the LocalPosSystemApi Helper is added to this CashBox, no Queue or SCU is required here. + +![new-cashbox-2.png](images/new-cashbox-2.png) + +| steps | description | +|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | Scroll down to the **Helpers** section and locate the `fiskaltrust.Middleware.Helper.LocalPosSystemApi` Helper created above. | +| ![Number 2](../../images/numbers/circle-2o.png) | Activate the Helper by selecting its checkbox. | +| ![Number 3](../../images/numbers/circle-3o.png) | `Save` the CashBox configuration. | + +![new-cashbox-3.png](images/new-cashbox-3.png) + +At this point you have two CashBoxes: the original 1.2 CashBox and the new 1.3 CashBox with the PosSystem API Helper assigned. + +## Download the Launcher for the 1.3 CashBox + +The 1.3 CashBox requires Launcher 2.0. To download it, navigate to `Configuration` / `CashBox`. + +![download-launcher-12.png](images/download-launcher-12.png) + +| steps | description | +|-------------------------------------------------|----------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | Locate the 1.3 CashBox and click `Rebuild configuration`. Wait for the success confirmation. | +| ![Number 2](../../images/numbers/circle-2o.png) | Click `Download` and select the correct **Version 2** Launcher architecture for your system. | + +## Run the Launcher for the 1.3 CashBox + +Once the Launcher package is downloaded, extract it and run `launcher-test.cmd` (or `launcher-test.sh` on Unix-based systems) to start the Middleware. For detailed instructions on starting the Launcher and installing it as a service, see [Launcher 2.0 Getting Started](https://github.com/fiskaltrust/middleware-launcher?tab=readme-ov-file#getting-started). + +## Download the Launcher for the 1.2 CashBox + +The 1.2 CashBox supports Launcher version 1. To download it, locate the existing 1.2 CashBox in the `Configuration` / `CashBox` view. + +| steps | description | +|-------------------------------------------------|-------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | Click `Rebuild configuration` and wait for the success confirmation. | +| ![Number 2](../../images/numbers/circle-2o.png) | Click `Download` and select the correct Launcher 1.2 or 1.3 architecture for your system. | + +## Run the Launcher for the 1.2 CashBox + +Extract and run `test.cmd` (or `test.sh` on Unix-based systems) to start the Middleware. For detailed instructions on starting the Launcher and installing it as a service, see [Launcher for Windows, Linux & macOS](launchers/desktop.md). + +## Find the Helper URL + +To get the Helper URL used for sending requests, navigate to `Configuration` / `CashBox`. + +![helper-url-1.png](images/helper-url-1.png) + +| steps | description | +|-------------------------------------------------|--------------------------------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | Locate the 1.3 CashBox and click the expand arrow to reveal the CashBox configuration inline. | +| ![Number 2](../../images/numbers/circle-2o.png) | The Helper URL is displayed below the PosSystem API Helper entry. Use this URL to send requests to the Middleware. | + +## Test the LocalPosSystemApi Helper + +Once the Middleware is running, verify that the LocalPosSystemApi Helper is working correctly by sending a test request. The easiest way to do this is to use the [fiskaltrust Developer Portal](https://developer.fiskaltrust.eu/), which provides an interactive interface for sending requests to the Middleware and inspecting the responses. + +![fiskaltrustfordevpage.png](images/fiskaltrustfordevpage.png) + +Select **POS System API** from the available options. + +![fiskaltrustfordev_selectmarket.png](images/fiskaltrustfordev_selectmarket.png) + +Select your market and then click **Settings** in the top-right corner. + +![settings_fr.png](images/settings_fr.png) + +A settings panel opens where you can configure the connection to the local Middleware. + +![fiskaltrustfordev_setsettings_fr.png](images/fiskaltrustfordev_setsettings_fr.png) + +| steps | description | +|-------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | In the `Environment` section, select `Local Middleware`. | +| ![Number 2](../../images/numbers/circle-2o.png) | In the `Middleware Endpoint` field, enter the Helper URL from the 1.3 CashBox found in the previous step. | +| ![Number 3](../../images/numbers/circle-3o.png) | Copy the PIN from the `Configuration` / `CashBox` page, enter it in the field below, then click `Pair`. A confirmation message should appear as shown below. | + +![pairedpin.png](images/pairedpin.png) + +| steps | description | +|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| +| ![Number 4](../../images/numbers/circle-4o.png) | The **CashBox ID** and **Access Token** fields will be populated with the values of the existing **1.2 CashBox**. | +| ![Number 5](../../images/numbers/circle-5o.png) | Click `Test Connection` — a green **201** response confirms the Helper is working correctly. | + +Close **Settings**. You can now use the available endpoints to send requests to the Middleware and verify the Helper's functionality. diff --git a/posdealers/technical-operations/middleware/localpossystemapi-helper.md b/posdealers/technical-operations/middleware/localpossystemapi-helper.md new file mode 100644 index 0000000..604f218 --- /dev/null +++ b/posdealers/technical-operations/middleware/localpossystemapi-helper.md @@ -0,0 +1,146 @@ +--- +slug: /posdealers/technical-operations/middleware/helper-possystemapi +title: Local PosSystem API Helper +--- +# How to Configure the Local PosSystem API Helper with Launcher 2.0 + +:::caution + +The LocalPosSystemApi Helper is currently in preview. + +::: + +:::info summary + +After reading this, you can set up and configure the LocalPosSystemApi Helper within a Launcher 2.0 deployment. + +## Introduction + +The LocalPosSystemApi Helper is a Middleware component that exposes a local endpoint through which the POS System communicates with the fiskaltrust Middleware. +It acts as a bridge between the POS System and the underlying Queue. + +:::caution + +The LocalPosSystemApi Helper must be part of the **same [CashBox](cashbox.md)** as the Queue it is intended to serve. + +::: + +:::caution + +As the LocalPosSystemApi Helper is currently only supported on the Launcher 2.0 this setup does not work for France. +Refer to the guide [../localpossystemapi-helper-existing.md] on how to setup the LocalPosSystemApi helper for the Middleware 1.2. + +If you're interested in running this in Austria reach out to us as the launcher 2.0 is not enabled per default there. + +::: + +## Add a LocalPosSystemApi Helper + +To add the LocalPosSystemApi Helper, navigate to `Configuration` / `Helper` in the fiskaltrust Portal and follow the steps below. +Note that the following figures and steps are exemplary. + +![possystemapihelper1.png](images/possystemapihelper1.png) + +| steps | description | +|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | _Choose `Configuration`/ `Helper` to get to the Helper configuration._ | +| ![Number 2](../../images/numbers/circle-2o.png) | _Click on `+Add` for creating a new Helper._ | +| ![Number 3](../../images/numbers/circle-3o.png) | Add or edit a **name** for your Helper at `Description`. | +| ![Number 4](../../images/numbers/circle-4o.png) | Select `fiskaltrust.Middleware.Helper.LocalPosSystemApi` from the **`Package name`** drop-down. Note that this selection **cannot be changed later**. | +| ![Number 5](../../images/numbers/circle-5o.png) | Select the latest `Package version` using the drop-down menu. | +| ![Number 6](../../images/numbers/circle-6o.png) | You can select one of the available outlets with the drop-down menu. | +| ![Number 7](../../images/numbers/circle-7o.png) | `Save` your changes. | + +Once saved, a **success** notification will appear confirming that the Helper has been created. The configuration window for the new Helper will then open automatically, allowing you to proceed with the setup. + +## Configure a LocalPosSystemApi Helper +![posystemapiconfiguration.png](images/posystemapiconfiguration.png) + +| steps | description | +|-------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | Click `http` to generate a URL through which the POS-System can access the Helper. You may also rename the URL to one of your own choosing. | +| ![Number 2](../../images/numbers/circle-2o.png) | `Save` your changes to return to `Configuration`/ `Helper`. | + +## Use a LocalPosSystemApi Helper + +![assignposysstemapi.png](images/assignposysstemapi.png) + +| steps | description | +|-------------------------------------------------|-----------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | Navigate to `Configuration` / `CashBox` and search for the desired CashBox. | +| ![Number 2](../../images/numbers/circle-2o.png) | Click `Edit` to open the CashBox configuration. | + +![selecthelper.png](images/selecthelper.png) + +| steps | description | +|-------------------------------------------------|---------------------------------------------------------------------------------| +| ![Number 3](../../images/numbers/circle-3o.png) | Scroll down to the **Helpers** section and locate the LocalPosSystemApi Helper. | +| ![Number 4](../../images/numbers/circle-4o.png) | Activate the Helper by selecting its checkbox. | + +![savecashboxconfig.png](images/savecashboxconfig.png) + +:::info + +The same LocalPosSystemApi Helper can be used in multiple cashboxes. + +::: + +| steps | description | +|-------------------------------------------------|-------------------------------------| +| ![Number 5](../../images/numbers/circle-5o.png) | Scroll back to the top of the page. | +| ![Number 6](../../images/numbers/circle-6o.png) | `Save` your configuration. | + +## Download Launcher + +:::caution + +The minimum required Launcher version is **2.0.0-rc.25**. When downloading a launcher the latest version is automatically downloaded. + +::: + +![downloadlauncher.png](images/downloadlauncher.png) + +| steps | description | +|-------------------------------------------------|--------------------------------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | Return to the `Configuration` / `CashBox` page. You should see the Helper URL you configured in the previous step. | +| ![Number 2](../../images/numbers/circle-2o.png) | Click `Rebuild configuration` and wait for the success confirmation. | +| ![Number 3](../../images/numbers/circle-3o.png) | Click `Download` and select the correct Version 2 Launcher architecture for your system. | + +## Deploy the CashBox + +Once the Launcher package is downloaded, extract it and run `launcher-test.cmd` (or `launcher-test.sh` on unix based systems) to start the Middleware. For detailed instructions on starting the Launcher and installing it as a service, see [Launcher 2.0 Getting Started](https://github.com/fiskaltrust/middleware-launcher?tab=readme-ov-file#getting-started). + +## Test the LocalPosSystemApi Helper + +Once the Middleware is running, verify that the LocalPosSystemApi Helper is working correctly by sending a test request. The easiest way to do this is to use the [fiskaltrust Developer Portal](https://developer.fiskaltrust.eu/), which provides an interactive interface for sending requests to the Middleware and inspecting the responses. + +![fiskaltrustfordevpage.png](images/fiskaltrustfordevpage.png) + +Select **POS System API** from the available options. + +![fiskaltrustfordev_selectmarket.png](images/fiskaltrustfordev_selectmarket.png) + +Select your market. + +![fiskaltrustfordev_settings.png](images/fiskaltrustfordev_settings.png) + +Click **Settings** in the top-right corner. + +![fiskaltrustfordev_setsettings.png](images/fiskaltrustfordev_setsettings.png) + +| steps | description | +|-------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ![Number 1](../../images/numbers/circle-1o.png) | In the `Environment` section, select `Local Middleware`. | +| ![Number 2](../../images/numbers/circle-2o.png) | In the `Middleware Endpoint` field, enter the Helper URL found on the `Configuration` / `CashBox` page. | +| ![Number 3](../../images/numbers/circle-3o.png) | Copy the PIN from the `Configuration` / `CashBox` page, enter it in the field below, then click `Pair`. A confirmation message should appear as shown below. | + +![pairedpin.png](images/pairedpin.png) + +| steps | description | +|-------------------------------------------------|----------------------------------------------------------------------------------------------| +| ![Number 4](../../images/numbers/circle-4o.png) | The `CashBox ID` and `Access Token` fields will be populated automatically. | +| ![Number 5](../../images/numbers/circle-5o.png) | Click `Test Connection` — a green **201** response confirms the Helper is working correctly. | + +Close **Settings**. You can now use the available endpoints to send requests to the Middleware and verify the Helper's functionality. + +![fiskaltrustfordev_endpoints.png](images/fiskaltrustfordev_endpoints.png) \ No newline at end of file diff --git a/posdealers/technical-operations/middleware/possystem-api-platforms.md b/posdealers/technical-operations/middleware/possystem-api-platforms.md new file mode 100644 index 0000000..45e8b21 --- /dev/null +++ b/posdealers/technical-operations/middleware/possystem-api-platforms.md @@ -0,0 +1,69 @@ +--- +slug: /posdealers/technical-operations/middleware/possystem-api-platforms +title: PosSystem API Platforms +--- + +# PosSystem API Platforms + +The PosSystem API can be used as a cloud hosted service or run locally inside of a CashBox. + +Each option has it's own usecases. + +## Cloud PosSystem API + +The Cloud hosted PosSystem API currently only works with the CloudCashbox. +It provides a fully manages solution and supports the full range of features the PosSystem API has to offer. + +*This works with a normal CloudCashbox. No special setup is needed. The cloud possystem api is reachable at http://possystem-api-sandbox.fiskaltrust.eu for sandbox or http://possystem-api.fiskaltrust.eu for production.* + +## Local PosSystem API + +The local possystem api works offline or online and runs inside your CashBox next to your queue. + +Currently only the `Echo`, `Sign` and `Journal` endpoints are supported when offline. + +*The `LocalPosSystemApi` Helper has to be configured in the cashbox for the PosSystem API to be available locally.* + +### Android + +The full Local PosSystem API experience is also provided on android through our android launcher (currently in preview). + +*No special configuration is needed. Communication works through [android intents](../../../poscreators/possystem-api/android-intent)* + + +## Setup Guides + +We've prepared some getting started guides for the local possystem api/android launcher/cloudcashbox. +Depending on your market and mode of operation please choose the correct setup from the table below. + +| | AT | FR | DE | IT | GR, PT, ES, BE | +|-------------|--------------------------------------------------------------|----------------------------------------------------------|--------------------------------------------------------------|--------------------------------------------------------------|-----------------------------------------------------------| +| **Local** | [1.3 CashBox Setup](./localpossystemapi-helper.md) | [1.2 CashBox Setup](./localpossystemapi-helper-1-2.md) | [1.3 CashBox Setup](./localpossystemapi-helper.md) | [1.3 CashBox Setup](./localpossystemapi-helper.md) | Currently not available | +| **Android** | [Android](../../../poscreators/possystem-api/android-intent) | Currently not available | [Android](../../../poscreators/possystem-api/android-intent) | [Android](../../../poscreators/possystem-api/android-intent) | Currently not available | +| **Cloud** | [CloudCashbox](./launchers/cloudcashbox.md#introductionn) | [CloudCashbox](./launchers/cloudcashbox.md#introduction) | [CloudCashbox](./launchers/cloudcashbox.md#introductionn) | [CloudCashbox](./launchers/cloudcashbox.md#introductionn) | [CloudCashbox](./launchers/cloudcashbox.md#introductionn) | + + +### Middleware 1.2 setups + +:::info + +Relevant only for the FR market aswell as for existing AT Queues. + +We're working on unifying these two markets with the others. + +::: + +The setup of the LocalPosSystemAPI helper is a bit more involved for the middleware 1.2. + +This is relevant for all local installations in the FR market and for existing 1.2 installations in the AT market. + +:::tip + +When starting a new implementation in the AT market it's already possible to use the 1.3 Middleware as per the table above. + +::: + +| | AT, FR | +|-----------|--------------------------------------------------------| +| **Local** | [1.2 CashBox Setup](./localpossystemapi-helper-1-2.md) | +