### Retail Transaction - Start Transaction

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

This example demonstrates the request payload for initiating a transaction in a retail scenario using the explicit flow. It includes details like cashbox ID, terminal ID, receipt reference, and the initial receipt case for starting a transaction.

```APIDOC
## POST /api/transactions/start

### Description
Initiates a new transaction for a retail scenario.

### Method
POST

### Endpoint
/api/transactions/start

### Request Body
- **ftCashBoxID** (string) - Required - The unique identifier for the cashbox.
- **ftPosSystemId** (string) - Required - The identifier for the POS system.
- **cbTerminalID** (string) - Required - The identifier for the terminal.
- **cbReceiptReference** (string) - Required - A reference number for the receipt.
- **cbReceiptMoment** (string) - Required - The timestamp when the receipt was created (ISO 8601 format).
- **cbChargeItems** (array) - Required - A list of items being charged.
- **cbPayItems** (array) - Required - A list of payment items.
- **ftReceiptCase** (number) - Required - The case type for the receipt, specifically for starting a transaction (e.g., 4919338167972134920 for start-transaction-receipt).
- **cbArea** (string) - Required - The area or section where the transaction is taking place.

### Request Example
```json
{
    "ftCashBoxID":"cashboxid-guid",
    "ftPosSystemId":"POS-Systemid-guid",
    "cbTerminalID":"T1",
    "cbReceiptReference":"233348",
    "cbReceiptMoment":"2020-05-22T10:47:40.960Z",
    "cbChargeItems":[],
    "cbPayItems":[],
    "ftReceiptCase":4919338167972134920, 
    "cbArea":"Scannerkasse 14"
}
```

### Response
#### Success Response (200)
- **ftCashBoxID** (string) - The identifier for the cashbox.
- **ftQueueID** (string) - The identifier for the queue.
- **ftQueueItemID** (string) - The identifier for the queue item.
- **ftQueueRow** (integer) - The row number in the queue.
- **cbTerminalID** (string) - The identifier for the terminal.
- **cbReceiptReference** (string) - The reference number for the receipt.
- **ftCashBoxIdentification** (string) - The identification of the cashbox.
- **ftReceiptIdentification** (string) - The identification of the receipt.
- **ftReceiptMoment** (string) - The timestamp of the receipt creation (ISO 8601 format).
- **ftSignatures** (array) - A list of signature objects.
  - **ftSignatureFormat** (integer) - The format of the signature.
  - **ftSignatureType** (number) - The type of the signature.
  - **Caption** (string) - A caption for the signature.
  - **Data** (string) - The signature data.
- **ftState** (number) - The state of the transaction.

#### Response Example
```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
}
```
```

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

### ftChargeItemCaseData Discount Percentage Example

Source: https://github.com/fiskaltrust/docs/blob/main/poscreators/middleware-doc/appendix-me/reference-tables/type-of-service-ftchargeitemcase.md

Example showing how to specify a discount percentage within `ftChargeItemCaseData` when a discount reduces the tax base price.

```json
ftChargeItemCaseData: "{\" DiscountPercentage\": 20}"
```

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

### Linux Daemon Installation Commands

Source: https://github.com/fiskaltrust/docs/blob/main/poscreators/middleware-doc/general/installation/installation.md

These commands are used to set up the fiskaltrust service as a daemon on Linux. They involve creating directories, setting permissions for the service executable and init script, and finally installing the daemon using `update-rc.d`.

```bash
sudo mkdir /etc/fiskaltrust
sudo chmod 777 /etc/fiskaltrust
sudo chmod +x /etc/init.d/fiskaltrust
sudo chmod +x /etc/fiskaltrust/fiskaltrust.exe
sudo update-rc.d fiskaltrust defaults
```

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

### Example Proxy Configuration Strings

Source: https://github.com/fiskaltrust/docs/blob/main/posdealers/technical-operations/middleware/network-requirements.md

These are example strings demonstrating various ways to configure the proxy settings. They show different combinations of address, username, password, and bypass rules. The 'bypass' argument can be used multiple times to specify multiple exclusion patterns.

```plaintext
address=192.168.0.1
address=192.168.0.1;username=proxyuser;password=proxypw
address=proxy.example.com;username=proxyuser
address=192.168.0.1;bypass=192\.168\.10\.1
address=192.168.0.1;bypass=192\.168\.10\.1;bypass=scu\d+\.example\.com
```

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

### fiskaltrust Firewall Script Output Example

Source: https://github.com/fiskaltrust/docs/blob/main/posdealers/technical-operations/troubleshooting/network-troubleshooting.md

Example console output from the `CheckFirewall.ps1` script, showing machine information, .NET Framework versions, and detailed results of network connection tests to fiskaltrust services.

```console
PS C:\fw-script>.\CheckFirewall.ps1 FirewallTests-ft.csv
CheckFirewall 2.0

Machine name: COMPUTER-NAME
OS version: 10.0.19044
Windows name: Windows 10 Enterprise
Overall connectivity: True
Active Middleware instances: 0

Name                             Version        Release
----                             -------        -------
v2.0.50727                       2.0.50727.4927
v3.0                             3.0.30729.4926
Windows Communication Foundation 3.0.4506.4926
Windows Presentation Foundation  3.0.6920.4902
v3.5                             3.5.30729.4926
Client                           4.8.04084      528372
Full                             4.8.04084      528372
Client                           4.0.0.0

We're all good!
Status: (SUCCESS) -- Purpose: ft cashbox download & upload receipt data
Status: (SUCCESS) -- Purpose: ft download packages
Status: (SUCCESS) -- Purpose: ft error reporting
Full Results below:

Url                                        Purpose                                   Notes From
---                                        -------                                   ----- ----
https://helipad.fiskaltrust.cloud/version  ft cashbox download & upload receipt data okay  COMPUTER-NAME
https://packages.fiskaltrust.cloud/version ft download packages                      okay  COMPUTER-NAME
https://dc.services.visualstudio.com/      ft error reporting                        okay  COMPUTER-NAME
```

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

### Install/Uninstall Windows Service

Source: https://github.com/fiskaltrust/docs/blob/main/poscreators/middleware-doc/general/installation/installation.md

These commands are used to install and uninstall the fiskaltrust service on a Windows operating system. The `-i` parameter installs the service, and the `-u` parameter uninstalls it. Successful installation will list the service in the Windows Services management console.

```bash
fiskaltrust.exe -i
fiskaltrust.exe -u
```

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

### Start Transaction Request (JSON)

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

This JSON object represents the request to start a transaction. It includes details like cash box ID, POS system ID, terminal ID, receipt reference, and an empty array for charge and pay items. The `ftReceiptCase` with value `0x4445000000000008` signifies the start of a transaction.

```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"
}
```

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

### ftReceiptCase Composition Examples in C#

Source: https://context7.com/fiskaltrust/docs/llms.txt

Demonstrates how to combine different ftReceiptCase flags using bitwise OR operations in C# to modify receipt processing behavior. Examples include combinations for Germany, Austria, and France, with options for POS receipts, implicit flows, training modes, and voided receipts.

```csharp
// ftReceiptCase composition examples

// Germany (0x4445) + POS Receipt (0x0001) + Implicit Flow (0x0000000100000000)
long implicitPosReceipt = 0x4445000100000001;

// Germany (0x4445) + POS Receipt (0x0001) + Training Mode (0x0000000000020000)
long trainingReceipt = 0x4445000000020001;

// Germany (0x4445) + POS Receipt (0x0001) + Voided Receipt (0x0000000000040000)
long voidedReceipt = 0x4445000000040001;

// Austria (0x4154) + POS Receipt (0x0001)
long austriaPosReceipt = 0x4154000000000001;

// France (0x4652) + POS Receipt (0x0001)
long francePosReceipt = 0x4652000000000001;
```

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

### Start-transaction-receipt Case

Source: https://github.com/fiskaltrust/docs/blob/main/poscreators/middleware-doc/middleware-de-kassensichv/reference-tables/type-of-receipt-ftreceiptcase.md

Starts a new, unfinished action. Use `ftChargeItems` and `ftPayItems` to hand over already known details. Using the same `cbReceiptReferece` in further calls connects the action items. This receipt case works only with explicit flow.

```APIDOC
## Start-transaction-receipt Case

### Description
Starts a new, unfinished action. Use `ftChargeItems` and `ftPayItems` to hand over already known details for the final receipt. Using the same `cbReceiptReferece` in further calls connects the action items. This receipt case works only with explicit flow. Calling with the `ftReceiptCaseFlag` `0x0000000100000000` results in an exception.

### Method
POST

### Endpoint
`/receipt`

### Parameters
#### Query Parameters
- **ftReceiptCaseID** (string) - Required - `0x4445000000000008`
- **ftReceiptCaseFlag** (string) - Required - `0x0000000100000000` (for explicit flow)

#### Request Body
- **cbReceiptReference** (string) - Required - A unique reference for the transaction.
- **ftChargeItems** (array) - Optional - Details of charged items.
- **ftPayItems** (array) - Optional - Details of payment items.

### Request Example
```json
{
  "cbReceiptReference": "unique-transaction-ref-123",
  "ftChargeItems": [
    {
      "Amount": 1000,
      "VatRate": 19
    }
  ],
  "ftPayItems": []
}
```

### Response
#### Success Response (200)
- **ReceiptID** (string) - The ID of the generated receipt.

#### Response Example
```json
{
  "ReceiptID": "generated-receipt-id"
}
```
```

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

### Set Configuration Parameters via Command Line (Shell)

Source: https://github.com/fiskaltrust/docs/blob/main/posdealers/technical-operations/middleware/launchers/desktop.md

Demonstrates how to launch the fiskaltrust.exe with specific configuration parameters set from the command line. This example shows setting the 'sandbox' parameter to 'false' and the 'logfile' parameter to a specified path. Values with spaces should be enclosed in double quotes.

```shell
C:\>fiskaltrust.exe -sandbox=false -logfile="D:\log\fiskaltrust.log"
```

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

### HTTP Echo Request Example

Source: https://github.com/fiskaltrust/docs/blob/main/posdealers/_markets/de/getting-started/my-first-cashbox/_echo.mdx

An example of an HTTP POST request to the fiskaltrust CloudCashbox endpoint for performing an echo request. It includes the necessary headers like 'cashboxid' and 'accesstoken', and the JSON payload with the message to be echoed.

```http
POST  https://cloudcashbox-sandbox.fiskaltrust.de/v1/Echo HTTP/1.1
Host: localhost
Content-Length: 46
Content-Type: application/json
cashboxid: XXXX
accesstoken: XXXX

{ "Message": "Hello fiskaltrust.Middleware!" }
```

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

### Initialize Mono Service for Linux

Source: https://github.com/fiskaltrust/docs/blob/main/poscreators/middleware-doc/general/installation/installation.md

This script initializes the fiskaltrust service as a daemon on Linux using Mono. It includes standard init script headers, defines start and stop actions, and uses the `mono-service` utility to run the fiskaltrust.exe executable. The script requires appropriate file permissions and execution rights.

```sh
#! /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

```

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

### ftChargeItemCase Data Structure Example

Source: https://github.com/fiskaltrust/docs/blob/main/poscreators/middleware-doc/appendix-me/reference-tables/type-of-service-ftchargeitemcase.md

Example demonstrating how to structure `ftChargeItemCaseData` for voucher-related transactions. This includes setting the expiration date and serial numbers of a voucher.

```json
ftChargeItemCaseData: "{\"ExpirationDate\": \"2022-12-24\", \"VoucherSerialNumbers\": [ \"2-2020-12345678\", \"optionally-more-numbers\" ]}"
```

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

### Base64 to Base32 OCR Conversion Example

Source: https://github.com/fiskaltrust/docs/blob/main/poscreators/middleware-doc/middleware-at-rksv/reference-tables/reference-tables.md

Demonstrates the Base64 encoded signature data and its subsequent conversion to Base32 format for OCR display, as required by RKSV regulations when QR code printing is not feasible. This ensures readability by avoiding characters that are visually similar.

```nohighlight
_R1-AT0_DEMO-CASH-BOX426_776730_2015-10-14T18:20:23_0,00_0,00_0,00_0,00_0,00_2IBFGFEPH7HKO===_968935007593160625_PT7P6PGD2KOQ2===_LYPHANPNDKI2JTSW6MQC2WWCOEMHNRTCGI7522EBXROOOG7YI26DVYS2KCZKFZX3KGM4NYFT4A6WYZS7KYFP34BQZICNFH5AZC3K47Q=
```

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

### Start Transaction Response (JSON)

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

This JSON object is the response received after initiating a transaction. It contains queue information, terminal and receipt details, and a signature block with a `ftSignatureType` of `0x4445000000000008` indicating a start transaction signature.

```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
}
```

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

### Sending VAT Key (ftSubChargeItemCase)

Source: https://github.com/fiskaltrust/docs/blob/main/poscreators/middleware-doc/middleware-de-kassensichv/procedural-documentation/dsfinv-k-generation.md

Demonstrates how to send the VAT key for the base price using 'ftSubChargeItemCase' within the 'SubItems' array. If not provided, the parent item's 'ftChargeItemCase' will be used.

```json
"SubItems": [
  {
    ...,
    "ftSubChargeItemCase": "4919338167972134929",
    ...
  }
]
```

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

### Example: Referencing SCU IDs with Counter

Source: https://github.com/fiskaltrust/docs/blob/main/posdealers/_markets/at/technical-operations/rollout-automation/templates/_variables.mdx

Demonstrates how to use reference variables to retrieve the IDs of SCUs that have an incrementing 'counter' field. This example shows referencing specific SCUs based on their counter value.

```plaintext
|[reference_scu_onlinescu_counter_1_id]|
```

```plaintext
|[reference_scu_onlinescu_counter_2_id]|
```

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

### Run fiskaltrust.exe in Test Mode (Windows)

Source: https://github.com/fiskaltrust/docs/blob/main/poscreators/middleware-doc/general/installation/installation.md

This command executes the fiskaltrust.exe launcher in test mode on Windows. It requires running the command prompt as an administrator. The `-test` parameter enables the test environment for development and integration purposes.

```bash
C:\Program Files\fiskaltrust\service\fiskaltrust.exe -test
```

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

### JSON Example: Copy Receipt Data for French Market

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

Shows an example of the JSON data required when creating a copy of a receipt using ReceiptCase `0x4652000000000016`. It includes the reason for the copy and the reference to the original receipt.

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

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

### SCU Parameters

Source: https://github.com/fiskaltrust/docs/blob/main/posdealers/_markets/fr/technical-operations/rollout-automation/api-templating/_parameters.mdx

This section details the parameters required for SCU configuration, specifically CompanyName and Siret.

```APIDOC
## SCU Parameters

### Description

This section details the parameters required for SCU configuration, specifically CompanyName and Siret.

### Parameters

#### Query Parameters

- **CompanyName** (string) - Required - The company name.
- **Siret** (string) - Required - The SIRET identifier of the outlet.
```