### gRPC Client Setup and Echo Example

Source: https://context7.com/fiskaltrust/interface-doc/llms.txt

Sets up a .NET gRPC client to connect to the fiskaltrust middleware and demonstrates an echo request. Ensure the gRPC channel address is correct. For other languages, use the provided `.proto` files.

```cs
// .NET gRPC client setup (Germany)
using var channel = GrpcChannel.ForAddress("http://localhost:1201");
var client = new IPOS.IPOSClient(channel);

var request = new EchoRequest { Message = "test" };
var response = await client.EchoAsync(request);
Console.WriteLine(response.Message);  // → "test"

// For Java, Node.js, Android — use the .proto files from dist/protos/
// See: https://github.com/fiskaltrust/middleware-demo-java
//      https://github.com/fiskaltrust/middleware-demo-node
//      https://github.com/fiskaltrust/middleware-demo-android
```

--------------------------------

### Install fiskaltrust.Middleware as a Service (Linux)

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/general/installation/installation.md

Install the fiskaltrust.Middleware as a Daemon on Linux using the pre-configured command file. Refer to the Mono service installation documentation for details.

```bash
sudo mono fiskaltrust.exe -test
```

--------------------------------

### Install fiskaltrust Launcher on Linux/macOS (Mono)

Source: https://context7.com/fiskaltrust/interface-doc/llms.txt

Install Mono and mono-service. Create a service folder and set permissions. Copy launcher files. Test mode requires specific parameters. Install as a daemon using update-rc.d.

```bash
# Install Mono (complete) + mono-service:
sudo apt update && sudo apt install mono-4.0-service

# Create service folder:
sudo mkdir /etc/fiskaltrust && sudo chmod 777 /etc/fiskaltrust

# Copy launcher files to /etc/fiskaltrust/

# Test mode:
sudo mono fiskaltrust.exe -test \
  -cashboxid 00000000-0000-0000-0000-000000000000 \
  -accesstoken <token> \
  -sandbox true

# Install as daemon:
sudo chmod +x /etc/init.d/fiskaltrust
sudo chmod +x /etc/fiskaltrust/fiskaltrust.exe
sudo update-rc.d fiskaltrust defaults
```

--------------------------------

### Install Windows Service

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/general/installation/installation.md

Use the -i parameter to install the Windows service. Use -u to uninstall.

--------------------------------

### Install fiskaltrust Launcher on Windows (Service)

Source: https://context7.com/fiskaltrust/interface-doc/llms.txt

Download the launcher from fiskaltrust.Portal and run as administrator. Use test mode for development. Install as a Windows service using install-service.cmd. Key launch parameters include cashboxid, accesstoken, useoffline, sandbox, servicefolder, verbosity, and proxy.

```cmd
# Download launcher from fiskaltrust.Portal → CashBox → Download
# Unzip and run as administrator:

# Test mode (recommended for development):
fiskaltrust.exe -test -cashboxid 00000000-0000-0000-0000-000000000000 -accesstoken <token>

# Install as Windows service:
install-service.cmd   # runs fiskaltrust.exe -i as administrator

# Key launch parameters:
# -cashboxid      GUID of the CashBox
# -accesstoken    authentication token for online communication
# -useoffline     true|false — use static local config
# -sandbox        true|false — sandbox vs production environment
# -servicefolder  path for data storage (config, SQLite db, exports)
# -verbosity      Trace|Debug|Information|Warning|Error|Critical  (DE only)
# -proxy          "address=1.2.3.4;username=u;password=p"
```

--------------------------------

### Install fiskaltrust.Middleware as a Service (Windows)

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/general/installation/installation.md

Install the fiskaltrust.Middleware as a Windows service using the install-service.cmd command file. This is recommended for permanent on-premise operation. Run the command file as administrator.

```batch
install-service.cmd
```

--------------------------------

### Copy Receipt Data Example

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/middleware-fr-boi-tva-decla-30-10-30/data-structures/data-structures.md

This example shows how to populate `ftReceiptCaseData` and `cbPreviousReceiptReference` for copy operations in French receipt requests.

```json
"ftReceiptCaseData" : "{\"CopyReason\" : \"Ticket réimprimé à la demande du client\"}",
"cbPreviousReceiptReference" : "HP202112-001"
```

--------------------------------

### Install Daemon

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/general/installation/installation.md

Command to install the fiskaltrust daemon using update-rc.d.

```bash
sudo update-rc.d fiskaltrust defaults
```

--------------------------------

### gRPC Client Setup

Source: https://context7.com/fiskaltrust/interface-doc/llms.txt

Demonstrates setting up a .NET gRPC client for the fiskaltrust middleware. gRPC is the recommended protocol for new integrations and supports Germany and Italy.

```APIDOC
## gRPC (Germany and Italy)

gRPC is the recommended protocol for new integrations. `.proto` files are available in `dist/protos/`. A NuGet client package is available at `fiskaltrust.Middleware.Interface.Client.Grpc`.

```cs
// .NET gRPC client setup (Germany)
using var channel = GrpcChannel.ForAddress("http://localhost:1201");
var client = new IPOS.IPOSClient(channel);

var request = new EchoRequest { Message = "test" };
var response = await client.EchoAsync(request);
Console.WriteLine(response.Message);  // → "test"

// For Java, Node.js, Android — use the .proto files from dist/protos/
// See: https://github.com/fiskaltrust/middleware-demo-java
//      https://github.com/fiskaltrust/middleware-demo-node
//      https://github.com/fiskaltrust/middleware-demo-android
```
```

--------------------------------

### Start, Stop, and End-of-Failure Zero Receipts (C#)

Source: https://context7.com/fiskaltrust/interface-doc/llms.txt

Use these special receipts for lifecycle management: initializing a new queue/SCU (Start Receipt), decommissioning a queue (Stop Receipt), or exiting late-signing mode after Middleware restoration (End-of-Failure Receipt). They feature empty charge and pay items.

```csharp
var startReceipt = new ReceiptRequest
{
    cbChargeItems = new ChargeItem[0],
    cbPayItems    = new PayItem[0],
    ftReceiptCase = 0x4445000000000003  // DE: initial receipt (Start Receipt)
};
var startResponse = proxy.Sign(startReceipt);
// ftReceiptIdentification will contain the TSE serial number in the signature block
```

```csharp
var endOfFailure = new ReceiptRequest
{
    cbChargeItems = new ChargeItem[0],
    cbPayItems    = new PayItem[0],
    ftReceiptCase = 0x4445000000000007  // DE: end-of-failure receipt
};
var endResponse = proxy.Sign(endOfFailure);
// ftState will return 0x4445000000000000 (healthy) if SCU is reachable
```

```csharp
var stopReceipt = new ReceiptRequest
{
    cbChargeItems = new ChargeItem[0],
    cbPayItems    = new PayItem[0],
    ftReceiptCase = 0x4445000000000004  // DE: stop receipt (closing receipt)
};

```

--------------------------------

### Example Version Information

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/general/reference-tables/reference-tables.md

This JSON structure represents version information for the fiskaltrust.Middleware. It includes assembly details and a structured version object with major, minor, build, and revision numbers.

```json
{
    "Assembly": "fiskaltrust.Middleware.Queue, Version=1.3.24.0, Culture=neutral, PublicKeyToken=null",
    "Version": {
        "Major": 1,
        "Minor": 3,
        "Build": 24,
        "Revision": 0,
        "MajorRevision": 0,
        "MinorRevision": 0
    }
}
```

--------------------------------

### Example OCR Output in Base64

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/middleware-at-rksv/reference-tables/reference-tables.md

This is an example of a signature value encoded in Base64, intended for OCR display when QR code printing is not supported.

```nohighlight
_R1-AT0_DEMO-CASH-BOX426_776730_2015-10-14T18:20:23_0,00_0,00_0,00_0,00_0,00_0gJTFI8/zqc=_968935007593160625_fP7/PMP-SnQ0=_Xh5wNe0akaTOVvMgLVrCcRh2xmIyP91ogbxc5xv4Rrw64lpQsqLm+1GZxuCz4D1sZl9WCv3wMMoE0p+gyLaufg==
```

--------------------------------

### Start Transaction Response (JSON)

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/middleware-de-kassensichv/cash-register-integration/single-receipt-creation.md

The middleware's response after a start transaction request. It contains queue information and a signature block with details for the receipt.

```json
{
    "ftCashBoxID": "cashboxid-guid",
    "ftQueueID": "b6c9f13b-b987-43cd-ab08-3f5cb2a850d6",
    "ftQueueItemID": "e617a29e-ed50-4a4c-ab8c-449884c0e217",
    "ftQueueRow": 11,
    "cbTerminalID": "T1",
    "cbReceiptReference": "233348",
    "ftCashBoxIdentification": "220130d5-9060-4e26-b75c-35968f49aae3",
    "ftReceiptIdentification": "ftA#ST10",
    "ftReceiptMoment": "2020-05-22T10:47:42.3247875Z",
    "ftSignatures": [
        {
            "ftSignatureFormat": 13,
            "ftSignatureType": 4919338167972134928,
            "Caption": "start-transaction-signature",
            "Data": "rYGXxEcXYlTqJ0K2VlcPXKG5G1cKBv1dCdcFPP9lFLguGa6tYGthqNUROqjxmID1/gZwv216P1CQklYiB8FV+A=="
        }
    ],
    "ftState": 4919338167972134912
}
```

--------------------------------

### Create Directory and Set Permissions

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/general/installation/installation.md

Commands to create the fiskaltrust directory and set its permissions to 777.

```bash
sudo mkdir /etc/fiskaltrust
```

```bash
sudo chmod 777 /etc/fiskaltrust
```

--------------------------------

### Configure Mono Service for Linux

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/general/installation/installation.md

This script initializes the fiskaltrust Mono service. Ensure the lock file path and executable path are correct for your system. The script handles starting and stopping the service.

```bash
#! /bin/sh
### BEGIN INIT INFO
# Provides:     fiskaltrust
# Required-Start:  $local_fs $network
# Required-Stop:   $local_fs $network
# Default-Start:   2 3 4 5
# Default-Stop:   0 1 6
# Short-Description: fiskaltrust.Sicherheitseinrichtung 
### END INIT INFO
# /etc/init.d/fiskaltrust
#
#
#rechte: sudo chmod +x /etc/init.d/fiskaltrust
#rechte: sudo chmod +x /etc/fiskaltrust/fiskaltrust.exe
#installieren: sudo update-rc.d fiskaltrust defaults
#deinstalllieren: sudo update-rc.d -f dispenser1 remove
#
#
#
#
# Some things that run always
# Load the VERBOSE setting and other rcS variables
. /lib/init/vars.sh

# Define LSB log_* functions.
# Depend on lsb-base (>= 3.2-14) to ensure that this file is present
# and status_of_proc is working.
. /lib/lsb/init-functions

# Carry out specific functions when asked to by the system
case "$1" in
 start)
  log_daemon_msg "Starting fiskaltrust.Sicherheitseinrichtung " "fiskaltrust"
  mono-service -l:/tmp/fiskaltrust.Sicherheitseinrichtung .lock -d:/etc/fiskaltrust/ /etc/fiskaltrust/fiskaltrust.exe
  log_end_msg $?
  ;;  
 stop)
  log_daemon_msg "Stopping fiskaltrust.Sicherheitseinrichtung " "fiskaltrust"
  kill `cat /tmp/fiskaltrust.Sicherheitseinrichtung .lock`
  log_end_msg $?
  ;;  
 *)
  echo "Usage: /etc/init.d/fiskaltrust {start|stop}"
  exit 1
  ;;esac

exit 0

```

--------------------------------

### Receipt Signature Data Example

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/middleware-de-kassensichv/cash-register-integration/single-receipt-creation.md

This snippet shows an example of the data structure returned in the signature block for a receipt. It includes various fields like signature format, type, caption, and the actual data payload.

```json
{
            "ftSignatureFormat": 1,
            "ftSignatureType": 4919338167972134933,
            "Caption": "Kassenbeleg-V1",
            "Data": "Kassenbeleg-V1"
        }
```

```json
{
            "ftSignatureFormat": 1,
            "ftSignatureType": 4919338167972134934,
            "Caption": "<processData>",
            "Data": "Beleg^7.50_0.00_0.00_0.00_0.00^7.50:Bar"
        }
```

```json
{
            "ftSignatureFormat": 1,
            "ftSignatureType": 4919338167972134935,
            "Caption": "<transaktions-nummer>",
            "Data": "11"
        }
```

```json
{
            "ftSignatureFormat": 1,
            "ftSignatureType": 4919338167972134936,
            "Caption": "<signatur-zaehler>",
            "Data": "21"
        }
```

```json
{
            "ftSignatureFormat": 1,
            "ftSignatureType": 4919338167972134937,
            "Caption": "<start-zeit>",
            "Data": "2020-05-22T11:33:01.000Z"
        }
```

```json
{
            "ftSignatureFormat": 1,
            "ftSignatureType": 4919338167972134938,
            "Caption": "<log-time>",
            "Data": "2020-05-22T11:33:02.000Z"
        }
```

```json
{
            "ftSignatureFormat": 1,
            "ftSignatureType": 4919338167972134939,
            "Caption": "<sig-alg>",
            "Data": "ecdsa-plain-SHA256"
        }
```

```json
{
            "ftSignatureFormat": 1,
            "ftSignatureType": 4919338167972134940,
            "Caption": "<log-time-format>",
            "Data": "utcTime"
        }
```

```json
{
            "ftSignatureFormat": 1,
            "ftSignatureType": 4919338167972134941,
            "Caption": "<signatur>",
            "Data": "HSmIZw0g6tpJ/UeNYutHic5PXORANAH5V9+Fon9SfCvx3A/gO7Dguaxd8Mn/YKadgfLTV7s1VzWPe/QolS6dAg=="
        }
```

```json
{
            "ftSignatureFormat": 1,
            "ftSignatureType": 4919338167972134942,
            "Caption": "<public-key>",
            "Data": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAENFFPGk1vDk92IL6tjsVQ6kpwc4TCsYNNGGoc0cN4dUPQZwOo2tuQlrQAVvMfO+XHWsnphAtN5cUbIwdtMk/Z6g=="
        }
```

```json
{
            "ftSignatureFormat": 1,
            "ftSignatureType": 4919338167972134943,
            "Caption": "<vorgangsbeginn>",
            "Data": "2020-05-22T10:47:40.960Z"
        }
```

--------------------------------

### Constructing ftReceiptCase with Flags

Source: https://context7.com/fiskaltrust/interface-doc/llms.txt

Illustrates how to construct the `ftReceiptCase` 64-bit integer by combining country codes, receipt types, and flags. Shows an example of creating a German voided receipt case by OR-combining the base type with `FLAG_REVERSE_RECEIPT`.

```cs
// Common ftReceiptCaseFlags (OR-combined with base receipt type):
const long FLAG_FAILED_RECEIPT    = 0x0000000000010000;  // late-signing mode
const long FLAG_TRAINING_RECEIPT  = 0x0000000000020000;  // training/test — no tax impact
const long FLAG_REVERSE_RECEIPT   = 0x0000000000040000;  // voided receipt (negative amounts)
const long FLAG_HANDWRITTEN       = 0x0000000000080000;  // handwritten receipt during outage
const long FLAG_IMPLICIT_FLOW_DE  = 0x0000000100000000;  // DE: implicit TSE transaction
const long FLAG_RECEIPT_REQUEST   = 0x0000800000000000;  // retrieve previously signed receipt

// Example: German voided receipt
long voidedReceiptCase = 0x4445000000000001  // DE POS receipt
                       | FLAG_REVERSE_RECEIPT; // mark as void

var voidRequest = new ReceiptRequest
{
    ftReceiptCase             = voidedReceiptCase,
    cbPreviousReceiptReference = "original-receipt-ref",  // link to voided receipt
    cbChargeItems             = new[] {
        new ChargeItem { Amount = -3.50m, Quantity = -1.0m, /* ... */ }  // negative values
    },
    cbPayItems                = new[] {
        new PayItem { Amount = -3.50m, /* ... */ }
    }
};
```

--------------------------------

### Run fiskaltrust.exe from Command Line

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/general/installation/installation.md

Execute the fiskaltrust.exe launcher with command-line parameters. Ensure you are running cmd.exe as administrator on Windows.

```bash
fiskaltrust.exe -test
```

--------------------------------

### Journal Function

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/middleware-fr-boi-tva-decla-30-10-30/function-structures/function-structures.md

The Journal function allows retrieval of various information from a fiskaltrust.SecurityMechanism. A C# example call is provided.

```APIDOC
## Journal Function

### Description
With this function, a variety of information can be retrieved from a fiskaltrust.SecurityMechanism.

### C# Call Example
```cs
Stream stream = proxy.Journal(ftJournalType, 0, DateTime.UtcNow.Ticks);
```

*Code 18. Call of iPos Journal (FR – BOI-TVA-DECLA 30-10-30)*

A list with various possibilities for the request parameter ftJournalType is included in the reference table ["Type of Journal: ftJournalType"](../reference-tables/reference-tables.md#t-type-of-journal-ftjournaltype-160).
```

--------------------------------

### Germany-Specific: Implicit Transaction Flow

Source: https://context7.com/fiskaltrust/interface-doc/llms.txt

The recommended flow for most use cases, where the Middleware handles transaction start and finish internally.

```APIDOC
## POST /json/v1/sign (Implicit Flow)

### Description
Handles a retail scenario using the implicit transaction flow. The Middleware manages the Start-Transaction and Finish-Transaction, consuming two TSE signatures.

### Method
POST

### Endpoint
`/json/v1/sign`

### Parameters
#### Request Body
- **ftCashBoxID** (string) - Required - Identifier for the cashbox.
- **ftPosSystemId** (string) - Required - Identifier for the POS system.
- **cbTerminalID** (string) - Required - Identifier for the terminal.
- **cbReceiptReference** (string) - Required - Unique reference for the receipt.
- **cbReceiptMoment** (string) - Required - Timestamp of the receipt.
- **cbChargeItems** (array) - Required - List of charge items.
  - **Quantity** (number) - Required - Quantity of the item.
  - **Description** (string) - Required - Description of the item.
  - **Amount** (number) - Required - Amount of the item.
  - **VATRate** (number) - Required - VAT rate applied.
  - **ftChargeItemCase** (number) - Required - Case identifier for the charge item.
  - **Moment** (string) - Required - Timestamp for the charge item.
- **cbPayItems** (array) - Required - List of payment items.
  - **Quantity** (number) - Required - Quantity of the item.
  - **Description** (string) - Required - Description of the item.
  - **Amount** (number) - Required - Amount of the item.
  - **ftPayItemCase** (number) - Required - Case identifier for the payment item.
  - **Moment** (string) - Required - Timestamp for the payment item.
- **ftReceiptCase** (number) - Required - Case identifier for the receipt.
- **cbArea** (string) - Optional - Area associated with the receipt.

### Request Example
```json
{
    "ftCashBoxID":        "cashboxid-guid",
    "ftPosSystemId":      "POS-Systemid-guid",
    "cbTerminalID":       "T1",
    "cbReceiptReference": "4747847",
    "cbReceiptMoment":    "2020-05-22T11:33:00.260Z",
    "cbChargeItems": [
        {
            "Quantity":         1.0,
            "Description":      "0,5 Soda Zitrone",
            "Amount":           3.50,
            "VATRate":          19.0,
            "ftChargeItemCase": 4919338167972134913,
            "Moment":           "2020-05-22T10:47:40.960Z"
        }
    ],
    "cbPayItems": [
        {
            "Quantity":      1.0,
            "Description":   "Cash",
            "Amount":        3.50,
            "ftPayItemCase": 4919338167972134913,
            "Moment":        "2020-05-22T11:33:00.260Z"
        }
    ],
    "ftReceiptCase": 4919338167972134909,
    "cbArea": "Tisch 19"
}
```

### Response
#### Success Response (200)
- **ftSignatureType 0x4445000000000019** (string) - Timestamp of transaction start.
- **ftSignatureType 0x444500000000001A** (string) - Timestamp of transaction end.
- **ftSignatureType 0x444500000000001F** (string) - Earliest item timestamp.
- **ftSignatureType 0x4445000000000001** (string) - QR-Code (format=3, full DSFinV-K string).
```

--------------------------------

### Start Transaction Request (JSON)

Source: https://github.com/fiskaltrust/interface-doc/blob/master/doc/middleware-de-kassensichv/cash-register-integration/single-receipt-creation.md

Send this JSON to the middleware to initiate a transaction. It includes details like cash box ID, POS system ID, terminal ID, and an empty array for charge and pay items.

```json
{
    "ftCashBoxID":"cashboxid-guid",
    "ftPosSystemId":"POS-Systemid-guid",
    "cbTerminalID":"T1",
    "cbReceiptReference":"233348",
    "cbReceiptMoment":"2020-05-22T10:47:40.960Z",
    "cbChargeItems":[],
    "cbPayItems":[],
    // 0x4445 0000 0000 0008 (start-transaction-receipt)  
    "ftReceiptCase":4919338167972134920,
    "cbArea":"Scannerkasse 14"
}
```