Markdown (Eisvogel)

itktwomanhandling-anwenderdokumentation.md

---
title: "ItkTwoManHandling"
subtitle: "Anwenderdokumentation"
author: ["André Fischer"]
date: "30-03-2026"
lang: de
titlepage: true
titlepage-color: "1E3A5F"
titlepage-text-color: "FFFFFF"
titlepage-rule-color: "4A90D9"
titlepage-rule-height: 4
toc: true
toc-own-page: true
numbersections: true
header-left: "ItkTwoManHandling"
header-right: "Anwenderdokumentation"
footer-left: "ITK Computer GmbH"
---

# Was macht dieses Plugin?

Du verkaufst **sperrige Geräte** und willst im Checkout klar und buchbar machen: **Zwei-Personen-Lieferung** und optional **Mitnahme des Altgeräts** – ohne dass der Kunde verwirrende Zusatzprodukte im Warenkorb wühlen muss.

Bei großen und schweren Geräten – denk an Waschmaschinen, Kühlschränke, große Fernseher – reicht eine normale Paketlieferung oft nicht aus. Für solche Produkte gibt es Speditionsdienstleistungen, bei denen ein Zweier-Team die Lieferung bis ins Wunschzimmer trägt, Verpackungen mitnimmt und im besten Fall auch noch das alte Gerät zur Entsorgung abholt. Genau das bildet dieses Plugin im Shop ab.

Das ItkTwoManHandling-Plugin ermöglicht es, ausgewählten Produkten zwei optionale Zusatzleistungen hinzuzufügen:

- **2-Mann-Handling**: Die Lieferung wird von einem Zweier-Team durchgeführt, das das Gerät ins gewünschte Zimmer trägt, aufstellt und die Verpackung entsorgt. Im Gegensatz zur normalen Haustür-Lieferung.
- **Altgeräte-Rücknahme**: Das Lieferteam nimmt beim Ausliefern des neuen Geräts das alte Altgerät mit zur Entsorgung.

Beide Optionen erscheinen im Shop als Checkboxen, die der Kunde individuell auswählen kann. Die Kosten für die gewählten Dienstleistungen landen dabei nicht als normaler Produktpreis im Warenkorb, sondern als Aufschlag auf die Versandkosten – das hat buchhalterische Gründe und vereinfacht die Darstellung für den Kunden.

---

## Diagramm: Kundensicht

```mermaid
flowchart LR
  P[Produktseite] --> X[Checkboxen waehlen]
  X --> W[In den Warenkorb]
  W --> V[Versandkosten mit Aufschlag]
```

# Plugin-Konfiguration (technisch)

Pfad im Admin: **Erweiterungen → Meine Erweiterungen → ITK 2-Mann-Handling** → Konfiguration (ggf. **Sales Channel** oben wählen).

| Feld im Admin | Interner Key (SystemConfig) |
|---------------|----------------------------|
| 2-Mann-Handling Produkt | `ItkTwoManHandling.config.twoManHandlingProductId` |
| Altgeräte-Rücknahme Produkt | `ItkTwoManHandling.config.oldDeviceReturnProductId` |

Beides sind **Produktauswahlfelder** (**sw-entity-single-select** in der `config.xml`). Gespeichert werden die **IDs** der Platzhalter-Produkte; Preise und Steuern kommen aus diesen Produkten, sobald der Warenkorb die Zusatzpositionen berechnet.

---

# Initiale Einrichtung: Was zuerst zu tun ist

Bevor das Plugin im Shop sichtbar funktioniert, sind zwei Dinge nötig: Die richtigen Produkte als Platzhalter für die Dienstleistungen anlegen, und diese dann im Plugin verknüpfen.

## Die Service-Produkte anlegen

Das Plugin braucht zwei normale Shopware-Produkte, die als technische Platzhalter für die Dienstleistungen dienen. Diese Produkte haben einen Preis – und genau dieser Preis wird als Aufpreis im Warenkorb angezeigt, wenn ein Kunde eine der Optionen auswählt.

Lege also im Produktbereich zwei neue Produkte an:

- Ein Produkt für das 2-Mann-Handling, z. B. mit dem Namen "2-Mann-Handling-Service" und dem gewünschten Preis (z. B. 49,99 €).
- Ein Produkt für die Altgeräte-Rücknahme, z. B. "Altgeräte-Rücknahme" mit dem entsprechenden Preis.

Diese Produkte sollten **nicht** als reguläre Artikel im Shop suchbar oder kaufbar sein. Dafür haben wir bereits in den Zusatzfeldern für Produkte eine "Produkt verstecken" Funktion, welches man an diesen Produkten setzen kannst.

## Das Plugin konfigurieren

Gehe zu **Erweiterungen → Meine Erweiterungen**, öffne **ITK 2-Mann-Handling** und dort **Konfiguration** – wähle in den beiden Feldern die soeben angelegten Produkte aus:

- `2-Mann-Handling-Produkt`: Wähle hier das Produkt aus, das du für den 2-Mann-Handling-Service angelegt hast.
- **Altgeräte-Rücknahme-Produkt**: Entsprechend das Produkt für die Rücknahme.

Diese Konfiguration kann pro Sales Channel unterschiedlich sein, falls verschiedene Kanäle unterschiedliche Preise oder Service-Produkte haben sollen.

---

# Produkte für die Zusatzoptionen freischalten

Nicht alle Produkte im Shop sollen die 2-Mann-Handling-Optionen anzeigen – das wäre bei einem USB-Kabel wenig sinnvoll. Das Plugin aktiviert die Optionen nur für Produkte, bei denen explizit ein Custom Field gesetzt ist.

Gehe zum jeweiligen Produkt in der Produktverwaltung. Unter dem Reiter **Spezifikationen** oder **Custom Fields**findest du nach der Plugin-Aktivierung ein neues Feld:

`itk_supports_two_man_handling`: Diese Checkbox musst du aktivieren, damit das Produkt die Auswahl-Optionen im Storefront anzeigt. Ohne dieses Flag passiert am Produkt gar nichts – der Kunde sieht keine zusätzlichen Optionen.

Ein typischer Workflow für ein neues Gerät mit 2-Mann-Handling: Produkt aufrufen, in den Custom Fields `itk_supports_two_man_handling` aktivieren, speichern. Fertig.

---

# Was der Kunde im Shop sieht

Wenn ein Kunde ein Produkt aufruft, das `itk_supports_two_man_handling` aktiviert hat, erscheinen auf der Produktseite und/oder im Warenkorb-Prozess zusätzliche Checkboxen. Der Kunde kann dort auswählen, ob er das 2-Mann-Handling und optional die Altgeräte-Rücknahme dazu buchen möchte.

Sobald eine Option ausgewählt ist und das Produkt in den Warenkorb gelegt wird, erscheinen die Zusatzleistungen als separate Positionen im Warenkorb unter dem Hauptprodukt. Der Gesamtpreis des Produkts selbst ändert sich nicht – die Kosten der Zusatzleistungen erscheinen als Versandaufpreis, was in einer eigenen Zeile in der Bestellzusammenfassung sichtbar ist.

Ein konkretes Beispiel: Der Kunde kauft eine Waschmaschine für 599 € und wählt das 2-Mann-Handling (49 €) und die Altgeräte-Rücknahme (29 €). Im Warenkorb sieht er dann:

- Waschmaschine: 599 €
- 2-Mann-Handling: + 49 € (als Versandanteil)
- Altgeräte-Rücknahme: + 29 € (als Versandanteil)
- Gesamtbetrag: 677 € + normaler Versand

Wenn der Kunde ein Zusatz-Item aus dem Warenkorb entfernt, wird es nicht mehr beim Checkout berechnet. Wenn der Kunde das Hauptprodukt aus dem Warenkorb entfernt, werden die Zusatz-Items automatisch mitentfernt.

**Wichtig**: Ein Kunde kann keine Altgeräte Rücknahme beordern, ohne dass er Zwei-Mann-Handling bucht. Das war zum Zeitpunkt der Entwicklung vorgabe.

---

# Preise aktualisieren

Die Preise der Zusatzleistungen kommen direkt aus den konfigurierten Service-Produkten. Wenn sich die Preise ändern sollen – z. B. weil der Logistikdienstleister seine Preise erhöht hat – gehe einfach zu den jeweiligen Service-Produkten und ändere dort den Preis. Die Änderung ist sofort im Shop wirksam (ggf. Shopware-Cache leeren).

---

# Häufige Probleme und Lösungen

## Die Checkboxen erscheinen nicht am Produkt

Das häufigste Problem ist, dass das Custom Field `itk_supports_two_man_handling` am Produkt nicht aktiviert ist. Gehe zum Produkt und prüfe unter den Custom Fields, ob der Haken gesetzt ist. Falls du die Custom Fields gar nicht siehst, stelle sicher, dass das Plugin installiert und aktiviert ist und das Theme neu kompiliert wurde.

## Die Service-Produkte sind im Shop sichtbar und kaufbar

Das Custom Field `itk_two_man_handling_hide_product` an den Service-Produkten wurde vergessen. Öffne beide Service-Produkte und aktiviere dieses Feld.

## Der Preis der Zusatzleistung stimmt nicht

Der Preis kommt aus dem konfigurierten Service-Produkt. Prüfe den Preis des Produkts in der Produktverwaltung. Wenn der Preis pro Sales Channel unterschiedlich sein soll, müssen entsprechende Preisregeln am Service-Produkt konfiguriert sein.

## Die Zusatzleistungen erscheinen nach dem Hinzufügen zum Warenkorb nicht

Das kann an einem JavaScript-Fehler liegen, der das Plugin-JS verhindert. Öffne die Browser-Konsole (F12) und schau, ob dort Fehler auftauchen. Außerdem prüfen, ob der Shopware-Theme-Cache nach der Plugin-Installation geleert wurde.

## Eine Zusatzleistung taucht in der Bestellung nicht auf

Schau in der Bestellung nach **Payload / technischen Daten** der Produkt-Position: die Auswahl steckt u. a. unter **itkTwoManHandlingOptions** (und ggf. weiteren Payload-Feldern). Falls Zusatzpositionen fehlen, wurden `customFields[itk_two_man_handling]` / `customFields[itk_old_device_return]` beim **POST des Produktdetail-Formulars** nicht mitgeschickt – im Netzwerk-Tab des Browsers prüfen (das Plugin-JS fügt Hidden-Felder ein und sendet das Formular per **`submit()`**).

---

# Logging

Das Plugin schreibt strukturiert nach `var/log/itk_two_man_handling.log`. Zusätzlich gibt es im PHP-Code **`error_log()`**-Aufrufe (Installation, Cart, Subscriber) – die landen im `PHP-/Webserver-Log`, nicht zwingend in derselben Datei. Wenn du mit dem Support telefonierst, schick am besten **beide** Logs mit.

---

# FAQ

**Warum werden Custom Fields beim Install nicht angelegt?**  
Dann ist meist die Installation fehlgeschlagen oder das Set `itk_two_man_handling` existierte schon. Einmal im Admin unter **Einstellungen → System → Custom Fields** nach dem Set suchen.

**Kann ich nur Altgerät ohne 2-Mann anbieten?**  
Mit dem **mitgelieferten Storefront-JS** nicht: die Altgerät-Checkbox ist nur aktiv, wenn `2-Mann-Handling` angehakt ist (sonst deaktiviert und geleert). Nur Altgerät ohne 2-Mann ginge nur mit **eigenem Theme/JS** oder anderer Request-Erzeugung.

**Ist das an DHL gebunden?**  
Nein, technisch sind es **beliebige** Service-Produkte mit Preis – die Ausführung im Versand ist eure organisatorische Vereinbarung mit dem Dienstleister.