openapi: 3.1.1
info:
  title: fiskaltrust PosSystem API
  description: |
    This API provides a variety of different functionalities for POS systems and is the central entry point to the **fiskaltrust.Middleware**. It can be
    used to **fiscalize (or sign) receipts**, execute **payments** via different payment providers, **digitally print receipts** (e.g. via the Receipt Bundle),
    and to **export data** from the Middleware.<br/>
    <h3>API design principles</h3>
    <p>
      While the POSSystem API was designed to be easily usable via HTTP calls and JSON the
      call patterns follow a processual principle. We believe that by giving POS Systems
      a way to handle core processes in a stateful way as if they are a statemachine,
      that we can always ensure that the processes run as frictionless as possible.
      Each call that is handled by the POS System API is safe to be replayed and idempotent.
    </p>
    <h4>Authentication</h4>
    <p>
      The POSSystem API can only be used with the access data of a CashBox. These credentials can be found on the
      fiskaltrust.Portal in the <i>CashBox Configuration page</i>.You will need both <code>CashBoxId</code>
      and <code>AccessToken</code> to use this API.
    </p>
    <h5>header x-cashbox-id</h5>
    <p>
      The CashBoxId needs to be sent in the header of each request to the POS System API to identify the target CashBox.
    </p>
    <h5>header x-cashbox-accesstoken</h5>
    <p>
      The AccessToken needs to be sent in the header of each request to the POS System API to authenticate the caller.
    </p>
    <h4>Versioning</h4>
    <p>
      This API uses semantic versioning, meaning only major version changes contain breaking
      changes. Non-breaking changes (like returning additional data without changing
      the original model) will not increase the major version.
    </p>
    <ul>
      <li>
        The latest version is used if no version is specified (like in the samples in this collection).</li>
      <li>
        Users can specify versions by explicitly stating it in the URL once more versions
        are released.
      </li>
    </ul>
    <h4>Operations and header x-operation-id</h4>
    <p>
      The operation id is meant to be a idempotency key that let's the caller of the API endpoints safely retry calls.
      In case of timeouts, network interruptions this gives the ability to safely retry the process.
      While the request on the server side is still in progress calling the endpoint again with the same
      operation id and body will block until the operation is finished is.<br />
      <b>Example - calling /sign</b> with x-operation-id ea4279ee-8684-412f-b8eb-32b5dea52811. The operation fails with a timeout.
      The caller handles the exception by performing the exact same operation again. The backend notices that this operation-id
      has been used in another transaction already and checks the state. If the state is finished it returnes the original response body immediately;
      otherwise it returns when finished.
    </p>
    <h4>POS System identification and header x-possystem-id</h4>
    <p>
      Each POS system variant must be registered in the fiskaltrust portal and gets assigned a unique POS System ID.
      This POS System ID needs to be sent in the header of each request to the POS System API where required.
      By this, the Middleware can identify the caller and apply specific logic if needed.
      For further detials see the header parameter x-possystem-id in the components section or in the individual endpoint documentation.
    </p>
    <h4>General datatype restrictions if not mentioned separately</h4>
    <ul>
      <li>All string properties have a maximum length of 1023 characters unless mentioned otherwise.</li>
      <li>All date-time properties are in UTC and use the ISO 8601 format. Example: 2026-01-30T13:30:27Z</li>
    </ul>
  contact:
    name: fiskaltrust
    email: hello@fiskaltrust.eu
  license:
    name: This documentation and samples are released under the EUPL license.
    url: https://opensource.org/licenses/EUPL
  version: "2.1"
servers:
- url: https://possystem-api-sandbox.fiskaltrust.eu/v2
  description: Sandbox
- url: https://possystem-api.fiskaltrust.eu/v2
  description: Production
security:
- CashBoxId: []
  CashBoxAccessToken: []
tags:
- name: /echo
  description: Health check
- name: /pay
  description: Execute payments
- name: /sign
  description: Sign receipts
- name: /issue
  description: Distribute receipts (digitally or printed)
- name: /journal
  description:  Export data
paths:
  /echo:
    post:
      tags:
      - /echo
      summary: /echo - health check
      description: |
        This method can be used to perform a basic health and communcation check.  
          
        Special Case for a cloud cashbox - Force reset of cached config:
        If the cashbox is a cloud based cashbox (= using the URLs as defined in the servers section above), the special case can be triggered to force a reset of the cached configuration.
        The point is that the cloud based cashboxes do cache their configuration for about 1h. When changing the configuration in the portal (and do a rebuild),
        this change is not immediately visible to the cashbox. The new configuration will be picked up latest after the caches expire which will happen after 1h where the cashbox was not used.
        To be sure a reset can be enforced via the /echo request by setting the message field in the body of this request to `null`.

      parameters:
      - $ref: "#/components/parameters/x-operation-id"
      - $ref: "#/components/parameters/x-possystem-id"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                Message: "Hello fiskaltrust!"
              properties:
                Message:
                  type: string
                  description: The message to be echoed back. Special case for cloud cashboxes - set to `null` to force reset of cached config.
      responses:
        "200":
          description: |
            operation-id found, response from cashbox/queue/terminal
          content:
            application/json:
              schema:
                type: object
                properties:
                  Message:
                    type: string
                    description: The echoed message
        "400":
          description: |
            The request was malformed or could not be processed.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                badRequest:
                  $ref: "#/components/examples/badRequest"
        "401":
          description: Access token is not set or invalid.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                unauthorized:
                  $ref: "#/components/examples/unauthorized"
        "500":
          description: The server encountered an unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                serverError:
                  $ref: "#/components/examples/server-error"
  /sign:
    post:
      tags:
      - /sign
      summary: /sign - fiscalize (sign) a receipt
      description: |
        This method can be used to sign different types of receipts according to local fiscalization regulations.
        After signing the receipt according to the fiscal law, this method synchronously returns the data that need to be printed onto the receipt.
        The format of the receipt request is documented in the Middleware API docs, and the exact behavior of the method is determined by the cases sent within the properties
        (see ftReceiptCase, ftChargeItemCase and ftPayItemCase).
      parameters:
      - $ref: "#/components/parameters/x-operation-id"
      - $ref: "#/components/parameters/x-possystem-id"
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: "#/components/schemas/ReceiptRequestBasic"
              - $ref: "#/components/schemas/ReceiptRequest"
            examples:
              ReceiptRequestMinimum1:
                summary: most simple ReceiptRequest example, which uses unknown tagging as a fallback
                description: |
                  As no case values are given in this example, the following fallbacks are used:
                  - ftReceiptCase fallback to 0xCCCC_2000_0000_0000  
                  - ftChargeItemCase fallback to 0xCCCC_2000_0000_0000  
                  - ftPayItemCase fallback to 0xCCCC_20000_0000_0000  
                value:
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.59
                    VATRate: 20
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.60
                    VATRate: 20
                  cbPayItems:
                  - ftPayItemID: "3ff388ce-96e4-4f19-9f19-b24ef38ec2b6"
                    Description: Cash
                    Amount: 7.20
              ReceiptRequestMinimum2:
                summary: ReceiptRequest example, downpayment of normal-vat and a coffee for take away
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Downpayment for Beer
                    Amount: 10
                    VATRate: 20
                    ftChargeItemCase: 35184372613139
                  - Quantity: 1
                    Description: Coffee (TakeAway)
                    Amount: 3.60
                    VATRate: 20
                    ftChargeItemCase: 35184374186003
                  cbPayItems:
                  - Description: Cash
                    Amount: 23.60
              ReceiptRequestMinimum3:
                summary: ReceiptRequest example, multiuse voucher handout
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Voucher
                    Amount: 10
                    VATRate: 20
                    ftChargeItemCase: 35184372088904
                  cbPayItems:
                  - Description: Cash
                    Amount: 10
              ReceiptRequestMinimum4:
                summary: ReceiptRequest example, goods in returnable packaging, paid via voucher
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Milk (Bottled)
                    Amount: 3.29
                    VATRate: 10
                    ftChargeItemCase: 35184372088849
                  - Quantity: 1
                    Description: Returnable Bottle
                    Amount: 0.20
                    VATRate: 10
                    ftChargeItemCase: 35184373137425
                  cbPayItems:
                  - Description: Voucher
                    Amount: 3.5
                    ftPayItemCase: 35184372088838
              RequestReceipt_DailyOperation_ZeroReceipt:
                summary: ZeroReceipt
                description: ftReceiptCase 0xCCCC_2000_0000_2000
                value:
                  ftReceiptCase: 35184372097024
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems: []
                  cbPayItems: []
              SignRequestReceipt_OpenTable_Order_Order_Pay_Receipt_CloseTable_1_1:
                summary: I go to a caffee, I order and the waiter is required to bring the relevant fiscal document (retail receipt) along with the order.
                value:
                  ftReceiptCase: 35184372101124
                  cbReceiptReference: order-12345
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.59
                    VATRate: 20
                    ftChargeItemCase: 35184372088867
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.60
                    VATRate: 20
                    ftChargeItemCase: 35184372088867
                  cbPayItems:
                  - Description: Grant ... OnCredit
                    Amount: 8.20
                    ftPayItemCase: 35184372088846
              SignRequestReceipt_OpenTable_Order_Order_Pay_Receipt_CloseTable_1_2:
                summary: |
                  I go to a caffee, I order and the waiter is required to bring the relevant fiscal document (retail receipt) along with the order.
                  Later, I call the waiter to pay (cash, card, or both). To properly "close" the receipt, it must be linked to these subsequent payments. Part 2 of 2, pay in cash
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: receipt-12345
                  cbPreviousReceiptReference: order-12345
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.59
                    VATRate: 20
                    ftChargeItemCase: 35184372088867
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.60
                    VATRate: 20
                    ftChargeItemCase: 35184372088867
                  cbPayItems:
                  - Description: Cash
                    Amount: 8.20
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_DrawerMoneyManagement_1:
                summary: move money from the vault to the drawer
                description: |
                  move money from the vault to the drawer using cbChargeItems for the vault side cbTerminalId comes from Header
                value:
                  ftReceiptCase: 35184372088834
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2025-05-27T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: move money from vault to drawer
                    Amount: 500.0
                    VATRate: 0
                    ftChargeItemCase: 35184372089000
                  cbPayItems:
                  - Description: Cash
                    Amount: 500.0
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_DrawerMoneyManagement_2:
                summary: move money from the drawer to the vault
                description: |
                  move money from the drawer to the vault using cbChargeItems for the vault side cbTerminalId comes from Header
                value:
                  ftReceiptCase: 35184372088834
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2025-05-27T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: move money from drawer to vault
                    Amount: -500.0
                    VATRate: 0
                    ftChargeItemCase: 35184372089000
                  cbPayItems:
                  - Description: Cash
                    Amount: -500.0
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_DrawerMoneyManagement_3:
                summary: move money from the vault to the drawer
                description: |
                  move money from the vault to the drawer using cbPayItem for the vault side cbTerminalId comes from Header
                value:
                  ftReceiptCase: 35184372088834
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2025-05-27T15:22:07Z
                  cbChargeItems: []
                  cbPayItems:
                  - Description: Vault
                    Amount: -500.0
                    ftPayItemCase: 35184372088844
                  - Description: Cash
                    Amount: 500.0
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_DrawerMoneyManagement_4:
                summary: move money from the drawer to the vault
                description: |
                  move money from the drawer to the vault using cbPayItems for the vault side cbTerminalId comes from Header
                value:
                  ftReceiptCase: 35184372088834
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2025-05-27T15:22:07Z
                  cbChargeItems: []
                  cbPayItems:
                  - Description: Vault
                    Amount: 500.0
                    ftPayItemCase: 35184372088844
                  - Description: Cash
                    Amount: -500.0
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_DrawerMoneyManagement_5:
                summary: open drawer
                description: |
                  open drawer cbTerminalId comes from Header
                value:
                  ftReceiptCase: 35184372101121
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2025-05-27T15:22:07Z
                  cbChargeItems: []
                  cbPayItems: []
              SignRequestReceipt_DrawerMoneyManagement_6:
                summary: "move money to consumer, e.g. atm/from debit card"
                description: |
                  move money to consumer atm feature / from debit card cbTerminalId comes from Header
                value:
                  ftReceiptCase: 35184372088834
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2025-05-27T15:22:07Z
                  cbChargeItems: []
                  cbPayItems:
                  - Description: Debit Card
                    Amount: 500.0
                    ftPayItemCase: 35184372088836
                  - Description: Cash
                    Amount: -500.0
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_DrawerMoneyManagement_7:
                summary: pay in foreign currency and give change in local currency
                description: |
                  pay in foreign currency give change in local currency cbTerminalId comes from Header
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2025-05-27T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Coffee
                    Amount: 5.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  cbPayItems:
                  - Description: Cash
                    Amount: 8.849558
                    ftPayItemCase: 35184373137409
                    ftPayItemCaseData:
                      foreignCurrencySymbol: USD
                      foreignCurrencyAmount: 10.0
                  - Description: Cash
                    Amount: -3.85
                    ftPayItemCase: 35184374185985
              SignRequestReceipt_CopyReceipt_1:
                summary: "most simple ReceiptRequest example, which uses unknown\
                  \ tagging as a fallback"
                description: |
                  long description cbTerminalId comes from Header ftReceiptCase fallback to 0xCCCC_2000_0000_0000 ftChargeItemCase fallback to 0xCCCC_2000_0000_0000 ftPayItemCase fallback to 0xCCCC_20000_0000_0000 with line breaks
                value:
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.6
                    VATRate: 20.0
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.6
                    VATRate: 20.0
                  cbPayItems:
                  - Description: Cash
                    Amount: 8.2
              SignRequestReceipt_CopyReceipt_2:
                summary: create a duplicate from previous receipt
                description: |
                  duplicate cbTerminalId comes from Header
                value:
                  cbReceiptCase: 35184372101136
                  cbReceiptReference: copy-1234
                  cbPreviousReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems: []
                  cbPayItems: []
              SignRequestReceipt_Discount_1:
                summary: 10% discount to the cart
                description: |
                  long description cbTerminalId comes from Header
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Position: 1.0
                    Quantity: 1
                    Description: Dress
                    Amount: 150.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  - Position: 1.1
                    Quantity: 1
                    Description: 10% off
                    Amount: -15.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184372350995
                  - Position: 2.0
                    Quantity: 1
                    Description: Shoes
                    Amount: 70.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184374186003
                  - Position: 2.1
                    Quantity: 1
                    Description: 10% off
                    Amount: -7.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184372350995
                  cbPayItems:
                  - Description: Cash
                    Amount: 193.0
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_Discount_2:
                summary: coupon from referal
                description: |
                  long description cbTerminalId comes from Header
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "2345"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Position: 1.0
                    Quantity: 1
                    Description: Dress
                    Amount: 150.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  - Position: 1.1
                    Quantity: 1
                    Description: coupon 2345
                    Amount: -50.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184372350995
                  - Position: 2.0
                    Quantity: 1
                    Description: Shoes
                    Amount: 70.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184374186003
                  cbPayItems:
                  - Description: Cash
                    Amount: 170.0
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_Discount_3:
                summary: buy 3 pay 2
                description: |
                  long description cbTerminalId comes from Header
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "3456"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Position: 1.0
                    Quantity: 1
                    Description: Dress
                    Amount: 87.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  - Position: 2.0
                    Quantity: 1
                    Description: Dress
                    Amount: 95.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  - Position: 3.0
                    Quantity: 1
                    Description: Dress
                    Amount: 69.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  - Position: 3.1
                    Quantity: 1
                    Description: buy 3 pay 2
                    Amount: -69.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184372350995
                  cbPayItems:
                  - Description: Cash
                    Amount: 182.0
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_ItalyLotterie_1:
                summary: "lottery, coffee paid via creditcard"
                description: |
                  long description cbTerminalId comes from Header
                value:
                  ftReceiptCase: 35184372088833
                  ftReceiptCaseData:
                    servizi_lotteriadegliscontrini_gov_it:
                      codicelotteria: KPSAVX2L
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.3
                    VATRate: 10.0
                    ftChargeItemCase: 35184372088867
                  cbPayItems:
                  - Description: CreditCard
                    Amount: 3.5
                    ftPayItemCase: 35184372088837
              SignRequestReceipt_multiple_orders_one_final_retail_receipt_1:
                summary: |
                  1/3 open table order, and get receipt
                description: |
                  first order, beer long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372101124
                  cbReceiptReference: order-12345
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088867
                  cbPayItems: []
              SignRequestReceipt_multiple_orders_one_final_retail_receipt_2:
                summary: |
                  2/3 open table order, and get receipt
                description: |
                  second order, coffee long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372101124
                  cbReceiptReference: order-23456
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088867
                  cbPayItems: []
              SignRequestReceipt_multiple_orders_one_final_retail_receipt_5:
                summary: |
                  3/3 open table order, and get receipt
                description: |
                  final receipt with all orders and payments long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: receipt-12345
                  cbPreviousReceiptReference:
                  - order-12345
                  - order-23456
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088867
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088867
                  cbPayItems:
                  - Description: Cash
                    Amount: 8.2
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_one_order_one_final_retail_receipt_1:
                summary: |
                  1/2 open table, one order, and get receipt
                description: |
                  first order, beer long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372101124
                  cbReceiptReference: order-12345
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088867
                  cbPayItems: []
              SignRequestReceipt_one_order_one_final_retail_receipt_5:
                summary: |
                  2/2 open table, one order, and get receipt
                description: |
                  final receipt with all orders and payments long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: receipt-12345
                  cbPreviousReceiptReference: order-12345
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088867
                  cbPayItems:
                  - Description: Cash
                    Amount: 4.6
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_Order_Order_Receipt_Pay_1_1:
                summary: |
                  1/4 order multiple times a round of beer, pay in cash next day
                description: |
                  order first round of beer long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372101124
                  cbReceiptReference: order-12345
                  cbReceiptMoment: 2025-06-03T15:22:07Z
                  cbChargeItems:
                  - Quantity: 3
                    Description: Beer 0.3l
                    Amount: 15.0
                    VATRate: 24.0
                    VATAmount: 2.9
                    ftChargeItemCase: 35184372088851
                    Position: 1
                  cbPayItems: []
                  cbArea: Table 12345
              SignRequestReceipt_Order_Order_Receipt_Pay_1_2:
                summary: |
                  2/4 order multiple times a round of beer, pay in cash next day
                description: |
                  order second round of beer long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372101124
                  cbReceiptReference: order-23456
                  cbReceiptMoment: 2025-06-03T15:22:07Z
                  cbChargeItems:
                  - Quantity: 3
                    Description: Beer 0.3l
                    Amount: 15.0
                    VATRate: 24.0
                    VATAmount: 2.9
                    ftChargeItemCase: 35184372088851
                    Position: 1
                  cbPayItems: []
                  cbArea: Table 12345
              SignRequestReceipt_Order_Order_Receipt_Pay_1_3:
                summary: |
                  3/4 order multiple times a round of beer, pay in cash next day
                description: |
                  get receipt for all orders and do not pay long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: receipt-12345
                  cbPreviousReceiptReference:
                  - order-12345
                  - order-23456
                  cbReceiptMoment: 2025-06-03T15:22:07Z
                  cbChargeItems:
                  - Quantity: 6
                    Description: Beer 0.3l
                    Amount: 30.0
                    VATRate: 24.0
                    VATAmount: 5.8
                    ftChargeItemCase: 35184372088851
                    Position: 1
                  cbPayItems:
                  - Description: AccountsReceivable
                    Amount: 30.0
                    ftPayItemCase: 35184372088841
                    Position: 1
                  cbArea: Table 12345
              SignRequestReceipt_Order_Order_Receipt_Pay_1_4:
                summary: |
                  4/4 order multiple times a round of beer, pay in cash next day
                description: |
                  pay for receipt from previous day long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372088834
                  cbReceiptReference: receipt-23456
                  cbPreviousReceiptReference:
                  - receipt-12345
                  cbReceiptMoment: 2025-06-03T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Accounts Receiveable
                    Amount: 30.0
                    VATRate: 0.0
                    ftChargeItemCase: 35184372088984
                    Position: 1
                  cbPayItems:
                  - Description: Cash
                    Amount: 30.0
                    ftPayItemCase: 35184372088833
                    Position: 1
              SignRequestReceipt_Sale_Refund_1:
                summary: |
                  1/4 sales of a T-Shirt with later partial refund
                description: |
                  sales t-shirt red + t-shirt green + jeans cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: receipt-12345
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: T-Shirt Red XL
                    Amount: 35.8
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  - Quantity: 1
                    Description: T-Shirt Green S
                    Amount: 35.8
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  - Quantity: 1
                    Description: Jeans
                    Amount: 89.9
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  cbPayItems:
                  - Description: Card
                    Amount: 161.5
                    ftPayItemCase: 35184372088837
              SignRequestReceipt_Sale_Refund_2:
                summary: |
                  2/4 sales of a T-Shirt with later partial refund
                description: |
                  refund t-shirt red in cash long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: receipt-23456
                  cbPreviousReceiptReference: receipt-12345
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: -1
                    Description: T-Shirt Red XL
                    Amount: -35.8
                    VATRate: 20.0
                    ftChargeItemCase: 35184372219923
                  cbPayItems:
                  - Description: Cash
                    Amount: -35.8
                    ftPayItemCase: 35184372219905
              SignRequestReceipt_Sale_Refund_3:
                summary: |
                  3/4 sales of a T-Shirt with later refund of complete receipt
                description: |
                  sales t-shirt green payment via card long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: receipt-34567
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: T-Shirt Green S
                    Amount: 35.8
                    VATRate: 20.0
                    ftChargeItemCase: 35184372219923
                  cbPayItems:
                  - Description: Card
                    Amount: 35.8
                    ftPayItemCase: 35184372088837
              SignRequestReceipt_Sale_Refund_4:
                summary: |
                  4/4 sales of a T-Shirt with later refund of complete receipt
                description: |
                  refund complete receipt refund t-shirt green refund card payment long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184388866049
                  cbReceiptReference: receipt-45678
                  cbPreviousReceiptReference: receipt-34567
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: -1
                    Description: T-Shirt Green S
                    Amount: -35.8
                    VATRate: 20.0
                    ftChargeItemCase: 35184372219923
                  cbPayItems:
                  - Description: Card
                    Amount: -35.8
                    ftPayItemCase: 35184372219909
              SignRequestReceipt_Sale_Refund_5:
                summary: |
                  5/4 sales of a T-Shirt with later refund of complete receipt without items given
                description: |
                  refund complete receipt refund t-shirt green refund card payment long description cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184388866049
                  cbReceiptReference: receipt-45678
                  cbPreviousReceiptReference: receipt-34567
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems: []
                  cbPayItems: []
              SignRequestReceipt_manual_print:
                summary: printing additional lines
                value:
                  ftReceiptCase: 35197257003008
                  ftReceiptCaseData:
                    cbReceiptLines:
                    - line1
                    - line2
                  cbReceiptReference: receipt-56789
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 0
                    Description: manual text chargeitem 1
                    Amount: 0.0
                    VATRate: 0.0
                    ftChargeItemCase: 35184372088832
                  - Quantity: 0
                    Description: manual text chargeitem 2
                    Amount: 0.0
                    VATRate: 0.0
                    ftChargeItemCase: 35184372088832
                  - Quantity: 0
                    Description: manual text chargeitem 3
                    Amount: 0.0
                    VATRate: 0.0
                    ftChargeItemCase: 35184372088832
                  cbPayItems:
                  - Description: manual text payitem 1
                    Amount: 0.0
                    ftPayItemCase: 35184372088832
                  - Description: manual text payitem 2
                    Amount: 0.0
                    ftPayItemCase: 35184372088832
              SignRequestReceipt_rtprinter_dailyclosing:
                summary: |
                  daily closing
                description: |
                  cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372097041
                  cbReceiptReference: receipt-67890
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems: []
                  cbPayItems: []
              SignRequestReceipt_rtprinter_xreport:
                summary: |
                  xreport
                description: |
                  cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35188667064320
                  cbReceiptReference: receipt-67890
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems: []
                  cbPayItems: []
              SignRequestReceipt_rtprinter_copyreceipt:
                summary: |
                  copy receipt
                description: |
                  cbTerminalId comes from Header with line breaks
                value:
                  ftReceiptCase: 35184372101136
                  cbReceiptReference: receipt-89012
                  cbPreviousReceiptReference: receipt-12345
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems: []
                  cbPayItems: []
              SignRequestReceipt_SinglePurposeVoucher_1:
                summary: issuing / selling single purpose voucher
                description: |
                  example of issuing / selling a single purpose voucher cbTerminalId comes from Header ftReceiptCase: API v2, point-of-sale receipt type
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 2
                    Description: Voucher for 2x Coffee
                    Amount: 7.2
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088899
                    VATAmount: 1.2
                  cbPayItems:
                  - Description: Cash
                    Amount: 7.2
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_SinglePurposeVoucher_2:
                summary: redeeming single purpose voucher
                description: |
                  example of redemption of a single purpose voucher cbTerminalId comes from Header ftReceiptCase: API v2, point-of-sale receipt type
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 2
                    Description: Coffee
                    Amount: 7.2
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                    VATAmount: 1.2
                  - Quantity: 1
                    Description: Voucher for 2x Coffee
                    Amount: -7.2
                    VATRate: 20.0
                    ftChargeItemCase: 35186519572547
                    VATAmount: -1.2
                  cbPayItems: []
              SignRequestReceipt_MultiPurposeVoucher_1:
                summary: issuing / selling multi purpose voucher
                description: |
                  example of issuing / selling a multi purpose voucher cbTerminalId comes from Header ftReceiptCase: API v2, point-of-sale receipt type
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Gift Voucher - EUR 100
                    Amount: 100.0
                    VATRate: 0.0
                    ftChargeItemCase: 35184372088904
                    VATAmount: 0.0
                  cbPayItems:
                  - Description: Cash
                    Amount: 100.0
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_MultiPurposeVoucher_2:
                summary: redeeming multi purpose voucher
                description: |
                  example of redemption of a multi purpose voucher cbTerminalId comes from Header ftReceiptCase: API v2, point-of-sale receipt type
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Sneakers
                    Amount: 100.0
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                    VATAmount: 16.6667
                  cbPayItems:
                  - Description: Gift Voucher - EUR 100
                    Amount: 100.0
                    ftPayItemCase: 35186519572486
              SignRequestReceipt_CashSaleReceipt_1:
                summary: simple ReceiptRequest example
                description: |
                  example of a simple receipt request cbTerminalId comes from Header ftReceiptCase: API v2, point-of-sale receipt type
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  cbPayItems:
                  - Description: Cash
                    Amount: 8.2
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_CashSaleReceipt_2:
                summary: example sale incl. tip to owner
                description: |
                  example of a sale incl. a tip to the owner of the business (taxable tip) cbTerminalId comes from Header ftReceiptCase: API v2, point-of-sale receipt type
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                    VATAmount: 0.7666
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                    VATAmount: 0.6
                  - Quantity: 1
                    Description: Company Tip
                    Amount: 0.8
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088883
                    VATAmount: 0.1333
                  cbPayItems:
                  - Description: Cash
                    Amount: 9.0
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_CashSaleReceipt_3:
                summary: example sale incl. tip to employee
                description: |
                  example of a sale incl. a tip to the employee (not taxable) cbTerminalId comes from Header ftReceiptCase: API v2, point-of-sale receipt type
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                    VATAmount: 0.7666
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                    VATAmount: 0.6
                  - Quantity: 1
                    Description: Tip
                    Amount: 0.8
                    VATRate: 0.0
                    ftChargeItemCase: 35184372088888
                    VATAmount: 0.0
                  cbPayItems:
                  - Description: Cash
                    Amount: 9.0
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_CashSaleReceipt_4:
                summary: sale with return change
                description: |
                  example of a sale for EUR 8.20, where the customer hands over EUR 10 and receives EUR 1.80 in change  cbTerminalId comes from Header ftReceiptCase: API v2, point-of-sale receipt type
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  cbPayItems:
                  - Description: Cash
                    Amount: 10.0
                    ftPayItemCase: 35184372088833
                  - Description: Change return
                    Amount: -1.8
                    ftPayItemCase: 35184374185985
              SignRequestReceipt_CashSaleReceipt_5:
                summary: take away sale
                description: |
                  example of a take away sale (take away has special special VAT treatment in some countries) cbTerminalId comes from Header ftReceiptCase: API v2, point-of-sale receipt type
                value:
                  ftReceiptCase: 35184372088833
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Pizza Prosciutto e funghi
                    Amount: 14.9
                    VATRate: 7.0
                    ftChargeItemCase: 35184374186001
                  - Quantity: 1
                    Description: Cheesburger
                    Amount: 15.9
                    VATRate: 7.0
                    ftChargeItemCase: 35184374186001
                  cbPayItems:
                  - Description: Cash
                    Amount: 30.8
                    ftPayItemCase: 35184372088833
              SignRequestReceipt_CashSaleReceipt_6:
                summary: simple Training ReceiptRequest example
                description: |
                  example of a simple training receipt request cbTerminalId comes from Header ftReceiptCase: API v2, training flag, point-of-sale receipt type
                value:
                  ftReceiptCase: 35184372219905
                  cbReceiptReference: "1234"
                  cbReceiptMoment: 2023-11-24T15:22:07Z
                  cbChargeItems:
                  - Quantity: 1
                    Description: Beer 0.3l
                    Amount: 4.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  - Quantity: 1
                    Description: Coffee
                    Amount: 3.6
                    VATRate: 20.0
                    ftChargeItemCase: 35184372088851
                  cbPayItems:
                  - Description: Cash
                    Amount: 8.2
                    ftPayItemCase: 35184372088833
      responses:
        "200":
          description: successful, response from existing item
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReceiptResponse"
        "201":
          description: successful created, response from queue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReceiptResponse"
        "400":
          description: The request was malformed or could not be processed.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                badRequest:
                  $ref: "#/components/examples/badRequest"
        "401":
          description: Access token is not set or invalid.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                unauthorized:
                  $ref: "#/components/examples/unauthorized"
        "500":
          description: The server encountered an unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                serverError:
                  $ref: "#/components/examples/server-error"
  /issue:
    post:
      tags:
      - /issue
      summary: /issue - receipt delivery
      description: issue (= create) a new receipt that can be retrieved digitally (or printed via the InStore App)
      operationId: Issue
      parameters:
      - $ref: "#/components/parameters/x-operation-id"
      - $ref: "#/components/parameters/x-possystem-id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IssueRequest"
            examples:
              IssueRequestExample:
                $ref: "#/components/examples/IssueRequestExample"
      responses:
        "200":
          description: |
            successful, response from existing item
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssueResponse"
        "201":
          description: |
            successful created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssueResponse"
        "400":
          description: |
            The request was malformed or could not be processed.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                badRequest:
                  $ref: "#/components/examples/badRequest"
        "401":
          description: Access token is not set or invalid.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                unauthorized:
                  $ref: "#/components/examples/unauthorized"
        "500":
          description: The server encountered an unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                serverError:
                  $ref: "#/components/examples/server-error"
  /issue/{QueueId}/{QueueItemId}:
    get:
      tags:
      - /issue
      summary: /issue/{QueueId}/{QueueItemId} - get receipt data
      description: get content of an issued receipt in requested format (png, pdf, json), without updateing the submitted state
      parameters:
      - name: QueueId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      - name: QueueItemId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: |
            (OK) successful
          content:
            image/png:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: object
            application/esc-pos-80mm:
              schema:
                type: string
                format: binary
            application/esc-pos-72mm:
              schema:
                type: string
                format: binary
            application/esc-pos-48mm:
              schema:
                type: string
                format: binary
        "400":
          description: |
            The request was malformed or could not be processed.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                badRequest:
                  $ref: "#/components/examples/badRequest"
        "401":
          description: Access token is not set or invalid.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                unauthorized:
                  $ref: "#/components/examples/unauthorized"
        "500":
          description: The server encountered an unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                serverError:
                  $ref: "#/components/examples/server-error"
    put:
      tags:
      - /issue
      summary: updates an issued and/or submitted receipt
      parameters:
      - $ref: "#/components/parameters/queueId"
      - $ref: "#/components/parameters/queueItemId"
      - $ref: "#/components/parameters/x-operation-id"
      - $ref: "#/components/parameters/x-possystem-id"
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: "#/components/schemas/IssueUpdateAcceptView"
              - $ref: "#/components/schemas/IssueUpdateLink"
              - $ref: "#/components/schemas/IssueUpdateDownload"
              - $ref: "#/components/schemas/IssueUpdatePrint"
              - $ref: "#/components/schemas/IssueUpdateSend"
              - $ref: "#/components/schemas/IssueUpdateUpload"
      responses:
        "200":
          description: |
            (OK) successfull action: download, print
          content:
            text/*:
              schema:
                type: string
            application/pdf:
              schema:
                type: string
                format: binary
            image/*:
              schema:
                type: string
                format: binary
        "201":
          description: |
            (Created) successfull action: send, upload
          content:
            text/*:
              schema:
                type: string
            application/pdf:
              schema:
                type: string
                format: binary
            image/*:
              schema:
                type: string
                format: binary
        "204":
          description: |
            (No Content) successfull action: accept, view
        "400":
          description: |
            The request was malformed or could not be processed.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "401":
          description: Access token is not set or invalid.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                unauthorized:
                  $ref: "#/components/examples/unauthorized"
        "500":
          description: The server encountered an unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                serverError:
                  $ref: "#/components/examples/server-error"
  /issue/{QueueId}/{QueueItemId}/link/qrcode:
    get:
      tags:
      - /issue
      summary: /issue/{QueueId}/{QueueItemId}/link/qrcode - receipt web link as qr code
      description: |
        get qr code for digital receipt url to show it on your pos system display similar to the InStore App  
        example:<br /><img width="150" src="https://receipts-sandbox.fiskaltrust.cloud/9330c645-e838-4b65-b77c-0ab6583d5e80/8fb08828-3f08-4622-8ba7-363552a5a5c0/link/qrcode">
      parameters:
      - name: QueueId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      - name: QueueItemId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: |
            successful
          content:
            image/png:
              schema:
                type: string
                format: byte
              example: "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6CAYA-this-is-not-a-valid-png-and-just-here-as-a-sample-but-in-real-reasponses-a-valid-one-is-returned-AAA+8c9mZt2rV"
        "400":
          description: |
            The request was malformed or could not be processed.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                badRequest:
                  $ref: "#/components/examples/badRequest"
        "401":
          description: Access token is not set or invalid.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                unauthorized:
                  $ref: "#/components/examples/unauthorized"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                notFound:
                  $ref: "#/components/examples/not-found"
        "500":
          description: The server encountered an unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                serverError:
                  $ref: "#/components/examples/server-error"
  /issue/{QueueId}/{QueueItemId}/delivered:
    get:
      tags:
      - /issue
      summary: /issue/{QueueId}/{QueueItemId}/delivered - query delivery status
      description: check if the issued receipt was delivered to the customer at least once (e.g. printed or sent via email/SMS)
      parameters:
      - name: QueueId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      - name: QueueItemId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: Delivered successfully --> OK
          content:
            application/json:
              schema:
                type: object
                description: Provides some details about how the delivery was executed for debug purpose.
                properties:
                  state:
                    type: string
                    example: "Printed"
                  message:
                    type: string
                    example: "Receipt was printed at 01/30/2026 00:03:57. DeliveryMethod: customeraccepted"
        "204":
          description: |
            Not (yet) delivered --> No Content
        "400":
          description: |
            The request was malformed or could not be processed.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                badRequest:
                  $ref: "#/components/examples/badRequest"
        "401":
          description: Access token is not set or invalid.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                unauthorized:
                  $ref: "#/components/examples/unauthorized"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                notFound:
                  $ref: "#/components/examples/not-found"
        "500":
          description: The server encountered an unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                serverError:
                  $ref: "#/components/examples/server-error"
        default:
          description: "unexpected error                    \n"
  /pay:
    post:
      tags:
      - /pay
      summary: /pay - payment handling
      description: Allows to execute payment actions like payment, cancel or refund via connected/configured payment providers
      parameters:
      - $ref: "#/components/parameters/x-operation-id"
      - $ref: "#/components/parameters/x-possystem-id"
      requestBody:
        content:
          application/json:
            schema:
              description: |
                Depending on the payment action different request body types must be used
              oneOf:
                - $ref: "#/components/schemas/PayPaymentRequest"
                - $ref: "#/components/schemas/PayCancelOrRefundRequest"
            examples:
              payment:
                $ref: "#/components/examples/PayRequestUseAuto"                                
              cancel or refund:
                $ref: "#/components/examples/PayRequestUseAuto_CancelOrRefund"
#                $ref: "#/components/examples/PayRequestHobexRestApiCancelMinimum_1"
#              refund:
#                $ref: "#/components/examples/PayRequestHobexRestApiRefundMinimum_1"
#              pre_authorize:
#                $ref: "#/components/examples/PayRequestHobexRestApiPreAuthMinimum_1_1"
#              pre_authorize_capture:
#                $ref: "#/components/examples/PayRequestHobexRestApiPreAuthMinimum_1_2"
#              pre_authorize_cancel:
#                $ref: "#/components/examples/PayRequestHobexRestApiPreAuthMinimum_1_3"
      responses:
        "200":
          description: |
            successful, response from existing item (response from a previous operation with same x-operation-id)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayPaymentResponse"
              examples:
                payment:
                  $ref: "#/components/examples/PayResponseDummyPaymentProvider"                
        "201":
          description: |
            successful created, response from queue (processed via payment handling)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayPaymentResponse"
              examples:
                payment:
                  $ref: "#/components/examples/PayResponseDummyPaymentProvider"
#                payment:
#                  $ref: "#/components/examples/PayResponseHobexRestApiPaymentMinimum_1"
#                cancel:
#                  $ref: "#/components/examples/PayResponseHobexRestApiCancelMinimum_1"
#                refund:
#                  $ref: "#/components/examples/PayResponseHobexRestApiRefundMinimum_1"
#                pre_authorize:
#                  $ref: "#/components/examples/PayResponseHobexRestApiPreAuthMinimum_1_1"
#                pre_authorize_capture:
#                  $ref: "#/components/examples/PayResponseHobexRestApiPreAuthMinimum_1_2"
#                pre_authorize_cancel:
#                  $ref: "#/components/examples/PayResponseHobexRestApiPreAuthMinimum_1_3"
        "400":
          description: |
            Either the x-operation-id header was not sent or the body that was sent doesn't meet the requirements
        "401":
          description: |
            Not authenticated
        default:
          description: "unexpected error \n"
  /journal/OperationItem/{Id}:
    get:
      tags:
      - /journal
      summary: /journal - export operation data
      parameters:
      - name: Id
        in: path
        required: true
        explode: false
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OperationItem"
        "404":
          description: Operation item with given ID  not found
        default:
          description: "unexpected error    \n"

components:
  parameters:
    queueId:
      name: QueueId
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type: string
        format: uuid
    queueItemId:        
      name: QueueItemId
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type: string
        format: uuid
    x-operation-id:
      name: x-operation-id
      in: header
      required: true
      description: |
        Operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communication issues
        or communication network switch. Calls or messages with same OperationId schould end up in only one action.
      schema:
        type: string
        format: uuid
      example: 3ff388ce-96e4-4f19-9f19-b24ef38ec2b6
    x-possystem-id:
      name: x-possystem-id
      in: header
      description: |
       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.
      required: true
      schema:
        type: string
  schemas:
    ProblemDetails:
      required:
      - title
      type: object
      properties:
        type:
          maxLength: 1024
          type: string
          description: A URI reference that identifies the problem type.
          format: uri
        status:
          maximum: 599
          minimum: 100
          type: integer
          description: The HTTP status code generated by the origin server for this
            occurrence of the problem.
          format: int32
          example: (see status code)
        title:
          maxLength: 1024
          type: string
          description: "A short, human-readable summary of the problem type. It should\
            \ not change from occurrence to occurrence of the problem, except for\
            \ purposes of localization."
        detail:
          maxLength: 4096
          type: string
          description: A human-readable explanation specific to this occurrence of
            the problem.
        instance:
          maxLength: 1024
          type: string
          description: A URI reference that identifies the specific occurrence of
            the problem. It may or may not yield further information if dereferenced.
        code:
          maxLength: 50
          type: string
          description: An API specific error code aiding the provider team understand
            the error based on their own potential taxonomy or registry.
    OperationStateEnum:
      type: string
      example: done
      default: unknown
      enum:
      - pending
      - processing
      - done
      - failed
      - unknown
    ReceiptRequestBasic:
      title: ReceiptRequestBasic
      required:
      - cbChargeItems
      - cbPayItems
      - cbReceiptMoment
      - cbReceiptReference
      type: object
      description: |
        The cash register transfers the data of an entire receipt request to the fiskaltrust.Middleware using the ReceiptRequest data structure.  
        The field fiskaltrust receipt case (ftReceiptCase) is of the highest importance for the correct processing of the receipt.
        This field defines the receipt type, determines if the receipt has to be secured accordingly to the national law, and establishes the method to calculate the correct values for each national counter.
      properties:
        cbReceiptReference:
          type: string
          description: |
            Reference number created by the caller. This value must be a unique string/receipt number related to the calling cash register.
            This string/receipt number is a unique primary key of the dataset of the cash register.
        cbReceiptMoment:
          type: string
          description: moment at which the receipt has been created by the cash register; must be provided in UTC.
          format: date-time
          example: 2020-06-29T17:45:40.505Z
        cbChargeItems:
          type: array
          description: |
            List of charge items related to services and products (e.g. sold products).
          items:
            $ref: "#/components/schemas/ChargeItemBasic"
        cbPayItems:
          type: array
          description: |
            List of line items related to payments; when using the /pay endpoint for payment the ftPayItems from the payment response can be used without alteration.
          items:
            $ref: "#/components/schemas/PayItemResponse"
        ftReceiptCase:
          type: integer
          description: |
            Type of business according to fiskaltrust reference.
            This is relevant for fiskaltrust middleware processing and is a country specific mapping. As fallback when not specified, a cash register business case at the point-of-sale is used.
          format: uint64
        cbPreviousReceiptReference:
          type: string
          description: Reference `cbReceiptReference` of the previous receipt. Used to connect multiple requests for a single Business Case.
    ReceiptRequest:
      title: ReceiptRequest
      required:
      - cbChargeItems
      - cbPayItems
      - cbReceiptMoment
      - cbReceiptReference
      type: object
      description: |
        The cash register transfers the data of an entire receipt request to the fiskaltrust.Middleware using the ReceiptRequest data structure.  
        The field fiskaltrust receipt case (ftReceiptCase) is of the highest importance for the correct processing of the receipt.
        This field defines the receipt type, determines if the receipt has to be secured accordingly to the national law, and establishes the method to calculate the correct values for each national counter.
      properties:
        cbTerminalID:
          type: string
          description: |
            The unique identification of the input-station/terminal within a cash-register/pos-system identified by `ftCashBoxID`.
          default: undefined
        cbReceiptReference:
          type: string
          description: |
            Reference number send by the cash register. This value must be a unique string/receipt number related to the calling cash register. This string/receipt number is a unique primary key of the dataset of the cash register.
          default: undefined
        cbReceiptMoment:
          type: string
          description: moment at which the receipt has been created by the cash register; must be provided in UTC.
          format: date-time
          example: 2020-06-29T17:45:40.505Z
        cbChargeItems:
          type: array
          description: |
            List of charge items related to services and products
          items:
            $ref: "#/components/schemas/ChargeItem"
        cbPayItems:
          type: array
          description: |
            List of pay items related to payments; when using the /pay endpoint for payment the ftPayItems from the payment response can be used.
          items:
            $ref: "#/components/schemas/PayItemResponse"
        ftCashBoxID:
          type: string
          description: |
            identification of the cash register
          format: uuid
        ftPosSystemID:
          type: string
          description: |
            identification of the used software of the cash register
          format: uuid
          default: 00000000-0000-0000-0000-000000000000
        ftReceiptCase:
          type: integer
          description: |
            Type of business according to fiskaltrust reference.
            This is relevant for fiskaltrust middleware processing and is a country specific mapping. As fallback when not specified, a cash register business case at the point-of-sale is used.
          format: uint64
        ftReceiptCaseData:
          description: |
            Gives additional details for defined type of business related to fiskaltrust reference.
          type: object
          additionalProperties: true
        ftQueueID:
          type: string
          description: |
            optional routing instruction to identify a specific queue behind a load balancer or in other usecases
          format: uuid
        cbPreviousReceiptReference:
          type: string
          description: |
            optional Reference `cbReceiptReference` of the previous receipt. Used to connect multiple requests for a single Business Case.
        cbReceiptAmount:
          description: |
            Total receipt amount, including value added taxes (=gross receipt amount) given to avoid calculation and rounding differences.
            Systems which are using net amounts as central calculation should alsways use this property.
            If not provided, the sum of `Amount` in all provided `ftChargeItems` is used as total receipt amount.
          type: number
          format: double
        cbUser:
          description: |
            Identification of the user, who creates the receipt.
          type: object
          additionalProperties: true
        cbArea:
          description: |
            Identification of the area/section/field, in which the receipt is created.
            E.g., table number of a restaurant business; a department of a commercial establishment; the vehicle of a taxi company
          type: object
          additionalProperties: true
        cbCustomer:
          description: |
            Identification of the consumer, for whom the receipt is created. e.g. Email address, phone number, personal tax number.
          type: object
          additionalProperties: true
        cbSettlement:
          description: |
            Settlement identification where this receipt will be added.  e.g. shift number or day of operation
          type: object
          additionalProperties: true
        Currency:
          $ref: "#/components/schemas/CurrencyEnum"
    ChargeItemCase:
      type: integer
      description: |
        Defines the type of service or product related to fiskaltrust reference. For detailed definition goto https://docs.fiskaltrust.eu.
        This is relevant for fiskaltrust middleware processing and is a country specific mapping.  
        As fallback when not specified, a service or product delivered at the point-of-sale with defined `VATRate` is used.
        Examples (IMPORTANT: For 100% accurate and up-to-date information please refer to fiskaltrust middleware documentation):
        - Austria (RKSV) CCCC V 000 00DD 00ST hex (Example: 4707387510509010947 = 4154 0 000 0000 0003 hex = 'AT' Version 0 Service Product with 20% VAT)
          - CCCC = country 'AT'
          - V = Version = 2
          - D = direction
            - 00 = standard / default
            - 01 = IsVoid
            - 02 = IsReturn/Refund
            - 04 = Discount
            - 08 = downpayment
            - 10 = Returnable
            - 20 = Takeaway
          - S = type of service (not 100% accurate; please refer to middleware documentation)
            - 0 = unknown
            - 1 = supply of goods
            - 2 = supply of services
            - 3 = tip to owner
            - 4 = single-use or multi-use voucher (depends on defined tax if single- or multi-use)
            - 5 = catalog service
            - 6 = agency business or receiveable of thired party (depends on defined tax if agency or receiveable of third party)
            - 7 = own consumption
            - 8 = grant (unreal)
            - 9 = receiveable
            - A = cash transfer
          - T = type of tax
            - 0 = unknown
            - 1 = discounted1 (as of 1.7.2016, this is calculated with 10%)
            - 2 = discounted2 (as of 1.7.2016, this is calculated with 13%)
            - 3 = standard (as of 1.7.2016, this is calculated with 20%)
      format: uint64
    ChargeItemBasic:
      title: ChargeItemBasic
      required:
      - Amount
      - Description
      - Quantity
      - VATRate
      type: object
      description: |
        represents a item related to a service or a product, taxable      
      properties:
        Quantity:
          description: defines the quantity of the charge item. quantities of charge items with same `Description`, `VATRate` and itemprice can be accumulated for better visualization.
          type: number
          format: double
          default: 1.0
        Description:
          type: string
          description: defines the description of the charge item.
        Amount:
          description: defines the (total) amount of the charge item. to get itemprice the amount need to be devided by quantity.
          type: number
          format: double
          default: 0.0
        VATRate:
          description: Defines the value added tax rate in percentage of the charge item.
          type: number
          format: double
          default: 0.0
        ftChargeItemCase:
          $ref: "#/components/schemas/ChargeItemCase"
        VATAmount:
          description: |
            When given this amount is used as the (total) value added taxes amount for the charge item to avoid rounding when accumulating value added taxes.  
            Systems which are using net amounts as central calculation should alsways use this property.
          type: number
          format: double
        Moment:
          type: string
          description: |
            Moment at which the serivce or product was ordered or delivered, must be provided in UTC.  
            Accumulated line items get the minimum (first) moment.  
            If not given, the `cbReceiptMoment` is used as fallback
          format: date-time
          example: 2020-06-29T17:45:40.505Z
        Position:
          description: |
            Used to sort and group the line items for receipt visualization. Accumulated line items get the minimum (first) position.  
            With a specific instruction/flag in `ftReceiptCase` a grouping of multiple line items can be activated.
            If this is the case, `Position` is treated as a decimal number, the whole number represents the grouped charge item and the fraction part is used within the group
          type: number
          format: double
          default: 0.0
          examples: [ 1.1, 2 ]
    ChargeItem:
      title: ChargeItem
      required:
      - Amount
      - Description
      - Quantity
      - VATRate
      type: object
      properties:
        ftChargeItemID:
          type: string
          description: |
            optional used as an identifier of a charge item, when reading data
          format: uuid
          readOnly: true
        Quantity:
          description: |
            Defines the quantity of the charge item. quantities of line items with same `Description`, `VATRate` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization.
          type: number
          format: double
          default: 1.0
        Description:
          type: string
          description: |
            defines the description of the charge item. line items with same `Description`, `VATRate` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization
        Amount:
          description: |
            Defines the (total) amount of the charge item. to get itemprice the amount need to be devided by quantity.
          type: number
          format: double
        VATRate:
          description: |
            Defines the value added tax rate in percentage of the charge item.
            Line items with same `Description`, `VATRate` and itemprice (=`Amount`/`Quantity`) can be accumulated for better visualization.            
          type: number
          format: double
        ftChargeItemCase:
          $ref: "#/components/schemas/ChargeItemCase"
        ftChargeItemCaseData:
          description: Gives additional details for defined type of service or product related to fiskaltrust reference.
          type: object
          additionalProperties: true
        VATAmount:
          description: |
            When given and not null this amount is used as the (total) value added taxes amount for the charge item to avoid rounding when accumulating value added taxes.
            Systems which are using net amounts as central calculation should alsways use this property.
          type: number
          format: double
        Moment:
          type: string
          description: |
            optional moment at which the serivce or product was ordered or delivered, must be provided in UTC. accumulated line items get the minimum (first) moment. if not given, the `cbReceiptMoment` is used as fallback
          format: date-time
          example: 2020-06-29T17:45:40.505Z
        Position:
          description: |
            Used to sort and group the line items for receipt visualization. accumulated line items get the minimum (first) position.  
            With a specific instruction/flag in `ftReceiptCase` a grouping of multiple line items can be activated..
            If this is the case,  `Position` is threaded as a decimal number, the whole number represents the grouped charge item and the fraction part is used within the group
          type: number
          format: double
        AccountNumber:
          type: string
          description: |
            optional account number for bookkeeping export purpose
        CostCenter:
          type: string
          description: |
            optional cost center for cost accounting purpose
        ProductGroup:
          type: string
          description: |
            optional product group related to charge item
        ProductNumber:
          type: string
          description: |
            optional product number related to charge item
        ProductBarcode:
          type: string
          description: |
            optional product barcode related to charge item
        Unit:
          type: string
          description: |
            Unit of measurement for the charge item. e.g. you have on one charging session of an electric vehicle, this would be `Quantity` 1 and the total amount of the session within `amount`.
            The unit of measurement could be `kW` for dc charging or `min` for ac charging.
            For an exmaple see UnitPrice.
        UnitQuantity:
          description: |
            The quantity related to the unit of measurement defined in `Unit`.
            For an exmaple see UnitPrice.
          type: number
          format: double
        UnitPrice:
          description: |
            The price related to the unit of measurement defined in `Unit`.  
            E.g., you have on one charging session of an electric vehicle, this would be `Quantity` 1 and as example the total amount
            of 30.7 of the session within `amount`. if the unit of measurement is `kW` for dc charging the `UnitQuantity` could be 65.4 as an example
            and for the given total amount the `UnitPrice` would be 0.5. which would mean the charge item represents a charging session with a total amount
            of power of 65.4kW with a price per kW of 0.5.
          type: number
          format: double
        Currency:
          $ref: "#/components/schemas/CurrencyEnum"
      description: |
        represents a item related to a service or a product, taxable
    CurrencyEnum:
      type: string
      description: |
        used as currency code for money numbers. along ISO 4217 (https://en.wikipedia.org/wiki/ISO_4217)
      default: EUR
      enum:
      - EUR
      - CHF
      - CZK
      - HUF
      - BAM
      - DKK
      - RON
      - NOK
      - PLN
      - RSD
      - SEK
      - UAH
      - USD
      - AED
      - AFN
      - ALL
      - AMD
      - ANG
      - AOA
      - ARS
      - AUD
      - AWG
      - AZN
      - BBD
      - BDT
      - BGN
      - BHD
      - BIF
      - BMD
      - BND
      - BOB
      - BOV
      - BRL
      - BSD
      - BTN
      - BWP
      - BYN
      - BZD
      - CAD
      - CDF
      - CHE
      - CHW
      - CLF
      - CLP
      - CNY
      - COP
      - COU
      - CRC
      - CUP
      - CVE
      - DJF
      - DOP
      - DZD
      - EGP
      - ERN
      - ETB
      - FJD
      - FKP
      - GBP
      - GEL
      - GHS
      - GIP
      - GMD
      - GNF
      - GTQ
      - GYD
      - HKD
      - HNL
      - HTG
      - IDR
      - ILS
      - INR
      - IQD
      - IRR
      - ISK
      - JMD
      - JOD
      - JPY
      - KES
      - KGS
      - KHR
      - KMF
      - KPW
      - KRW
      - KWD
      - KYD
      - KZT
      - LAK
      - LBP
      - LKR
      - LRD
      - LSL
      - LYD
      - MAD
      - MDL
      - MGA
      - MKD
      - MMK
      - MNT
      - MOP
      - MRU
      - MUR
      - MVR
      - MWK
      - MXN
      - MXV
      - MYR
      - MZN
      - NAD
      - NGN
      - NIO
      - NPR
      - NZD
      - OMR
      - PAB
      - PEN
      - PGK
      - PHP
      - PKR
      - PYG
      - QAR
      - RUB
      - RWF
      - SAR
      - SBD
      - SCR
      - SDG
      - SGD
      - SHP
      - SLE
      - SLL
      - SOS
      - SRD
      - SSP
      - STN
      - SVC
      - SYP
      - SZL
      - THB
      - TJS
      - TMT
      - TND
      - TOP
      - TRY
      - TTD
      - TWD
      - TZS
      - UGX
      - USN
      - UYI
      - UYU
      - UYW
      - UZS
      - VED
      - VES
      - VND
      - VUV
      - WST
      - XAF
      - XAG
      - XAU
      - XBA
      - XBB
      - XBC
      - XBD
      - XCD
      - XDR
      - XOF
      - XPD
      - XPF
      - XPT
      - XSU
      - XTS
      - XUA
      - XXX
      - YER
      - ZAR
      - ZMW
      - ZWL
    PayItemRequest:
      title: PayItemRequest
      required:
      - Amount
      - Description
      type: object
      properties:
        Description:
          type: string
          description: defines the description of the line item
          example: Card
        Amount:
          description: defines the (total) amount of the line item
          type: number
          format: double
          example: "1.0"
    PayItemResponse:
      title: PayItemResponse
      required:
      - ftPayItemID
      - Amount
      - Description
      type: object
      properties:
        ftPayItemID:
          type: string
          description: ID of the pay item
          format: uuid
        Description:
          type: string
          description: defines the description of the line item
          example: Card
        Amount:
          description: defines the (total) amount of the line item
          type: number
          format: double
          example: "1.0"
        ftPayItemCase:
          type: integer
          description: |
            Defines the type of payment related to fiskaltrust reference. For detailed definition goto https://docs.fiskaltrust.eu
          format: uint64
        ftPayItemCaseData:
          description: Gives additional details for the used payment method.
          type: object
          properties:
            Provider:
              type: object
              description: |
                Set by POS System API when using the /pay endpoint. Can be ignored in allother cases.  
                Information about the used payment provider used to execute the payment transaction
              properties:
                Protocol:
                  description: |
                    Can be used to identify the payment provider when "use_auto" was used in the request.
                    NOTE: use_auto will never be returned here. The actual used protocol will be returned.
                  $ref: "#/components/schemas/PaymentProtocolEnum"
                Action:
                  $ref: "#/components/schemas/PaymentActionEnum"
                ProtocolRequest:
                  description: Original request sent to the payment provider for debugging purpose.
                  oneOf:
                    - type: string
                    - type: object
                      additionalProperties: true
                ProtocolResponse:
                  description: Original response received from the payment provider for debugging purpose.
                  oneOf:
                    - type: string
                    - type: object
                      additionalProperties: true
            Receipt:
              type: array
              description: The receipt lines returned by the payment provider to be printed on the fiskal receipt
              items:
                type: string
          additionalProperties: true
        Moment:
          type: string
          description: moment at which the payment was executed, must be provided in UTC. accumulated line items get the minimum (first) moment
          format: date-time
          example: 2020-06-29T17:45:40.505Z
    ReceiptResponse:
      required:
      - ftCashBoxIdentification
      - ftQueueId
      - ftQueueItemId
      - ftQueueRow
      - ftReceiptIdentification
      - ftReceiptMoment
      - ftSignatures
      - ftState
      - cbReceiptReference
      - ftCashBoxID
      type: object
      description: |
        fiskaltrust.Middleware sends back the processed data to the cash register through the receipt response.
        The data included in the request, such as header, service, pay items, and footer, will not be sent back.
        The returned data is added to the receipt as supplement to the data of the receipt request.
      properties:
        ftQueueID:
          type: string
          description: Identification of the queue used for processing.
          format: uuid
        ftQueueItemID:
          type: string
          description: Identification of the item within a specific queue used for processing.
          format: uuid
        ftQueueRow:
          type: integer
          description: Row in which the item is stored within a specific queue used for processing.
          format: uint64
        ftCashBoxIdentification:
          type: string
          description: |
            Human readable identification or serial number of the cash register related to the national regulation/law.  
            This need to be printed on the receipt to identify the cash register within a merchant, and is unique over a single merchant.  
            Do not mix up `ftCashBoxId` with `ftCashBoxIdentification`.
        ftReceiptIdentification:
          type: string
          description: |
            Human readable identification of the receipt related to the national regulation/law and the `ftCashBoxIdentification`/ Queue.  
            This need to be printed on the receipt to identify it within a merchant and cash register.
            This always starts with 'ft', followed by the row number of the queue in hexadecimal, followed by '#',
            followed by national required or defined receipt numbering.
          example: ft2BC#685
        ftReceiptMoment:
          type: string
          description: UTC Moment at which the receipt was processed by fiskaltrust.Middleware. Must be printed on the receipt in local date/time.
          format: date-time
          example: 2020-06-29T17:45:40.505Z
        ftSignatures:
          type: array
          description: |
            List of signature items generated by fiskaltrust.Middleware.
            This need to be printed on the receipt according to given format instructions to comply with national regulation/law and to enable fiskaltrust's compliance-as-a-service.
          items:
            $ref: "#/components/schemas/SignatureItem"
        ftState:
          type: integer
          description: |
            Indicates the status of the fiskaltrust.Middleware according to fiskaltrust reference. Depending on the country you are operating in the values can vary.  
            For detailed definition goto https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc
            Format: _CCCC_vlll_gggg_gggg_
            - CCCC = country code
            - v = version
            - lll = local flags -> xxa
              - a = SCU related
            - gggg gggg = global flags
          format: uint64
        ftStateData:
          description: Gives additional details for the status of fiskaltrust.Middleware for debug purposes.
          type: object
          additionalProperties: true
        ftCashBoxID:
          type: string
          description: Identification of the cash box / cash register. Required for a later /issue request.
          format: uuid
        cbTerminalID:
          type: string
          description: Mirror from `ReceiptRequest` The unique identification of the input-station/terminal within a cash-register/pos-system identified by `ftCashBoxID`.
        cbReceiptReference:
          type: string
          description: Mirror from `ReceiptRequest` Reference number sent by the cash register. Required for a later /issue request.
        ftReceiptHeader:
          type: array
          description: Additional header lines this need to be printed on the receipt.
          items:
            type: string
        ftChargeItems:
          type: array
          description: List of charge items added by fiskaltrust.Middleware while processing the request related to services and products this need to be printed on the receipt.
          items:
            $ref: "#/components/schemas/ChargeItem"
        ftChargeLines:
          type: array
          description: Additional text for line items related to services and products this need to be printed on the receipt.
          items:
            type: string
        ftPayItems:
          type: array
          description: List of pay items added by fiskaltrust.Middleware while processing the request related to payments this need to be printed on the receipt.
          items:
            $ref: "#/components/schemas/PayItemResponse"
        ftPayLines:
          type: array
          description: Additional text for line items related to payments this need to be printed on the receipt.
          items:
            type: string
        ftReceiptFooter:
          type: array
          description: Additional footer lines this need to be printed on the receipt.
          items:
            type: string
    SignatureType:
      type: integer
      description: |
        Type of signature according to fiskaltrust reference. For further details see [middleware-doc](https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc).
        Basic foramt (as hex number): CCCC V xxx xxxx xxxx  
        Example:  
        - Austria (RKSV): 4707422694881099777 = 4154 2 000 0000 0001 hex = 'AT' + v2 + '000 0000 0001' which is a signature according to RKSV (see also [ftsignaturetype RKSV](https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc/austria/reference-tables#type-of-signature-ftsignaturetype) )
          - 4154 2 000 0000 0000 hex unknown signature type  
          - 4154 2 000 0000 0001 hex RKSV signature type  
          - 4154 2 000 0001 0002 hex daily operation notification, archiving required  
          - 4154 2 000 0001 0003 hex RKSV FinanzOnline notification, archiving required
        - Germany (KassenSichV): 4919373352344223745 = 4445 2 000 0000 0001 hex = 'DE' + v2 + '000 0000 0001' which is a signature according to KassenSichV (see also [ftsignaturetype KassenSichV](https://docs.fiskaltrust.cloud/docs/poscreators/middleware-doc/germany/reference-tables/ftsignaturetype))
          - 4445 2 000 0000 0000 hex unknown signature type
          - 4445 2 000 0000 0001 hex KassenSichV signature type
          - 4445 2 000 0020 0010 hex Start-transaction-result [do-not-print] flag
          - 4445 2 000 0020 0011 hex Finish-transaction-payload [do-not-print] flag
          - 4445 2 000 0020 0012 hex Finish-transaction-result [do-not-print] flag
          - 4445 2 000 0010 0013 hex QR-Code Version for receipt [optional-print] flag
          - 4445 2 000 0010 0014 hex Cashregister Serialnumber for receipt [optional-print] flag
          - 4445 2 000 0010 0015 hex ProcessType for receipt [optional-print] flag
          - 4445 2 000 0010 0016 hex ProcessData for receipt [optional-print] flag
          - 4445 2 000 0010 0017 hex Transaction number for receipt [optional-print] flag
          - 4445 2 000 0010 0018 hex Signature counter for receipt [optional-print] flag
          - 4445 2 000 0010 0019 hex Transaction start time for receipt [optional-print] flag
          - 4445 2 000 0010 001A hex Signature logtime for receipt [optional-print] flag
          - 4445 2 000 0010 001B hex Signature algorithm for receipt [optional-print] flag
          - 4445 2 000 0010 001C hex Signature logtime format for receipt [optional-print] flag
          - 4445 2 000 0010 001D hex Signature for receipt [optional-print] flag
          - 4445 2 000 0010 001E hex Public key for receipt [optional-print] flag
          - 4445 2 000 0000 001F hex Process start time for receipt
          - 4445 2 000 0020 0020 hex Update-transaction-payload [do-not-print] flag
          - 4445 2 000 0020 0021 hex Update-transaction-result [do-not-print] flag
          - 4445 2 000 0000 0022 hex Certification identification and protec-tion profile restrictions for receipt
          - 4445 2 000 0000 0023 hex TSE serial number for receipt
      format: uint64
    SignatureItem:
      required:
      - Data
      - ftSignatureFormat
      - ftSignatureType
      type: object
      description: |
        The signature of the receipt must comply with the national law and is controlled via the ftReceiptCase provided in the ReceiptRequest.  
        The signature data returned in the response must be visualized on the receipt related to format instruction and to fiskaltrust reference.  
        The signature entries can also be used to visualize hints and messages related to the fiskaltrust.SecurityMechanism.
      properties:
        ftSignatureFormat:
          $ref: "#/components/schemas/SignatureFormat"
        ftSignatureType:
          $ref: "#/components/schemas/SignatureType"
        Caption:
          type: string
          description: Heading, which has to be displayed as text above the signature data.
        Data:
          description: Signature content which has to be displayed in the specified format (see ftSignatureFormat).
          type: string
    SignatureFormat:
      type: integer
      description: |
        Definiton on how to display signature data according to fiskaltrust reference.
        - Format type - bitmask 0x0000_0000_0000_FFFF:
          - 0 = Unknown
          - 1 = Text
          - 2 = Link
          - 3 = QRCode
          - 4 = Code128
          - 5 = OcrA
          - 6 = Pdf417
          - 7 = DataMatrix
          - 8 = Aztec
          - 9 = Ean8Barcode
          - 10 = Ean13
          - 11 = UPCA
          - 12 = Code39
          - 13 = Base64
        - Position - bitmask 0x0000_0000_FFFF_0000:
          - integer value defining the position on the receipt. TODO
      format: uint64
    IssueRequest:
      title: IssueRequest
      description: Request to issue receipt based on previously signed receipt (ReceiptRequest and ReceiptResponse are both a copy of the previous /sign request and response)
      required:
      - ReceiptRequest
      - ReceiptResponse
      type: object
      properties:
        ReceiptRequest:
          $ref: "#/components/schemas/ReceiptRequest"
        ReceiptResponse:
          $ref: "#/components/schemas/ReceiptResponse"
      additionalProperties: false
    IssueResponse:
      required:
      - QueueId
      - QueueItemId
      properties:
        ftQueueID:
          type: string
          format: uuid
          example: "99869afd-f29a-4048-925a-faca4d8b997a"
        ftQueueItemID:
          type: string
          format: uuid
          example: "893673be-ddd8-4653-93ba-7c32f9aefc71"
        DocumentURL:
          type: string
          format: uri
          example: "https://receipts-sandbox.fiskaltrust.eu/99869afd-f29a-4048-925a-faca4d8b997a/893673be-ddd8-4653-93ba-7c32f9aefc71"
        # OUTCOMMENTED - seems to be empty anyway all the time
        #DocumentContentType:
        #  type: [string, "null"]
      description: |
        result of issued receipt
    IssueUpdateAcceptView:
      title: IssueUpdateAcceptView
      required:
      - Action
      type: object
      properties:
        Action:
          type: string
          enum:
          - accept
          - view
    IssueUpdateLink:
      title: IssueUpdateLink
      required:
      - Action
      properties:
        Action:
          type: string
          enum:
          - link
        Target:
          $ref: "#/components/schemas/IssueUpdateLink_Target"
        Handout:
          type: boolean
          default: false
    IssueUpdateDownload:
      title: IssueUpdateDownload
      required:
      - Action
      properties:
        Action:
          type: string
          enum:
          - download
        Format:
          $ref: "#/components/schemas/IssueUpdateFormatEnum"
    IssueUpdateFormatEnum:
      type: string
      enum:
      - text/html
      - text/plain
      - application/pdf
      - image/png
      - image/jpeg
      - text/vnd.esc-pos;charset=utf-8
    IssueUpdatePrint:
      title: IssueUpdatePrint
      required:
      - Action
      properties:
        Action:
          type: string
          enum:
          - print
        Format:
          $ref: "#/components/schemas/IssueUpdateFormatEnum"
        Width:
          type: integer
        EscPosBrand:
          type: string
          enum:
          - none
          - epson
          - tousei
    IssueUpdateSend:
      title: IssueUpdateSend
      required:
      - Action
      properties:
        Action:
          type: string
          enum:
          - send
        Format:
          $ref: "#/components/schemas/IssueUpdateFormatEnum"
        Target:
          $ref: "#/components/schemas/IssueUpdateSend_Target"
    IssueUpdateUpload:
      title: IssueUpdateUpload
      required:
      - Action
      properties:
        Action:
          type: string
          enum:
          - upload
        Format:
          $ref: "#/components/schemas/IssueUpdateFormatEnum"
        Filename:
          type: string
        Filecontent:
          type: string
          format: binary
      description: accept receipt
    PayPaymentRequest:
      title: PayPaymentRequest
      required:
      - Action
      - Protocol
      - cbPayItem
      type: object
      properties:
        Protocol:
          $ref: "#/components/schemas/PaymentProtocolEnum"
        Action:
          const: payment
          description: Execute a new payment transaction
        cbPayItem:
          description: The payment request item
          $ref: "#/components/schemas/PayItemRequest"
        cbTerminalID:
          type: string
          description: |
            Allows to identify a specific target device/terminal or group that should process the request.<br />
            See cbTerminalID settings documentation for the InStore App about further details how to use this property.<br />
            Example: If you use just a signgle device / terminal in a site the cbTerminalID can be ignored (= undefined)<br />
            Example: If you use multiple devices the idea is to assign a unique cbTerminalID per device / terminal and use this property to address a specific device / terminal.
          default: undefined
    PayCancelOrRefundRequest:
      title: PayCancelOrRefundRequest
      required:
      - Action
      - Protocol
      - cbPayItem
      type: object
      properties:
        Protocol:
          $ref: "#/components/schemas/PaymentProtocolEnum"
        Action:
          $ref: "#/components/schemas/PaymentActionCancelRefundEnum"
        cbPayItem:
          description: The pay item received in the response of the payment action to cancel or refund
          $ref: "#/components/schemas/PayItemResponse"
        cbTerminalID:
          type: string
          description: |
            Allows to identify a specific target device/terminal or group that should process the request.<br />
            See cbTerminalID settings documentation for the InStore App about further details how to use this property.<br />
            Example: If you use just a signgle device / terminal in a site the cbTerminalID can be ignored (= undefined)<br />
            Example: If you use multiple devices the idea is to assign a unique cbTerminalID per device / terminal and use this property to address a specific device / terminal.
          default: undefined          
    PaymentProtocolEnum:
      type: string
      description: |       
        a list of supported protocols<br />
        - use_auto triggers a automaticaly selected, single payment protocol, best match for given PayItemCase; it depends on the target device which ones are available/configured and used<br />
        - gp_softpos_gptom ... GP tom SoftPOS app (from Global Payments; actions: payment)<br />
        - gp_mpas ... Global Payments via dedicaited payment terminal (like PAX A920 Pro from Global Payments; actions: payment)<br />
        - payone_softpos_wpi ... PayOne SoftPOS app (actions: payment)<br />
        - hobex_softpos_posit ... Hobex POSit SoftPOS payment app (actions: payment)<br />
        Not supported as enum values but supported via device configuraiton and using protocol "use_auto":<br />
        - viva_eft_pos_instore ... Viva Wallet SoftPOS app (actions: payment, refund, cancel) <br />
        - hobexecr ... Hobex ecr protocol via dedicated payment terminal (like Sunmi P2 Pro from Hobex; actions: payment)<br />
        - softpayio ... Softpay.io SoftPOS app (actions: payment)<br />
        - shift4 ... Shift4 SoftPOS app (actions: payment, refund, cancel)<br />
        - test ... Dummy Payment Provider, only available when developer mode is activated in InStore app (actions: payment, refund, cancel)<br />
      enum:
      - use_auto
      - gp_softpos_gptom
      - gp_mpas
      - payone_softpos_wpi      
      - hobex_softpos_posit
      - viva_eft_pos_instore
      - hobexecr
      - softpayio
      - shift4
      - test
    PaymentActionEnum:
      type: string
      description: |
        Possible pay actions. NOTE: Not all actions are supported by all payment protocols.<br />
        - payment: Execute a payment<br />
        - cancel: Cancel a payment previous executed, successful payment action. (before settlement; = no money moved)<br />
        - refund: Refund a payment previous executed, successful payment action. (after settlement; = paying the money back)<br />
      enum:
      - payment
      - cancel
      - refund
    PaymentActionCancelRefundEnum:
      type: string
      description: |
        Possible pay actions. NOTE: Not all actions are supported by all payment protocols.<br />
        - cancel: Cancel a payment previous executed, successful payment action. (before settlement; = no money moved)<br />
        - refund: Refund a payment previous executed, successful payment action. (after settlement; = paying the money back)<br />
      enum:
      - cancel
      - refund
    PayPaymentResponse:
      required:
      - Protocol
      - ftPayItems
      - ftQueueId
      type: object
      properties:
        Protocol:
          $ref: "#/components/schemas/PaymentProtocolEnum"
        ftQueueID:
          type: string
          description: |
            identification of the queue used for processing
          format: uuid
          default: 00000000-0000-0000-0000-000000000000
        ftPayItems:
          type: array
          items:
            $ref: "#/components/schemas/PayItemResponse"
    OperationItem:
      title: OperationItem
      required:
      - LastState
      - OperationId
      properties:
        cbOperationItemID:
          type: string
          description: The operation ID of the requested item.
          format: uuid
        ftQueueID:
          type: string
          description: identification of the queue used for processing
          format: uuid
        Method:
          type: string
          example: POST
          description: The HTTP method used for the operation
        Path:
          type: string
          example: /sign
          description: The API path of the operation
        RequestHeaders:
          type: object
          description: The headers sent / used to process the request.
        Request:
          type: string
          description: The request payload sent / used to process the request (serialized JSON).
        Response:
          type: string
          description: The response payload received after processing the request (serialized JSON).
        ResponseCode:
          type: integer
          description: The HTTP response code received after processing the request.
        LastState:
          $ref: "#/components/schemas/OperationStateEnum"
        TimeStamp:
          type: string
          description: The UTC timestamp of the last state change of the operation.
          format: date-time
        ftOperationItemMoment:
          type: string
          description: moment at which the operation item was created, must be provided in UTC.
          format: date-time
      description: |
        reflects a single operation
    IssueUpdateLink_Target:
      type: object
      properties:
        Host:
          type: string
          format: uri
        Path:
          type: string
    IssueUpdateSend_Target:
      type: object
      properties:
        Scheme:
          type: string
          enum:
          - email
          - sms
          - whatsapp
        Address:
          type: string
        Attach:
          type: string
          enum:
          - none
          - pdf
          - png
        Send:
          type: boolean
          default: true
  examples:
    badRequest:
      value:
        type: about:blank
        title: Bad Request
        detail: The request is invalid and cannot be processed. The request must not be repeated without modification.
        status: 400
    unauthorized:
      value:
        type: about:blank
        title: Unauthorized
        detail: Access token not set or invalid. The requested resource could not
          be returned
        status: 401
    server-error:
      value:
        type: about:blank
        title: Server Error
        detail: The server encountered an unexpected error
        status: 500
    not-found:
      value:
        type: about:blank
        title: Not found
        detail: The requested resource was not found
        status: 404
    PayRequestUseAuto:
      description: |
        request a payment amount is EUR 1.50 chooses a payment-device assigned to `cbTerminalId` by itself
      value:
        Action: payment
        Protocol: use_auto
        cbPayItem:
          Description: Card
          Amount: 1.5
        cbTerminalId: 1
    PayRequestUseAuto_CancelOrRefund:
      description: |
        request a cancellation of a previous payment<br /><br />
        **IMPORTANT:** The cbPayItem is the same as received in the response of the previous payment action to cancel, including the ftPayItemCase and ftPayItemCaseData to identify the previous payment correctly<br /><br />
        **REFUND:** For a refund the action must be "refund" instead of "cancel"
      value:
        Action: cancel
        Protocol: use_auto
        cbPayItem:
          ftPayItemId: 00000000-0000-0000-0000-xxxxxxxxxxxx
          Description: Card
          Amount: 1.5
          ftPayItemCase: 14757170079003049989
          ftPayItemCaseData:
            Provider:
              Protocol: test
              Action: payment
              ProtocolRequest: dummy provider request
              ProtocolResponse:
                OperationID: 00000000-0000-0000-0000-xxxxxxxxxxxx
                "Amount": 1.5
            Receipt:
            - Line1
            - Line2
            - Line3
            - Line4
          Moment: 2020-06-29T17:45:40.505Z
        cbTerminalId: 1      
    PayResponseDummyPaymentProvider:
      description: |
        response to PayRequestUseAuto
      value:
        Protocol: use_auto
        ftQueueId: 00000000-0000-0000-0000-xxxxxxxxxxxx
        ftPayItems:
        - ftPayItemId: 00000000-0000-0000-0000-xxxxxxxxxxxx
          Description: Card
          Amount: 1.5
          ftPayItemCase: 14757170079003049989
          ftPayItemCaseData:
            Provider:
              Protocol: test
              Action: payment
              ProtocolRequest: dummy provider request
              ProtocolResponse:
                OperationID: 00000000-0000-0000-0000-xxxxxxxxxxxx
                "Amount": 1.5
            Receipt:
            - Line1
            - Line2
            - Line3
            - Line4
          Moment: 2020-06-29T17:45:40.505Z    
    IssueRequestExample:
      summary: Example IssueRequest with ReceiptRequest and ReceiptResponse (as received from /sign)
      description: |
        This example shows how to issue a receipt by providing both the <b>original ReceiptRequest and the ReceiptResponse received from the /sign endpoint</b>.
        This is used to register receipts that were already signed by fiskaltrust.Middleware.
      value:
        ReceiptRequest:
          cbReceiptReference: "POS-2024-001234"
          cbReceiptMoment: "2024-01-30T14:30:00Z"
          ftReceiptCase: 4707387510509010945
          cbChargeItems:
          - Quantity: 2
            Description: "Coffee"
            Amount: 7.20
            VATRate: 20
          - Quantity: 1
            Description: "Cake"
            Amount: 4.50
            VATRate: 20
          cbPayItems:
          - ftPayItemID: "3ff388ce-96e4-4f19-9f19-b24ef38ec2b6"
            Description: "Card"
            Amount: 11.70
            ftPayItemCase: 4707387510509010948
            Moment: "2024-01-30T14:30:05Z"
        ReceiptResponse:
          ftQueueID: "99869afd-f29a-4048-925a-faca4d8b997a"
          ftQueueItemID: "893673be-ddd8-4653-93ba-7c32f9aefc71"
          ftQueueRow: 1234
          ftCashBoxID: "99869afd-f29a-4048-925a-faca4d8b997a"
          ftCashBoxIdentification: "ATFT01234"
          ftReceiptIdentification: "ft4D2#1234"
          ftReceiptMoment: "2024-01-30T14:30:05.123Z"
          cbReceiptReference: "POS-2024-001234"
          ftState: 4707422694881099784
          ftSignatures:
          - ftSignatureFormat: 1
            ftSignatureType: 4707422694881099776
            Caption: "S A N D B O X"
            Data: "99869afd-f29a-4048-925a-faca4d8b997a"
          - ftSignatureFormat: 3
            ftSignatureType: 4707422694881099777
            Caption: "QR-Code"
            Data: "_R1-AT3_fiskaltrust2_ft2D3#708_2026-01-30T08:40:42_20,00_10,00_0,00_0,00_0,00_YEWmar4=_476f96b33ee4274b_U0BXdZagqEI=_dzAutPjzsZQIILJISgU9hbWp+372Uis+DitKfLNweVpAISQp9WP3A+njutnTxofermudUJqVAQwk8afYpf8n8w=="
  securitySchemes:
    CashBoxId:
      type: apiKey
      name: x-cashbox-id
      in: header
    CashBoxAccessToken:
      type: apiKey
      name: x-cashbox-accesstoken
      in: header
