#1 do add x-possystem-id header to all requests in howtos/lib

README.MD

@@ -38,11 +38,14 @@ So far we only provide HOWTOs written in C#. To run them:
 ### Install and configure the InStore App
 
 - InStore App is [installed](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/installation-guides) and connected to a CashBox via your fiskaltrust sandbox portal
-- the HOWTO(s) use environment variables for configuration
+- the HOWTO(s) use environment variables for configuration (read via the used libPosSystemAPI further discussed in HOWTO 01)
     - `FISKALTRUST_CASHBOX_ID` - can be found in your fiskaltrust portal when configuring the CashBox
     - `FISKALTRUST_CASHBOX_ACCESS_TOKEN` - can be found in your fiskaltrust portal when configuring the CashBox
     - `FISKALTRUST_POS_SYSTEM_API_URL`  
       default is `https://possystem-api-sandbox.fiskaltrust.eu/v2`
+    - `FISKALTRUST_POS_SYSTEM_ID` - required for production use
+      For production usage and release tests you have to use a valid possystem id issued by fiskaltrust by adding/registering a "POS System" in the fiskaltrust portal.
+      Further details about POS System registration can be found in the fiskaltrust PosCreator documentation described in the section about PosDealer onboarding.
 - A payment provider is [configured](https://docs.fiskaltrust.eu/docs/poscreators/middleware-doc/instore-app/available-settings#payment-settings)
 
 #### Using the `Dummy Payment Provider` for easier integration (InStore App Developer Mode)

libPosSystemAPI.Test/IntegrationTestsBase.cs

@@ -82,7 +82,7 @@ protected async Task<Guid> InitFtPosSystemAPIClient()
         {
             (Guid ftCashboxID, string ftCashboxAccessToken)? credentials = Utils.GetCashboxCredentialsFromEnvironment();
             string? posSystemAPIUrl = Environment.GetEnvironmentVariable("FISKALTRUST_POS_SYSTEM_API_URL");
-            ftPosAPI.Init(credentials!.Value.ftCashboxID, credentials.Value.ftCashboxAccessToken, posSystemAPIUrl!, 75);
+            ftPosAPI.Init(credentials!.Value.ftCashboxID, credentials.Value.ftCashboxAccessToken, Guid.Parse("00000000-0000-0000-0000-000000000000"), posSystemAPIUrl!, 75);
             return credentials.Value.ftCashboxID;
         }
     }

libPosSystemAPI/PosAPIUtils/Utils.cs

@@ -133,8 +133,32 @@ public static async Task<bool> PingFtPosApiAvailable(string posSystemAPIUrl = "h
                 Logger.LogInfo("Using POS System API URL from environment FISKALTRUST_POS_SYSTEM_API_URL: " + posSystemAPIUrl);
             }
 
+            string? posSystemIDStr = Environment.GetEnvironmentVariable("FISKALTRUST_POS_SYSTEM_ID");
+            Guid? posSystemID = null;
+            if (posSystemIDStr == null)
+            {
+                Logger.LogWarning("!!! ATTENTION !!!");
+                Logger.LogWarning("FISKALTRUST_POS_SYSTEM_ID not set, using default ID 00000000-0000-0000-0000-000000000000");
+                Logger.LogWarning("NOT FOR PRODUCTION USE! ONLY FOR DEVELOPMENT AND TESTING PURPOSES WITH THE FISKALTRUST SANDBOX ENVIRONMENT!");
+                Logger.LogWarning("!!! ATTENTION !!!");
+                posSystemID = Guid.Parse("00000000-0000-0000-0000-000000000000");
+            }
+            else
+            {
+                try
+                {
+                    posSystemID = Guid.Parse(posSystemIDStr);
+                }
+                catch (FormatException)
+                {
+                    Logger.LogError($"Invalid POS System ID format in environment variable FISKALTRUST_POS_SYSTEM_ID  {posSystemIDStr}");
+                    return (false, "Invalid POS System ID format. Please ensure FISKALTRUST_POS_SYSTEM_ID is a valid GUID.");
+                }
+                Logger.LogInfo("Using POS System ID from environment FISKALTRUST_POS_SYSTEM_ID: " + posSystemID);
+            }
+
             Logger.LogInfo("Initializing ftPosAPI for cashbox ID: " + credentials.Value.ftCashboxID);
-            ftPosAPI.Init(credentials.Value.ftCashboxID, credentials.Value.ftCashboxAccessToken, posSystemAPIUrl, 75);
+            ftPosAPI.Init(credentials.Value.ftCashboxID, credentials.Value.ftCashboxAccessToken, posSystemID.Value, posSystemAPIUrl, 75);
 
             (bool success, _) = await ftPosAPI.EchoAsync();
             if (!success)

libPosSystemAPI/ftPosAPI.cs

@@ -26,17 +26,26 @@ public static class ftPosAPI
         internal static string PathPrefix { get; private set; } = string.Empty;
         internal static Guid CashBoxId { get; private set; }
 
+        internal static Guid PosSystemId { get; private set; }
+
         /// <summary>
         /// Initializes the ftPosAPI client with the given parameters.
         /// </summary>
         /// <param name="cashboxID"></param>
         /// <param name="cashboxAccessToken"></param>
+        /// <param name="posSystemID">
+        /// Identifies the calling possystem.  
+        /// For development and dev-testing purposes when using the fiskaltrust sandbox environment, you can use "00000000-0000-0000-0000-000000000000" as value.  
+        /// For production usage and release tests you have to use a valid possystem id issued by fiskaltrust by adding/registering a "POS System" in the fiskaltrust portal.
+        /// Further details about POS System registration can be found in the fiskaltrust PosCreator documentation described in the section about PosDealer onboarding.
+        /// </param>
         /// <param name="posSystemAPIUrl"></param>
         /// <param name="httpTimeoutSeconds">Timeout for HTTP requests in seconds.</param>
-        public static void Init(Guid cashboxID, string cashboxAccessToken, string posSystemAPIUrl = "https://possystem-api-sandbox.fiskaltrust.eu/v2", int httpTimeoutSeconds = 60)
+        public static void Init(Guid cashboxID, string cashboxAccessToken, Guid posSystemID, string posSystemAPIUrl = "https://possystem-api-sandbox.fiskaltrust.eu/v2", int httpTimeoutSeconds = 60)
         {
             POSSystemAPIUrl = posSystemAPIUrl;
             CashBoxId = cashboxID;
+            PosSystemId = posSystemID;
             Uri uri = new Uri(posSystemAPIUrl);
             PathPrefix = uri.AbsolutePath;
 
@@ -47,6 +56,7 @@ public static void Init(Guid cashboxID, string cashboxAccessToken, string posSys
             };
             Client.DefaultRequestHeaders.Add("x-cashbox-id", CashBoxId.ToString());
             Client.DefaultRequestHeaders.Add("x-cashbox-accesstoken", cashboxAccessToken);
+            Client.DefaultRequestHeaders.Add("x-possystem-id", PosSystemId.ToString());
         }
 
         public static async Task<(bool success, EchoRequestResponse? responseMessage)> EchoAsync(string message = "Hello fiskaltrust POS System API!")