Dokumentation

Checkout-Erweiterungen

Das ShopBite Plugin bietet erweiterte Checkout-Funktionen, die speziell für Gastronomie- und Einzelhandelsbetriebe entwickelt wurden. Dieses Kapitel erklärt die Konfiguration und Nutzung dieser Funktionen.

Übersicht

Die Checkout-Erweiterungen umfassen:

  • Container-basierte Produkte: Spezielle Verarbeitung für Produktgruppen
  • Bon-Drucktypen: Unterschiedliche Druckformate für verschiedene Produkte
  • Custom Fields: Erweiterte Produktattribute für Gastronomie
  • Lieferzeitberechnung: Dynamische Berechnung basierend auf Produktattributen
  • Warenkorb-Empfehlungen: Zusatzprodukte wie Desserts im Warenkorb vorschlagen (Up-Selling)
  • Bestelltypen: Abholung, Lieferung, Vor Ort

Container-basierte Produkte

Funktionsweise

Container-basierte Produkte ermöglichen die Gruppierung von Artikeln:

  • Beispiel: Menü mit Hauptgericht, Beilage und Getränk
  • Vorteile: Einfache Bestellung komplexer Produktkombinationen
  • Verarbeitung: Spezielle Logik im Checkout-Prozess

Konfiguration

  1. Produkt erstellen:
    • Navigieren Sie zu Katalog > Produkte
    • Neues Produkt erstellen
    • Produkttyp: "Container" auswählen
  2. Container-Inhalte definieren:
    • Container-Elemente hinzufügen
    • Pflichtfelder markieren
    • Auswahloptionen konfigurieren
  3. Preisgestaltung:
    • Fester Preis: Gesamtpreis für den Container
    • Dynamischer Preis: Summe der enthaltenen Artikel
    • Rabatte: Container-spezifische Rabatte

Beispiel: Pizza-Menü

Container: Pizza-Menü
- Hauptgericht: Pizza (Pflichtfeld)
  - Optionen: Margherita, Salami, Hawaii
- Beilage: Salat oder Pommes (Pflichtfeld)
  - Optionen: Caesar Salat, Gemischter Salat, Pommes
- Getränk: Optional
  - Optionen: Cola, Fanta, Wasser, Bier

Bon-Drucktypen

Custom Fields Konfiguration

  1. Custom Fields einrichten:
    • Navigieren Sie zu Einstellungen > Custom Fields
    • ShopBite Produkt Set auswählen
  2. Bon-Drucktyp Feld:
    • Feldname: shopbite_receipt_print_type
    • Typ: Auswahlfeld
    • Optionen:
      • standard: Normaler Bon-Druck
      • kitchen: Küchenbon für Zubereitung
      • bar: Barbon für Getränke
      • no_print: Kein Bon-Druck erforderlich

Produktkonfiguration

  1. Produkt bearbeiten:
    • Navigieren Sie zu Katalog > Produkte
    • Produkt auswählen
  2. Custom Fields setzen:
    • Bon-Drucktyp auswählen
    • Speichern

Beispielkonfiguration

ProduktBon-DrucktypBeschreibung
Pizza MargheritakitchenWird in der Küche zubereitet
Cola 0,33lbarWird an der Bar ausgegeben
DessertstandardNormaler Bon-Druck
Gutscheinno_printKein physischer Bon nötig

Technische Implementierung

Der ReceiptPrintTypeProcessor verarbeitet die Bon-Drucktypen:

// src/Checkout/Cart/ReceiptPrintTypeProcessor.php

public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
{
    foreach ($toCalculate->getLineItems()->filterFlatByType(LineItem::PRODUCT_LINE_ITEM_TYPE) as $lineItem) {
        $productId = $lineItem->getReferencedId();
        if ($productId === null) {
            continue;
        }
        
        $product = $data->get(self::DATA_KEY . $productId);
        if ($product === null) {
            continue;
        }
        
        $customFields = $product->getCustomFields() ?? [];
        if (!isset($customFields[CustomFieldsInstaller::SHOPBITE_RECEIPT_PRINT_TYPE])) {
            continue;
        }
        
        $lineItem->setPayloadValue(
            CustomFieldsInstaller::SHOPBITE_RECEIPT_PRINT_TYPE,
            $customFields[CustomFieldsInstaller::SHOPBITE_RECEIPT_PRINT_TYPE]
        );
    }
}

Lieferzeitberechnung

Custom Fields für Lieferzeiten

  1. Lieferzeitfaktor Feld:
    • Feldname: shopbite_delivery_time_factor
    • Typ: Ganzzahl
    • Standardwert: 1
  2. Produktkonfiguration:
    • Faktor 1: Standard-Lieferzeit
    • Faktor 2: Doppelte Lieferzeit
    • Faktor 3: Dreifache Lieferzeit

Berechnungslogik

// Beispielberechnung in der Storefront
function calculateDeliveryTime(product) {
    const baseTime = 30; // Basis-Lieferzeit in Minuten
    const factor = product.customFields?.shopbite_delivery_time_factor || 1;
    
    return baseTime * factor; // Ergebnis in Minuten
}

// Beispiel
const pizza = { customFields: { shopbite_delivery_time_factor: 2 } };
const deliveryTime = calculateDeliveryTime(pizza); // 60 Minuten

Beispielprodukte

ProduktFaktorBerechnete Lieferzeit
Pizza260 Minuten
Salat130 Minuten
Getränk0.515 Minuten
Dessert130 Minuten

Warenkorb-Empfehlungen (Up-Selling)

Kurz vor dem Bestellabschluss zeigt die Storefront im Warenkorb Produkte an, die sich mit einem Klick hinzufügen lassen, z. B. ein Tiramisu zum Nachtisch. Welche Produkte dort erscheinen, legen Sie am Produkt fest. Die Cross-Selling-Funktion von Shopware wird dafür nicht verwendet, weil sie in ShopBite bereits die Extras eines Produkts abbildet (z. B. „Extras“, „Beilagen“).

Produkt als Empfehlung markieren

  1. Navigieren Sie zu Katalog > Produkte und öffnen Sie das Produkt
  2. Aktivieren Sie im Zusatzfeld-Set ShopBite die Checkbox Warenkorb-Empfehlung (Up-Selling)
  3. Speichern

Das Feld wird bei der Installation bzw. dem Update des Plugins angelegt. Fehlt es nach einem Update, führen Sie bin/console plugin:update ShopBitePlugin aus.

EigenschaftWert
Feldnameshopbite_cart_upsell
TypCheckbox (Boolean)
Zusatzfeld-Setshopbite_product_set

Empfohlen werden nur Produkte, die aktiv und im Verkaufskanal sichtbar sind.

Varianten

Die Storefront lädt die Empfehlungen mit Vererbung. Ist die Checkbox am Hauptprodukt gesetzt, gilt sie für alle seine Varianten. Das Hauptprodukt selbst wird nie vorgeschlagen, da es nicht direkt in den Warenkorb gelegt werden kann. Soll nur eine bestimmte Variante empfohlen werden, setzen Sie die Checkbox an dieser einzelnen Variante statt am Hauptprodukt.

Store-API-Abfrage

Es gibt keinen eigenen Endpunkt. Die Storefront filtert die Standard-Produktliste nach dem Zusatzfeld:

curl -X POST "https://Ihre-Shopware-Domain.de/store-api/product" \
  -H "sw-access-key: IhrAccessKey" \
  -H "sw-inheritance: true" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": [
      { "type": "equals", "field": "customFields.shopbite_cart_upsell", "value": true },
      { "type": "equals", "field": "childCount", "value": 0 }
    ]
  }'

Der Header sw-inheritance: true sorgt dafür, dass Varianten den Wert vom Hauptprodukt erben. Der Filter childCount = 0 schließt Hauptprodukte mit Varianten aus.

Bestelltypen

Konfiguration

  1. Bestelltypen aktivieren:
    • Navigieren Sie zu ShopBite > Checkout > Bestelltypen
    • Gewünschte Typen aktivieren
  2. Bestelltypen:
    • Abholung: Kunden holen die Bestellung selbst ab
    • Lieferung: Bestellung wird geliefert
    • Vor Ort: Bestellung für den sofortigen Verzehr

Checkout-Integration

// Bestelltypen in der Storefront
const orderTypes = [
    { id: 'pickup', name: 'Abholung', description: 'Selbst abholen' },
    { id: 'delivery', name: 'Lieferung', description: 'Zustellung' },
    { id: 'on_site', name: 'Vor Ort', description: 'Hier verzehren' }
];

// Bestelltyp auswählen
function selectOrderType(typeId) {
    // Logik zur Auswahl des Bestelltyps
    console.log(`Bestelltyp ausgewählt: ${typeId}`);
}

Custom Fields Installation

Automatische Installation

Das Plugin installiert die Custom Fields automatisch:

// src/Service/CustomFieldsInstaller.php

public function install(Context $context): void
{
    $customFieldSetId = Uuid::fromHexToBytes(self::CUSTOM_FIELDSET_ID);
    
    $customFieldSetData = [
        'id' => self::CUSTOM_FIELDSET_ID,
        'name' => self::CUSTOM_FIELDSET_NAME,
        'config' => [
            'label' => [
                'en-GB' => 'ShopBite',
                'de-DE' => 'ShopBite',
            ],
        ],
        'customFields' => [
            [
                'id' => '0198be8b24a0722cac46b07e3a9686ec',
                'name' => 'shopbite_delivery_time_factor',
                'type' => CustomFieldTypes::INT,
                'config' => [
                    'label' => [
                        'en-GB' => 'Delivery Time Factor',
                        'de-DE' => 'Lieferzeitfaktor',
                    ],
                ],
            ],
            [
                'id' => '01944f2b1875706596395b8d23966952',
                'name' => self::SHOPBITE_RECEIPT_PRINT_TYPE,
                'type' => CustomFieldTypes::SELECT,
                'config' => [
                    'label' => [
                        'en-GB' => 'Receipt Print Type',
                        'de-DE' => 'Bon-Drucktyp',
                    ],
                    'options' => [
                        ['value' => 'standard', 'label' => ['en-GB' => 'Standard', 'de-DE' => 'Standard']],
                        ['value' => 'kitchen', 'label' => ['en-GB' => 'Kitchen', 'de-DE' => 'Küche']],
                        ['value' => 'bar', 'label' => ['en-GB' => 'Bar', 'de-DE' => 'Bar']],
                        ['value' => 'no_print', 'label' => ['en-GB' => 'No Print', 'de-DE' => 'Kein Druck']],
                    ],
                ],
            ],
        ],
    ];
    
    $this->customFieldSetRepository->upsert([$customFieldSetData], $context);
}

Manuelle Installation

Falls die automatische Installation fehlschlägt:

# Custom Fields manuell installieren
bin/console shopbite:custom-fields:install

# Custom Fields prüfen
bin/console custom-field:set:list | grep shopbite

API-Integration

Checkout-API-Endpunkte

POST /store-api/checkout/cart/line-item

Beispielanfrage

curl -X POST "https://Ihre-Shopware-Domain.de/store-api/checkout/cart/line-item" \
  -H "Authorization: Bearer IhrAPIToken" \
  -H "sw-access-key: IhrAccessKey" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "019a36f224b0704fb6835914050392f4",
        "type": "product",
        "referencedId": "019a36f224b0704fb6835914050392f4",
        "quantity": 1,
        "payload": {
          "shopbite_receipt_print_type": "kitchen",
          "shopbite_delivery_time_factor": 2
        }
      }
    ]
  }'

Beispielantwort

{
  "data": {
    "lineItems": [
      {
        "id": "019a36f224b0704fb6835914050392f4",
        "type": "product",
        "referencedId": "019a36f224b0704fb6835914050392f4",
        "quantity": 1,
        "payload": {
          "shopbite_receipt_print_type": "kitchen",
          "shopbite_delivery_time_factor": 2
        }
      }
    ],
    "deliveryTime": 60
  }
}

Best Practices

1. Konsistente Produktkonfiguration

  • Verwenden Sie einheitliche Custom Fields für alle Produkte
  • Dokumentieren Sie die Bedeutung der Felder
  • Schulen Sie Ihr Team in der korrekten Nutzung

2. Performance-Optimierung

-- Indizes für Custom Fields
CREATE INDEX `idx_custom_fields` ON `product` (`custom_fields`);

-- Optimierung für häufige Abfragen
CREATE INDEX `idx_receipt_print_type` ON `product` 
  ((CAST(custom_fields->>'$.shopbite_receipt_print_type' AS CHAR(50))));

3. Validierung

// Validierung im Checkout-Prozess
public function validateCheckout(Cart $cart): array
{
    $errors = [];
    
    foreach ($cart->getLineItems() as $lineItem) {
        $payload = $lineItem->getPayload();
        
        if (!isset($payload['shopbite_receipt_print_type'])) {
            $errors[] = sprintf(
                'Produkt %s hat keinen Bon-Drucktyp',
                $lineItem->getLabel()
            );
        }
        
        if (!isset($payload['shopbite_delivery_time_factor'])) {
            $errors[] = sprintf(
                'Produkt %s hat keinen Lieferzeitfaktor',
                $lineItem->getLabel()
            );
        }
    }
    
    return $errors;
}

4. Caching-Strategie

# In config/packages/cache.yaml
framework:
    cache:
        pools:
            shopbite.checkout:
                adapter: cache.adapter.redis
                default_lifetime: 300  # 5 Minuten Cache

Fehlerbehandlung

Häufige Probleme

Problem: Custom Fields werden nicht angezeigt

Symptome:

  • Custom Fields fehlen in der Administration
  • Felder werden nicht gespeichert

Lösungen:

# Custom Fields neu installieren
bin/console shopbite:custom-fields:install --force

# Cache leeren
bin/console cache:clear

# Datenbank prüfen
mysql -u shopware -p shopware -e "SELECT * FROM custom_field_set WHERE name = 'shopbite_product_set';"

Problem: Bon-Drucktyp wird ignoriert

Symptome:

  • Alle Bons werden mit Standardtyp gedruckt
  • Custom Field-Werte werden nicht übernommen

Lösungen:

# Checkout-Prozessor prüfen
bin/console debug:container --tag=shopware.checkout.cart.processor

# Plugin-Cache leeren
bin/console plugin:refresh ShopBite

# Custom Fields prüfen
bin/console custom-field:set:list

Problem: Lieferzeitberechnung falsch

Symptome:

  • Falsche Lieferzeiten
  • Berechnung stimmt nicht mit Erwartungen überein

Lösungen:

# Custom Field-Werte prüfen
mysql -u shopware -p shopware -e "
  SELECT id, custom_fields FROM product 
  WHERE custom_fields LIKE '%shopbite_delivery_time_factor%' LIMIT 5;
"

# Berechnungslogik prüfen
bin/console config:get ShopBitePlugin.config.baseDeliveryTime

# Debug-Modus aktivieren
bin/console config:set ShopBitePlugin.config.debug true

Nächste Schritte