Bon-Vorlagen Dokumentation

Komplette Referenz für JSON-basierte Kassenbons

Inhaltsverzeichnis

Quick Start

Tipp: Starten Sie mit einem Basis-Template und passen Sie es schrittweise an Ihre Bedürfnisse an.

Ein Bon-Template besteht aus JSON-Code, der in 4 Hauptbereiche unterteilt ist:

{
  "version": "1.0",
  "name": "Mein Bon-Template",
  "paperWidth": "80mm",
  "sections": [
    { "type": "header", "elements": [...] },
    { "type": "items", "elements": [...] },
    { "type": "totals", "elements": [...] },
    { "type": "footer", "elements": [...] }
  ]
}

Template-Struktur

Template-Eigenschaften

  • version: Template-Version (aktuell "1.0")
  • name: Name des Templates
  • description: (Optional) Beschreibung
  • paperWidth: Papierbreite ("58mm", "80mm" oder "210mm")
  • sections: Array von Sections

Section-Typen

Type Beschreibung Loop
header Kopfzeile (Firma, Logo, Adresse) Nein
items Artikelliste (wird für jeden Artikel wiederholt) Ja
totals Summen (Netto, MwSt, Brutto) Nein
tax_breakdown MwSt-Aufschlüsselung (wird für jeden Steuersatz wiederholt) Ja
footer Fußzeile (Kassier, Terminal-ID, TSE-Daten) Nein

Verfügbare Variablen

Variablen werden in geschweiften Klammern geschrieben: {VARIABLE_NAME}

Firmen-Informationen

Variable Beispiel-Wert
{COMPANY_NAME}BISpicy Restaurant GmbH
{COMPANY_ADDRESS}Hauptstraße 123
{COMPANY_POSTAL_CODE}12345
{COMPANY_CITY}Berlin
{COMPANY_COUNTRY}Deutschland
{COMPANY_FULL_ADDRESS}Hauptstraße 123
12345 Berlin
{COMPANY_PHONE}+49 30 12345678
{COMPANY_EMAIL}info@bispicy.de
{COMPANY_WEBSITE}www.bispicy.de
{COMPANY_TAX_ID}12/345/67890
{COMPANY_VAT_ID}DE123456789
{COMPANY_REGISTER}HRB 12345

Beleg-Informationen

Variable Beispiel-Wert
{RECEIPT_NUMBER}2025-001234
{RECEIPT_DATE}06.11.2025
{RECEIPT_TIME}14:35:22
{RECEIPT_DATETIME}06.11.2025 14:35:22
{RECEIPT_TYPE}Verkaufsbeleg
{RECEIPT_COPY}KOPIE (falls Kopie)

Kunden-Informationen

Variable Beispiel-Wert
{CUSTOMER_NAME}Max Mustermann
{CUSTOMER_PHONE}+49 170 1234567
{CUSTOMER_EMAIL}max@example.com
{CUSTOMER_NUMBER}K-12345
{CUSTOMER_ADDRESS}Musterstraße 1, 12345 Stadt

Zahlungs-Informationen

Variable Beispiel-Wert
{PAYMENT_METHOD}Barzahlung / SumUp Terminal
{PAYMENT_AMOUNT}50,00 €
{PAYMENT_CHANGE}3,50 €
{PAYMENT_CARD_TYPE}MASTERCARD / VISA
{PAYMENT_CARD_NUMBER}**** **** **** 1234
{PAYMENT_AUTH_CODE}ABC123456

Summen & Totals

Variable Beispiel-Wert
{TOTAL_NET}38,66 €
{TOTAL_TAX}7,84 €
{TOTAL_GROSS}46,50 €
{TOTAL_DISCOUNT}3,50 €

TSE-Informationen

Variable Beschreibung
{TSE_TRANSACTION_NUMBER}TSE-Transaktionsnummer
{TSE_SIGNATURE}Kryptographische TSE-Signatur
{TSE_SERIAL_NUMBER}TSE-Seriennummer
{TSE_SIGNATURE_COUNTER}TSE-Signatur-Zähler
{TSE_TIMESTAMP}TSE-Zeitstempel
{TSE_PUBLIC_KEY}TSE-Public-Key
{TSE_PROCESS_TYPE}TSE-Prozess-Typ
{TSE_QR_DATA}QR-Code Daten (komplett)

Artikel-Variablen (für "items" Section)

Wichtig: Diese Variablen funktionieren nur innerhalb einer Section mit type: "items"!
Variable Beispiel-Wert
{ITEM_NAME}Aromamassage 60Min
{ITEM_QUANTITY}2
{ITEM_UNIT}Stk
{ITEM_UNIT_PRICE}15,00 €
{ITEM_TOTAL_PRICE}30,00 €
{ITEM_TAX_RATE}19,0%
{ITEM_TAX_AMOUNT}4,79 €
{ITEM_DISCOUNT}2,00 €
{ITEM_NOTES}Extra scharf

Steuer-Breakdown (für "tax_breakdown" Section)

Wichtig: Diese Variablen funktionieren nur innerhalb einer Section mit type: "tax_breakdown"!
Variable Beispiel-Wert
{TAX_RATE}19,0%
{TAX_NET_AMOUNT}25,00 €
{TAX_AMOUNT}4,75 €
{TAX_GROSS_AMOUNT}29,75 €

Footer-Informationen

Variable Beispiel-Wert
{FOOTER_CASHIER}Anna Schmidt
{FOOTER_TERMINAL_ID}POS-001
{FOOTER_CUSTOM_TEXT}Vielen Dank!

Gutscheine

Variable Beispiel-Wert
{VOUCHER_CODES}GIFT-ABC123, GIFT-XYZ789

Layout & Formatierung

Element-Eigenschaften

Eigenschaft Werte Beschreibung
align "left", "center", "right" Text-Ausrichtung
bold true, false Fettschrift
underline true, false Unterstrichen
fontSize "small", "normal", "large", "xlarge" Schriftgröße

Beispiele

// Zentrierter Firmenname in großer Schrift
{
  "type": "text",
  "content": "{COMPANY_NAME}",
  "align": "center",
  "fontSize": "large",
  "bold": true
}

// Rechtsbündige Summe
{
  "type": "text",
  "content": "Gesamt: {TOTAL_GROSS}",
  "align": "right",
  "bold": true
}

// Kleine Schrift für Fußzeile
{
  "type": "text",
  "content": "Terminal: {FOOTER_TERMINAL_ID}",
  "align": "center",
  "fontSize": "small"
}

Element-Typen

1. Text-Element

Das wichtigste Element für Text-Ausgaben.

{
  "type": "text",
  "content": "{COMPANY_NAME}",
  "align": "center",
  "bold": true,
  "fontSize": "large"
}

2. Trennlinie

Erzeugt eine horizontale Linie.

{
  "type": "line",
  "lineChar": "-"
}

// Alternative Zeichen: "=", "*", "─"

3. Leerzeile (Spacer)

Fügt Leerzeilen ein.

{
  "type": "spacer",
  "lines": 2
}

// lines: Anzahl der Leerzeilen (1-5)

4. QR-Code

Generiert einen QR-Code (ideal für TSE-Daten).

{
  "type": "qr_code",
  "content": "{TSE_QR_DATA}",
  "qrSize": 200
}

// qrSize: Größe in Pixeln (100-300)

5. Barcode

Generiert einen Barcode.

{
  "type": "barcode",
  "content": "{RECEIPT_NUMBER}",
  "barcodeType": "CODE128"
}

// Typen: "EAN13", "CODE128", "CODE39"

Conditional Rendering

Elemente können basierend auf Variablen-Verfügbarkeit ein-/ausgeblendet werden:

// Zeige nur, wenn Kunde vorhanden
{
  "type": "text",
  "content": "Kunde: {CUSTOMER_NAME}",
  "condition": "CUSTOMER_NAME"
}

// Zeige nur, wenn KEINE TSE-Daten (Negation mit !)
{
  "type": "text",
  "content": "Nicht-TSE-Beleg",
  "condition": "!TSE_SIGNATURE"
}

// Spezielle Conditionals für Items:
{
  "type": "text",
  "content": "Rabatt: {ITEM_DISCOUNT}",
  "condition": "HAS_DISCOUNT"
}

{
  "type": "text",
  "content": "Notiz: {ITEM_NOTES}",
  "condition": "HAS_NOTES"
}
Automatisches Ausblenden: Elemente mit leerem Content werden automatisch ausgeblendet (außer hideIfEmpty: false).

Komplette Beispiele

Minimales Template

{
  "version": "1.0",
  "name": "Minimal Bon",
  "paperWidth": "80mm",
  "sections": [
    {
      "type": "header",
      "elements": [
        {
          "type": "text",
          "content": "{COMPANY_NAME}",
          "align": "center",
          "bold": true,
          "fontSize": "large"
        },
        {
          "type": "line"
        }
      ]
    },
    {
      "type": "items",
      "elements": [
        {
          "type": "text",
          "content": "{ITEM_QUANTITY}x {ITEM_NAME}",
          "align": "left"
        },
        {
          "type": "text",
          "content": "{ITEM_TOTAL_PRICE}",
          "align": "right"
        }
      ]
    },
    {
      "type": "totals",
      "elements": [
        {
          "type": "line"
        },
        {
          "type": "text",
          "content": "GESAMT: {TOTAL_GROSS}",
          "align": "right",
          "bold": true,
          "fontSize": "large"
        }
      ]
    },
    {
      "type": "footer",
      "elements": [
        {
          "type": "spacer",
          "lines": 2
        },
        {
          "type": "text",
          "content": "Vielen Dank!",
          "align": "center"
        }
      ]
    }
  ]
}

Vollständiges Template mit TSE

{
  "version": "1.0",
  "name": "Standard Bon mit TSE",
  "paperWidth": "80mm",
  "sections": [
    {
      "type": "header",
      "elements": [
        {
          "type": "text",
          "content": "{COMPANY_NAME}",
          "align": "center",
          "bold": true,
          "fontSize": "xlarge"
        },
        {
          "type": "text",
          "content": "{COMPANY_FULL_ADDRESS}",
          "align": "center",
          "fontSize": "small"
        },
        {
          "type": "text",
          "content": "Tel: {COMPANY_PHONE}",
          "align": "center",
          "fontSize": "small"
        },
        {
          "type": "line",
          "lineChar": "="
        },
        {
          "type": "text",
          "content": "Beleg: {RECEIPT_NUMBER}",
          "align": "left"
        },
        {
          "type": "text",
          "content": "{RECEIPT_DATETIME}",
          "align": "left"
        },
        {
          "type": "text",
          "content": "Kunde: {CUSTOMER_NAME}",
          "align": "left",
          "condition": "CUSTOMER_NAME"
        },
        {
          "type": "line"
        }
      ]
    },
    {
      "type": "items",
      "elements": [
        {
          "type": "text",
          "content": "{ITEM_QUANTITY}x {ITEM_NAME}",
          "align": "left"
        },
        {
          "type": "text",
          "content": "  à {ITEM_UNIT_PRICE} ({ITEM_TAX_RATE})",
          "align": "left",
          "fontSize": "small"
        },
        {
          "type": "text",
          "content": "{ITEM_TOTAL_PRICE}",
          "align": "right",
          "bold": true
        },
        {
          "type": "text",
          "content": "  Notiz: {ITEM_NOTES}",
          "align": "left",
          "fontSize": "small",
          "condition": "HAS_NOTES"
        },
        {
          "type": "spacer",
          "lines": 1
        }
      ]
    },
    {
      "type": "totals",
      "elements": [
        {
          "type": "line",
          "lineChar": "="
        },
        {
          "type": "text",
          "content": "Zwischensumme:  {TOTAL_NET}",
          "align": "right"
        },
        {
          "type": "text",
          "content": "MwSt.:          {TOTAL_TAX}",
          "align": "right"
        },
        {
          "type": "text",
          "content": "GESAMT:         {TOTAL_GROSS}",
          "align": "right",
          "bold": true,
          "fontSize": "xlarge"
        },
        {
          "type": "line",
          "lineChar": "="
        },
        {
          "type": "text",
          "content": "Zahlungsart: {PAYMENT_METHOD}",
          "align": "left"
        },
        {
          "type": "text",
          "content": "Gegeben:    {PAYMENT_AMOUNT}",
          "align": "left"
        },
        {
          "type": "text",
          "content": "Rückgeld:   {PAYMENT_CHANGE}",
          "align": "left"
        }
      ]
    },
    {
      "type": "tax_breakdown",
      "elements": [
        {
          "type": "text",
          "content": "MwSt {TAX_RATE}: Netto {TAX_NET_AMOUNT} / Steuer {TAX_AMOUNT}",
          "align": "left",
          "fontSize": "small"
        }
      ]
    },
    {
      "type": "footer",
      "elements": [
        {
          "type": "spacer",
          "lines": 1
        },
        {
          "type": "line"
        },
        {
          "type": "text",
          "content": "TSE-Transaktion: {TSE_TRANSACTION_NUMBER}",
          "align": "left",
          "fontSize": "small",
          "condition": "TSE_TRANSACTION_NUMBER"
        },
        {
          "type": "text",
          "content": "TSE-Seriennr.: {TSE_SERIAL_NUMBER}",
          "align": "left",
          "fontSize": "small",
          "condition": "TSE_SERIAL_NUMBER"
        },
        {
          "type": "text",
          "content": "Signatur-Zähler: {TSE_SIGNATURE_COUNTER}",
          "align": "left",
          "fontSize": "small",
          "condition": "TSE_SIGNATURE_COUNTER"
        },
        {
          "type": "spacer",
          "lines": 1
        },
        {
          "type": "qr_code",
          "content": "{TSE_QR_DATA}",
          "qrSize": 200,
          "condition": "TSE_QR_DATA"
        },
        {
          "type": "spacer",
          "lines": 1
        },
        {
          "type": "text",
          "content": "{FOOTER_CUSTOM_TEXT}",
          "align": "center",
          "fontSize": "small"
        },
        {
          "type": "text",
          "content": "Kassier: {FOOTER_CASHIER}",
          "align": "center",
          "fontSize": "small"
        },
        {
          "type": "text",
          "content": "Terminal: {FOOTER_TERMINAL_ID}",
          "align": "center",
          "fontSize": "small"
        },
        {
          "type": "spacer",
          "lines": 2
        }
      ]
    }
  ]
}

Tipps & Best Practices

Empfohlene Vorgehensweise:
  • Testen Sie Templates mit unterschiedlichen Verkaufsdaten (mit/ohne Kunde, mit/ohne TSE)
  • Verwenden Sie condition für optionale Felder wie Kunde oder TSE-Daten
  • Nutzen Sie fontSize für wichtige Informationen wie die Gesamtsumme
  • Fügen Sie Leerzeilen (spacer) für bessere Lesbarkeit ein
  • Testen Sie die Papierbreite (58mm vs 80mm) auf Ihrem Drucker
Häufige Fehler vermeiden:
  • Artikel-Variablen ({ITEM_...}) nur in "type": "items" Sections verwenden!
  • Steuer-Variablen ({TAX_...}) nur in "type": "tax_breakdown" Sections verwenden!
  • JSON-Syntax prüfen: Kommas, Anführungszeichen, geschweifte Klammern müssen korrekt sein
  • Variablen-Namen exakt wie dokumentiert schreiben (Groß-/Kleinschreibung beachten)
Pro-Tipps:
  • Speichern Sie verschiedene Templates für verschiedene Anlässe (Standard, Gastronomie, Dienstleistung)
  • Nutzen Sie die Drucker-Zuordnung in der Vorlagen-Bibliothek für Multi-Printer-Setups
  • Kombinieren Sie bold und fontSize: "xlarge" für die Gesamtsumme
  • Verwenden Sie QR-Codes nur für TSE-Daten oder URLs, nicht für normale Texte
Zurück zur App