# configento.app – Full documentation

> Complete user documentation of configento.app, the cloud SaaS product configurator for Magento, Shopware, Shopify, PrestaShop and any website (HTML5 snippet). Short overview, pricing and key URLs: https://configento.app/llms.txt

---

# Login und Account-Navigation

Source: https://configento.app/docs/login-und-account-navigation
Section: Erste Schritte

Alles rund um dein Konto – Dienste, Zahlungen, Team und Shop-Verbindungen – erledigst du im **Service-Portal** unter [service.configento.app](https://service.configento.app). Von dort öffnest du auch den Admin, in dem du deine Konfiguratoren baust. Dieser Artikel zeigt, wie du ein Konto anlegst, dich anmeldest und dich im Portal zurechtfindest.

## Konto anlegen

Ein neues Konto legst du über den Testzugang auf [configento.app](https://configento.app/?subscribe=true) an. Auch auf der Anmeldeseite des Portals führt der Link **Jetzt Testzugang anlegen!** dorthin.

1. Fülle das Formular aus: Firma, deine Rolle im Unternehmen, Branche, Anrede, Vor- und Nachname, E-Mail, Telefon und ein **Passwort** (8 bis 32 Zeichen). Das Passwort legst du also schon hier fest.
2. Du bekommst eine E-Mail mit einem Bestätigungslink.
3. Ein Klick auf den Link bestätigt deine E-Mail-Adresse, richtet deinen Testzugang ein und meldet dich direkt im Portal an. Oben erscheint der Hinweis „Dein Testzugang ist nun vollständig eingerichtet.“

Der Testzugang läuft **14 Tage** im Tarif **Professional**. Was danach passiert, steht unter [Service-Portal — Überblick](/docs/service-portal-uebersicht#testzugang).

Wurdest du von einem Kollegen eingeladen, legst du dein Konto stattdessen über den Link in der Einladungs-E-Mail an – siehe [Team verwalten](/docs/team-verwalten#einladung-annehmen).

## Anmelden

1. Öffne [service.configento.app](https://service.configento.app).
2. Gib **E-Mail** und **Passwort** ein.
3. Optional: Hake **Login im Browser speichern** an. Dann bleibst du in diesem Browser angemeldet, bis du dich abmeldest.
4. Klicke auf **Anmelden**.

Nach fünf falschen Versuchen sperrt das Portal die Anmeldung für diese E-Mail-Adresse kurz und zeigt an, wann du es erneut versuchen kannst.

## Passwort vergessen

1. Klicke auf der Anmeldeseite auf **Passwort vergessen?**.
2. Gib deine E-Mail-Adresse ein und klicke auf **Link per E-Mail erhalten**.
3. Über den Link in der E-Mail legst du ein neues Passwort fest. Der Link ist **60 Minuten** gültig.

Das Passwort änderst du später jederzeit unter **Profil → Passwort ändern**.

## Die Navigation

Welche Einträge du oben in der Navigation siehst, hängt von deiner **Rolle** beim jeweiligen Kunden ab (siehe [Team verwalten](/docs/team-verwalten#rollen-und-rechte)):

| Eintrag | Inhalt | Sichtbar für |
|---|---|---|
| **Dienste** | Deine Dienste, Admin öffnen, Dienst umstellen oder kündigen | alle Rollen |
| **Verbindungen** | Verbundene Shop-Plugins | Inhaber, Admin, Bearbeiter, Nur-Lesen |
| **Abrechnung** → **Zahlungsarten** | Kreditkarte, SEPA-Lastschrift, PayPal | Inhaber, Admin, Buchhaltung |
| **Abrechnung** → **KI-Tokens** | Token-Bestand und Nachkauf | Inhaber, Admin, Bearbeiter, Buchhaltung – sofern KI-Tokens für dein Konto freigeschaltet sind |
| **Abrechnung** → **Rechnungen** | Rechnungsanschrift und Rechnungen | Inhaber, Admin, Buchhaltung, Nur-Lesen |
| **Team** | Mitglieder einladen und Rollen vergeben | Inhaber, Admin |

Rechts daneben findest du:

- die **Sprachauswahl** **DE | EN | FR | ES** – sie stellt die Sprache des Portals um,
- bei mehreren Kunden die **Kundenauswahl** (siehe unten),
- ein Menü mit deinem Namen: **Profil** und **Abmelden**.

## Mehrere Kunden

Bist du Mitglied bei mehreren Kunden – etwa weil du als Agentur für mehrere Firmen arbeitest –, erscheint oben rechts ein Feld **Kunde:** mit dem Namen der aktuell gewählten Firma. Darüber wählst du unter **Kunden wechseln** einen anderen Kunden; unter jedem Namen steht seine Kundennummer.

Alles im Portal – Dienste, Rechnungen, Team – bezieht sich immer auf den gewählten Kunden. Deine Rolle kann je Kunde eine andere sein.

Hast du gar keinen Kunden mehr (zum Beispiel, weil du aus dem Team entfernt wurdest), zeigt das Portal **Kein Kundenzugriff**. Bitte dann den Inhaber, dich erneut einzuladen.

## Den Admin öffnen

Deine Konfiguratoren baust du im Admin. Du öffnest ihn unter **Dienste** beim jeweiligen Dienst mit **Verwalten**. Der Admin öffnet sich direkt über dem Portal; du musst dich nicht erneut anmelden.

- Bei älteren Verträgen öffnet **Verwalten** noch den bisherigen Admin. Ist für dein Konto der neue Admin freigeschaltet, steht darunter zusätzlich **Manage V3** mit dem Kennzeichen **BETA**.
- Den Knopf siehst du nur bei aktiven Diensten und nur mit den Rollen Inhaber, Admin oder Bearbeiter.

Wie es im Admin weitergeht, zeigt [Erste Komponente anlegen](/docs/erste-komponente-anlegen).

## Profil

Unter **Profil** (Menü mit deinem Namen) findest du drei Bereiche:

| Bereich | Inhalt |
|---|---|
| **Dein Profil** | Vorname, Nachname, E-Mail, Telefon, deine Rolle im Unternehmen und **Deine Sprache** |
| **Passwort ändern** | Aktuelles Passwort, neues Passwort und Bestätigung |
| **Zugang löschen** | Löscht deinen Benutzerzugang nach Eingabe deines Passworts endgültig |

**Zugang löschen** entfernt deinen Benutzer. Deine Dienste kündigst du damit nicht – das geht unter **Dienste** mit **Dienst kündigen**.

## Nachrichten im Portal

Wichtige Hinweise – etwa zu einer neuen Rechnung, einer fehlgeschlagenen Zahlung oder einem gekündigten Dienst – zeigt das Portal oben auf jeder Seite an. Manche davon bleiben stehen, bis du sie mit **Nachricht gelesen** bestätigst.

## Fehlersuche

1. **Die Anmeldung schlägt fehl, obwohl das Passwort stimmt** – setze das Passwort über **Passwort vergessen?** neu. Das hilft auch bei sehr alten Zugängen.
2. **Ich habe keine Bestätigungs-E-Mail bekommen** – sieh im Spam-Ordner nach. Ohne bestätigte E-Mail-Adresse ist dein Testzugang noch nicht eingerichtet.
3. **Ein Menüpunkt fehlt** – deine Rolle beim gewählten Kunden erlaubt ihn nicht. Prüfe oben rechts, ob der richtige Kunde gewählt ist, und frag sonst den Inhaber.
4. **Der Knopf „Verwalten“ fehlt** – der Dienst ist nicht aktiv (z. B. **temporär deaktiviert** wegen fehlender Zahlungsdaten) oder deine Rolle ist Buchhaltung oder Nur-Lesen.

## Nächste Schritte

- [Service-Portal — Überblick](/docs/service-portal-uebersicht)
- [Team verwalten](/docs/team-verwalten)
- [Erste Komponente anlegen](/docs/erste-komponente-anlegen)

---

# Einstieg & Übersicht

Source: https://configento.app/docs/einstieg-und-uebersicht
Section: Erste Schritte

configento.app ist eine Cloud-Lösung für Produktkonfiguratoren, Angebotskonfiguratoren und Preiskalkulatoren. Du baust deinen Konfigurator im Browser auf und bindest ihn per Plugin oder HTML-Snippet in deinen Shop oder deine Website ein. Dieser Artikel zeigt, wie die Teile zusammenhängen, erklärt die wichtigsten Begriffe und gibt dir einen Lernpfad durch die Dokumentation.

## Die drei Teile

| Teil | Wofür | Wo |
|---|---|---|
| **Service-Portal** | Dein Konto: Dienste und Tarife, Zahlungsdaten und Rechnungen, Shop-Verbindungen, Team | [service.configento.app](https://service.configento.app) |
| **Admin** | Deine Konfiguratoren: Merkmale, Werte, Preise, Regeln, Vorschau, Veröffentlichen | Im Service-Portal unter **Dienste** mit **Verwalten** |
| **Shop oder Website** | Zeigt den Konfigurator auf der Produktseite, übernimmt Preis und Auswahl in den Warenkorb oder verschickt eine Anfrage | Dein Magento-, Shopware-, Shopify- oder PrestaShop-Shop oder jede Website |

So fließen die Daten:

1. Du meldest dich im **Service-Portal** an und öffnest mit **Verwalten** den **Admin**. Eine zweite Anmeldung ist nicht nötig.
2. Im Admin baust du eine **Komponente** auf und **speicherst** sie. Gespeichert ist ein Entwurf, den nur die Vorschau im Admin zeigt.
3. Mit **Veröffentlichen** gibst du den Stand frei. Erst dann sieht ihn dein Shop.
4. Der Shop lädt die veröffentlichte Komponente aus der Cloud und zeigt sie deinen Kunden. Für sie ist die Cloud nicht sichtbar – der Konfigurator erscheint als Teil deiner Seite.

Bei älteren Verträgen öffnet **Verwalten** noch den bisherigen Admin; der neue steht dann darunter unter **Manage V3** mit dem Kennzeichen **BETA**. Mehr dazu: [Login und Account-Navigation](/docs/login-und-account-navigation).

## Die wichtigsten Begriffe

| Begriff | Bedeutung | Beispiel |
|---|---|---|
| **Komponente** | Ein Konfigurator. Sie enthält alles, was zu einem Produkt oder einer Produktgruppe gehört. | „Rollo nach Maß“ |
| **Gruppe** | Fasst Merkmale zusammen. Im Shop erscheinen Gruppen z. B. als Reiter oder als Schritte eines Wizards. | „Maße“, „Ausstattung“ |
| **Merkmal** | Eine Eigenschaft, die dein Kunde festlegt oder die der Konfigurator berechnet. | Farbe, Breite, Antrieb, Fläche |
| **Wert** | Eine wählbare Möglichkeit eines Merkmals, mit optionalem Aufpreis. | Weiß, Anthrazit (+25 €) |
| **Regel** | Eine Abhängigkeit zwischen Merkmalen: Werte ausblenden, Werte vorbelegen oder einen Hinweis bzw. Fehler zeigen. | „Bei Solar-Antrieb kein Weiß“ |
| **Baustein** | Eine zentral gepflegte Preisliste oder ein zentral gepflegter Staffelpreis, den mehrere Komponenten nutzen. Eine Änderung wirkt in allen verknüpften Komponenten. | Preistabelle Breite × Höhe für fünf Rollo-Modelle |

Wie du diese Teile anlegst, zeigt [Erste Komponente anlegen](/docs/erste-komponente-anlegen) Schritt für Schritt.

## Wo der Konfigurator läuft

| Integration | Was dein Kunde erlebt | Anleitung |
|---|---|---|
| **Magento 2 / Adobe Commerce** | Konfigurator auf der Produktseite, Preis und Auswahl gehen in den Warenkorb | [Magento-Plugin installieren](/docs/magento-plugin-installieren) |
| **Shopware 6** | Konfigurator auf der Produktseite, Preis und Auswahl gehen in den Warenkorb | [Shopware-Plugin installieren](/docs/shopware-plugin-installieren) |
| **Shopify** | Konfigurator auf der Produktseite, Preis und Auswahl gehen in den Warenkorb | [Shopify-Plugin installieren](/docs/shopify-plugin-installieren) |
| **PrestaShop 9** | Konfigurator auf der Produktseite, Preis und Auswahl gehen in den Warenkorb | [PrestaShop-Plugin installieren](/docs/prestashop-plugin-installieren) |
| **HTML-Snippet** | Konfigurator auf jeder Website – WordPress, TYPO3, Joomla, Jimdo oder eigenes HTML. Ohne Warenkorb schickt der Kunde seine Konfiguration über den Aktions-Button. | [HTML-Snippet Integration](/docs/html-snippet-integration) |

Shop-Plugins gibt es ab dem Tarif **Professional**.

**Magento 1** und **Shopware 5** werden nur noch für bestehende Konten mit der klassischen Cloud angeboten. Bei diesen Konten findest du die Plugins im Admin unter **Einstellungen → Integrationen** – siehe [Globale Einstellungen](/docs/globale-einstellungen#integrationen).

### Angebots- und Anfragekonfigurator

Ohne Warenkorb – oder zusätzlich dazu – schließt der **Aktions-Button** die Konfiguration ab. Er hat vier Aktionen:

- **Eigene URL** – sendet die Konfiguration an eine Adresse deiner Wahl, z. B. an dein CRM,
- **PDF erzeugen** – der Kunde lädt ein PDF seiner Konfiguration herunter,
- **E-Mail verschicken** – die Konfiguration geht per E-Mail an den Kunden, auf Wunsch in Kopie an dich,
- **E-Mail mit PDF verschicken** – wie oben, mit dem PDF im Anhang.

Mehr dazu: [Der Aktions-Button](/docs/aktions-button).

## Zwei Frontend-Engines

Jede Komponente läuft im Shop mit einer von zwei Frontend-Engines: **Legacy**, dem bewährten Konfigurator, oder **V3**, der neuen Engine im Beta-Stadium. Beide lesen dieselben Daten, einige Funktionen gibt es aber nur in einer der beiden. Shopify und PrestaShop laufen immer mit V3, Shopware 6 immer mit Legacy; in Magento 2 und in der Vorschau stellst du die Engine je Komponente ein. Alles dazu: [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Der KI-Assistent

Am unteren Rand des Admins liegt der **KI-Assistent**. Du beschreibst dein Produkt im Chat, und er legt Gruppen, Merkmale, Werte, Preistabellen und Regeln für dich an. Er liest auch PDF-Datenblätter und Bilder, die du anhängst. Veröffentlichen musst du selbst – das kann der Assistent nicht.

Der Assistent verbraucht **KI-Tokens**; jeder Tarif enthält ein monatliches Kontingent. Abschalten kannst du ihn unter **Einstellungen → KI**.

- [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen)
- [KI-Agent: Produktdaten importieren](/docs/ki-agent-daten-importieren)
- [KI-Tokens](/docs/ki-tokens)

## Dein Lernpfad

**1. Konto einrichten**

- [Login und Account-Navigation](/docs/login-und-account-navigation)
- [Service-Portal — Überblick](/docs/service-portal-uebersicht)
- [Zahlungsarten & Rechnungen](/docs/zahlungsarten-verwalten)
- [Team verwalten](/docs/team-verwalten)

**2. Den ersten Konfigurator bauen**

- [Erste Komponente anlegen](/docs/erste-komponente-anlegen)
- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [Gruppen, Darstellung & Wizard](/docs/merkmalsgruppen-wizard)
- [Bildvisualisierung & Bilder hochladen](/docs/bildvisualisierung-bilder)

**3. Preise und Regeln**

- [Preisberechnung einrichten](/docs/preisberechnung-einrichten)
- [Formeln & Berechnungen](/docs/preisformeln)
- [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv)
- [Regelwerk aufbauen](/docs/regelwerk-aufbauen)

**4. Feinschliff und Einstellungen**

- [Der Aktions-Button](/docs/aktions-button)
- [Komponenten-Einstellungen](/docs/komponente-einstellungen)
- [Globale Einstellungen](/docs/globale-einstellungen)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)

**5. In den Shop bringen**

- [Magento-Plugin installieren](/docs/magento-plugin-installieren)
- [Shopware-Plugin installieren](/docs/shopware-plugin-installieren)
- [Shopify-Plugin installieren](/docs/shopify-plugin-installieren)
- [PrestaShop-Plugin installieren](/docs/prestashop-plugin-installieren)
- [HTML-Snippet Integration](/docs/html-snippet-integration)

**6. Schneller mit KI und API**

- [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen)
- [KI-Agent: Produktdaten importieren](/docs/ki-agent-daten-importieren)
- [KI-Agent: Regeln per Chat definieren](/docs/ki-agent-regeln-definieren)
- [KI-Tokens](/docs/ki-tokens)
- [API — Einstieg & Übersicht](/docs/api-einstieg)

---

# Service-Portal — Überblick

Source: https://configento.app/docs/service-portal-uebersicht
Section: Erste Schritte

Das **Service-Portal** unter [service.configento.app](https://service.configento.app) ist die Verwaltung deines configento.app-Kontos: Hier siehst du deine Dienste, öffnest den Admin, stellst Tarife um, pflegst Zahlungsdaten und Rechnungsanschrift, verwaltest Shop-Verbindungen und dein Team. Dieser Artikel geht alle Bereiche durch.

Anmeldung, Navigation und Kundenauswahl erklärt [Login und Account-Navigation](/docs/login-und-account-navigation). Welche Bereiche du siehst, hängt von deiner Rolle ab – siehe [Team verwalten](/docs/team-verwalten#rollen-und-rechte).

## Dienste

Unter **Dienste** steht die Tabelle **Meine Dienste** mit allen Diensten des gewählten Kunden, der neueste oben. Ein Dienst ist ein gebuchter Tarif, zum Beispiel „configento.app Professional“.

| Spalte | Inhalt |
|---|---|
| **Dienst** | Tarif und Dienstnummer, darunter **Kunde** (deine Kundennummer) und – sofern vorhanden – der **Sicherheitsschlüssel**, jeweils mit **copy**-Knopf. Läuft ein Test, steht hier auch sein Ende. |
| **Status** | **aktiv**, **gekündigt** oder **temporär deaktiviert**, jeweils mit Datum (**seit …**) |
| **Preis** | Preis pro Monat oder pro Jahr und **Nächste Zahlung fällig am …** – nur bei aktiven, kostenpflichtigen Diensten |
| **Aktionen** | Die Knöpfe unten |

Kundennummer und Sicherheitsschlüssel brauchst du nur noch für die [klassische Anmeldung](/docs/shopware-plugin-installieren#klassische-anmeldung) von Shop-Plugins. Neue Plugins verbinden sich über **Mit Configento verbinden**.

### Aktionen

Welche Knöpfe erscheinen, hängt vom Dienst ab. Bedienen dürfen sie nur die Rollen Inhaber, Admin und Bearbeiter.

| Knopf | Erscheint, wenn … | Wirkung |
|---|---|---|
| **Verwalten** | der Dienst aktiv ist | Öffnet den Admin über dem Portal. Bei älteren Verträgen öffnet er den bisherigen Admin, der neue steht dann unter **Manage V3** (**BETA**). |
| **Dienst umstellen** | der Dienst aktiv ist, nicht im Test und nicht über Shopify abgerechnet | Wechselt den Tarif, siehe unten |
| **Dienst kündigen** | der Dienst nicht schon gekündigt ist und nicht über Shopify abgerechnet wird | Kündigt sofort, siehe unten |
| **Jährlich bezahlen** | der Dienst monatlich bezahlt wird, nicht im Test ist und keinen Sonderpreis hat | Stellt auf jährliche Zahlung um – „Jetzt Dienst auf jährliche Zahlung umstellen und jedes Jahr zwei Monatsraten sparen!“ |
| **Monatlich bezahlen** | der Dienst jährlich bezahlt wird (gleiche Bedingungen) | Stellt auf monatliche Zahlung um |

Die Umstellung der Zahlweise bestätigst du in einem Dialog (**Auf jährliche Zahlung umstellen** bzw. **Auf monatliche Zahlung umstellen**). Sie gilt ab der nächsten Abrechnung; das Portal meldet „Die Abrechnung für deinen Dienst erfolgt künftig jährlich.“

### Dienst umstellen

**Dienst umstellen** zeigt deinen aktuellen Tarif und die Tarife, auf die du wechseln kannst.

- Beim **Wechsel in einen teureren Tarif** wird die Preisdifferenz für die restlichen Tage des laufenden Zeitraums sofort in Rechnung gestellt und abgebucht.
- Beim **Wechsel in einen günstigeren Tarif** gibt es **keine Erstattung** bereits bezahlter Gebühren.
- Der Dienst bekommt dabei eine **neue Dienstnummer**; der alte erscheint als gekündigt in der Liste.
- Wechselst du von Professional oder Ultimate auf **Basic**, werden alle Shop-Plugin-Verbindungen dieses Dienstes getrennt – Basic enthält keine Shop-Plugins.

### Dienst kündigen

**Dienst kündigen** fragt „Möchtest du den Dienst wirklich endgültig kündigen?“ und weist darauf hin:

> Alle Konfiguratoren, Bilder und Einstellungen dieses Dienstes werden dabei gelöscht und lassen sich nicht wiederherstellen.

Die Kündigung wirkt **sofort**. Sichere deine Komponenten deshalb vorher im Admin mit **Komponente exportieren** als ZIP. Der Inhaber bekommt eine Bestätigung per E-Mail.

### Testzugang

Ein neuer Testzugang läuft 14 Tage im Tarif Professional. Zwei Tage vor Ablauf bekommt der Inhaber eine Erinnerung per E-Mail. Am Ende des Tests

- wird der Dienst automatisch kostenpflichtig weitergeführt, wenn eine **Rechnungsanschrift** und eine aktive **Zahlungsart** hinterlegt sind,
- sonst wird er **temporär deaktiviert**. Sobald du beides nachträgst, kannst du ihn wieder nutzen.

### Temporär deaktiviert

Ein Dienst wird temporär deaktiviert, wenn eine Zahlung endgültig fehlgeschlagen ist oder bei einem fälligen Dienst Zahlungsart oder Rechnungsanschrift fehlen. Neben dem Dienst steht dann „Überprüfe deine Zahlungsdaten um den Dienst wieder zu aktivieren.“ Wie es dazu kommt und wie du ihn wieder aktivierst: [Zahlungsarten & Rechnungen](/docs/zahlungsarten-verwalten#wenn-eine-zahlung-fehlschlägt).

### Über Shopify gebuchte Dienste

Dienste, die du über den Shopify App Store gebucht hast, rechnet Shopify ab. Im Portal stehen dafür weder **Dienst umstellen** noch **Dienst kündigen** – Tarifwechsel und Kündigung erledigst du in Shopify. Das Portal sagt dazu: „Abrechnung und Verwaltung erfolgen über den Shopify App Store.“

## Verbindungen

Unter **Verbindungen** siehst du alle Shop-Plugins, die mit dem gewählten Kunden über **Mit Configento verbinden** verbunden sind (Magento 2, Shopware 6, …):

| Spalte | Inhalt |
|---|---|
| **Shop-Host** | Adresse des Shops |
| **Plugin** | Welches Plugin verbunden ist |
| **Dienst** | Der verbundene Dienst mit Dienstnummer |
| **Verbunden von** | Wer die Verbindung hergestellt hat |
| **Aktive Tokens** | Wie viele Anmeldungen der Shop gerade hält |
| **Zuletzt verwendet** | Wann der Shop die Verbindung zuletzt genutzt hat |

Mit **Widerrufen** (Rückfrage **Sicher?**) trennst du einen Shop vollständig – etwa wenn du keinen Zugriff mehr auf ihn hast. Der Shop muss sich danach neu verbinden. Widerrufen dürfen Inhaber, Admin und Bearbeiter.

## Abrechnung

Das Menü **Abrechnung** fasst drei Seiten zusammen:

- **Zahlungsarten** – Kreditkarte, SEPA-Lastschrift oder PayPal hinterlegen. Details: [Zahlungsarten & Rechnungen](/docs/zahlungsarten-verwalten)
- **KI-Tokens** – Bestand und Nachkauf für den KI-Assistenten. Details: [KI-Tokens](/docs/ki-tokens)
- **Rechnungen** – Rechnungsanschrift und alle Rechnungen als PDF. Details: [Zahlungsarten & Rechnungen](/docs/zahlungsarten-verwalten#zuerst-die-rechnungsanschrift)

## Team

Unter **Team** laden Inhaber und Admins Kollegen ein und vergeben Rollen. Details: [Team verwalten](/docs/team-verwalten)

## Fehlersuche

1. **„Dienst umstellen“ fehlt** – der Dienst ist im Test, nicht aktiv oder wird über Shopify abgerechnet.
2. **Nach dem Tarifwechsel ist mein Shop nicht mehr verbunden** – du bist auf Basic gewechselt. Shop-Plugins gibt es erst ab Professional.
3. **Der Dienst ist „temporär deaktiviert“** – hinterlege Rechnungsanschrift und Zahlungsart, siehe [Zahlungsarten & Rechnungen](/docs/zahlungsarten-verwalten).
4. **Ich sehe „KI-Tokens“ nicht** – KI-Tokens sind für dein Konto noch nicht freigeschaltet, oder deine Rolle ist Nur-Lesen.

## Nächste Schritte

- [Login und Account-Navigation](/docs/login-und-account-navigation)
- [Zahlungsarten & Rechnungen](/docs/zahlungsarten-verwalten)
- [KI-Tokens](/docs/ki-tokens)
- [Team verwalten](/docs/team-verwalten)

---

# Captcha-Spamschutz

Source: https://configento.app/docs/captcha-spamschutz
Section: Konfigurator aufbauen

Ein Aktions-Button, der E-Mails verschickt, ist ein öffentliches Formular: Wer die Seite findet, kann darüber automatisiert Mails auslösen – über deinen Mailserver. Das Merkmal **Captcha** schützt davor. Es arbeitet im Hintergrund, braucht keinen Dienst eines Drittanbieters und setzt keine Cookies. Dieser Artikel zeigt, wie du es einrichtest und was es prüft.

## So funktioniert das Captcha

configento.app verwendet **Altcha**, ein Captcha nach dem Prinzip **Proof-of-Work**:

1. Beim Laden des Konfigurators holt der Browser des Kunden eine Rechenaufgabe von configento.app.
2. Der Browser löst die Aufgabe selbst. Das dauert je nach Gerät und Schwierigkeit Sekundenbruchteile bis wenige Sekunden.
3. Klickt der Kunde auf den Aktions-Button, wird die Lösung mitgeschickt. Der Server prüft sie und führt die Aktion nur dann aus.

Der Kunde muss keine Bilder anklicken und nichts abtippen. Für einen einzelnen Besucher kostet die Aufgabe kaum Zeit, für ein Programm, das tausende Anfragen schicken will, wird sie teuer. Jede Lösung gilt nur **einmal** und nur für begrenzte Zeit.

## Voraussetzung: Frontend-Engine V3

Das Captcha gibt es nur in der Frontend-Engine **V3**. Der Datentyp heißt deshalb **Captcha (nur V3)**.

Enthält eine Komponente ein Captcha,

- trägt sie in der Komponenten-Übersicht das Kennzeichen **V3**,
- zeigen die Komponenten-Einstellungen den Hinweis **Benötigt Frontend V3**,
- lädt **Magento 2** sie automatisch mit V3,
- läuft sie in **Shopify** ohnehin mit V3.

In **Shopware 6** und im klassischen **HTML5**-Snippet läuft immer die Legacy-Engine. Dort kann das Captcha nicht angezeigt werden – und der Server lehnt die Aktionen der Komponente trotzdem ab, weil die Lösung fehlt. Verwende dort kein Captcha. Mehr dazu: [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3#das-kennzeichen-v3).

Stelle in den Komponenten-Einstellungen unter **Allgemein** die **Engine** auf **V3 (Beta)**. Die Vorschau im Admin richtet sich nach dieser Einstellung – nur mit V3 siehst du das Captcha dort.

## Captcha einrichten

1. Öffne die Komponente und lege ein neues Merkmal an.
2. Wähle unter **Frontend** den Datentyp **Captcha (nur V3)**.
3. Lege es in dieselbe Gruppe wie den Aktions-Button, am besten direkt darüber.
4. Wähle unter **Captcha-Einstellungen** die **Captcha-Komplexität** (siehe unten).
5. Speichere, prüfe die Vorschau und **veröffentliche** die Komponente.

![Merkmal mit Datentyp Captcha in einem Anfrageformular: Captcha-Einstellungen mit Anbieter Altcha und Komplexität](/storage/app/media/docs/captcha-spamschutz/01-captcha.webp)

Als **Captcha-Anbieter** steht fest **Altcha**. Ein Captcha pro Komponente genügt, auch bei mehreren Aktions-Buttons.

### Captcha-Komplexität

| Captcha-Komplexität | Wirkung |
|---|---|
| **Einfach (schnelle Prüfung)** | Kaum spürbar, auch auf langsamen Geräten |
| **Mittel (Standard)** | Für die meisten Shops die richtige Wahl |
| **Stark (langsamer, mehr Spam-Schutz)** | Etwa viermal so viel Rechenaufwand wie **Mittel**. Auf älteren Smartphones kann das Lösen spürbar dauern. |

Fang mit **Mittel (Standard)** an und erhöhe nur, wenn trotzdem Spam ankommt.

## Was das Captcha schützt

Sobald eine Komponente ein Captcha enthält, prüft der Server bei jedem Klick auf einen ihrer Aktions-Buttons die Lösung:

| Aktion des Aktions-Buttons | Mit Captcha in der Komponente |
|---|---|
| **E-Mail verschicken** | Nur mit gültiger Lösung |
| **E-Mail mit PDF verschicken** | Nur mit gültiger Lösung |
| **PDF erzeugen** | Nur mit gültiger Lösung |
| **Eigene URL** | Nur mit gültiger Lösung – geprüft, bevor die Daten an deine Adresse weitergeleitet werden |

Ohne gültige Lösung antwortet der Server mit **HTTP 403** und führt die Aktion nicht aus.

Auch im Konfigurator selbst zählt das Captcha: Solange es nicht gelöst ist, zeigt V3 „Bitte löse das Captcha vor dem Absenden.“ und hält den Aktions-Button und den Warenkorb zurück. Da der Browser die Aufgabe beim Laden von selbst löst, merkt der Kunde davon normalerweise nichts. Nach jeder Aktion löst das Captcha eine neue Aufgabe – klickt der Kunde den Aktions-Button ein zweites Mal oder versucht es nach einem Fehler erneut, hat er wieder eine gültige Lösung.

Alles zu den Aktionen selbst: [Der Aktions-Button](/docs/aktions-button).

### Hinweise im Editor

In den Einstellungen eines Aktions-Buttons, der E-Mails verschickt, steht **Spam-Risiko: kein Captcha in dieser Komponente**, solange die Komponente kein Captcha hat.

Die Prüfung vor dem Veröffentlichen warnt außerdem:

- „Ein Aktions-Button verschickt E-Mails ohne Captcha – Spam-Risiko im öffentlichen Shop.“
- „Es gibt ein Captcha, aber keinen Aktions-Button, der es auslöst – das Captcha wird nie geprüft.“ – wenn kein Aktions-Button **E-Mail verschicken**, **E-Mail mit PDF verschicken** oder **Eigene URL** verwendet.

Die Warnungen blockieren das Veröffentlichen nicht.

## Datenschutz

- Die Rechenaufgabe kommt vom Server von configento.app. Es werden keine Skripte, Schriften oder Bilder eines Drittanbieters geladen.
- Das Captcha setzt keine Cookies und verfolgt den Besucher nicht über Seiten hinweg. Es rechnet nur die Aufgabe.
- Übertragen wird nur die Lösung der Aufgabe, zusammen mit den übrigen Daten der Konfiguration.

## Weitere Schutzmechanismen

Das Captcha ist nicht der einzige Schutz. Unabhängig davon begrenzt configento.app, wie oft eine Aktion ausgelöst werden kann, und verschickt dieselbe Konfiguration nicht mehrfach kurz hintereinander. Die Grenzen stehen im Artikel [Der Aktions-Button](/docs/aktions-button).

## Fehlersuche

1. **„Übermittlung fehlgeschlagen: HTTP 403“** – die Lösung fehlte oder war abgelaufen. Warte, bis das Captcha eine neue Aufgabe gelöst hat, und versuche es noch einmal. Tritt der Fehler immer auf, läuft die Komponente vermutlich mit der Legacy-Engine (Shopware 6, klassisches HTML5-Snippet) – dort kann das Captcha nicht gelöst werden.
2. **„Captcha konnte nicht geladen werden. Bitte Seite neu laden.“** – der Browser konnte die Aufgabe nicht abrufen, etwa wegen eines Werbeblockers oder einer Firewall. Prüfe, ob die Seite configento.app erreichen darf.
3. **Das Captcha erscheint in der Vorschau nicht** – die **Engine** der Komponente steht auf **Legacy (Standard)**. Stelle sie auf **V3 (Beta)**.
4. **Das Lösen dauert auf dem Smartphone lange** – setze die **Captcha-Komplexität** auf **Mittel (Standard)** oder **Einfach (schnelle Prüfung)**.
5. **Der Warenkorb-Button reagiert erst nach einem Moment** – der Browser löst noch die Aufgabe. Bei **Stark** auf langsamen Geräten kann das spürbar sein.
6. **Trotz Captcha kommt Spam an** – erhöhe die **Captcha-Komplexität**. Prüfe außerdem, ob die Mails wirklich über diese Komponente kommen und nicht über ein anderes Formular deiner Website.

## Nächste Schritte

- [Der Aktions-Button](/docs/aktions-button)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [Komponenten-Einstellungen](/docs/komponente-einstellungen)

---

# Entwurf, Vorschau & Veröffentlichen

Source: https://configento.app/docs/entwurf-vorschau-veroeffentlichen
Section: Konfigurator aufbauen

Jede Komponente gibt es in zwei Ständen: dem **Entwurf**, an dem du im Admin arbeitest, und der **veröffentlichten Fassung**, die deine Shops zeigen. Speichern ändert nur den Entwurf, erst **Veröffentlichen** bringt ihn in den Shop. Dieser Artikel erklärt, wie Speichern, Vorschau, Veröffentlichen und Versionen zusammenspielen – und wie du sicher zu einem früheren Stand zurückkommst.

## Die zwei Stände einer Komponente

| Stand | Wer sieht ihn | Wie er sich ändert |
|---|---|---|
| **Entwurf** | Du im Editor und in der **Vorschau** | Mit jedem **Speichern** – auch Änderungen des KI-Assistenten landen hier |
| **Veröffentlichte Fassung** | Deine Kunden im Shop – in Magento, Shopware, Shopify und im HTML-Snippet | Nur mit **Veröffentlichen** |

Solange sich die beiden unterscheiden, steht oben rechts im Editor **Noch nicht live**. Fährst du mit der Maus darüber, erscheint: „Die Shops zeigen bis zum Veröffentlichen weiter die zuletzt veröffentlichte Fassung.“

Du kannst also in Ruhe umbauen, testen und erst dann freigeben, wenn alles stimmt – deine Kunden merken bis dahin nichts.

## Speichern

Sobald du etwas änderst, erscheint über dem rechten Bereich der Knopf **Speichern**, im Reiter **Regeln** zusätzlich mit dem Hinweis **Ungespeicherte Änderungen**.

- **Speichern** schreibt deinen Stand in den Entwurf und legt eine neue Version an (siehe [Versionen](#versionen)).
- **Rückgängig** oben rechts nimmt die letzte Änderung zurück, auch mehrfach hintereinander. Das gilt nur für die aktuelle Sitzung: Nach dem Neuladen der Seite ist der Verlauf leer – zurück geht es dann über die Versionen.
- Der Admin speichert nicht automatisch. Willst du den Editor mit ungespeicherten Änderungen verlassen, fragt er „Du hast ungespeicherte Änderungen. Den Editor trotzdem verlassen?“ – beim Schließen des Browser-Tabs fragt der Browser selbst nach.

Beim Speichern prüft der Admin die Komponente nicht. Fehler zeigt er erst beim Veröffentlichen.

## Vorschau

Die Vorschau zeigt den Konfigurator so, wie ihn deine Kunden sehen werden – mit der eingestellten [Frontend-Engine](/docs/frontend-engine-legacy-v3), aber mit dem **gespeicherten Entwurf** statt der veröffentlichten Fassung. So testest du Änderungen, bevor sie live gehen.

1. Schalte in der mittleren Spalte von **Bearbeiten** auf **Vorschau**.
2. Hast du ungespeicherte Änderungen, fragt der Admin: „Aktuellen Stand vor der Vorschau speichern? Andernfalls wird der zuletzt gespeicherte Stand angezeigt.“ Bestätigst du, speichert er zuerst.
3. Änderst du danach weiter, erscheint in der Vorschau der Hinweis **Vorschau zeigt die zuletzt gespeicherte Version. Speichere, um deine Änderungen zu sehen.** Speichere und lade mit **↺** (**Vorschau aktualisieren**) neu.

Weitere Möglichkeiten:

- **Sprache:** Hat dein Konto mehrere Sprachen aktiv, wählst du oben in der Vorschau, in welcher Sprache du den Konfigurator sehen willst.
- **In eigenes Fenster verschieben:** öffnet die Vorschau in einem eigenen Fenster, der Editor wird breiter. Das Fenster lädt nach jedem Speichern im Editor selbst neu.
- **Bereiche ein- und ausblenden:** In der Leiste über der Vorschau schaltest du **Gesamtpreis**, **Kombiniertes Produktbild** (wenn die Komponente eines hat) und **Zusammenfassung** ein oder aus. Die Schalter wirken nur auf die Vorschau, nicht auf den Shop.
- **Kombinierte Artikelnummer** (nur V3): zeigt neben dem Gesamtpreis die Artikelnummer des konfigurierten Produkts, z. B. `CL-W-GR` – zusammengesetzt aus den Artikelnummern der gewählten Werte. So prüfst du, welche Nummer in den Warenkorb geht, auch wenn sie in der Zusammenfassung ausgeschaltet ist. Anfangs aus. Mehr dazu in den [Komponenten-Einstellungen](/docs/komponente-einstellungen).

Die Vorschau braucht die Integration **HTML5**. Ist sie aus, erscheint stattdessen ein Hinweis, sie unter **Einstellungen** → **Integrationen** zu aktivieren.

## Veröffentlichen

Der Knopf **Veröffentlichen** oben rechts erscheint, sobald es etwas zu veröffentlichen gibt – bei einer neuen Komponente immer.

1. Klicke auf **Veröffentlichen**. Ungespeicherte Änderungen speichert der Admin zuerst.
2. Der Dialog **Komponente veröffentlichen?** prüft die Komponente (**Wird geprüft …**):
   - **Veröffentlichen blockiert – diese Fehler müssen behoben werden:** – zum Beispiel ein Preislisten-Merkmal ohne Matrix-Einstellungen. **Ja, veröffentlichen** bleibt gesperrt, bis du den Fehler behoben hast.
   - **Warnungen (Veröffentlichen trotzdem möglich):** – zum Beispiel eine leere Formel, ein doppelt vergebener interner Name oder ein E-Mail-Button ohne Captcha.
3. Bestätige mit **Ja, veröffentlichen**. Der Dialog erinnert daran: Eine frühere Version kannst du jederzeit unter **Versionen** wiederherstellen und erneut veröffentlichen.

Danach öffnet sich **Komponente wird veröffentlicht** mit dem Fortschritt. Dabei werden auch neue Bilder übertragen; bei großen Komponenten mit vielen Bildern dauert das einen Moment. Du kannst die Seite verlassen – das Veröffentlichen läuft im Hintergrund weiter. Öffnest du die Komponente in der Zwischenzeit wieder, zeigt der Editor den Fortschritt erneut an.

Ist alles durch, verschwindet **Noch nicht live**, und alle Shops zeigen die neue Fassung.

### Das erste Veröffentlichen

Eine neue, noch nie veröffentlichte Komponente trägt in der Übersicht das Kennzeichen **Lokal** und statt einer Nummer **ID —**. Beim ersten Veröffentlichen bekommt sie ihre endgültige **ID**, und der Editor wechselt automatisch auf die neue Adresse.

Erst mit dieser ID kannst du die Komponente in deinem Shop einem Produkt zuordnen – siehe [Magento-Plugin](/docs/magento-plugin-installieren), [Shopware-Plugin](/docs/shopware-plugin-installieren), [Shopify-Plugin](/docs/shopify-plugin-installieren) oder [HTML-Snippet](/docs/html-snippet-integration).

### Wenn das Veröffentlichen scheitert

Schlägt das Veröffentlichen fehl, meldet der Dialog: „Veröffentlichen fehlgeschlagen — dein lokaler Entwurf ist unverändert. Behebe den Fehler unten und versuche es erneut.“ Unter **Fehlgeschlagene Uploads** stehen Bilder, die nicht übertragen werden konnten. Dein Entwurf bleibt erhalten, die Shops zeigen weiter die bisherige Fassung.

**SVG-Bilder:** Die klassische Cloud nimmt nur JPEG, PNG, BMP und GIF an. SVG-Bilder werden deshalb nicht dorthin übertragen – der Dialog meldet **SVG-Bilder bleiben im V3-Konfigurator**. In V3 erscheinen sie normal, nur Legacy kann sie nicht laden.

## Zurück zur veröffentlichten Fassung

Willst du alle Änderungen seit dem letzten Veröffentlichen verwerfen, klicke oben rechts auf **Zurücksetzen** und bestätige **Auf veröffentlichte Version zurücksetzen?** mit **Ja, zurücksetzen**. Der Entwurf wird durch die veröffentlichte Fassung ersetzt. Das lässt sich nicht rückgängig machen – auch nicht über **Rückgängig**.

Eine Komponente, die noch nie veröffentlicht wurde, hat diesen Knopf nicht.

## Versionen

Im Reiter **Versionen** findest du den **Versionsverlauf** der Komponente, die neueste Version oben.

![Reiter „Versionen“: Versionsverlauf mit „Mit Entwurf vergleichen“, „Wiederherstellen“ und „Vergleichen“ für zwei Versionen](/storage/app/media/docs/entwurf-vorschau-veroeffentlichen/01-versionen.webp)

- **Jedes Speichern** legt eine Version an, ebenso jede Änderung des KI-Assistenten und jede Wiederherstellung.
- **Jedes Veröffentlichen** legt eine eigene Version mit der Markierung **Veröffentlicht** an – genau der Stand, den die Shops seitdem bekommen.
- Die Versionen bleiben erhalten, bis du die Komponente löschst.

Gibt es noch keine Version, steht dort **Noch keine Versionen — speichere die Komponente, um eine zu erstellen.**

### Vergleichen

| Aktion | Was sie zeigt |
|---|---|
| **Mit Entwurf vergleichen** | Die gewählte Version gegenüber deinem **Aktuellen Entwurf** |
| Zwei Versionen anhaken, dann **Vergleichen** | Die ältere gegenüber der neueren der beiden. Hakst du eine dritte an, fällt die zuerst gewählte heraus. |

Der Vergleich listet die Unterschiede nach Bereichen – Komponente (**Oberste Ebene**), Gruppen, Merkmale, Regeln. Mit **Springen zu** wechselst du zwischen den Bereichen. Sind beide Stände gleich, steht dort **Keine Unterschiede**.

Mit **Vergleich an KI senden** übergibst du den Vergleich an den [KI-Assistenten](/docs/ki-agent-konfigurator-aufbauen). Er kann dir dann erklären, was sich geändert hat.

Ein typischer Einsatz: Vor dem Veröffentlichen die zuletzt veröffentlichte Version mit **Mit Entwurf vergleichen** öffnen – so siehst du genau, was gleich live geht.

### Wiederherstellen

1. Klicke bei der gewünschten Version auf **Wiederherstellen**.
2. Bestätige „Diese Version wiederherstellen? Dein aktueller Entwurf wird überschrieben.“

Der Entwurf hat jetzt den Stand dieser Version, und es entsteht eine neue Version. Die Wiederherstellung lässt sich also ihrerseits wieder rückgängig machen, indem du die vorherige Version wiederherstellst. Ungespeicherte Änderungen gehen dabei verloren.

Im Shop ist der wiederhergestellte Stand erst nach dem **Veröffentlichen** zu sehen. So machst du ein missglücktes Veröffentlichen rückgängig: die letzte gute **Veröffentlicht**-Version wiederherstellen und erneut veröffentlichen.

## Mehrere Personen an einer Komponente

Der Admin sperrt eine Komponente nicht, während jemand sie bearbeitet. Speichern zwei Personen nacheinander, gilt das zuletzt Gespeicherte – die Änderungen der anderen Person sind dann nur noch in den [Versionen](#versionen) zu finden.

Beim Veröffentlichen prüft der Admin zusätzlich, ob die Komponente in der Cloud seit dem Öffnen des Editors geändert wurde, etwa im alten Admin. Dann erscheint **Gleichzeitige Bearbeitung erkannt!**. Veröffentlichst du trotzdem, überschreibst du diese Änderungen. Diese Prüfung erkennt nicht jeden Fall – gespeicherte, aber noch nicht veröffentlichte Änderungen einer anderen Person im Admin zum Beispiel nie.

Sprecht euch deshalb ab, wer gerade an einer Komponente arbeitet. Hast du eine Komponente lange offen gelassen, lade sie vor dem Weiterarbeiten neu.

## Bausteine: veröffentlichen für viele Komponenten

Nutzen mehrere Komponenten denselben **Baustein** – eine zentral gepflegte Preistabelle oder Staffel –, änderst du ihn unter **Bausteine** in der Hauptnavigation. Beim Speichern entscheidest du mit **Betroffene Komponenten veröffentlichen**, ob die verknüpften Komponenten gleich veröffentlicht werden.

Komponenten mit eigenen unveröffentlichten Änderungen werden dabei nur im Entwurf aktualisiert – sonst gingen diese Änderungen ungefragt mit live. Der Admin listet sie danach auf; du veröffentlichst sie, wenn ihre eigenen Änderungen fertig sind.

## Fehlersuche

1. **Meine Änderung ist im Shop nicht zu sehen** – du hast nur gespeichert. Steht oben **Noch nicht live**, klicke auf **Veröffentlichen**.
2. **Die Vorschau zeigt meine Änderung nicht** – die Vorschau zeigt den gespeicherten Stand. Speichere und klicke auf **↺**.
3. **Ja, veröffentlichen ist ausgegraut** – der Dialog listet einen Fehler unter **Veröffentlichen blockiert**. Behebe ihn, speichere und öffne den Dialog erneut.
4. **Die Vorschau bleibt leer mit einem Hinweis auf HTML5** – aktiviere die Integration unter **Einstellungen** → **Integrationen** (siehe [Globale Einstellungen](/docs/globale-einstellungen#integrationen)).
5. **Eine Änderung meiner Kollegin ist verschwunden** – ihr habt gleichzeitig gespeichert. Öffne **Versionen**, vergleiche ihre Version mit dem Entwurf und übernimm die fehlenden Änderungen oder stelle ihre Version wieder her.
6. **Im Shop fehlt die Komponente, obwohl sie veröffentlicht ist** – im Shop braucht es die endgültige ID. Prüfe in der Übersicht, ob die Komponente noch **Lokal** ist, und ob dem Produkt die richtige ID zugeordnet ist.
7. **Die kombinierte Artikelnummer erscheint in der Vorschau nicht** – die Komponente läuft mit Legacy, oder weder die gewählten Werte noch die Merkmale haben eine Artikelnummer.

## Nächste Schritte

- [Komponenten-Einstellungen](/docs/komponente-einstellungen)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [Erste Komponente anlegen](/docs/erste-komponente-anlegen)
- [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen)

---

# Frontend-Merkmale: Statisches Feld & Diagramm

Source: https://configento.app/docs/frontend-merkmale
Section: Konfigurator aufbauen

Nicht jedes Merkmal fragt etwas ab. Die Merkmale der Datenkategorie **Frontend** gestalten den Konfigurator: Sie zeigen Texte und Bilder, nehmen Dateien entgegen oder lösen eine Aktion aus. Dieser Artikel stellt sie vor – vor allem das **Statische Feld**, mit dem du Hinweise, Zwischenüberschriften und Bilder an jede Stelle des Konfigurators setzt.

## Die Frontend-Merkmale im Überblick

Du wählst sie unter **Grundeinstellungen**: **Datenkategorie** **Frontend**, dann den **Datentyp**.

| Datentyp | Wofür | Mehr dazu |
|---|---|---|
| **Statisches Feld** | Text, Bilder, Links und Hinweise an einer festen Stelle | dieser Artikel |
| **Dateiupload** | Der Kunde lädt Dateien hoch, z. B. eine Druckvorlage | [Uploads & Deep Links](/docs/uploads-und-deep-links) |
| **Diagramm** | Zeigt ein Diagramm | siehe [unten](#diagramm) |
| **Aktions-Button** | Verschickt eine E-Mail, erzeugt ein PDF oder sendet die Konfiguration an eine eigene Adresse | [Der Aktions-Button](/docs/aktions-button) |
| **Captcha (nur V3)** | Schützt den Aktions-Button vor Spam | [Captcha-Spamschutz](/docs/captcha-spamschutz) |

**Dateiupload** und **Diagramm** gibt es nur im Tarif **Ultimate**.

## Statisches Feld

Ein Statisches Feld zeigt einen Inhalt, den du im Admin festlegst. Der Kunde kann nichts auswählen oder eingeben. Typische Einsätze:

- **Zwischenüberschrift**, die eine lange Gruppe gliedert, z. B. „Maße“ und „Ausstattung“,
- **Hinweis** an der richtigen Stelle, z. B. „Maße bitte in Zentimetern angeben“,
- **Bild**, z. B. eine Maßskizze vor den Eingabefeldern für Breite und Höhe,
- **Link** auf eine Seite mit Montageanleitung oder Farbmustern.

![Statisches Feld im Editor: in der Mitte die Vorschau des Inhalts, rechts der Abschnitt „Inhalt“ mit dem Texteditor](/storage/app/media/docs/frontend-merkmale/01-statisches-feld.webp)

### Anlegen

1. Lege im Strukturbaum ein neues Merkmal an der gewünschten Stelle an.
2. Stelle unter **Grundeinstellungen** die **Datenkategorie** auf **Frontend** und den **Datentyp** auf **Statisches Feld**.
3. Schreibe im Abschnitt **Inhalt** den Text.
4. Speichere. Die **Vorschau** zeigt das Feld sofort.

Die **Bezeichnung** des Merkmals erscheint wie bei jedem Merkmal als Überschrift über dem Inhalt, die **Informationen** darunter. Lässt du die Bezeichnung leer, erscheint keine Überschrift – in Legacy wie in V3. So steht ein Hinweistext ohne eigene Überschrift im Konfigurator.

### Der Inhalt

Das Feld **Inhalt** ist ein Editor mit Formatierung:

| Werkzeug | Wirkung |
|---|---|
| **Fett**, **Kursiv**, **Unterstrichen**, **Durchgestrichen** | Textauszeichnung |
| **Überschrift 2**, **Überschrift 3** | Zwischenüberschriften |
| **Liste**, **Nummerierte Liste**, **Zitat** | Gliederung |
| **Linksbündig**, **Zentriert**, **Rechtsbündig** | Textausrichtung |
| **Link einfügen** | Verlinkt den markierten Text |
| **Bild einfügen** | Lädt ein Bild hoch (höchstens 5 MB) und setzt es in den Text |
| **HTML-Quelltext bearbeiten** | Zeigt den Inhalt als HTML zum direkten Bearbeiten |

Den Inhalt pflegst du je Inhaltssprache. Wechselst du oben die Sprache, bearbeitest du die Übersetzung; ist für eine Sprache nichts eingetragen, steht der Inhalt der Standardsprache als grauer Platzhalter im Feld. Fehlt eine Übersetzung, zeigt V3 im Konfigurator den Inhalt einer anderen Sprache.

Ist der Inhalt leer, zeigt das Feld nur Bezeichnung und Informationen.

### Statisches Feld per Regel ein- und ausblenden

Wie jedes Merkmal kannst du ein Statisches Feld mit einer **Blacklist**-Regel ausblenden. So erscheint ein Hinweis nur, wenn er passt – etwa „Ab 6 m Breite ist ein zusätzlicher Pfosten nötig“ nur bei großen Breiten. Siehe [Regelwerk aufbauen](/docs/regelwerk-aufbauen).

### Inhalte aus Magento-CMS-Blöcken

In Magento 2 setzt du mit `$content[kennung]` den Inhalt eines CMS-Blocks ein; `kennung` ist die Kennung des Blocks. Dazu muss in der Erweiterung **CMS Block Integration** aktiv sein, siehe [Magento-Plugin installieren](/docs/magento-plugin-installieren). In den **Informationen** eines Merkmals funktioniert das mit beiden Engines, im **Inhalt** eines Statischen Felds nur mit V3.

## Einstellungen, die für alle Frontend-Merkmale gelten

| Einstellung | Bei Frontend-Merkmalen |
|---|---|
| **Pflichtfeld** | Fehlt beim Statischen Feld, Diagramm, Aktions-Button und Captcha – der Kunde füllt sie nicht aus. Beim **Dateiupload** vorhanden. |
| **Sichtbarkeit** | **Ja (sichtbar)** oder **Nur Shop** zeigen das Merkmal im Konfigurator, **Nein (versteckt)** und **Nur Backend** blenden es aus. |
| **Bild** | Beim Statischen Feld kannst du zusätzlich ein Merkmalbild hinterlegen, wie bei anderen Merkmalen auch. |
| **Informationen** / **Zusätzliche Informationen** | Hinweistexte neben dem Merkmal, wie bei anderen Merkmalen |
| **CSS-Klasse** | Eigene Klasse für individuelles Styling, z. B. um einen Hinweis farbig hervorzuheben |

Statisches Feld, Diagramm, Aktions-Button und Captcha landen nicht in der Zusammenfassung und nicht im Warenkorb – sie haben keinen Wert. Mehr zu den Einstellungen: [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen#verhalten).

## Diagramm

Den Datentyp **Diagramm** kannst du anlegen, seine Einstellungen folgen im Admin aber erst in einer späteren Version. V3 zeigt an seiner Stelle nur einen Platzhalter. Ein Diagramm, das in einer älteren Komponente schon eingerichtet ist, stellt nur Legacy dar; in Shopware 6 und Magento 2 muss dafür die Einstellung **Chart-Plugin laden** aktiv sein.

## Unterschiede zwischen Legacy und V3

| | Legacy | V3 |
|---|---|---|
| **Statisches Feld** | Zeigt den Inhalt | Zeigt den Inhalt |
| `$content[…]` im Inhalt eines Statischen Felds | Wird nicht ersetzt | Wird durch den Magento-CMS-Block ersetzt |
| **Dateiupload** | Funktioniert | Funktioniert, siehe [Uploads & Deep Links](/docs/uploads-und-deep-links) |
| **Diagramm** | Zeigt ein vorhandenes Diagramm | Zeigt einen Platzhalter |
| **Captcha (nur V3)** | Kann es nicht darstellen | Funktioniert |

Mehr zu den Engines: [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Fehlersuche

1. **Das Statische Feld erscheint nicht** – prüfe die **Sichtbarkeit** und ob eine Blacklist-Regel es ausblendet.
2. **`$content[…]` steht als Text im Konfigurator** – das funktioniert nur in Magento 2 mit aktiver **CMS Block Integration**, im Inhalt eines Statischen Felds nur mit V3. Prüfe außerdem die Kennung des CMS-Blocks.
3. **Eingefügte `<style>`-Angaben verschwinden** – der Editor entfernt sie. Lege Formatierungen über eine **CSS-Klasse** und das eigene CSS der Komponente an.
4. **Ein Bild lässt sich nicht einfügen** – das Bild ist größer als 5 MB. Verkleinere es und lade es erneut hoch.
5. **Das Diagramm zeigt nur einen Platzhalter** – die Komponente läuft mit V3. Diagramme stellt nur Legacy dar.

## Nächste Schritte

- [Uploads & Deep Links](/docs/uploads-und-deep-links)
- [Der Aktions-Button](/docs/aktions-button)
- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [Regelwerk aufbauen](/docs/regelwerk-aufbauen)

---

# Komponenten verwalten

Source: https://configento.app/docs/komponenten-verwalten
Section: Konfigurator aufbauen

In der **Komponenten-Übersicht** findest du alle Konfiguratoren deiner Service Order. Hier legst du neue an, suchst, sortierst mit Tags, duplizierst, sicherst Komponenten als ZIP und spielst sie wieder ein – auch in eine andere Service Order. Dieser Artikel erklärt jede dieser Aufgaben.

## Die Komponenten-Übersicht

Du erreichst sie über **Komponenten** in der Hauptnavigation; nach dem Öffnen des Admins aus dem Service-Portal landest du direkt hier.

![Komponenten-Übersicht mit Suche, Tags, Kacheln und Liste, „Neue Komponente“ und „ZIP importieren“](/storage/app/media/docs/komponenten-verwalten/01-uebersicht.webp)

Oben findest du:

| Element | Wirkung |
|---|---|
| **Komponenten suchen…** | Sucht im Titel – in allen Sprachen – und in der ID |
| **Tags** | Filtert nach Tags, siehe [Tags](#tags) |
| **Kachel-Ansicht** / **Listen-Ansicht** | Wechselt die Darstellung. Der Admin merkt sich deine Wahl. |
| **Neue Komponente** | Legt eine leere Komponente an |
| **ZIP importieren** | Spielt eine exportierte Komponente ein, siehe [Export und Import als ZIP](#export-und-import-als-zip) |
| **Komponenten aus der Cloud abgleichen** | Nur bei Konten mit klassischer Cloud: holt Komponenten, die außerhalb dieses Admins angelegt oder gelöscht wurden |

### Was eine Komponente in der Übersicht zeigt

- **Titel** – in der Sprache, in der die Komponente angelegt wurde.
- **ID** – die Nummer, mit der du die Komponente im Shop einem Produkt zuordnest. Bei einer Komponente, die noch nie veröffentlicht wurde, steht **ID —**.
- **Lokal** – die Komponente wurde noch nie veröffentlicht und existiert nur als Entwurf. Solche Komponenten stehen immer oben.
- **V3** – die Komponente braucht die Frontend-Engine V3, etwa weil sie ein Captcha enthält. Ältere Shop-Plugins können sie nicht laden – siehe [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3#das-kennzeichen-v3).
- **Tags** – farbige Markierungen, die du selbst vergibst.

Fährst du mit der Maus über eine Komponente, erscheinen die Aktionen **Anhänge**, **Komponente exportieren**, **Komponente duplizieren** und **Komponente löschen**. Ein Klick auf die Komponente selbst öffnet den Editor.

## Neue Komponente anlegen

1. Klicke auf **Neue Komponente**.
2. Gib einen **Titel** ein, z. B. „Rollo nach Maß“.
3. Klicke auf **Erstellen**. Der Editor öffnet sich mit einer leeren Komponente.

Die neue Komponente ist **Lokal**, bis du sie zum ersten Mal veröffentlichst. Erst dann bekommt sie ihre ID. Wie es weitergeht, zeigt [Erste Komponente anlegen](/docs/erste-komponente-anlegen).

### Beispielkomponenten

Ist deine Service Order noch leer, bietet dir der Admin beim ersten Besuch vier **Beispielkomponenten** an: „Dein Arbeitsbereich ist noch leer. Sollen wir vier Beispielkomponenten anlegen?“ Sie zeigen ein kombiniertes Produktbild, Kombinationsmerkmale mit Formeln, ein Regelwerk und grafische Icons.

Mit **Ja, anlegen** erscheinen sie in der Übersicht. Sie werden im Hintergrund veröffentlicht und funktionieren damit sofort im Shop – das dauert einen Moment. Du kannst sie bearbeiten, veröffentlichen oder löschen wie jede andere Komponente.

Hast du das Angebot mit **Nein, danke** abgelehnt, erreichst du es über **Einführung** in der Hauptnavigation wieder, solange die Übersicht leer ist.

## Tags

Mit Tags ordnest du viele Komponenten, etwa nach Produktlinie, Kunde oder Status.

**Tag zuweisen:**

1. Klicke bei der Komponente auf das Tag-Symbol (**Tags zuweisen**).
2. Hake vorhandene Tags an, oder gib unter **Neuer Tag** einen Namen ein und klicke auf **Hinzufügen**.

**Nach Tags filtern:** Klicke oben auf **Tags** und wähle einen oder mehrere Tags. Die Übersicht zeigt dann alle Komponenten, die **mindestens einen** der gewählten Tags tragen. **Filter zurücksetzen** zeigt wieder alle. Der Filter bleibt erhalten, solange der Browser-Tab offen ist.

**Tags verwalten:** Unter **Tags** → **Tags verwalten** benennst du Tags um, änderst ihre Farbe oder löschst sie (**Tag löschen**). Ein gelöschter Tag verschwindet von allen Komponenten.

Gut zu wissen:

- Tags gehören zur Service Order. Sie werden nicht in die Cloud übertragen und haben keinen Einfluss auf den Shop.
- Tags werden nicht mit exportiert. Beim Duplizieren bekommt die Kopie dieselben Tags wie das Original.
- Tags an einer **lokalen** Komponente bleiben beim ersten Veröffentlichen erhalten.

## Komponente duplizieren

**Komponente duplizieren** legt eine vollständige Kopie an: alle Gruppen, Merkmale, Werte, Regeln, Einstellungen und Bilder. Die Kopie

- heißt wie das Original mit vorangestelltem „Kopie - “ – in jeder Sprache in deren Wort, z. B. „copy - “ im Englischen, „copie - “ im Französischen,
- ist **Lokal**, also noch nicht veröffentlicht,
- öffnet sich direkt im Editor,
- bleibt mit denselben [Bausteinen](#bausteine) verknüpft wie das Original.

Die Bilder werden kopiert. Änderst du an der Kopie ein Bild, bleibt das Original unberührt.

Benenne die Kopie unter **Einstellungen** → **Allgemein** → **Titel** um, bevor du sie veröffentlichst.

## Export und Import als ZIP

Mit dem ZIP-Export sicherst du eine Komponente als Datei – zur Ablage, als Vorlage oder um sie in eine andere Service Order zu übertragen.

### Exportieren

1. Fahre mit der Maus über die Komponente und klicke auf **Komponente exportieren**.
2. Der Admin meldet **Exportieren… bitte warten** und danach **Download gestartet**.

Die ZIP-Datei enthält die komplette Komponente mit allen Bildern. Sie enthält den **Entwurf** – also auch Änderungen, die du gespeichert, aber noch nicht veröffentlicht hast. Bei Komponenten mit vielen Bildern dauert der Export etwas länger.

### Importieren

1. Klicke in der Übersicht auf **ZIP importieren**.
2. Wähle die ZIP-Datei – höchstens 50 MB.
3. Der Admin legt daraus eine neue Komponente an und öffnet sie im Editor.

Die importierte Komponente ist **Lokal** und bekommt beim ersten Veröffentlichen eine neue ID. Sie ersetzt keine vorhandene Komponente – importierst du dieselbe Datei zweimal, hast du zwei Komponenten.

Verknüpfungen mit [Bausteinen](#bausteine) kommen beim Import nicht mit. Die Preistabellen sind in der importierten Komponente als eigene Kopie enthalten.

### Eine Komponente in eine andere Service Order übertragen

Jede Service Order hat ihren eigenen Arbeitsbereich. So nimmst du eine Komponente mit, etwa von einem Test- in ein Live-Konto oder in den Arbeitsbereich deines Shopify-Shops:

1. Öffne im Service-Portal unter **Dienste** die Service Order, in der die Komponente liegt, mit **Verwalten**.
2. Exportiere die Komponente als ZIP.
3. Öffne im Portal die Ziel-Service-Order mit **Verwalten**.
4. Importiere die ZIP-Datei mit **ZIP importieren**.
5. Prüfe die Komponente in der Vorschau und **veröffentliche** sie.
6. Ordne im Shop die neue ID dem Produkt zu.

Einstellungen der Service Order – Sprachen, Domänen, E-Mail-Versand, Branding – reisen nicht mit. Prüfe sie in der Ziel-Service-Order unter **Einstellungen** (siehe [Globale Einstellungen](/docs/globale-einstellungen)), vor allem, wenn die Komponente einen [Aktions-Button](/docs/aktions-button) mit E-Mail-Versand hat.

## Komponente löschen

1. Fahre mit der Maus über die Komponente und klicke auf **Komponente löschen**.
2. Bestätige **Komponente löschen?** mit **Ja, löschen**.

Gelöscht werden der Entwurf, alle Versionen und – bei einer veröffentlichten Komponente – auch die veröffentlichte Fassung. **Die Komponente verschwindet damit sofort aus allen Shops**, in denen sie eingebunden ist. Das lässt sich nicht rückgängig machen.

Willst du eine Komponente nur vorübergehend aus dem Verkehr ziehen, entferne sie im Shop vom Produkt, statt sie zu löschen. Zur Sicherheit kannst du sie vorher exportieren.

## Anhänge

Unter **Anhänge** siehst du, was zu einer Komponente bei deinen Kunden angefallen ist: **Hochgeladene Dateien** aus Datei-Upload-Merkmalen, **Kombinationsbilder**, **Konfigurationsdateien** und **Deep Links**. Mit **Sitzung löschen** entfernst du die Daten einer Kundensitzung.

## Bausteine

Preistabellen und Staffelpreise, die mehrere Komponenten gemeinsam nutzen, pflegst du zentral unter **Bausteine** in der Hauptnavigation. Ändert sich ein Baustein, aktualisiert der Admin alle verknüpften Komponenten – beim Speichern entscheidest du mit **Betroffene Komponenten veröffentlichen**, ob sie auch gleich veröffentlicht werden.

Beim Duplizieren bleibt die Verknüpfung erhalten, beim ZIP-Import nicht.

## Werte einer Komponente austauschen

Einzelne Wertelisten – etwa alle Farben eines Merkmals – tauschst du nicht über den Komponenten-Export aus, sondern direkt am Merkmal mit **Werte exportieren** und **Werte importieren** als CSV oder ZIP mit Bildern. Wie das geht, steht in [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen#werte-importieren-und-exportieren).

## Fehlersuche

1. **Eine Komponente fehlt in der Übersicht** – prüfe Suche und Tag-Filter (**Filter zurücksetzen**). Bei Konten mit klassischer Cloud hilft **Komponenten aus der Cloud abgleichen**, wenn sie außerhalb dieses Admins angelegt wurde.
2. **Der Import bricht ab** – die Datei ist keine Komponenten-ZIP aus einem Export oder größer als 50 MB. Die Datei muss so aufgebaut sein, wie der Export sie erzeugt.
3. **Nach dem Duplizieren passiert nichts** – warte einen Moment, die Kopie entsteht mit allen Bildern. Erscheint sie nicht, lade die Übersicht neu und prüfe, ob eine Komponente mit „Kopie - “ entstanden ist.
4. **Die importierte Komponente funktioniert im Shop nicht** – sie hat beim ersten Veröffentlichen eine neue ID bekommen. Ordne im Shop die neue ID zu und prüfe die Domänen unter **Einstellungen** → **Domänen**.
5. **Ein Kunde sieht den Konfigurator nicht mehr** – prüfe, ob die Komponente gelöscht wurde. Eine gelöschte Komponente lässt sich nur aus einem vorher erstellten Export wiederherstellen – als neue Komponente mit neuer ID.

## Nächste Schritte

- [Erste Komponente anlegen](/docs/erste-komponente-anlegen)
- [Komponenten-Einstellungen](/docs/komponente-einstellungen)
- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [Globale Einstellungen](/docs/globale-einstellungen)

---

# Mehrsprachige Konfiguratoren

Source: https://configento.app/docs/mehrsprachige-konfiguratoren
Section: Konfigurator aufbauen

Ein Konfigurator kann in vielen Sprachen erscheinen: Titel, Merkmale, Werte, Hinweise und die Texte des Aktions-Buttons pflegst du je Sprache, und der Shop zeigt automatisch die passende Fassung. Dieser Artikel zeigt, wie du Sprachen aktivierst, Inhalte übersetzt, welche Sprache der Shop wählt und was passiert, wenn eine Übersetzung fehlt.

## Zwei verschiedene Sprachen: Admin und Inhalt

| Sprache | Was sie bestimmt | Wo du sie einstellst |
|---|---|---|
| **Sprache des Admins** | Menüs, Knöpfe und Meldungen im Admin – Deutsch, Englisch, Französisch oder Spanisch | Der Admin übernimmt die Sprache, die im Service-Portal eingestellt ist, wenn du ihn mit **Verwalten** öffnest |
| **Inhaltssprache** | Die Texte deiner Konfiguratoren, die deine Kunden sehen | **Einstellungen** → **Lokalisierung** → **Aktive Sprachen** |

Beide sind unabhängig: Du kannst den Admin auf Deutsch bedienen und dabei die englischen und französischen Texte deiner Konfiguratoren pflegen. Willst du die Sprache des Admins wechseln, stelle sie im Portal um (siehe [Login & Navigation](/docs/login-und-account-navigation)) und öffne den Admin erneut.

## Sprachen aktivieren

Die Inhaltssprachen gelten für alle Komponenten deiner Service Order.

1. Öffne **Einstellungen** → **Lokalisierung**.
2. Wähle unter **Aktive Sprachen** mit **Sprache hinzufügen…** eine Sprache aus. Zur Wahl stehen 39 Sprachen und Varianten, darunter mehrere Regionen derselben Sprache – etwa `de_DE`, `de_AT` und `de_CH` oder `en_GB` und `en_US`.
3. Lege unter **Standardsprache** die Hauptsprache deiner Inhalte fest.
4. Speichere mit **Einstellungen speichern**.

Mit **×** entfernst du eine Sprache wieder. Bereits gepflegte Übersetzungen bleiben in den Komponenten erhalten, du siehst sie im Editor nur nicht mehr.

Mehr zu diesem Reiter: [Globale Einstellungen](/docs/globale-einstellungen#lokalisierung).

### Region oder nur Sprache?

Lege nur die Varianten an, die du wirklich unterschiedlich pflegst. Für einen einheitlichen englischen Text genügt eine englische Variante – der Shop findet sie auch, wenn er nach einer anderen englischen Region fragt (siehe [Wenn eine Übersetzung fehlt](#wenn-eine-übersetzung-fehlt)).

## Die Standardsprache der Komponente

Jede Komponente hat eine **Standardsprache**: die Sprache, in der du sie aufbaust. Du stellst sie im Editor unter **Einstellungen** → **Allgemein** → **Grundeinstellungen** bei **Standardsprache für diese Komponente** ein, oder du übernimmst mit **Globale Einstellungen verwenden** die Standardsprache des Kontos – Editor und Konfigurator richten sich dann nach der Standardsprache unter **Einstellungen** → **Lokalisierung**.

In der Standardsprache siehst du im Editor alle Einstellungen. In jeder anderen Sprache nur die Felder, die übersetzt werden.

## Inhalte übersetzen

Hat dein Konto mehrere Sprachen aktiv, erscheint oben im Editor **Inhaltssprache:** mit einem Knopf je Sprache. Die Standardsprache ist mit **(Standard)** markiert.

![Übersetzungsmodus: Inhaltssprache gewählt, rechts der Text der Standardsprache und die Übersetzung von Merkmal und Werten](/storage/app/media/docs/mehrsprachige-konfiguratoren/01-uebersetzungsmodus.webp)

1. Baue die Komponente zuerst vollständig in der Standardsprache auf.
2. Klicke bei **Inhaltssprache:** auf die Sprache, die du übersetzen willst. Der Editor zeigt jetzt **Übersetzungsmodus – nur übersetzbare Felder sichtbar**.
3. Wähle links ein Merkmal. Rechts siehst du unter **Übersetzung – <Sprache>** die übersetzbaren Felder; als Platzhalter steht jeweils der Text der Standardsprache.
4. Übersetze und **speichere**.

### Was du je Sprache pflegst

| Wo | Übersetzbare Felder |
|---|---|
| **Merkmal** | **Bezeichnung**, **Informationen**, **Zusätzliche Informationen** |
| **Werte** eines Merkmals | Bezeichnung jedes Werts, aufklappbar auch seine Informationen |
| **Kleines Eingabefeld**, **Großes Eingabefeld**, **Datum** | **Standardwert** |
| **Statisches Feld** | **Inhalt** |
| **Aktions-Button** | **Bezeichnung**, **Betreff**, **E-Mail-Inhalt**, **PDF-Inhalt** – siehe [Der Aktions-Button](/docs/aktions-button) |
| **Gruppe** | **Gruppenname** – hier stehen alle Sprachen untereinander, unabhängig von der gewählten Inhaltssprache |
| **Komponente** | **Titel** und **Überschrift** unter **Einstellungen** → **Allgemein**, jeweils für die gewählte Inhaltssprache |

**Nicht** je Sprache gibt es alles, was nicht als Text beim Kunden ankommt: interne Namen, der **Wert** eines Werts, Preise, Formeln, Regeln und Bilder. Auch die **Fehlermeldung** einer Regel hat nur einen Text für alle Sprachen – formuliere sie in der Sprache, die die meisten deiner Kunden sprechen. Ältere Regeln, deren Meldung noch je Sprache gespeichert ist, zeigen im Feld den deutschen Text (sonst den ersten vorhandenen); beim Speichern wird daraus ein Text für alle Sprachen.

### Übersetzen mit dem KI-Assistenten

Der [KI-Assistent](/docs/ki-agent-konfigurator-aufbauen) übersetzt für dich, zum Beispiel: „Übersetze alle Merkmale und Werte dieser Komponente ins Französische.“ Er schreibt nur in Sprachen, die in deinem Konto aktiv sind. Fehlt die gewünschte Sprache, bittet er dich, sie zuerst unter **Einstellungen** → **Lokalisierung** zu aktivieren.

Prüfe das Ergebnis in der Vorschau, bevor du veröffentlichst – vor allem Fachbegriffe deiner Branche.

## Übersetzung prüfen

Schalte in der mittleren Spalte auf **Vorschau**. Oben in der Vorschau wählst du die Sprache, in der du den Konfigurator sehen willst – so sieht ihn ein Kunde im Shop in dieser Sprache. Die Vorschau zeigt den gespeicherten Stand.

Erst nach dem **Veröffentlichen** erscheinen die Übersetzungen im Shop – siehe [Komponenten-Einstellungen](/docs/komponente-einstellungen#veröffentlichen-im-detail).

## Welche Sprache der Shop zeigt

Die Sprache bestimmt dein Shop, nicht die Komponente:

| Integration | Woher die Sprache kommt |
|---|---|
| **Magento 2** | Die Sprache der Store-View, in der der Kunde einkauft |
| **Shopware 6** | Die Sprache, in der der Kunde den Shop gerade ansieht |
| **Shopify** | Die Sprache, in der der Kunde den Shop gerade ansieht |
| **HTML-Snippet (V3)** | Das Attribut `data-configento-locale`, z. B. `de_DE`. Auf Wunsch fragt der Konfigurator den Besucher zuerst nach der Sprache – siehe [HTML-Snippet Integration](/docs/html-snippet-integration#sprachen). |
| **HTML-Snippet (klassisch)** | Die Spracheinstellung im Browser des Besuchers. Meldet der Browser nur eine Sprache ohne Region (z. B. „en“), lädt der Konfigurator Deutsch. |

Pflegst du eine Sprache, die dein Shop nicht anbietet, ist sie im Shop nicht zu sehen. Bietet dein Shop eine Sprache an, für die die Komponente keine Texte hat, greift die Regel im nächsten Abschnitt.

## Wenn eine Übersetzung fehlt

Findet der Konfigurator keinen Text in der Sprache des Shops, nimmt er einen Ersatz. Wie er sucht, hängt von der [Frontend-Engine](/docs/frontend-engine-legacy-v3) ab:

| Reihenfolge | V3 | Legacy |
|---|---|---|
| 1. | Genau die Sprache des Shops, z. B. `en_GB` | Genau die Sprache des Shops |
| 2. | Dieselbe Sprache in einer anderen Region, z. B. `en_US` | Die **Standardsprache der Komponente** |
| 3. | Die erste vorhandene Übersetzung | Dieselbe Sprache in einer anderen Region |
| 4. | – | Die erste vorhandene Übersetzung |

Ein englischer Kunde sieht also bei fehlender Übersetzung in Legacy meist die Standardsprache, in V3 eine andere vorhandene Übersetzung – in der Regel die, in der du die Komponente angelegt hast. Am sichersten ist es, jede Sprache, die dein Shop anbietet, vollständig zu übersetzen.

### Beschriftungen des Konfigurators

Neben deinen Texten zeigt der Konfigurator eigene Beschriftungen wie „Bitte wählen“ oder „Weiter“. Diese bringt die Frontend-Engine mit:

- **V3** hat sie auf Deutsch, Englisch, Französisch, Spanisch, Italienisch und Niederländisch. Bei anderen Sprachen nimmt V3 die Sprache des Browsers, sonst Englisch.
- **Legacy** hat sie nur für genau `de_DE`, `fr_FR`, `it_IT` und `nl_NL`. In allen anderen Sprachen und Varianten – auch Englisch oder `de_AT` – erscheinen die Grundtexte, teils unvollständig.

### E-Mails und PDFs

Der [Aktions-Button](/docs/aktions-button) verschickt E-Mails und PDFs in der Sprache, in der der Kunde den Konfigurator benutzt. Fehlt dort ein Betreff oder Inhalt, nimmt configento.app die Standardsprache der Komponente. Legacy entscheidet nach der Sprache des Browsers: Deutsch oder sonst Englisch.

## Fehlersuche

1. **Oben im Editor fehlt „Inhaltssprache:“** – in deinem Konto ist nur eine Sprache aktiv. Füge unter **Einstellungen** → **Lokalisierung** weitere hinzu.
2. **Ich sehe nur einen Teil der Einstellungen** – du bist im Übersetzungsmodus. Wechsle bei **Inhaltssprache:** auf die Sprache mit **(Standard)**.
3. **Im Shop erscheint die falsche Sprache** – prüfe in der Tabelle [Welche Sprache der Shop zeigt](#welche-sprache-der-shop-zeigt), woher die Sprache kommt. Fehlt die Übersetzung, siehst du den Ersatz aus [Wenn eine Übersetzung fehlt](#wenn-eine-übersetzung-fehlt).
4. **Die Übersetzung ist im Shop noch nicht da** – du hast gespeichert, aber nicht veröffentlicht.
5. **Eine Fehlermeldung erscheint in allen Sprachen gleich** – Fehlermeldungen von Regeln haben nur einen Text. Siehe [Was du je Sprache pflegst](#was-du-je-sprache-pflegst).
6. **Der Admin ist in der falschen Sprache** – der Admin übernimmt die Sprache des Service-Portals beim Öffnen. Stelle sie dort um und öffne den Admin mit **Verwalten** erneut.

## Nächste Schritte

- [Globale Einstellungen](/docs/globale-einstellungen)
- [Komponenten-Einstellungen](/docs/komponente-einstellungen)
- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [HTML-Snippet Integration](/docs/html-snippet-integration)

---

# Uploads & Deep Links

Source: https://configento.app/docs/uploads-und-deep-links
Section: Konfigurator aufbauen

Mit dem Datentyp **Dateiupload** laden deine Kunden im Konfigurator eigene Dateien hoch – etwa eine Druckvorlage, ein Logo oder eine Skizze. Mit **Deep Links** speicherst du eine Konfiguration und öffnest sie später wieder, zum Beispiel aus einer E-Mail heraus. Dieser Artikel zeigt, wie du beides einrichtest, wohin hochgeladene Dateien gehen und wo sich die beiden [Frontend-Engines](/docs/frontend-engine-legacy-v3) unterscheiden.

## Dateiupload anlegen

1. Lege im Strukturbaum ein neues Merkmal an oder wähle ein bestehendes.
2. Stelle unter **Grundeinstellungen** die **Datenkategorie** auf **Frontend** und den **Datentyp** auf **Dateiupload**.
3. Trage im Abschnitt **Upload-Einstellungen** die Grenzen ein (siehe unten).
4. Speichere und veröffentliche die Komponente.

Den Datentyp **Dateiupload** gibt es nur im Tarif **Ultimate**. Mehr zu Datenkategorien und Datentypen: [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen).

## Upload-Einstellungen

| Feld | Bedeutung |
|---|---|
| **Erlaubte Dateitypen/-endungen** | Kommagetrennte Liste der erlaubten Endungen, z. B. `.jpg,.png,.pdf`. Den Punkt kannst du weglassen – `jpg,png,pdf` funktioniert genauso. Leer bedeutet: alle Dateitypen. |
| **Max. Dateigröße (MB)** | Höchstgröße einer einzelnen Datei in Megabyte. Eine Zahl ohne Einheit gilt als MB. Unabhängig davon nimmt configento.app höchstens 25 MB pro Datei an. |
| **Min. Dateien** | Wie viele Dateien der Kunde mindestens hochladen muss. Ist das Merkmal kein **Pflichtfeld**, gilt die Untergrenze nur, sobald er überhaupt eine Datei hochlädt. |
| **Max. Dateien** | Wie viele Dateien der Kunde höchstens hochladen darf |

Unter **Verhalten** stellst du wie bei jedem Merkmal **Pflichtfeld** und **Sichtbarkeit** ein. Über **Informationen** gibst du dem Kunden einen Hinweis mit, etwa „Bitte als PDF mit 3 mm Beschnitt“.

## Was der Kunde sieht

Der Kunde zieht Dateien in das Feld oder wählt sie per Klick aus. Hochgeladene Dateien erscheinen im Feld, und der Kunde kann jede einzeln wieder entfernen.

Ist eine Datei zu groß, hat sie eine nicht erlaubte Endung oder sind es zu viele Dateien, erscheint eine Meldung, und die Datei wird nicht hochgeladen.

## Wohin die Dateien gehen

- **Beim Hochladen:** Die Datei wird sofort hochgeladen und bei configento.app gespeichert – nicht erst beim Klick auf **In den Warenkorb**.
- **Magento 2:** Mit der Einstellung **Activate Asset Sync?** lädt die Erweiterung die hochgeladenen Dateien regelmäßig in deine Magento-Installation. Siehe [Magento-Plugin installieren](/docs/magento-plugin-installieren#asset-synchronisation).
- **Download-Link:** In V3 bekommt jede Datei eine eigene Download-Adresse bei configento.app. Sie öffnet die Datei immer als Download.
- **Aktions-Button:** Eine E-Mail oder ein PDF enthält keine Dateien als Anhang. Die Konfigurationstabelle (`{{configuration_table}}`) verlinkt in V3 jede hochgeladene Datei zum Download. Mit dem Platzhalter `{{characteristic:NAME.value}}` übernimmst du die Dateinamen in den Text. Siehe [Der Aktions-Button](/docs/aktions-button#platzhalter).

Mit Legacy muss in Shopware 6 und Magento 2 die Einstellung **Dropzone-Plugin laden** eingeschaltet sein, sonst funktioniert der Upload im Shop nicht.

## Unterschiede zwischen Legacy und V3

| | Legacy | V3 |
|---|---|---|
| Upload | Funktioniert | Funktioniert, auch in Shopify |
| **Min. Dateien** und **Pflichtfeld** | Werden geprüft; ohne Angabe bei **Min. Dateien** verlangt ein Pflichtfeld eine Datei | Werden genauso geprüft, bevor der Kunde in den Warenkorb legt oder den Aktions-Button nutzt |
| Dateien in der Konfigurationstabelle des Aktions-Buttons | Dateinamen | Dateinamen, jeweils als Download-Link |
| Anzeige der Grenzen | – | Neben dem Feld stehen erlaubte Endungen, Höchstgröße und Anzahl |
| Deep Link anlegen | Leiste mit `?tb=1`, Adresse im Hinweisfenster | Leiste mit `?tb=1`, Adresse im Feld und in der Zwischenablage |
| Deep Link öffnen | Links aus Legacy | Links aus V3 und aus Legacy |

Mehr zu den Engines: [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Konfiguration wieder öffnen

### Bearbeiten aus dem Warenkorb

- **Magento 2:** Über **Bearbeiten** im Warenkorb oder Wunschzettel öffnet sich der Konfigurator wieder mit der gespeicherten Auswahl.
- **Shopify:** Mit der Warenkorb-Erweiterung **Configento Cart** steht an jeder konfigurierten Position der Link **Bearbeiten**. Er führt zur Produktseite mit der bisherigen Auswahl; nach dem erneuten Hinzufügen ersetzt die neue Konfiguration die alte Position. Siehe [Shopify-Plugin installieren](/docs/shopify-plugin-installieren).

### Deep Link

Ein Deep Link ist die Adresse der Produktseite mit dem Zusatz `?dl=` und der Kennung einer gespeicherten Konfiguration, zum Beispiel:

```
https://dein-shop.de/carport.html?dl=KENNUNG
```

Öffnet jemand diese Adresse, lädt der Konfigurator mit der gespeicherten Auswahl. Ist die Kennung unbekannt, startet der Konfigurator ganz normal ohne Auswahl.

**Deep Link anlegen:** Hänge an die Adresse der Produktseite `?tb=1` an. Oben auf der Seite erscheint eine Leiste mit dem Button **Deep Link anlegen** (Legacy) bzw. **Deep Link erzeugen** (V3). Stelle die Konfiguration zusammen und klicke auf den Button:

- **Legacy** zeigt die fertige Adresse in einem Hinweisfenster.
- **V3** speichert die Konfiguration, zeigt die Adresse in einem Feld in der Leiste und kopiert sie in die Zwischenablage. Das funktioniert im Shop – mit Magento 2, Shopify und dem HTML-Snippet –, nicht in der Vorschau im Admin.

![Produktseite mit ?tb=1: oben die Leiste mit dem Button Deep Link erzeugen, darunter der Konfigurator](/storage/app/media/docs/uploads-und-deep-links/01-deep-link-leiste.webp)

Die Leiste ist ein Werkzeug für dich; ohne `?tb=1` sehen deine Kunden sie nicht.

**Deep Link per JavaScript (V3):** Wer die Adresse selbst erzeugen will, etwa für einen eigenen „Teilen“-Button, nutzt die JavaScript-Schnittstelle: `storeAsset()` speichert die aktuelle Konfiguration und liefert ihre Kennung als `id`; die hängst du als `?dl=` an die Adresse. Mehr zur Schnittstelle: [JavaScript-Schnittstelle (V3)](/docs/javascript-schnittstelle#konfiguration-speichern-und-wieder-öffnen).

```html
<script>
  Configento.ready.then(async function () {
      var gespeichert = await Configento.first().storeAsset();
      var link = location.origin + location.pathname + '?dl=' + gespeichert.id;
      console.log('Deep Link:', link);
  });
</script>
```

**Nach dem Umstellen auf V3:** Deep Links, die du mit Legacy angelegt hast (kurze Kennung aus Ziffern und Buchstaben), öffnet V3 weiterhin – die gespeicherte Konfiguration kommt dann aus der klassischen Cloud. Links aus V3 haben eine lange Kennung mit Bindestrichen; Legacy kann sie nicht öffnen. Stellst du eine Komponente von V3 zurück auf Legacy, lege die Links also neu an.

## Fehlersuche

1. **Der Upload bricht mit „Server hat den Upload abgelehnt (HTTP 413)“ ab** – die Datei ist größer als 25 MB. Bitte den Kunden um eine kleinere Datei.
2. **Im Shop erscheint kein Upload-Feld** – die Komponente läuft mit Legacy, und in Shopware 6 oder Magento 2 ist **Dropzone-Plugin laden** ausgeschaltet. Schalte die Einstellung ein und leere den Cache.
3. **Eine Datei wird abgelehnt** – prüfe **Erlaubte Dateitypen/-endungen** und **Max. Dateigröße (MB)**. Die Endung muss genau passen: `.jpeg` ist nicht `.jpg`.
4. **Die Dateien fehlen in der E-Mail des Aktions-Buttons** – Dateien werden nicht angehängt. Füge `{{configuration_table}}` ein, dann stehen die Dateien als Download-Links in der E-Mail, oder übernimm die Namen mit `{{characteristic:NAME.value}}`.
5. **Ein Deep Link öffnet einen leeren Konfigurator** – die Kennung ist falsch abgeschrieben, die Konfiguration gehört zu einer anderen Komponente, oder ein V3-Link wird mit Legacy geöffnet. Lege den Link auf der richtigen Produktseite neu an.
6. **Mit `?tb=1` erscheint keine Leiste** – in der Vorschau im Admin gibt es sie nicht; öffne die Produktseite im Shop. Erscheint sie auch dort nicht, lädt die Seite keinen Konfigurator.

## Nächste Schritte

- [Frontend-Merkmale: Statisches Feld & Diagramm](/docs/frontend-merkmale)
- [Der Aktions-Button](/docs/aktions-button)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)

---

# Frontend-Engine: Legacy oder V3

Source: https://configento.app/docs/frontend-engine-legacy-v3
Section: Konfigurator aufbauen

Jede Komponente läuft im Shop mit einer von zwei **Frontend-Engines**: **Legacy**, dem bewährten Konfigurator, oder **V3**, der neuen Engine im Beta-Stadium. Beide lesen dieselben Daten – Merkmale, Werte, Preise und Regeln. Sie stellen sie aber unterschiedlich dar, und einige Funktionen gibt es nur in einer der beiden. Dieser Artikel zeigt, wo welche Engine läuft, worin sie sich unterscheiden und wie du sicher umstellst.

## Wo du die Engine einstellst

Die Engine stellst du **pro Komponente** ein:

1. Öffne die Komponente und wechsle links in den Reiter **Einstellungen**.
2. Im Reiter **Allgemein** findest du ganz unten **Frontend-Engine** mit dem Feld **Engine**.
3. Wähle **Legacy (Standard)** oder **V3 (Beta)**.
4. Speichere und **veröffentliche** die Komponente. Erst dann gilt die neue Engine im Shop.

Die Einstellung ändert **nicht**:

- deine Daten – Merkmale, Werte, Preise, Regeln und Tabellen bleiben, wie sie sind,
- den Editor im Admin – du bearbeitest die Komponente genauso wie vorher,
- das Veröffentlichen – Prüfung und Ablauf sind für beide Engines gleich.

Du kannst also jederzeit zurückstellen.

## Welche Engine wo läuft

Nicht jede Integration richtet sich nach der Einstellung:

| Wo die Komponente läuft | Engine |
|---|---|
| **Vorschau im Admin** | Die eingestellte Engine. So testest du eine Umstellung, bevor deine Kunden sie sehen. |
| **Magento 2** | Die eingestellte Engine. Komponenten mit Legacy und mit V3 laufen im selben Shop nebeneinander. |
| **Shopify** | Immer **V3**, unabhängig von der Einstellung. |
| **PrestaShop 9** | Immer **V3**, unabhängig von der Einstellung. |
| **Shopware 6** | Immer **Legacy**. Das Shopware-Plugin kann die V3-Engine derzeit nicht laden. |
| **HTML-Snippet** | Bestimmt das Snippet, nicht die Einstellung: Das klassische Snippet der Karte **HTML5** lädt Legacy, das Snippet der Karte **HTML5 (V3 Beta)** lädt V3. |

**Konten ohne klassische Cloud** laufen überall mit **V3**, wo die Engine vom Konto abhängt – die Einstellung **Legacy (Standard)** hat dort keine Wirkung. Du erkennst solche Konten daran, dass unter **Einstellungen → Integrationen** steht: „Shop-Plugins verbinden sich über das Service-Portal — ein Sicherheitstoken ist hier nicht nötig.“

Mehr zu den einzelnen Integrationen: [Magento-Plugin installieren](/docs/magento-plugin-installieren), [Shopware-Plugin installieren](/docs/shopware-plugin-installieren), [Shopify-Plugin installieren](/docs/shopify-plugin-installieren), [PrestaShop-Plugin installieren](/docs/prestashop-plugin-installieren), [HTML-Snippet Integration](/docs/html-snippet-integration).

## Was sich unterscheidet

### Nur in V3

| Funktion | Was Legacy stattdessen macht |
|---|---|
| **Captcha** (Datentyp **Captcha (nur V3)**, schützt den Aktions-Button vor Spam) | Kann es nicht darstellen – siehe [Das Kennzeichen „V3“](#das-kennzeichen-v3) |
| **Kombiniertes Produktbild in PDF und E-Mail** (Platzhalter `{{combined_image}}` im [Aktions-Button](/docs/aktions-button)) | Der Platzhalter bleibt leer |
| **Gewichtung von Regeln** (Feld **Gewichtung** in den Regel-Einstellungen bestimmt die Reihenfolge) | Wertet die Gewichtung nicht aus, Regeln laufen in gespeicherter Reihenfolge |
| **Bedingungen im Staffelpreis** (`>=`, `>`, `=`, `<=`, `<`, `!=`) | Ignoriert die Bedingung und nimmt immer die höchste Stufe, deren Wert kleiner oder gleich der Eingabe ist; liegt die Eingabe unter allen Stufen, gilt die kleinste |
| **Formeln mit Merkmalsnamen ohne `$`** (`breite * hoehe`) und `round(x, 2)` mit Nachkommastellen | Braucht `$breite`; ob `round` bekannt ist, hängt von der Shopseite ab |

### Nur in Legacy

| Funktion | Was V3 stattdessen macht |
|---|---|
| **Darstellung Accordion** | Zeigt die Merkmale ohne Gruppen-Navigation (wie **Keine Gruppen**) |
| **360°-Ansicht** des kombinierten Produktbilds | Zeigt das kombinierte Bild nur als statische Ebenen |
| **Autocomplete** (Auswahl als Suchfeld) | Zeigt eine normale Auswahlliste mit allen Werten |
| **Datumsfeld** mit Kalender und Einschränkungen (z. B. **Vergangene Tage erlauben**) | Zeigt ein normales Textfeld ohne Kalender |
| **Mengen-Vorbelegung** und **Min/Max-Vorbelegung** (Regeltypen) | Überspringt diese Regeln |
| **Mehrzeilige Formeln** mit `var`, `if` oder `for` | Wertet nur **einen** Ausdruck aus; mehrzeilige Formeln liefern kein Ergebnis. Schreibe Bedingungen als `bedingung ? a : b`. |

Mehr zu Formeln: [Formeln & Berechnungen](/docs/preisformeln). Mehr zu Staffelpreisen: [Preisberechnung einrichten](/docs/preisberechnung-einrichten).

## Das Kennzeichen „V3“

Manche Merkmale **brauchen** V3 – derzeit ist das das **Captcha**. Enthält eine Komponente ein solches Merkmal,

- trägt sie in der Komponenten-Übersicht das Kennzeichen **V3**,
- zeigen die Komponenten-Einstellungen den Hinweis **Benötigt Frontend V3**,
- lädt **Magento 2** sie automatisch mit V3 – auch wenn bei **Engine** noch **Legacy (Standard)** steht.

Das Veröffentlichen wird dadurch nicht blockiert. Integrationen, die nur Legacy laden – **Shopware 6** und das klassische **HTML5**-Snippet –, können eine solche Komponente aber nicht richtig anzeigen. Verwende dort kein Captcha.

Das Kennzeichen sagt also nicht, welche Engine du eingestellt hast, sondern dass die Komponente ohne V3 nicht vollständig funktioniert.

## Welche Engine solltest du nehmen?

**Bleib bei Legacy (Standard)**, wenn

- deine Komponente schon live ist und so funktioniert, wie sie soll,
- du Accordion, 360°-Ansicht, Autocomplete, Datumsfelder, Mengen- oder Min/Max-Vorbelegung oder mehrzeilige Formeln verwendest,
- dein Shop auf Shopware 6 läuft.

**Nimm V3 (Beta)**, wenn

- du eine neue Komponente baust und keine der Legacy-Funktionen oben brauchst,
- du Captcha, das kombinierte Produktbild im PDF oder die Gewichtung von Regeln nutzen willst,
- dein Shop auf Shopify oder PrestaShop läuft – dort läuft ohnehin V3.

### Eine bestehende Komponente umstellen

1. Stelle **Engine** auf **V3 (Beta)** und **speichere** – noch nicht veröffentlichen.
2. Prüfe in der **Vorschau**: Erscheinen alle Merkmale? Stimmt der Preis bei einigen typischen Konfigurationen?
3. Achte besonders auf **Staffelpreise**: Steht bei einer Stufe eine andere Bedingung als `>=`, rechnet V3 anders als vorher. Eine Stufe „`>` 10“ greift in V3 erst ab 11, in Legacy schon ab 10.
4. Prüfe **Formeln**: Mehrzeilige Formeln musst du vorher in einen Ausdruck umschreiben.
5. Passt alles, **veröffentliche**. Gefällt dir das Ergebnis nicht, stellst du einfach wieder auf **Legacy (Standard)** und veröffentlichst erneut.

## Fehlersuche

1. **Die Umstellung wirkt im Shop nicht** – die Engine gilt erst nach dem **Veröffentlichen**. Prüfe außerdem die Tabelle oben: Shopify und PrestaShop laufen immer mit V3, Shopware 6 immer mit Legacy, und beim HTML-Snippet entscheidet das Snippet.
2. **Ein Merkmal fehlt oder sieht anders aus** – die Komponente nutzt eine Funktion, die die gewählte Engine nicht kennt. V3 zeigt bei Merkmalen, die es gar nicht kennt, den Hinweis „Unbekannter Merkmal-Typ“. Vergleiche mit den Tabellen oben.
3. **Der Preis weicht nach der Umstellung ab** – meist ein Staffelpreis mit einer Bedingung außer `>=` oder eine Formel, die in einer Engine kein Ergebnis liefert. Teste die betroffene Konfiguration in der Vorschau mit beiden Engines.
4. **Eine Formel liefert in V3 kein Ergebnis** – sie besteht aus mehreren Anweisungen (`var`, `if`, `;`). Schreibe sie als einen Ausdruck, z. B. `$breite > 200 ? $breite * 1.2 : $breite`.
5. **Die Komponente hat das Kennzeichen V3, obwohl Legacy eingestellt ist** – sie enthält ein Captcha. In Magento 2 läuft sie deshalb mit V3; in Shopware 6 und im klassischen HTML5-Snippet funktioniert sie nicht vollständig.

## Nächste Schritte

- [Komponenten-Einstellungen](/docs/komponente-einstellungen)
- [Erste Komponente anlegen](/docs/erste-komponente-anlegen)
- [Preisberechnung einrichten](/docs/preisberechnung-einrichten)
- [Regelwerk aufbauen](/docs/regelwerk-aufbauen)
- [JavaScript-Schnittstelle (V3)](/docs/javascript-schnittstelle)

---

# Erste Komponente anlegen

Source: https://configento.app/docs/erste-komponente-anlegen
Section: Konfigurator aufbauen

In configento.app heißt jeder Konfigurator **Komponente**. Eine Komponente enthält alle Merkmale, Werte, Preise und Regeln für ein Produkt oder eine Produktgruppe. Dieser Artikel führt dich einmal komplett durch: von der leeren Komponente über Merkmale und Aufpreise bis zur veröffentlichten Fassung, die dein Shop anzeigt. Die Details zu jedem Schritt findest du in den verlinkten Fachartikeln.

## Das Prinzip in drei Sätzen

1. Du baust die Komponente im Editor auf und **speicherst** sie. Gespeichert ist ein Entwurf – den sieht nur die Vorschau.
2. Mit **Veröffentlichen** wird der aktuelle Stand geprüft und für die Shops freigegeben.
3. Dein Shop oder deine Website bindet die Komponente über ein Plugin oder ein HTML-Snippet ein und zeigt immer die **zuletzt veröffentlichte** Fassung.

## Schritt 1: Admin öffnen

Melde dich im [Service-Portal](/docs/login-und-account-navigation) an und klicke bei deinem Dienst auf **Verwalten**. Es öffnet sich die Komponenten-Übersicht.

![Komponenten-Übersicht mit Suche, Tags, „Neue Komponente“ und „ZIP importieren“](/storage/app/media/docs/erste-komponente/01-komponenten-uebersicht.webp)

Die Hauptnavigation hat vier Einträge:

| Eintrag | Inhalt |
|---|---|
| **Komponenten** | Alle deine Konfiguratoren |
| **Bausteine** | Zentral gepflegte Preislisten und Tabellen, die mehrere Komponenten nutzen |
| **Einstellungen** | Einstellungen für das ganze Konto, z. B. Sprachen und Integrationen – siehe [Globale Einstellungen](/docs/globale-einstellungen) |
| **Einführung** | Startet die Tour durch die Oberfläche noch einmal |

### Leeres Konto: Beispielkomponenten

Ist dein Konto noch leer, fragt dich der Admin beim ersten Besuch, ob er vier **Beispielkomponenten** anlegen soll. Sie zeigen ein kombiniertes Produktbild, Kombinations- und Formelmerkmale, ein Regelwerk und grafische Icons. Du kannst sie wie jede andere Komponente bearbeiten, veröffentlichen oder löschen – sie eignen sich gut als Vorlage zum Abschauen. Hast du die Frage weggeklickt, erreichst du sie über **Einführung** wieder, solange das Konto leer ist.

## Schritt 2: Komponente anlegen

![Dialog „Neue Komponente“ mit dem Feld „Titel“](/storage/app/media/docs/erste-komponente/02-neue-komponente.webp)

In der Komponenten-Übersicht hast du zwei Wege:

- **Neue Komponente:** Gib einen **Titel** ein, z. B. „Rollo nach Maß“, und klicke auf **Erstellen**. Der Editor öffnet sich mit einer leeren Komponente.
- **ZIP importieren:** Übernimmt eine Komponente, die du vorher mit **Komponente exportieren** als ZIP gesichert hast – etwa aus einem anderen Konto.

Eine bestehende Komponente als Ausgangspunkt nutzt du mit **Komponente duplizieren** auf ihrer Karte.

Lieber per Chat? Der KI-Assistent legt die Komponente samt Merkmalen für dich an – siehe [Mit dem KI-Assistenten](#mit-dem-ki-assistenten).

## Schritt 3: Der Editor im Überblick

![Editor: links der Strukturbaum, in der Mitte die Merkmale, rechts die Einstellungen des gewählten Merkmals](/storage/app/media/docs/erste-komponente/03-editor-ueberblick.webp)

Der Editor hat drei Spalten:

| Bereich | Inhalt |
|---|---|
| **Links** | Vier Reiter: **Merkmale** (der Strukturbaum mit Gruppen und Merkmalen), **Regeln**, **Einstellungen** (der ganzen Komponente) und **Versionen** |
| **Mitte** | Umschalter **Bearbeiten** / **Vorschau**. *Bearbeiten* zeigt alle Merkmale schematisch – ein Klick wählt ein Merkmal aus. *Vorschau* zeigt den echten Konfigurator. |
| **Rechts** | Die **Einstellungen** des ausgewählten Merkmals oder der ausgewählten Gruppe |

Oben rechts findest du **Rückgängig**, **Zurücksetzen** (verwirft alle Änderungen und lädt die zuletzt veröffentlichte Fassung neu) und **Veröffentlichen**. Gibt es ungespeicherte Änderungen, erscheint über dem rechten Bereich der Knopf **Speichern**.

## Schritt 4: Gruppen und Merkmale anlegen

Merkmale liegen immer in einer **Gruppe**. Eine neue Komponente hat noch keine, deshalb beginnst du dort:

1. Klicke im Reiter **Merkmale** auf **Gruppe hinzufügen**. Es entsteht eine Gruppe „Neue Gruppe“. Über das Zahnrad (**Gruppeneinstellungen**) gibst du ihr einen Namen, z. B. „Maße“.
2. Klicke an der Gruppe auf **+** (**Merkmal hinzufügen**). Es entsteht ein Merkmal „Neues Merkmal“ vom Typ **Auswahl**.
3. Stelle rechts unter **Grundeinstellungen** ein:

| Feld | Bedeutung |
|---|---|
| **Bezeichnung** | Was deine Kunden sehen, z. B. „Farbe“ |
| **Interner Name (ID)** | Eindeutiger Name für Formeln und Regeln, z. B. `farbe`. Vergib ihn gleich am Anfang sprechend – den automatisch vergebenen Namen `new_option_…` willst du später in keiner Formel sehen. |
| **Datenkategorie** | Grobe Art des Merkmals (siehe unten) |
| **Datentyp** | Konkrete Darstellung innerhalb der Kategorie |

Wie viele Gruppen du brauchst und wie sie angezeigt werden (ohne Gruppen, als Tabs, als Accordion oder Schritt für Schritt als Wizard), erklärt [Merkmalsgruppen & Wizard](/docs/merkmalsgruppen-wizard).

### Die vier Datenkategorien

| Datenkategorie | Datentypen (Auswahl) | Wofür |
|---|---|---|
| **Diskretes Merkmal** | Auswahl, Radio Buttons, Checkbox, Liste mit Bildern, Mehrfachauswahl | Der Kunde wählt aus festen **Werten**, z. B. Farbe oder Antrieb |
| **Freie Eingabe** | Kleines Eingabefeld, Großes Eingabefeld, Datum | Der Kunde gibt etwas ein, z. B. Breite in cm |
| **Berechnung** | Formel, Preisliste, Einfache Kombination | Der Konfigurator rechnet selbst, z. B. Fläche oder Matrixpreis |
| **Frontend** | Statisches Feld, Aktions-Button, Dateiupload | Inhalte und Aktionen ohne eigene Auswahl, z. B. Hinweistext oder „Angebot anfordern“ |

Alle Typen im Detail: [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen).

## Schritt 5: Werte und Aufpreise

![Einstellungen eines Werts: Bezeichnung, Wert, Preis, Artikelnummer](/storage/app/media/docs/erste-komponente/04-wert-bearbeiten.webp)

Bei einem diskreten Merkmal legst du im Abschnitt **Werte** mit **+ Wert** die Auswahlmöglichkeiten an. Ein Klick auf einen Wert öffnet seine Einstellungen:

| Feld | Bedeutung |
|---|---|
| **Bezeichnung** | Was der Kunde sieht, z. B. „Anthrazit“ |
| **Wert** | Interner Wert, z. B. `anthrazit` – wird in Regeln und Formeln verwendet |
| **Preis** | Aufpreis, wenn der Kunde diesen Wert wählt |
| **Artikelnummer** | Optional, z. B. für Stücklisten im Shop |

Wie Aufpreise angezeigt werden, stellst du für die ganze Komponente im Reiter **Einstellungen** unter **Aufpreis** ein: **Preisanzeige** ein oder aus, **Preistyp** **Absolut** (der Aufpreis des Werts) oder **Relativ** (der Unterschied zur aktuellen Auswahl) und das **Preismuster**.

Preise, die von Eingaben abhängen – Staffeln, Formeln, Preismatrizen –, erklären [Preisberechnung einrichten](/docs/preisberechnung-einrichten), [Preisformeln](/docs/preisformeln) und [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv).

## Schritt 6: Grundeinstellungen der Komponente

![Komponenteneinstellungen, Reiter „Allgemein“ mit dem Abschnitt „Aufpreis“](/storage/app/media/docs/erste-komponente/05-komponenten-einstellungen.webp)

Im linken Reiter **Einstellungen** findest du die Einstellungen der ganzen Komponente, aufgeteilt in **Allgemein**, **Design**, **Reporting** und **Benutzerdefinierte Felder**. Für den Anfang reichen diese aus **Allgemein**:

| Einstellung | Wirkung |
|---|---|
| **Titel** | Name der Komponente in der Übersicht |
| **Überschrift** | Optionale Überschrift über dem Konfigurator |
| **Standardsprache für diese Komponente** | Sprache, in der du die Inhalte pflegst |
| **Darstellung** | Keine Gruppen, Tabs oder Accordion |
| **Frontend-Engine** | **Legacy (Standard)** oder **V3 (Beta)** – siehe unten |

Alle weiteren Einstellungen: [Komponenten-Einstellungen](/docs/komponente-einstellungen).

### Frontend-Engine: Legacy oder V3

Die Engine bestimmt, welcher Konfigurator im Shop läuft. **Legacy** ist der bewährte Standard. **V3** ist die neue Engine im Beta-Stadium; einige Funktionen gibt es nur dort, andere nur in Legacy. Für deine erste Komponente lässt du **Legacy (Standard)** eingestellt. Welche Funktionen es nur in einer Engine gibt, wo welche Engine läuft und was das Kennzeichen **V3** in der Übersicht bedeutet, erklärt [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Schritt 7: Speichern und in der Vorschau testen

![Vorschau im Editor mit Sprachwahl, Desktop/Tablet/Mobile und Gesamtpreis](/storage/app/media/docs/erste-komponente/06-vorschau.webp)

Klicke auf **Speichern**. Jedes Speichern legt im Reiter **Versionen** einen Eintrag an – darüber kannst du später zu einem früheren Stand zurück (**Wiederherstellen**) oder zwei Stände vergleichen.

Schalte dann in der mittleren Spalte auf **Vorschau**. Du siehst den Konfigurator so, wie ihn deine Kunden sehen werden, mit der eingestellten Frontend-Engine. Prüfe:

- Erscheinen alle Merkmale in der richtigen Reihenfolge?
- Stimmen die Aufpreise und der Gesamtpreis?
- Greifen deine Regeln, falls du schon welche hast?

Wichtig zu wissen:

- Die Vorschau zeigt den **zuletzt gespeicherten** Stand. Hast du danach etwas geändert, weist ein gelber Hinweis darauf hin – speichere und lade die Vorschau mit **↺** neu.
- Die Vorschau braucht die Integration **HTML5**. Ist sie aus, bittet dich der Admin, sie zu aktivieren: unter **Einstellungen** → **Integrationen** den Schalter auf der Karte **HTML5** einschalten. Das ist einmalig nötig.
- Mit **In eigenes Fenster verschieben** öffnest du die Vorschau separat – der Editor bekommt dann mehr Platz.

## Schritt 8: Veröffentlichen

![Rückfrage „Komponente veröffentlichen?“](/storage/app/media/docs/erste-komponente/07-veroeffentlichen.webp)

Bis hierher sieht dein Shop nichts davon. Solange der gespeicherte Stand von der veröffentlichten Fassung abweicht, steht oben **Noch nicht live**.

1. Klicke oben rechts auf **Veröffentlichen**.
2. Der Admin prüft die Komponente. **Fehler** – etwa eine Preisliste ohne Tabellen-Konfiguration – blockieren das Veröffentlichen und werden aufgelistet. **Warnungen** – etwa eine leere Formel oder ein doppelt vergebener Interner Name – werden ebenfalls angezeigt, das Veröffentlichen bleibt aber möglich.
3. Bestätige mit **Ja, veröffentlichen**. Dabei werden auch ungespeicherte Änderungen gespeichert.

Ab jetzt zeigen alle Shops diese Fassung. Änderungen, die du danach speicherst, landen wieder nur im Entwurf – bis zum nächsten Veröffentlichen.

## Schritt 9: Im Shop einbinden

Wie die Komponente auf deine Produktseite kommt, hängt von deinem System ab:

- **Magento 2 / Adobe Commerce:** [Magento-Plugin installieren](/docs/magento-plugin-installieren)
- **Shopware 6:** [Shopware-Plugin installieren](/docs/shopware-plugin-installieren)
- **Shopify:** [Shopify-Plugin installieren](/docs/shopify-plugin-installieren)
- **WordPress, TYPO3 oder jede andere Website:** [HTML-Snippet Integration](/docs/html-snippet-integration)

In jedem Fall wählst du dort die Komponente aus, die auf dem Produkt erscheinen soll. Veröffentliche sie vorher – der Shop zeigt nur veröffentlichte Fassungen.

## Mit dem KI-Assistenten

Am unteren Rand des Admins liegt über die volle Breite der **KI-Assistent**. Klicke auf **Neuer Chat** und beschreibe dein Produkt, zum Beispiel:

> Ich verkaufe Rollos nach Maß. Lege eine Komponente „Rollo“ an mit Breite und Höhe in cm (je 40 bis 240), Stoffart (Standard, Verdunkelung +15 €) und Antrieb (Kette, Motor +89 €).

Der Assistent legt Gruppen, Merkmale, Werte und Aufpreise an. Kontrolliere das Ergebnis anschließend im Editor und in der Vorschau, und veröffentliche selbst. Der KI-Assistent verbraucht [KI-Tokens](/docs/ki-tokens) und erscheint nur, wenn er für dein Konto aktiviert ist. Mehr dazu: [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen).

## Häufige Stolpersteine

1. **Der Shop zeigt meine Änderung nicht** – gespeichert ist nicht veröffentlicht. Steht oben **Noch nicht live**, klicke auf **Veröffentlichen**.
2. **Die Vorschau zeigt einen alten Stand** – sie zeigt immer den zuletzt gespeicherten Stand. Speichern, dann mit **↺** neu laden.
3. **Die Vorschau bleibt leer mit einem Hinweis auf HTML5** – die Integration **HTML5** unter **Einstellungen** → **Integrationen** einschalten.
4. **Ich finde keinen Knopf für ein neues Merkmal** – Merkmale brauchen eine Gruppe. Zuerst **Gruppe hinzufügen**, dann an der Gruppe **+**.
5. **Eine Formel findet ein Merkmal nicht** – Formeln verwenden den **Internen Namen (ID)**, nicht die Bezeichnung. Prüfe die Schreibweise.

## Nächste Schritte

- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [Merkmalsgruppen & Wizard](/docs/merkmalsgruppen-wizard)
- [Preisberechnung einrichten](/docs/preisberechnung-einrichten)
- [Regelwerk aufbauen](/docs/regelwerk-aufbauen)
- [Bildvisualisierung & Bilder hochladen](/docs/bildvisualisierung-bilder)
- [Der Aktions-Button](/docs/aktions-button)

---

# Merkmale & Werte anlegen

Source: https://configento.app/docs/merkmale-optionen-anlegen
Section: Konfigurator aufbauen

Merkmale sind die Eigenschaften, die deine Kunden im Konfigurator festlegen – Farbe, Breite, Material, Antrieb. Bei einem **diskreten Merkmal** wählen sie aus festen **Werten** (z. B. Weiß, Anthrazit, RAL 7016), bei einer **freien Eingabe** tippen sie selbst etwas ein (z. B. 1200 mm). Dazu kommen Merkmale, die selbst rechnen oder Inhalte zeigen. Dieser Artikel erklärt alle Datentypen, alle Einstellungen eines Merkmals und eines Werts und wie du viele Werte auf einmal per CSV pflegst.

## Merkmal anlegen

1. Öffne die Komponente. Links im Reiter **Merkmale** siehst du den Strukturbaum mit Gruppen und Merkmalen.
2. Gibt es noch keine Gruppe, klicke unten im Baum auf **Gruppe hinzufügen**. Merkmale liegen immer in einer Gruppe.
3. Klicke an der Gruppe auf **+** (**Merkmal hinzufügen**). Es entsteht ein neues Merkmal vom Typ **Auswahl** und ist sofort ausgewählt.
4. Stelle rechts unter **Grundeinstellungen** die **Bezeichnung**, den **Internen Namen (ID)**, die **Datenkategorie** und den **Datentyp** ein.
5. Bei diskreten Merkmalen legst du im Abschnitt **Werte** die Auswahlmöglichkeiten an.

Ein Klick auf ein Merkmal im Strukturbaum oder in der mittleren Spalte öffnet rechts seine Einstellungen. Ist nichts ausgewählt, steht dort „Merkmal in der Vorschau oder im Strukturbaum auswählen“.

## Datenkategorien und Datentypen

Zuerst wählst du die **Datenkategorie**, dann innerhalb der Kategorie den **Datentyp**. Wechselst du die Kategorie, springt der Datentyp auf den ersten Typ, den dein Tarif erlaubt.

### Diskretes Merkmal

Der Kunde wählt aus Werten, die du vorgibst.

| Datentyp | Darstellung | Typischer Einsatz |
|---|---|---|
| **Auswahl** | Dropdown, ein Wert | Farbe, Material – viele Werte, wenig Platz |
| **Mehrfachauswahl** | Liste, mehrere Werte gleichzeitig | Zubehör, das sich kombinieren lässt |
| **Radio Buttons** | Alle Werte sichtbar, ein Wert | Wenige Werte, die man auf einen Blick vergleichen soll |
| **Checkbox** | Alle Werte sichtbar, mehrere Werte gleichzeitig | Extras zum An- und Abwählen |
| **Liste mit Bildern** | Werte als Bilder (wahlweise mit Bezeichnung), ein Wert | Stoffe, Dekore, Formen |
| **Mehrfachauswahl mit Mengen** | Mehrere Werte, je Wert eine Menge | Stückzahlen pro Variante, z. B. Größen |
| **Autovervollständigung** | Suchfeld, das passende Werte vorschlägt; gewählt werden kann nur ein vorhandener Wert | Sehr lange Listen, z. B. Artikel- oder Typennummern |

### Freie Eingabe

Der Kunde gibt selbst etwas ein.

| Datentyp | Darstellung | Typischer Einsatz |
|---|---|---|
| **Kleines Eingabefeld** | Einzeiliges Feld; mit **Erlaubte Eingabe** auf Zahlen, Text, E-Mail usw. eingeschränkt | Maße, Mengen, Gravurtext |
| **Großes Eingabefeld** | Mehrzeiliges Textfeld | Anmerkungen, längere Texte |
| **Datum** | Datumsfeld mit Kalender | Liefer- oder Wunschtermin |

### Berechnung

Diese Merkmale füllt der Konfigurator selbst – der Kunde gibt nichts ein.

| Datentyp | Was es tut |
|---|---|
| **Formel** | Rechnet aus anderen Merkmalen ein Ergebnis, z. B. eine Fläche – siehe [Formeln & Berechnungen](/docs/preisformeln) |
| **Preisliste** | Liest einen Wert aus einer Tabelle, z. B. Breite × Höhe – siehe [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv) |
| **Einfache Kombination** | Verknüpft die Werte mehrerer Merkmale, z. B. als Summe, Produkt oder zusammengesetzter Text |
| **Produktattribut** | Übernimmt einen Wert vom Shop-Produkt, z. B. ein Gewicht |
| **Webservice** | Holt einen Wert von einer externen Adresse (URL) |
| **Paket** | Schalter, der eine vorgegebene Zusammenstellung von Werten in anderen Merkmalen auswählt |

### Frontend

Inhalte und Aktionen ohne eigene Auswahl.

| Datentyp | Was es tut |
|---|---|
| **Statisches Feld** | Zeigt Text, Bilder oder Hinweise an deiner Stelle im Konfigurator |
| **Dateiupload** | Kunde lädt Dateien hoch, z. B. eine Druckvorlage |
| **Diagramm** | Zeigt ein Diagramm. Die Einstellungen dafür folgen in einer späteren Version. |
| **Aktions-Button** | Button für „Angebot anfordern“, PDF oder E-Mail – siehe [Der Aktions-Button](/docs/aktions-button) |
| **Captcha (nur V3)** | Schützt einen Aktions-Button mit E-Mail-Versand vor Spam |

### Tarif und Frontend-Engine

- **Webservice**, **Dateiupload**, **Diagramm** und **Paket** gibt es nur im Tarif **Ultimate**. In kleineren Tarifen sind sie in der Liste mit 🔒 markiert, und unter den Einstellungen steht, welcher Tarif aktiv ist. Ein bereits vorhandenes Merkmal eines gesperrten Typs bleibt erhalten und bearbeitbar.
- **Autovervollständigung** und **Datum** mit Kalender funktionieren nur in der Frontend-Engine **Legacy**. In V3 erscheint die Autovervollständigung als normale Auswahlliste und das Datum als einfaches Textfeld.
- **Captcha** funktioniert nur in der Frontend-Engine **V3**.

Alle Unterschiede: [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Die Einstellungen eines Merkmals

![Editor mit Strukturbaum links, Vorschau in der Mitte und rechts den Einstellungen des gewählten Merkmals: Bezeichnung, interner Name, Datenkategorie, Datentyp und Verhalten](/storage/app/media/docs/merkmale-optionen-anlegen/01-merkmal-einstellungen.webp)

Rechts oben hat jedes Merkmal drei Reiter: **Einstellungen**, **Referenziert in** und **Medien**. Im Reiter **Einstellungen** stehen die Abschnitte – welche du siehst, hängt vom Datentyp ab.

### Grundeinstellungen

| Feld | Bedeutung |
|---|---|
| **Bezeichnung** | Was deine Kunden sehen. Wird je Inhaltssprache gepflegt. |
| **Interner Name (ID)** | Eindeutiger Name, über den Formeln, Regeln, Kombinationen und Preislisten das Merkmal ansprechen, z. B. `breite`. Benennst du ihn um, ziehen die Verweise auf dieses Merkmal mit. |
| **Datenkategorie** | Diskretes Merkmal, Freie Eingabe, Berechnung oder Frontend |
| **Datentyp** | Konkrete Darstellung innerhalb der Kategorie (siehe oben) |

### Verhalten

| Feld | Bedeutung |
|---|---|
| **Pflichtfeld** | **Ja**: Der Kunde muss etwas auswählen oder eingeben. Fehlt bei Typen, die der Kunde nicht selbst ausfüllt (z. B. Formel, Statisches Feld). |
| **Sichtbarkeit** | **Ja (sichtbar)**: im Konfigurator und in der Zusammenfassung. **Nein (versteckt)**: nirgends sichtbar, rechnet aber mit – typisch für Hilfsformeln und Preislisten. **Nur Shop**: im Konfigurator, aber nicht in der Zusammenfassung. **Nur Backend**: nicht im Konfigurator, aber in der Zusammenfassung und damit in der Bestellung. |
| **Reihenfolge** | Position innerhalb der Gruppe. Einfacher: Merkmal im Strukturbaum verschieben (siehe unten). |
| **CSS-Klasse** | Eigene CSS-Klasse für individuelles Styling |

### Auswahl-Einstellungen (diskrete Merkmale)

| Feld | Bedeutung |
|---|---|
| **Standardwert** | Wert, der beim Öffnen des Konfigurators schon gewählt ist. **kein Standardwert** lässt das Merkmal leer. |
| **Artikelnummer** | Artikelnummer des Merkmals, z. B. für Stücklisten im Shop |
| **Bildreihenfolge** | Ebene im kombinierten Produktbild: Bilder mit höherer Zahl liegen über Bildern mit niedrigerer |
| **Menge** | Nur bei Auswahl, Radio Buttons, Checkbox, Liste mit Bildern und Mehrfachauswahl mit Mengen: **Nein**, **Freie Eingabe** oder **Bereich**. Bei Freie Eingabe und Bereich legst du **Min. Menge** und **Max. Menge** fest. Der Kunde sieht vor dem Wert ein Mengenfeld (bei Checkbox je angehaktem Wert), der Aufpreis wird mit der Menge multipliziert. |
| **Tooltip für Werte aktivieren** | Nur bei Radio Buttons und Checkbox: zeigt die Informationen eines Werts als Tooltip |

### Kombination & Darstellung (diskrete Merkmale)

| Feld | Bedeutung |
|---|---|
| **Kombination** | **Ja** verknüpft dieses Merkmal mit anderen Merkmalen zu einem gemeinsamen Ergebnis. Dann erscheinen **Kombinierte Werte**, **Wert-Operator** (+, *, String, Formel), **Preis-Operator** und **Dezimalstellen**. |
| **Preise für Wert aus Matrix** | **Ja** holt die Aufpreise der Werte aus einer Preisliste, z. B. je nach Größe – siehe [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv#preise-für-werte-aus-einer-matrix) |
| **Bilder für Werte** | Ob die Bilder der Werte angezeigt werden: **Ausblenden**, **Bei Auswahl** oder – nur bei Radio Buttons und Checkbox – **Immer** |
| **Darstellung** | Nur bei Liste mit Bildern: **Nur Bilder** oder **Bild mit Bezeichnung** |
| **Stil** | Nur bei Liste mit Bildern: **Inline**, **Einklappbar** oder **Overlay** |
| **Autovervollst. – Suche nach** | Nur bei Autovervollständigung: Suche in **Bezeichnung**, **Wert** oder **Beide** |
| **Autovervollst. – Eintrag-Template** | Nur bei Autovervollständigung: wie ein Vorschlag angezeigt wird, z. B. `{{label}} ({{value}})` |

### Textfeld-Einstellungen (Kleines Eingabefeld, Datum)

**Erlaubte Eingabe** schränkt ein, was der Kunde eintippen darf: **Keine Einschränkung**, **Zahl**, **Ganzzahl**, **Größer als 0**, **0 oder größer**, **Buchstaben**, **Kleinbuchstaben**, **Großbuchstaben**, **Code (a-z, 0-9, _)**, **Buchst., Ziffern, _**, **Buchstaben & Ziffern**, **Postleitzahl**, **Telefonnummer**, **E-Mail**, **URI**, **IBAN**, **BIC** und **Umsatzsteuer-ID**.

| Feld | Bedeutung |
|---|---|
| **Mindestwert**, **Höchstwert**, **Exakter Wert** | Bei Zahlen: erlaubter Bereich bzw. genau ein erlaubter Wert. Bei **Größer als 0** und **0 oder größer** entfällt der Mindestwert. |
| **Min. Zeichenlänge**, **Max. Zeichenlänge** | Bei Buchstaben- und Code-Eingaben |
| **Standardwert** | Vorbelegung, je Inhaltssprache |
| **Standardwert anzeigen als** | **Als Standardwert anzeigen** (echter Inhalt, wird übernommen) oder **Als Platzhalter anzeigen** (grauer Hinweis, der beim Tippen verschwindet) |

Beim **Datum** gibt es stattdessen **Vergangene Tage erlauben**, **Datum-Einschränkung** (**Alle Tage erlauben** oder **Wochentage deaktivieren** mit **Deaktivierte Wochentage**) und als **Standardwert** **Nächstmögliches Datum**.

Das **Große Eingabefeld** hat im Abschnitt **Textarea-Einstellungen** **Min. Zeichenlänge**, **Max. Zeichenlänge**, **Standardwert** und **Standardwert anzeigen als**.

### Einstellungen der übrigen Typen

| Datentyp | Abschnitt | Was du einstellst |
|---|---|---|
| **Formel** | **Formel-Einstellungen**, **Staffelpreis** | **Berechnung (Formel)**, **Dezimalstellen**, **Preis-Operator** – siehe [Formeln & Berechnungen](/docs/preisformeln) und [Preisberechnung einrichten](/docs/preisberechnung-einrichten) |
| **Preisliste** | **Matrix-Einstellungen**, **Matrixdaten**, **Staffelpreis** | Siehe [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv) |
| **Einfache Kombination** | **Kombinations-Einstellungen**, **Staffelpreis** | **Kombinierte Werte**, **Wert-Operator**, **Preis-Operator**, **Mindestwert**, **Höchstwert**, **Dezimalstellen** |
| **Produktattribut** | **Produktattribut-Einstellungen** | Welches **Produktattribut** des Shop-Produkts übernommen wird |
| **Webservice** | **Webservice-Einstellungen** | **Webservice-URL** (feste Adresse, wird einmal beim Laden abgerufen – Platzhalter für Merkmalswerte gibt es nicht) und **Rückgabe-Format** (JSON mit JSPath oder XML mit XPath) |
| **Dateiupload** | **Upload-Einstellungen** | **Erlaubte Dateitypen/-endungen**, **Max. Dateigröße (MB)**, **Min. Dateien**, **Max. Dateien** |
| **Statisches Feld** | **Inhalt** | Text mit Formatierung, Bildern und Links |
| **Aktions-Button** | **Button-Einstellungen** | Siehe [Der Aktions-Button](/docs/aktions-button) |
| **Captcha (nur V3)** | **Captcha-Einstellungen** | **Captcha-Anbieter** und **Captcha-Komplexität** (**Einfach**, **Mittel (Standard)**, **Stark**) |

### Bild, Informationen, Benutzerdefinierte Felder

- **Bild:** Ein Bild für das Merkmal selbst, z. B. eine Maßskizze neben dem Eingabefeld. Wo es erscheint, stellst du in den Komponenten-Einstellungen ein. Mehr: [Bildvisualisierung & Bilder hochladen](/docs/bildvisualisierung-bilder).
- **Informationen** und **Zusätzliche Informationen:** Hinweistexte zum Merkmal mit Formatierung, je Inhaltssprache.
- **Benutzerdefinierte Felder:** erscheinen nur, wenn du sie für die Komponente angelegt hast.

## Werte anlegen und bearbeiten

Bei diskreten Merkmalen steht unten der Abschnitt **Werte** mit der Anzahl der Werte.

- **+ Wert** legt einen neuen Wert an und öffnet ihn.
- **+ Gruppe** legt eine Wertegruppe an – damit gliederst du lange Listen, z. B. Farben nach Farbfamilie. In einer Gruppe legst du Werte mit **+ Wert** an der Gruppe an.
- Über das Suchfeld findest du Werte in langen Listen.
- **Alle Werte und Gruppen löschen** (Papierkorb) leert die Liste nach einer Rückfrage.

Ein Klick auf einen Wert öffnet seine Einstellungen; mit dem Pfeil oben links kommst du zurück zum Merkmal.

| Abschnitt | Feld | Bedeutung |
|---|---|---|
| **Grundeinstellungen** | **Bezeichnung** | Was der Kunde sieht, je Inhaltssprache, z. B. „Anthrazit“ |
| | **Wert** | Interner Wert, z. B. `anthrazit`. Diesen Wert verwenden Regeln, Formeln und Preislisten – nicht die Bezeichnung. |
| | **Preis** | Aufpreis, wenn der Kunde diesen Wert wählt, z. B. `15` |
| | **Artikelnummer** | Optional, z. B. für Stücklisten im Shop |
| | **Reihenfolge** | Position in der Liste |
| **Vorschaubild** | | Kleines Bild neben dem Wert, mit Breite und Höhe in Pixeln |
| **Bild** | | Ebene für das kombinierte Produktbild, mit Versatz X/Y. Bei einer 360°-Ansicht heißt der Abschnitt **360°-Bilder**. |
| **Informationen** | **Informationen**, **Zusätzliche Informationen** | Hinweistexte zum Wert |
| **Benutzerdefinierte Felder** | | Nur, wenn für die Komponente angelegt |

Wie Aufpreise im Konfigurator angezeigt werden (absolut oder relativ, mit welchem Preismuster), stellst du für die ganze Komponente ein – siehe [Erste Komponente anlegen](/docs/erste-komponente-anlegen#schritt-5-werte-und-aufpreise).

## Werte importieren und exportieren

Bei vielen Werten pflegst du die Liste bequemer in Excel.

1. Klicke auf **↓ Werte exportieren**. Du bekommst eine CSV-Datei mit allen Werten. Haben Werte Bilder, bekommst du eine ZIP-Datei mit der CSV und den Bildern.
2. Bearbeite die Datei und speichere sie wieder als CSV (bzw. packe sie mit den Bildern wieder als ZIP).
3. Klicke auf **↑ Werte importieren** und wähle die Datei.
4. Wähle, wie die importierten Werte übernommen werden: **Alte Werte löschen** ersetzt die Liste, **Werte zusammenfügen** hängt die importierten Werte an die vorhandenen an.
5. Prüfe das Ergebnis und **speichere** die Komponente.

Die CSV hat diese Spalten, getrennt durch Komma:

| Spalte | Inhalt |
|---|---|
| `type` | `value` für einen Wert, `group` für eine Wertegruppe |
| `group_id` | Nummer der Gruppe, zu der ein Wert gehört; `0` = keine Gruppe |
| `id` | Kennung des Werts – bei neuen Werten leer lassen |
| `alt_title` | Interner Name (nur bei Gruppen relevant) |
| `value` | Der interne **Wert** |
| `price` | Aufpreis |
| `sort_order` | Reihenfolge |
| `thumbnail_filelink`, `thumbnail_original`, `image_filelink`, `image_original` | Dateinamen von Vorschaubild und Bild (beim ZIP-Import) |
| `title_de_DE`, `title_en_US`, … | Bezeichnung je Sprache |
| `info_…`, `additional_info_…` | Informationen und Zusätzliche Informationen je Sprache |

Am einfachsten exportierst du zuerst ein Merkmal mit ein, zwei Werten und nimmst die Datei als Vorlage. Die **Artikelnummer** der Werte ist im Export nicht enthalten und muss nach einem Import von Hand gepflegt werden.

Werte aus Datenblättern oder Tabellen kann auch der KI-Assistent anlegen – siehe [KI-Agent: Produktdaten importieren](/docs/ki-agent-daten-importieren).

## Reihenfolge ändern

Im Strukturbaum verschiebst du Merkmale per Drag & Drop – innerhalb einer Gruppe und auch in eine andere Gruppe. Gruppen lassen sich genauso verschieben. Die Reihenfolge im Baum ist die Reihenfolge im Konfigurator. Wie Gruppen angezeigt werden (ohne Gruppen, Tabs, Accordion, Wizard), erklärt [Merkmalsgruppen & Wizard](/docs/merkmalsgruppen-wizard).

## Referenziert in und Medien

- **Referenziert in** zeigt, wo das Merkmal verwendet wird – gegliedert nach **Regeln**, **Formeln**, **Kombinationen** und **Preismatrizen**. Ein Klick springt zur jeweiligen Stelle. Die Zahl am Reiter sagt, wie viele Verweise es gibt.
- **Medien** zeigt alle Bilder der Komponente auf einen Blick. Ein Klick öffnet das Merkmal, zu dem das Bild gehört.

## Merkmal löschen

Ganz unten in den Einstellungen steht **Merkmal löschen**. Wird das Merkmal noch in Regeln, Formeln, Kombinationen oder Preislisten verwendet, listet die Rückfrage diese Stellen auf – die Verweise werden beim Löschen zurückgesetzt. Mit **Ja, löschen** bzw. **Trotzdem löschen** wird das Merkmal sofort und unwiderruflich gelöscht. Im Shop verschwindet es nach dem nächsten **Veröffentlichen**.

Einzelne Werte löschst du in der Werteliste. Auch hier warnt der Admin, wenn Regeln den Wert verwenden.

## Fehlersuche

1. **Ich finde keinen Knopf für ein neues Merkmal** – Merkmale brauchen eine Gruppe. Zuerst **Gruppe hinzufügen**, dann an der Gruppe **+**.
2. **Ein Datentyp ist nicht wählbar (🔒)** – er gehört zum Tarif Ultimate.
3. **Eine Formel oder Regel findet das Merkmal nicht** – sie verwenden den **Internen Namen (ID)**, nicht die Bezeichnung. Prüfe die Schreibweise und schau unter **Referenziert in**, ob die Verbindung besteht.
4. **Eine Regel oder Preisliste greift bei einem Wert nicht** – sie vergleicht den **Wert**, nicht die Bezeichnung. „Anthrazit“ mit dem Wert `ral7016` muss in der Regel als `ral7016` stehen.
5. **Das Merkmal fehlt im Konfigurator** – prüfe die **Sichtbarkeit** (**Nein (versteckt)** und **Nur Backend** blenden es aus) und ob eine Regel es ausblendet.
6. **Autovervollständigung oder Datumskalender sieht im Shop anders aus** – die Komponente läuft mit der Frontend-Engine V3, die beides nicht kennt. Siehe [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).
7. **Der Import meldet „Die hochgeladene CSV-Datei enthält Fehler“** – die Datei muss Komma als Trennzeichen und die Spaltennamen der ersten Zeile haben. Exportiere ein Merkmal als Vorlage.
8. **Änderungen sind im Shop nicht zu sehen** – speichern und **veröffentlichen**.

## Nächste Schritte

- [Merkmalsgruppen & Wizard](/docs/merkmalsgruppen-wizard)
- [Regelwerk aufbauen](/docs/regelwerk-aufbauen)
- [Preisberechnung einrichten](/docs/preisberechnung-einrichten)
- [Bildvisualisierung & Bilder hochladen](/docs/bildvisualisierung-bilder)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)

---

# Regelwerk aufbauen

Source: https://configento.app/docs/regelwerk-aufbauen
Section: Konfigurator aufbauen

Mit Regeln sorgst du dafür, dass deine Kunden nur Konfigurationen zusammenstellen, die du auch liefern kannst. Eine Regel prüft eine Bedingung – etwa „Antrieb ist Solar“ – und löst eine Wirkung aus: Sie blendet Werte oder ganze Merkmale aus, belegt Werte vor oder zeigt eine Meldung.

## Das Prinzip

- **Regelgruppen** ordnen deine Regeln, z. B. „Antrieb“, „Maße“, „Farben“. Jede neue Regel legst du in einer Regelgruppe an.
- Jede **Regel** besteht aus einer **Bedingung (WENN)** und einer Wirkung, die vom **Regeltyp** abhängt.
- Regeln werden bei jeder Auswahl neu geprüft. Trifft die Bedingung nicht mehr zu, endet auch die Wirkung – ein ausgeblendeter Wert erscheint wieder.

## Schritt für Schritt

1. Öffne die Komponente und wechsle links in den Reiter **Regeln**.
2. Lege mit **+** neben **Regeln** eine Regelgruppe an (**Regelgruppe hinzufügen**). Über das Zahnrad (**Gruppeneinstellungen**) gibst du ihr einen **Gruppennamen**.
3. Klicke an der Gruppe auf **+** (**Regel hinzufügen**). Es entsteht die Regel „Neue Regel“ vom Typ **Blacklist**.
4. Rechts unter **Regeleinstellungen** vergibst du eine **Regelbezeichnung** und wählst den **Regeltyp**.
5. In der Mitte baust du unter **Bedingung (WENN)** die Bedingung auf (siehe [Bedingungen](#bedingungen)).
6. Lege rechts die Wirkung fest – je nach Regeltyp unterschiedlich (siehe [Regeltypen](#regeltypen)).
7. Speichere und teste in der **Vorschau**. Wie jede Änderung gilt eine Regel im Shop erst nach dem **Veröffentlichen**.

Mit **Regel löschen** unten in den Regeleinstellungen entfernst du eine Regel. Wird eine Regelgruppe gelöscht, verschwinden alle Regeln darin.

## Regeltypen

| Regeltyp | Wirkung, wenn die Bedingung zutrifft | Engine |
|---|---|---|
| **Blacklist** | Blendet einzelne Werte oder ganze Merkmale aus | Legacy und V3 |
| **Wertvorbelegung** | Setzt in einem Merkmal einen bestimmten Wert | Legacy und V3, mit Unterschieden |
| **Mengenvorbelegung** | Setzt Mindest- und Höchstmenge eines Merkmals mit Mengeneingabe | nur Legacy |
| **Min/Max-Vorbelegung** | Ändert den erlaubten Bereich eines Eingabefelds | nur Legacy |
| **Fehler / Hinweis** | Zeigt dem Kunden eine Meldung | Legacy und V3, mit Unterschieden |

Was „Legacy“ und „V3“ bedeuten, erklärt [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

### Blacklist

Rechts siehst du alle Merkmale nach Gruppen geordnet.

- **Einzelne Werte ausblenden:** Klappe ein Merkmal auf und hake die Werte an, die nicht mehr wählbar sein sollen.
- **Ganzes Merkmal ausblenden:** Hake das Kästchen vor dem Merkmalsnamen an (**Ganzes Merkmal sperren**). Das Merkmal verschwindet vollständig, auch aus Preis und Zusammenfassung.

Mit **Alle auswählen** und **Alle abwählen** markierst du alle Einträge einer Gruppe oder eines Merkmals auf einmal.

### Wertvorbelegung

Für jedes Merkmal wählst du einen Modus:

| Modus | Wann der Wert gesetzt wird |
|---|---|
| **Deaktiviert** | Nie – das Merkmal bleibt unberührt (Standard) |
| **Immer anwenden** | Immer, auch wenn der Kunde schon etwas anderes gewählt hat |
| **Nur bei Standardwert** | Nur wenn noch nichts oder der Standardwert gewählt ist |
| **Keine Auswahl oder Standardwert** | Wie *Nur bei Standardwert* – und zusätzlich, wenn eine Blacklist den bisher gewählten Wert gerade ausgeblendet hat |

Danach wählst du den Wert, der gesetzt werden soll. Einen Wert, den eine Blacklist gerade sperrt, setzt die Regel nicht.

**Dynamischer Wert** (nur Legacy): Statt eines festen Werts übernimmt die Regel den aktuellen Wert eines anderen Merkmals. Bei Merkmalen mit Werten legst du fest, ob über den **Wert** (**Wert abgleichen**) oder die **ID** (**ID abgleichen**) zugeordnet wird. V3 überspringt dynamische Vorbelegungen.

Bei Eingabefeldern setzt V3 nur Zahlen vor, Legacy auch Text.

### Mengenvorbelegung (nur Legacy)

Gilt für Merkmale, bei denen die **Menge** aktiviert ist. Du trägst **Min. Menge** und **Max. Menge** ein. Mit **Dynamisch** übernimmst du die Grenzen aus einem anderen Merkmal. V3 ignoriert diesen Regeltyp.

### Min/Max-Vorbelegung (nur Legacy)

Ändert den erlaubten Bereich eines Eingabefelds, z. B. „bei Material Holz höchstens 180 cm Breite“. Für das Merkmal stellst du **Ja** ein und trägst den Bereich als `min-max` ein, etwa `40-180` (ganze Zahlen). Angeboten werden Eingabefelder mit einer **Erlaubten Eingabe**. V3 ignoriert diesen Regeltyp – wenn deine Komponente mit V3 läuft, begrenze Maße stattdessen über eine **Fehler / Hinweis**-Regel.

### Fehler / Hinweis

| Einstellung | Bedeutung |
|---|---|
| **Fehlermeldung** | Der Text, den der Kunde sieht. Du kannst Merkmale über ihren internen Namen einsetzen, z. B. `Maximal $max_breite cm` – im Shop steht dort der aktuelle Wert (bei Merkmalen mit Werten das Feld **Wert**). |
| **Meldungstyp** | **Fehler** oder **Hinweis** |
| **Ausführen bei** | Wann die Meldung erscheint (nur Legacy, siehe unten) |

So verhalten sich die Engines:

| | Legacy | V3 |
|---|---|---|
| **Fehler** | Erscheint als Fenster und **verhindert** das Hinzufügen zum Warenkorb | Erscheint rot unter dem Gesamtpreis und **verhindert** Warenkorb und Aktions-Button, solange die Bedingung zutrifft |
| **Hinweis** | Erscheint als Fenster mit **Fortfahren** – der Kunde kann trotzdem bestellen | Erscheint gelb unter dem Gesamtpreis – der Kunde kann trotzdem bestellen |
| **Ausführen bei** | **Direkt danach**: sobald die Bedingung zutrifft. **Wizard**: beim Weiterklicken aus dem Schritt. **Warenkorb**: beim Klick auf In den Warenkorb. Geprüft wird beim Warenkorb in jedem Fall. | Wird nicht ausgewertet – die Meldung erscheint, sobald die Bedingung zutrifft |
| **Merkmale im Meldungstext** | Werden ersetzt | Werden ersetzt |

## Bedingungen

![Regel-Editor: links die Regeln der Regelgruppe, in der Mitte die Bedingung (WENN), rechts die Regeleinstellungen mit Regeltyp, Gewichtung und den ausgeblendeten Werten](/storage/app/media/docs/regelwerk-aufbauen/01-regel-editor.webp)

Die Bedingung baust du in der Mitte unter **Bedingung (WENN)** auf:

1. Wähle das Merkmal.
2. Wähle den Vergleich (Operator).
3. Wähle den Wert oder gib ihn ein.

Mit **+ Bedingung** fügst du eine weitere Zeile hinzu, mit **+ Gruppe** eine Untergruppe. Über **und** / **oder** legst du fest, ob alle Zeilen zutreffen müssen oder eine genügt.

### Operatoren

| Operator | Bedeutung | Für |
|---|---|---|
| **enthält** | Einer der gewählten Werte ist ausgewählt | alle Merkmale mit Werten |
| **enthält nicht** | Keiner der gewählten Werte ist ausgewählt | alle Merkmale mit Werten |
| **ist leer** | Nichts gewählt bzw. nichts eingegeben | alle |
| **ist nicht leer** | Etwas gewählt bzw. eingegeben | alle |
| **=** / **≠** | Gleich / ungleich | Eingabefelder, Berechnungen |
| **<** / **≤** / **>** / **≥** | Kleiner, kleiner gleich, größer, größer gleich | Zahlen, z. B. Breite |

Bei Merkmalen mit Werten (Auswahl, Radio Buttons, Checkbox, Liste mit Bildern …) bietet der Editor nur **enthält**, **enthält nicht**, **ist leer** und **ist nicht leer** an. Du kannst mehrere Werte auf einmal angeben – die Bedingung trifft zu, wenn einer davon gewählt ist. Bei Checkbox und Mehrfachauswahl genügt es, wenn einer der angehakten Werte in deiner Liste steht.

### Was als Bedingung taugt

| Merkmal | Legacy | V3 |
|---|---|---|
| Auswahl, Radio Buttons, Liste mit Bildern | ✓ | ✓ |
| Checkbox, Mehrfachauswahl | ✓ | ✓ |
| Eingabefelder (Zahl, Text) | ✓ | ✓ |
| Berechnete Merkmale (Formel, Preisliste, Kombination) | ✓ | ✓ |

### Untergruppen: Hinweis für Legacy

V3 wertet verschachtelte Gruppen genau so aus, wie sie im Editor stehen. Legacy verknüpft eine Untergruppe dagegen immer mit **und** mit der Zeile direkt davor – auch wenn außen **oder** eingestellt ist – und kann eine Untergruppe an erster Stelle nicht auswerten. Für Komponenten mit Legacy gilt deshalb: Untergruppe nie an den Anfang stellen und nur mit **und** kombinieren. Brauchst du ein **oder** zwischen Gruppen, lege lieber zwei Regeln an.

Legacy wertet bei **ist leer** außerdem die Zahl `0` als leer.

## Wenn mehrere Regeln zusammentreffen

- **Blacklists** addieren sich: Ausgeblendet ist alles, was mindestens eine zutreffende Regel ausblendet.
- **Ketten:** Ein Merkmal, das eine Regel ausblendet, und ein gesperrter Wert lösen keine weiteren Regeln aus. Beide Engines werten neu aus, bis sich nichts mehr ändert. Legacy löscht dabei die Auswahl des ausgeblendeten Merkmals; V3 merkt sie sich und zeigt sie wieder, sobald die Regel nicht mehr greift.
- **Vorbelegungen** für dasselbe Merkmal: Es gewinnt eine Regel.
  - In **V3** entscheidet die **Gewichtung**: Die Regel mit dem höheren Wert gewinnt. Bei gleicher Gewichtung gewinnt die Regel, die weiter unten in der Liste steht.
  - In **Legacy** wird die **Gewichtung** nicht ausgewertet. Es gilt die Reihenfolge in der Liste.
- **Meldungen** zeigt V3 nach Gewichtung sortiert an, die schwerste zuerst.

Die **Gewichtung** stellst du in den Regeleinstellungen ein (Standard `0`). Regeln mit einer Gewichtung ungleich 0 tragen sie in der Liste als Kennzeichen, z. B. **+5**.

### Reihenfolge

Die Reihenfolge der Regeln und Regelgruppen änderst du per Ziehen am Griff ⠿ in der Regelliste. Ausgewertet werden zuerst Regeln außerhalb von Gruppen, dann die Gruppen von oben nach unten.

## Regeln testen

1. Speichere die Komponente.
2. Schalte in der Mitte auf **Vorschau** und klicke typische und kritische Kombinationen durch.
3. Prüfe, ob Werte verschwinden und wieder auftauchen, Vorbelegungen greifen und Meldungen erscheinen.

Die Vorschau läuft mit der eingestellten Frontend-Engine. Wechselst du später die Engine, teste die Regeln erneut – vor allem Untergruppen, Vorbelegungen und Fehlermeldungen.

Welche Regeln ein Merkmal betreffen, siehst du im Merkmal rechts im Reiter **Referenziert in**. Von dort springst du direkt zur Regel.

## Regeln per KI-Agent

Regeln kannst du auch beschreiben statt klicken: „Wenn das Material Holz ist, soll die Farbe RAL 7016 nicht wählbar sein.“ Der KI-Agent legt die Regel an. Kontrolliere sie danach im Reiter **Regeln** und in der Vorschau. Mehr dazu: [KI-Agent: Regeln per Chat definieren](/docs/ki-agent-regeln-definieren).

## Praxisbeispiele

**1. Farbe passt nicht zum Antrieb**
Regeltyp **Blacklist**. Bedingung: *Antrieb* **enthält** *Solar*. Wirkung: bei *Farbe* den Wert *Weiß* anhaken.

**2. Zubehör nur mit Motor**
Regeltyp **Blacklist**. Bedingung: *Antrieb* **enthält** *Kurbel*. Wirkung: beim Merkmal *Fernbedienung* **Ganzes Merkmal sperren** anhaken.

**3. Sinnvolle Vorauswahl**
Regeltyp **Wertvorbelegung**. Bedingung: *Modell* **enthält** *Basic*. Wirkung: *Farbe* auf **Keine Auswahl oder Standardwert**, Wert *Weiß*. Hat der Kunde schon eine eigene Farbe gewählt, bleibt sie erhalten.

**4. Maß nicht lieferbar**
Regeltyp **Fehler / Hinweis**. Bedingung: *Material* **enthält** *Holz* **und** *Breite* **>** `180`. **Meldungstyp** **Fehler**, **Fehlermeldung** „Holz ist bis 180 cm Breite lieferbar.“

**5. Nur in Legacy: Bereich begrenzen**
Regeltyp **Min/Max-Vorbelegung**. Bedingung: *Material* **enthält** *Holz*. Wirkung: *Breite* auf **Ja**, Bereich `40-180`.

## Fehlersuche

1. **Die Regel greift gar nicht** – prüfe den Operator: Bei Merkmalen mit Werten brauchst du **enthält**, nicht **=**. Prüfe auch, ob die Komponente veröffentlicht ist; der Shop zeigt den zuletzt veröffentlichten Stand.
2. **Die Regel greift nur manchmal** – steht eine Untergruppe am Anfang oder ist sie mit **oder** verknüpft? In Legacy wird das anders ausgewertet (siehe [Untergruppen](#untergruppen-hinweis-für-legacy)).
3. **Mengen- oder Min/Max-Vorbelegung wirkt nicht** – die Komponente läuft mit V3, das diese Regeltypen nicht kennt.
4. **Zwei Vorbelegungen widersprechen sich** – vergib in V3 eine **Gewichtung**, in Legacy ändere die Reihenfolge.
5. **Der Kunde kann trotz Meldung bestellen** – prüfe den **Meldungstyp**: Nur **Fehler** sperrt den Warenkorb, ein **Hinweis** informiert nur.

## Nächste Schritte

- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [KI-Agent: Regeln per Chat definieren](/docs/ki-agent-regeln-definieren)
- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [Merkmalsgruppen & Wizard](/docs/merkmalsgruppen-wizard)
- [Preisberechnung einrichten](/docs/preisberechnung-einrichten)

---

# Gruppen, Darstellung & Wizard

Source: https://configento.app/docs/merkmalsgruppen-wizard
Section: Konfigurator aufbauen

Gruppen fassen zusammengehörige Merkmale zusammen – etwa „Maße“, „Material & Farbe“ und „Antrieb“. Wie die Gruppen im Shop erscheinen, bestimmst du mit der **Darstellung**: alle Merkmale untereinander, als Tabs, als Accordion oder als **Wizard**, der deine Kunden Schritt für Schritt durch die Konfiguration führt.

## Gruppen im Editor

![Einstellungen einer Gruppe: Gruppenname je Sprache, Gruppe ausblenden und Gruppe löschen](/storage/app/media/docs/merkmalsgruppen-wizard/01-gruppe.webp)

Jedes Merkmal liegt in genau einer Gruppe. Die Gruppen siehst du links im Reiter **Merkmale** unter **Struktur**. Rechts neben **Struktur** steht, welche Darstellung gerade eingestellt ist.

| Aktion | So geht's |
|---|---|
| **Gruppe anlegen** | Ganz unten im Strukturbaum auf **Gruppe hinzufügen** klicken. Es entsteht eine Gruppe „Neue Gruppe“. |
| **Gruppe umbenennen** | Am Zahnrad der Gruppe (**Gruppeneinstellungen**) unter **Gruppenname** den Namen eintragen – für jede aktive Sprache ein eigenes Feld. |
| **Merkmal in die Gruppe legen** | Am **+** der Gruppe (**Merkmal hinzufügen**) ein neues Merkmal anlegen oder ein vorhandenes Merkmal am Griff ⠿ in die Gruppe ziehen. |
| **Reihenfolge ändern** | Gruppen und Merkmale am Griff ⠿ an die gewünschte Stelle ziehen. Merkmale lassen sich auch in eine andere Gruppe ziehen. |
| **Internen Namen vergeben** | In den Gruppeneinstellungen unter **Interner Name (ID)** einen Namen wie `fahrzeug` eintragen – optional, nur Buchstaben, Ziffern und Unterstriche, eindeutig je Komponente. Damit sprechen Shop-Entwickler die Gruppe über die [JavaScript-Schnittstelle](/docs/javascript-schnittstelle#wizard-und-gruppen-steuern) an. |
| **Gruppe ausblenden** | In den Gruppeneinstellungen unter **Sichtbarkeit** den Haken **Gruppe ausblenden** setzen. Die Gruppe erscheint nicht im Konfigurator, ihre Regeln werden aber weiter ausgewertet. |
| **Gruppe löschen** | In den Gruppeneinstellungen **Gruppe löschen**. |

> **Achtung beim Löschen:** Mit der Gruppe werden **alle Merkmale darin** unwiderruflich gelöscht. Die Löschung wird sofort gespeichert. Willst du die Merkmale behalten, ziehe sie vorher in eine andere Gruppe.

Eine neue Komponente hat noch keine Gruppe. Lege deshalb zuerst eine Gruppe an, bevor du Merkmale anlegst.

## Die Darstellung wählen

Die Darstellung stellst du für die ganze Komponente ein: Reiter **Einstellungen** → **Allgemein** → Abschnitt **Darstellung**.

| Darstellung | So sieht es im Shop aus | Engine |
|---|---|---|
| **Keine Gruppen** | Alle Merkmale stehen untereinander, ohne Gruppennamen. | Legacy und V3 |
| **Tabs** | Jede Gruppe ist ein Reiter, der Kunde klickt zwischen den Reitern. | Legacy und V3 |
| **Accordion** | Jede Gruppe ist ein aufklappbarer Abschnitt. | Nur Legacy – V3 zeigt die Merkmale wie bei **Keine Gruppen** |

Ist im Feld **Darstellung** nichts gewählt (**—**), zeigen die beiden Engines Unterschiedliches: Legacy zeigt Tabs, V3 zeigt keine Gruppen. Wähle deshalb immer ausdrücklich eine Darstellung.

Mehr zu den Unterschieden der Engines: [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

### Gruppen, die automatisch verschwinden

Eine Gruppe wird im Shop ausgeblendet, wenn **keines** ihrer Merkmale sichtbar ist – etwa weil eine [Regel](/docs/regelwerk-aufbauen) alle Merkmale der Gruppe sperrt. Eine eigene Regel, die eine ganze Gruppe ein- oder ausblendet, gibt es nicht. Willst du eine Gruppe abhängig von einer Auswahl verbergen, sperre ihre Merkmale.

## Der Wizard

![Komponente mit Darstellung Wizard: oben im Editor die Schritte, unten Zurück und Weiter](/storage/app/media/docs/merkmalsgruppen-wizard/02-wizard.webp)

Mit dem Wizard führst du deine Kunden Schritt für Schritt durch die Gruppen: Erst wenn ein Schritt vollständig ist, geht es weiter.

**Einschalten:** Reiter **Einstellungen** → **Allgemein** → Abschnitt **Darstellung** → **Wizard** anhaken. Das Feld erscheint nur, wenn als Darstellung nicht **Keine Gruppen** gewählt ist.

| Einstellung | Wirkung |
|---|---|
| **Wizard** | Schaltet die Schritt-für-Schritt-Führung ein. |
| **Auto-Scroll bei Tab-Wechsel** | Scrollt beim Wechsel zum nächsten Schritt nach oben zum Konfigurator – sinnvoll bei langen Gruppen. |
| **Versatz oben für Auto-Scroll** | Abstand in Pixeln zum oberen Rand, z. B. für eine feste Kopfzeile deines Shops. Vorgabe 80. |
| **Wizard-Navigation (V3)** | Was V3 an Navigation zeigt: **Tabs, Fortschritt und Buttons** (Standard), **Nur Zurück/Weiter** oder **Keine** – dann steuert die Shopseite die Schritte über die [JavaScript-Schnittstelle](/docs/javascript-schnittstelle#wizard-und-gruppen-steuern). Legacy ignoriert die Einstellung. |

### So verhält sich der Wizard

| | Legacy | V3 |
|---|---|---|
| **Navigation** | Unter jeder Gruppe die Knöpfe **Zurück** und **Weiter**. Im ersten Schritt fehlt **Zurück**, im letzten **Weiter**. | Ein Fortschrittsbalken mit „Schritt 2 / 4“ und darunter **← Zurück** und **Weiter →**. |
| **Weiter** | Prüft die Pflichtfelder des aktuellen Schritts. Fehlt etwas, bleibt der Kunde im Schritt und sieht die Fehlermeldung. | Genauso. |
| **Fehler-Regeln** | Eine [Fehler-Regel](/docs/regelwerk-aufbauen) mit „Ausführen bei“ Wizard hält den Kunden ebenfalls im Schritt und zeigt ihre Meldung. | Genauso, wenn der Meldungstyp **Fehler** ist. Die Meldung steht am Merkmal der Regel, sonst über **Zurück** und **Weiter**. |
| **Zurück** | Immer möglich, ohne Prüfung. | Genauso. |
| **Klick auf einen späteren Reiter** | Prüft alle Schritte bis dorthin. Der Kunde landet beim ersten unvollständigen Schritt. | Genauso. |
| **Ausgeblendete Gruppen** | Werden übersprungen. | Werden übersprungen. |
| **Wizard mit Accordion** | Möglich. | Nicht möglich – V3 zeigt bei Accordion keine Gruppen und damit auch keinen Wizard. |

**Pflichtfelder** legst du am Merkmal fest: Abschnitt **Verhalten** → **Pflichtfeld** = **Ja**. Ohne Pflichtfelder lässt der Wizard den Kunden jederzeit weiter.

## Eine gute Gruppenstruktur

Ordne die Gruppen so, wie dein Kunde entscheidet – vom Grundsätzlichen zum Detail:

1. **Produkttyp** – bestimmt, welche Merkmale danach überhaupt in Frage kommen
2. **Maße** – Breite, Höhe, Tiefe
3. **Material & Oberfläche** – oft abhängig vom Produkttyp
4. **Ausstattung** – Extras und Zubehör
5. **Abschluss** – Zusammenfassung und Aktions-Button

Merkmale, von denen spätere Gruppen per Regel abhängen, gehören in frühe Gruppen. Sonst ändert sich beim Zurückblättern plötzlich etwas, was der Kunde schon ausgefüllt hat.

## Fehlersuche

1. **Ich kann kein Merkmal anlegen** – die Komponente hat noch keine Gruppe. Klicke unten im Strukturbaum auf **Gruppe hinzufügen**.
2. **Das Feld „Wizard“ fehlt** – als Darstellung ist **Keine Gruppen** gewählt. Wähle **Tabs**.
3. **Der Wizard lässt Kunden ohne Eingabe weiter** – die Merkmale sind keine Pflichtfelder. Setze am Merkmal **Pflichtfeld** auf **Ja**.
4. **Accordion erscheint im Shop nicht** – die Komponente läuft mit V3. Nimm **Tabs** oder stelle auf Legacy.
5. **Eine Gruppe fehlt im Shop** – sie ist ausgeblendet (**Gruppe ausblenden**) oder alle ihre Merkmale sind unsichtbar bzw. per Regel gesperrt.
6. **Nach dem Schrittwechsel steht der Konfigurator unter der Kopfzeile des Shops** – erhöhe **Versatz oben für Auto-Scroll**.

## Nächste Schritte

- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [Regelwerk aufbauen](/docs/regelwerk-aufbauen)
- [Komponenten-Einstellungen](/docs/komponente-einstellungen)

---

# Bildvisualisierung & Bilder hochladen

Source: https://configento.app/docs/bildvisualisierung-bilder
Section: Konfigurator aufbauen

Bilder zeigen deinen Kunden, was sie gerade konfigurieren. configento.app kennt drei Arten: ein **Bild am Merkmal**, ein **Vorschaubild am Wert** für die Auswahl und das **kombinierte Produktbild**, das aus den Bildern der gewählten Werte Ebene für Ebene zusammengesetzt wird – auf Wunsch auch als drehbare 360°-Ansicht.

## Welche Bildart brauchst du?

| Du willst … | Dann nimm … |
|---|---|
| neben einem Merkmal ein erklärendes Bild zeigen, z. B. eine Skizze „So misst du die Breite“ | das **Bild am Merkmal** |
| dass deine Kunden Werte über kleine Bilder auswählen, z. B. Farbmuster | das **Vorschaubild** am Wert |
| das fertige Produkt aus den gewählten Werten zusammensetzen, z. B. Gestell + Stoff + Antrieb | das **kombinierte Produktbild** |
| das zusammengesetzte Produkt drehbar zeigen | das **360° kombinierte Produktbild** (nur Legacy) |

## Bild am Merkmal

1. Wähle das Merkmal im Strukturbaum.
2. Öffne rechts den Abschnitt **Bild** und lade das Bild hoch.

Wo das Bild neben dem Merkmal steht, stellst du für die ganze Komponente ein: Reiter **Einstellungen** → **Allgemein** → **Position Merkmalbilder** → **Links**, **Rechts** oder **Nicht anzeigen**.

Ein Bild am Merkmal gibt es bei Auswahl-Merkmalen, Eingabefeldern, statischen Feldern, Produktattribut und Paket.

## Bilder an Werten

Ein Klick auf einen Wert im Abschnitt **Werte** öffnet seine Einstellungen. Dort gibt es zwei Bildfelder:

| Abschnitt | Wofür | Zusätzliche Felder |
|---|---|---|
| **Vorschaubild** | Das kleine Bild, über das der Kunde den Wert auswählt – vor allem beim Datentyp **Liste mit Bildern** | **W (px)** und **H (px)**: Anzeigegröße des Vorschaubilds (nur Legacy) |
| **Bild** | Die Ebene für das **kombinierte Produktbild** | **Offset X** und **Offset Y**: Verschiebung der Ebene in Pixeln (nur Legacy) |

Ist das kombinierte Produktbild auf 360° gestellt, heißt der Abschnitt **Bild** stattdessen **360°-Bilder** und nimmt eine ganze Bildfolge auf (siehe unten).

## Das kombinierte Produktbild

Statt für jede Kombination ein eigenes Foto zu machen, legst du für jeden Wert **eine Ebene** an. Der Konfigurator legt die Ebenen der gewählten Werte übereinander.

![Vorschau einer Haustür: das kombinierte Produktbild setzt sich aus den Bildebenen der gewählten Werte zusammen](/storage/app/media/docs/bildvisualisierung-bilder/01-kombiniertes-bild.webp)

**Beispiel Terrassendach:**

| Merkmal | Bildreihenfolge | Ebenen der Werte |
|---|---|---|
| Gestell | 1 | Gestell anthrazit, Gestell weiß |
| Dacheindeckung | 2 | Glas klar, Glas matt, Stegplatten |
| Seitenwand | 3 | ohne (kein Bild), Glas-Schiebewand |

### Einrichten

1. Schalte das kombinierte Bild ein: Reiter **Einstellungen** → **Allgemein** → Abschnitt **Kombiniertes Produktbild** → **Kombiniertes Bild** = **Kombiniertes Produktbild**.
2. Lade an jedem Wert, der im Bild sichtbar sein soll, im Abschnitt **Bild** seine Ebene hoch.
3. Lege die Stapelfolge fest: am **Merkmal** im Feld **Bildreihenfolge**. Merkmale mit kleinerer Zahl liegen unten, mit größerer Zahl darüber.
4. Prüfe das Ergebnis in der Vorschau.

### Damit die Ebenen passen

- Alle Ebenen haben **dieselbe Bildgröße** und denselben Bildausschnitt.
- Alles außer dem eigentlichen Teil ist **transparent** – nimm PNG oder WebP mit Transparenz, SVG geht ebenfalls.
- Die unterste Ebene (meist das Grundgestell) deckt den ganzen Hintergrund ab.
- Ein Wert ohne Bild trägt nichts zum Gesamtbild bei – praktisch für „ohne“.

### Wo das Bild im Shop erscheint

Wo das kombinierte Bild auf der Produktseite sitzt, hängt von der Integration ab. In Magento und Shopware gibst du in den Plugin-Einstellungen einen CSS-Selektor für den Bildbereich an, siehe [Magento-Plugin installieren](/docs/magento-plugin-installieren) und [Shopware-Plugin installieren](/docs/shopware-plugin-installieren).

### Das Bild im PDF und in der E-Mail

Mit dem Platzhalter `{{combined_image}}` fügst du das aktuelle Produktbild in das PDF oder die E-Mail des [Aktions-Buttons](/docs/aktions-button) ein. Das funktioniert nur mit der Frontend-Engine **V3** – in Legacy bleibt der Platzhalter leer.

## Die 360°-Ansicht

Die 360°-Ansicht zeigt das kombinierte Produkt drehbar. Sie gibt es nur in der Frontend-Engine **Legacy**; V3 zeigt stattdessen das statische kombinierte Bild. Siehe [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

1. Stelle **Kombiniertes Bild** auf **360° kombiniertes Produktbild**.
2. Lade an jedem Wert im Abschnitt **360°-Bilder** die ganze Bildfolge hoch – eine Aufnahme pro Blickwinkel, in Drehrichtung sortiert. Die Reihenfolge änderst du per Ziehen, **Alle löschen** leert die Folge.
3. Alle Werte brauchen gleich viele Bilder mit denselben Blickwinkeln, sonst passen die Ebenen beim Drehen nicht zusammen.

Weitere Einstellungen im Abschnitt **Kombiniertes Produktbild**:

| Einstellung | Wirkung |
|---|---|
| **Animation 360** | Ladeanimation während die Bilder laden: **Keine Ladeanimation**, **Ladeanimation ohne Fortschrittsanzeige**, **Ladeanimation mit Fortschrittsanzeige** oder **Nur Fortschrittsanzeige** |
| **Start-Sequenz in der 360°-Ansicht** | Mit welchem Bild der Folge die Ansicht beginnt |
| **3D-Icon anzeigen nach (CSS-Selektor)** | Hinter welchem Element der Seite das 3D-Symbol erscheint |

Die Farbe der Ladeanimation stellst du im Reiter **Design** unter **Ladeanimationsfarbe** ein.

## Formate und Größen

| | Erlaubt | Größe |
|---|---|---|
| Bild am Merkmal, Vorschaubild, Ebene | JPG, PNG, GIF, WebP, SVG | max. 5 MB pro Bild |
| 360°-Bilder | JPG, PNG, GIF, WebP – kein SVG | max. 5 MB pro Bild, höchstens 360 Bilder pro Wert |

Du kannst Bilder per Klick auswählen oder in das Feld ziehen. **Bild ersetzen** tauscht ein Bild aus, **Bild entfernen** löscht es.

**Empfehlungen** (keine Vorgaben des Systems): Vorschaubilder klein halten, etwa 100–200 px. Ebenen des kombinierten Bilds in der Größe, in der das Bild auf der Seite erscheint – meist 800–1200 px Breite. WebP ist bei gleicher Qualität deutlich kleiner als PNG. Große Bilder bremsen den Konfigurator, besonders auf dem Smartphone und bei 360° mit vielen Bildern pro Wert.

## Alle Bilder einer Komponente: der Reiter „Medien“

Rechts in den Einstellungen eines Merkmals zeigt der Reiter **Medien** alle Bilder der ganzen Komponente – Bilder an Merkmalen, Vorschaubilder und Ebenen. Ein Klick auf ein Bild öffnet das Merkmal, zu dem es gehört. So findest du schnell, wo ein Bild hinterlegt ist.

## Fehlersuche

1. **Das kombinierte Bild bleibt leer** – **Kombiniertes Bild** steht auf **Nein**, oder die gewählten Werte haben im Abschnitt **Bild** keine Ebene.
2. **Eine Ebene liegt hinter einer anderen** – prüfe die **Bildreihenfolge** der beiden Merkmale. Größere Zahl liegt oben.
3. **Ebenen sind gegeneinander verschoben** – die Bilder haben unterschiedliche Größen oder Ausschnitte. Exportiere alle Ebenen mit derselben Leinwandgröße. **Offset X/Y** hilft nur in Legacy.
4. **Die 360°-Ansicht dreht sich nicht** – die Komponente läuft mit V3. 360° gibt es nur in Legacy.
5. **Das Produktbild fehlt im PDF** – `{{combined_image}}` funktioniert nur mit V3.
6. **Upload wird abgelehnt** – Datei größer als 5 MB oder kein Bildformat. Bei 360°-Bildern ist SVG nicht erlaubt.
7. **Das Bild am Merkmal erscheint nicht** – **Position Merkmalbilder** steht auf **Nicht anzeigen**.

## Nächste Schritte

- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [Komponenten-Einstellungen](/docs/komponente-einstellungen)
- [Der Aktions-Button](/docs/aktions-button)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)

---

# Der Aktions-Button

Source: https://configento.app/docs/aktions-button
Section: Konfigurator aufbauen

Mit dem Aktions-Button schließt dein Kunde die Konfiguration ab: Er fordert ein Angebot per E-Mail an, lädt ein PDF herunter oder schickt die Konfiguration an dein eigenes System. Der Aktions-Button ist ein Merkmal mit eigenen Einstellungen. Dieser Artikel erklärt alle Aktionen, die Platzhalter für E-Mail und PDF und was du gegen Spam tun solltest.

## Aktions-Button anlegen

1. Öffne die Komponente und klicke im Strukturbaum an der gewünschten Gruppe auf **+** (**Merkmal hinzufügen**).
2. Stelle unter **Grundeinstellungen** die **Datenkategorie** auf **Frontend** und den **Datentyp** auf **Aktions-Button**.
3. Trage unter **Bezeichnung** die Beschriftung des Buttons ein, z. B. „Angebot anfordern“ – je Inhaltssprache.
4. Wähle im Abschnitt **Button-Einstellungen** die **Aktion** und fülle die zugehörigen Felder aus (siehe unten).
5. Speichere und **veröffentliche** die Komponente.

![Aktions-Button im Editor: rechts Datenkategorie Frontend, Datentyp Aktions-Button und die Button-Einstellungen mit der Aktion E-Mail mit PDF verschicken](/storage/app/media/docs/aktions-button/01-button-einstellungen.webp)

Der Button trägt die **Bezeichnung**. Ist sie leer, zeigt V3 den internen Namen. In **Legacy** erscheinen unter dem Button zusätzlich die **Informationen** des Merkmals, in **V3** nur der Button.

Die übrigen Felder wie **Sichtbarkeit**, **Reihenfolge** und **CSS-Klasse** funktionieren wie bei jedem Merkmal – siehe [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen#die-einstellungen-eines-merkmals).

## Die Aktionen

| Aktion | Was beim Klick passiert |
|---|---|
| **Eigene URL** | Die Konfiguration geht an eine Adresse deiner Wahl, z. B. an dein CRM oder ein eigenes Skript. |
| **PDF erzeugen** | Der Kunde bekommt ein PDF mit seiner Konfiguration zum Herunterladen (nur V3). |
| **E-Mail verschicken** | Eine E-Mail geht an die Adresse, die der Kunde im Konfigurator eingegeben hat. |
| **E-Mail mit PDF verschicken** | Wie **E-Mail verschicken**, mit dem PDF als Anhang |

Vor jeder Aktion prüft der Konfigurator die Eingaben: Fehlt ein Pflichtfeld, steht die Meldung am Merkmal und es wird nichts verschickt. In **V3** hält auch eine **Fehler**-Regel den Button auf – siehe [Regelwerk aufbauen](/docs/regelwerk-aufbauen#fehler-hinweis).

## Eigene URL

Unter **Eigene POST-URL** trägst du die Adresse ein, an die die Konfiguration gehen soll, z. B. `https://www.meinshop.de/anfrage.php`.

Mit `{$baseurl}/pfad` wird die Adresse zur Domäne der Seite ergänzt, auf der der Konfigurator gerade läuft. So funktioniert derselbe Button auf mehreren Domänen.

**So kommt die Konfiguration an (V3):** configento.app schickt sie als JSON an deine URL. Für jedes Merkmal gibt es einen Eintrag unter seinem internen Namen mit u. a. `label` (Bezeichnung), `value` (Wert bzw. Eingabe), `valueLabel` (Bezeichnung des Werts), `choiceSku` (Artikelnummer des Werts), `valueQty` (Menge) und `visibility`. Dazu kommt `_combined_sku` mit der kombinierten Artikelnummer des konfigurierten Produkts (siehe [Komponenten-Einstellungen](/docs/komponente-einstellungen)). Antwortet deine URL mit einem PDF, lädt der Browser des Kunden es herunter.

In **Legacy** schickt der Browser des Kunden die Konfiguration direkt an deine URL. Dein Server muss Anfragen von der Domäne deines Shops erlauben (CORS).

## PDF erzeugen

| Feld | Bedeutung |
|---|---|
| **Dateiname** | Name der PDF-Datei, Platzhalter erlaubt, z. B. `Angebot-{{date}}`. Umlaute und Sonderzeichen werden entfernt, `.pdf` wird angehängt. Ohne Angabe heißt die Datei `document.pdf`. |
| **Format** | A4, A5, Letter oder Legal |
| **Orientierung** | **Hochformat** oder **Querformat** |
| **PDF-Inhalt** | Text des PDFs mit Formatierung und Platzhaltern, je Inhaltssprache |

Den **PDF-Inhalt** bearbeitest du per Klick auf die Vorschau (**Zum Bearbeiten klicken**). Unter **Body-CSS (optional)** kannst du eigene CSS-Regeln für das PDF hinterlegen. Kopf- und Fußzeile, Logo und Schrift kommen aus dem [Branding](/docs/globale-einstellungen#branding).

Der Download funktioniert nur in **V3**. In **Legacy** wird das PDF zwar erzeugt, aber nicht an den Kunden ausgeliefert – nimm dort **E-Mail mit PDF verschicken**.

## E-Mail verschicken

| Feld | Bedeutung |
|---|---|
| **Empfänger-Feld** | Das Merkmal, in das der Kunde seine E-Mail-Adresse eingibt (Pflicht) |
| **BCC** | Weitere Empfänger, die eine Kopie erhalten, z. B. `vertrieb@meinshop.de`. Mehrere Adressen trennst du mit Komma. |
| **Betreff** | Betreff der E-Mail, Platzhalter erlaubt, je Inhaltssprache (Pflicht) |
| **E-Mail-Inhalt** | Text der E-Mail mit Formatierung und Platzhaltern, je Inhaltssprache (Pflicht). Wie beim PDF mit **Body-CSS (optional)**. |

**Empfänger-Feld vorbereiten:** Zur Auswahl stehen nur Merkmale vom Typ **Kleines Eingabefeld** mit **Erlaubte Eingabe** = **E-Mail**. Gibt es keines, zeigt der Editor „Lege ein Text-Merkmal mit E-Mail-Validierung an, um es als Empfänger zu verwenden.“ Lege es an und stelle **Pflichtfeld** auf **Ja**. Die Liste zeigt die internen Namen der Merkmale.

**Absender und Versand:** Die E-Mail geht über deinen eigenen SMTP-Server raus. Absender-Adresse und -Name kommen aus **Einstellungen → E-Mail-Versand**. Ohne vollständige Einstellungen dort wird keine E-Mail verschickt – siehe [Globale Einstellungen](/docs/globale-einstellungen#e-mail-versand).

**Sprachen:** Betreff und Inhalt pflegst du für jede Inhaltssprache. Der Editor warnt, solange in der gewählten Sprache ein Teil fehlt. Verschickt wird in der Sprache, in der der Kunde den Konfigurator benutzt; fehlt dafür ein Text, nimmt configento.app die Standardsprache der Komponente. Legacy entscheidet nach der Sprache des Browsers: Deutsch oder sonst Englisch.

**E-Mail mit PDF verschicken** zeigt die Felder für E-Mail und PDF zusammen.

## Redirect nach Aktion

Unter **Redirect nach Aktion** trägst du optional eine Seite ein, auf die der Kunde nach erfolgreicher Aktion geleitet wird, z. B. eine Danke-Seite. Ohne Redirect zeigt V3 unter dem Button „Erfolgreich übermittelt.“ **Legacy** zeigt ohne Redirect keine Meldung – trag dort eine Danke-Seite ein, damit der Kunde sieht, dass seine Anfrage angekommen ist.

## Platzhalter

Platzhalter funktionieren in **Betreff**, **E-Mail-Inhalt**, **PDF-Inhalt** und **Dateiname**.

| Platzhalter | Ergebnis |
|---|---|
| `{{date}}` | Heutiges Datum – deutsch `19.10.2026`, sonst `2026-10-19` |
| `{{time}}` | Uhrzeit, z. B. `14:30` |
| `{{component_title}}` | Titel der Komponente in der Sprache des Kunden |
| `{{combined_sku}}` | Kombinierte Artikelnummer des konfigurierten Produkts, z. B. `CL-W-GR` – aus den Artikelnummern der gewählten Werte (nur V3, sonst leer) |
| `{{configuration_table}}` | Tabelle aller sichtbaren Merkmale mit Auswahl, Artikelnummer und Menge |
| `{{combined_image}}` | Das kombinierte Produktbild, bis 600 px breit (nur V3, in Legacy leer) |
| `{{combined_image:400}}` | Wie oben, mit eigener Höchstbreite in Pixeln |
| `{{characteristic:NAME.FELD}}` | Ein einzelnes Merkmal, siehe unten |

Bei `{{characteristic:NAME.FELD}}` ist **NAME** der interne Name des Merkmals und **FELD** eines davon:

| Feld | Ergebnis | Beispiel |
|---|---|---|
| `label` | Bezeichnung des Merkmals | `Farbe` |
| `value` | Wert bzw. Eingabe des Kunden | `ral7016` oder `Max Mustermann` |
| `valueLabel` | Bezeichnung des gewählten Werts | `Anthrazit` |
| `choiceSku` | Artikelnummer des gewählten Werts | `FA-7016` |
| `valueQty` | Menge | `2` |

Beispiel: `Hallo {{characteristic:name.value}}, deine Farbe: {{characteristic:farbe.valueLabel}}`.

Bei Checkbox und Mehrfachauswahl werden mehrere Werte mit Komma verbunden. Ein unbekannter Name ergibt einen leeren Text.

`{{configuration_table}}` zeigt nur Merkmale mit **Sichtbarkeit** **Ja (sichtbar)** oder **Nur Backend**, die einen Wert haben. Die Spaltenköpfe lauten immer „Merkmal“, „Auswahl“, „Artikel-Nr.“ und „Menge“.

## Spam-Schutz mit Captcha

Eine E-Mail-Aktion ist ein öffentliches Formular: Wer es findet, kann darüber Mails an beliebige Adressen auslösen – über deinen SMTP-Server. Enthält die Komponente kein Captcha, warnt der Editor: **Spam-Risiko: kein Captcha in dieser Komponente**.

So schützt du den Button:

1. Lege in derselben Komponente ein Merkmal mit dem Datentyp **Captcha (nur V3)** an, am besten direkt über dem Aktions-Button.
2. Stelle die Komponente auf die Frontend-Engine **V3** – siehe [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

Sobald die Komponente ein Captcha enthält, verschickt configento.app E-Mails und PDFs nur noch mit gelöstem Captcha. Der Kunde merkt davon wenig: Das Captcha löst sein Browser im Hintergrund.

Zusätzlich begrenzt configento.app den Versand: höchstens 100 E-Mails pro Stunde je Aktions-Button und 10 pro Minute je Besucher. Schickt jemand dieselbe Konfiguration innerhalb einer Minute erneut ab, geht keine zweite E-Mail raus.

## Was der Kunde sieht

| | V3 | Legacy |
|---|---|---|
| Während des Sendens | Der Button zeigt „Sende …“ | – |
| Nach Erfolg | „Erfolgreich übermittelt.“ oder Weiterleitung | Weiterleitung auf die Seite unter **Redirect nach Aktion**, ohne sie keine Meldung |
| Bei einem Fehler | „Übermittlung fehlgeschlagen: …“ mit dem Grund | Keine Meldung |
| PDF erzeugen | Download startet | Kein Download |

## Wann Änderungen gelten

Änderungen am Aktions-Button – Aktion, Texte, Empfänger-Feld – gelten im Shop erst nach dem **Veröffentlichen**. Änderungen an **E-Mail-Versand** und **Branding** in den Einstellungen wirken dagegen sofort.

## Mehrere Buttons

Brauchst du mehrere Aktionen, legst du mehrere Aktions-Buttons an, z. B. „PDF herunterladen“ und „Angebot per E-Mail“. Jeder Button hat seine eigene Aktion und seine eigenen Texte.

## Aktions-Button per KI-Agent

Der KI-Agent kann einen Aktions-Button für dich einrichten: „Lege einen Button ‚Angebot anfordern‘ an, der eine E-Mail mit PDF an die Adresse aus dem Feld E-Mail schickt, mit Kopie an vertrieb@meinshop.de.“ Prüfe danach Texte und Empfänger-Feld im Editor. Mehr dazu: [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen).

## Fehlersuche

1. **Unter dem Button steht „Für diese Aktion ist kein Endpunkt konfiguriert.“** – bei **Eigene URL** fehlt die **Eigene POST-URL**. Bei den anderen Aktionen: Komponente speichern und veröffentlichen.
2. **Es kommt keine E-Mail an** – prüfe unter **Einstellungen → E-Mail-Versand** die Verbindung mit **Verbindung testen** und einer Test-E-Mail. Prüfe, ob ein **Empfänger-Feld** gewählt ist und der Kunde dort eine gültige Adresse eingetragen hat.
3. **„Übermittlung fehlgeschlagen: HTTP 403“** – die Seite läuft auf einer Shop-Domäne, die nicht unter **Einstellungen → Domänen** steht, oder das Captcha wurde nicht gelöst. Die Vorschau im Admin und Shopify-Shops werden nie wegen der Domäne abgelehnt – den Button kannst du also in der Vorschau testen.
4. **„Übermittlung fehlgeschlagen: HTTP 429“** – das Versandlimit ist erreicht. Warte ein paar Minuten.
5. **„Übermittlung fehlgeschlagen: HTTP 500“** – meist fehlen die SMTP-Einstellungen oder der SMTP-Server lehnt ab.
6. **Ein Platzhalter bleibt leer** – prüfe den internen Namen (Groß-/Kleinschreibung) und das Feld. `{{combined_image}}` ist in Legacy immer leer und braucht außerdem ein kombiniertes Produktbild in der Komponente. `{{combined_sku}}` bleibt leer, wenn keiner der gewählten Werte und keines der Merkmale eine Artikelnummer hat.
7. **Die E-Mail kommt in der falschen Sprache** – für die Sprache des Kunden fehlen Betreff oder Inhalt. Wechsle bei **Inhaltssprache:** auf die Sprache und fülle beides aus.
8. **Der Button tut nichts, ein Merkmal ist rot markiert** – ein Pflichtfeld fehlt oder eine Fehler-Regel trifft zu. Die Meldung steht am Merkmal bzw. unter dem Gesamtpreis.

## Nächste Schritte

- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [Globale Einstellungen](/docs/globale-einstellungen)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [HTML-Snippet Integration](/docs/html-snippet-integration)

---

# KI-Agent: Konfigurator per Chat aufbauen

Source: https://configento.app/docs/ki-agent-konfigurator-aufbauen
Section: Konfigurator aufbauen

Der **KI-Assistent** baut Konfiguratoren per Chat: Du beschreibst dein Produkt, und er legt Gruppen, Merkmale, Werte, Preistabellen und Regeln an. Er beantwortet auch Fragen zu einer bestehenden Komponente, erklärt Formeln und vergleicht Versionen. Dieser Artikel zeigt, wie du den Assistenten bedienst, was er kann und was nicht und wie du das Ergebnis prüfst.

## Voraussetzungen

Der Assistent ist für jedes Konto **eingeschaltet**, solange du ihn nicht abschaltest. Die Schalter findest du im Admin unter **Einstellungen → KI**:

- **KI-Assistent** – ausgeschaltet verschwindet das KI-Panel, und es werden keine Daten an den KI-Dienstleister (Anthropic) übertragen. Du kannst ihn jederzeit wieder einschalten.
- **KI-Modell** – **Sparsam**, **Standard** oder **Maximal**. Leistungsfähigere Modelle antworten besser und verbrauchen mehr Tokens. Siehe [Das KI-Modell wählen](/docs/ki-tokens#das-ki-modell-wählen).

Jede Anfrage verbraucht [KI-Tokens](/docs/ki-tokens) aus dem Kontingent deines Tarifs.

## Den Assistenten bedienen

Das KI-Panel liegt am unteren Rand des Admins, auf jeder Seite. Die Leiste zeigt von links nach rechts:

| Element | Wirkung |
|---|---|
| **KI-Assistent** | Name des Panels. Während der Assistent arbeitet, steht daneben **arbeitet…**. |
| Chat-Reiter | Deine zuletzt genutzten Chats, bis zu fünf. Weitere Chats erreichst du über den Verlauf. |
| **Neuer Chat** | Startet einen leeren Chat. |
| Uhr-Symbol (**Chat-Verlauf**) | Zeigt alle Chats mit Datum und Vorschau. Mit **Chats durchsuchen…** findest du einen alten Chat wieder. |
| Token-Anzeige | Dein aktueller Token-Bestand |
| Pfeil | **Ausklappen** bzw. **Einklappen**. Die Höhe des Panels ziehst du am oberen Rand. |

![KI-Panel am unteren Rand: Chat-Reiter, Neuer Chat, Chat-Verlauf und Token-Anzeige, darunter ein leerer Chat mit Vorschlägen und dem Eingabefeld](/storage/app/media/docs/ki-agent-konfigurator-aufbauen/01-chat-panel.webp)

Ein Rechtsklick auf einen Chat-Reiter oder einen Eintrag im Verlauf bietet **Umbenennen** und **Löschen**. Neue Chats heißen nach dem Anfang deiner ersten Nachricht.

**Achtung:** Das **×** an einem Chat-Reiter schließt den Chat nicht nur, sondern **löscht** ihn – ohne Rückfrage. Er ist danach auch im Verlauf nicht mehr zu finden.

Deine Chats sind privat: Teammitglieder sehen sie nicht. Wechselst du im Portal zu einer anderen Service Order, siehst du deren Chats.

### Nachricht schreiben

Tippe deine Anfrage in das Feld **Schreib mir, was du brauchst…** und drücke **Enter**. Ein leerer Chat bietet dir Vorschläge an, im Editor zum Beispiel „Was kann dieser Konfigurator?“ oder „Füge eine Preismatrix für Breite und Höhe hinzu“. Ein Klick übernimmt den Vorschlag ins Eingabefeld.

Während der Assistent arbeitet, zeigen kleine Hinweise unter seiner Antwort, welchen Schritt er gerade ausführt. Mit **Antwort abbrechen** stoppst du ihn.

### Wo du den Chat öffnest, zählt

| Wo | Was der Assistent darf |
|---|---|
| **Im Editor einer Komponente** | Er ändert **nur diese Komponente**. Andere Komponenten kann er lesen, z. B. zum Vergleichen, aber nicht ändern. |
| **Auf allen anderen Seiten**, z. B. in der Komponenten-Übersicht | Er legt neue Komponenten an. Bevor er eine bestehende ändert, fragt er dich, welche er nehmen soll. |

Legt der Assistent eine neue Komponente an, öffnet der Admin sie danach im Editor.

## Was der Assistent kann

| Bereich | Was er anlegt, ändert oder löscht |
|---|---|
| **Komponenten** | Neue Komponente mit Titel anlegen, alle Komponenten auflisten |
| **Gruppen** | Anlegen, umbenennen, löschen |
| **Merkmale** | Anlegen mit allen Datentypen, Einstellungen ändern, Reihenfolge ändern, löschen; ein Bild an das Merkmal hängen, das du im Chat angehängt hast |
| **Werte** | Anlegen, umbenennen, internen Wert und Aufpreis ändern, löschen |
| **Formeln** | Formeln schreiben und erklären |
| **Preismatrizen** | Preislisten-Merkmal anlegen, Tabelle hochladen, Dimensionen und Operatoren einstellen |
| **Staffelpreise** | Alle Stufen eines Staffelpreises setzen |
| **Regeln** | Regeln und Regelgruppen anlegen, ändern, verschieben und löschen; zeigen, welche Regeln ein Merkmal oder einen Wert betreffen |
| **Aktions-Button** | Aktion einrichten – **Eigene URL**, **PDF erzeugen**, **E-Mail verschicken**, **E-Mail mit PDF verschicken** – mit Betreff, Text und PDF-Vorlage |
| **Eigenes CSS und JavaScript** | Das eigene CSS und JavaScript der Komponente lesen und ergänzen |
| **Vergleichen** | Zwei Versionen oder zwei Komponenten vergleichen, z. B. „Was hat sich seit dem letzten Veröffentlichen geändert?“ |
| **Bedienfragen** | Fragen wie „Wo stelle ich die Frontend-Engine ein?“ anhand dieser Dokumentation beantworten – in der Sprache, in der du den Admin nutzt – und den passenden Artikel verlinken |

### Was er nicht kann

- **Veröffentlichen.** Das bleibt immer dein Schritt – siehe [Ergebnis prüfen und veröffentlichen](#ergebnis-prüfen-und-veröffentlichen).
- **Bausteine ändern.** Ist eine Preisliste oder ein Staffelpreis als Baustein verknüpft, lehnt er die Änderung ab. Ändere den Baustein unter **Bausteine**.
- **Bilder an Werten** und das kombinierte Produktbild einrichten. Ein Bild am Merkmal selbst kann er setzen.
- **Artikelnummern** von Werten pflegen.
- Die **Einstellungen der Komponente** ändern, z. B. Darstellung, Wizard oder Frontend-Engine, und Gruppen-Einstellungen außer dem Namen.
- **Werte-CSVs importieren** – dafür gibt es **↑ Werte importieren** im Editor, siehe [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen#werte-importieren-und-exportieren).

## Dateien anhängen

Über die Büroklammer (**Datei anhängen (PDF, Bild, Markdown, Text)**) oder per Drag & Drop in den Chat gibst du dem Assistenten Dateien mit:

| Erlaubt | Bis 10 MB pro Datei |
|---|---|
| **PDF** | z. B. Datenblätter, Preislisten, Kataloge |
| **Bilder** | JPG, PNG, GIF, WebP – z. B. eine Skizze oder ein Bild für ein Merkmal |
| **Text** | `.txt`, `.md` |

**CSV- und Excel-Dateien** nimmt der Chat nicht an. Kopiere den Inhalt als Text in den Chat oder speichere die Datei als `.txt`. Wie das am besten geht, steht in [KI-Agent: Produktdaten importieren](/docs/ki-agent-daten-importieren).

Angehängte Dateien stehen dem Assistenten 24 Stunden lang zur Verfügung. Große PDFs und Bilder verbrauchen spürbar mehr Tokens als Text.

## Ein Beispiel Schritt für Schritt

**1. Komponente anlegen** – in der Komponenten-Übersicht:

> Lege eine neue Komponente „Rollladen“ an. Breite und Höhe in cm als Eingabefelder (Breite 50–400, Höhe 50–350), Farbe als Auswahl mit Weiß, Anthrazit, Braun und RAL-Wunschfarbe (+45 €), Antrieb als Auswahl mit Manuell, Elektrisch 230 V (+120 €) und Solar (+180 €).

**2. Preistabelle übergeben** – im Editor der neuen Komponente:

> Hier ist meine Preistabelle. Spalten sind die Breite, Zeilen die Höhe, Preise in Euro. Bei Zwischenmaßen auf das nächste Tabellenmaß aufrunden.
> (Tabelle als Text einfügen)

**3. Regeln beschreiben:**

> Bei Antrieb Solar soll Weiß nicht wählbar sein. Ist die Breite über 300 cm, ist Manuell nicht möglich.

**4. Verfeinern:**

> Benenne „RAL-Wunschfarbe“ in „RAL nach Wahl“ um.
> Füge eine Checkbox „Aufmaßservice“ mit 49 € Aufpreis hinzu.

Mehr Beispiele für Regeln: [KI-Agent: Regeln per Chat definieren](/docs/ki-agent-regeln-definieren).

## Ergebnis prüfen und veröffentlichen

Jede Änderung des Assistenten landet sofort im **Entwurf** der Komponente – nicht im Shop. Ist der Editor dieser Komponente offen, lädt er den neuen Stand automatisch.

1. **Im Editor prüfen:** Stimmen Merkmale, Datentypen, Werte und Aufpreise? Sind die Regeln im Reiter **Regeln** so, wie du sie meinst?
2. **In der Vorschau testen:** Schalte auf **Vorschau** und spiele einige typische Konfigurationen durch – vor allem Preise und Regeln.
3. **Zurücknehmen, wenn nötig:** **Rückgängig** setzt den Editor auf den Stand vor der letzten Antwort des Assistenten zurück; **speichere** danach, damit das auch im Entwurf gilt. Ältere Stände holst du im Reiter **Versionen** mit **Wiederherstellen** zurück.
4. **Veröffentlichen:** Erst wenn alles passt, klicke auf **Veröffentlichen**.

Hast du im Editor noch **ungespeicherte** Änderungen, speichere sie, bevor du den Assistenten an derselben Komponente arbeiten lässt. Sonst ersetzt sein Stand deine Änderungen; mit **Rückgängig** bekommst du sie zurück.

Eine Änderung, die die Komponente beschädigen würde – z. B. eine Preisliste ohne Tabellen-Konfiguration –, nimmt der Assistent selbst wieder zurück und meldet den Fehler im Chat.

### Versionen vergleichen lassen

Im Reiter **Versionen** kannst du zwei Stände **Vergleichen**. Mit **Vergleich an KI senden** übergibst du das Ergebnis an den Assistenten und kannst ihn z. B. fragen, ob eine Änderung Folgen für die Preise hat.

## Was sich der Assistent merkt

Erklärst du dem Assistenten etwas, das er künftig wissen sollte – etwa einen Fachbegriff deiner Branche oder eine Namenskonvention –, fragt er im Chat: **Soll ich mir das merken?**

- **Ja, merken** speichert den Punkt,
- **Anpassen** lässt dich den Text vorher ändern (**Speichern und merken**),
- **Nein, vergessen** verwirft ihn.

Bestätigte Punkte nutzt er in jedem neuen Chat dieser Service Order – auch für deine Teammitglieder. Unter **Einstellungen → KI** im Abschnitt **Was wir über dich wissen** siehst du alle gemerkten Punkte und kannst sie **Anpassen** oder **Vergessen**. Siehe [Globale Einstellungen](/docs/globale-einstellungen#was-sich-der-assistent-merkt).

## Tipps für gute Ergebnisse

- **Konkret werden:** Statt „verschiedene Größen“ lieber „50, 100, 150 und 200 cm“. Nenne Aufpreise gleich mit.
- **In Schritten arbeiten:** Erst die Merkmale, dann Preise, dann Regeln. Prüfe nach jedem Schritt kurz im Editor.
- **Namen verwenden, die im Editor stehen:** Sprich Merkmale und Werte mit ihrer Bezeichnung an, z. B. „das Merkmal Antrieb“.
- **Ein Thema pro Chat:** In langen Chats vergisst der Assistent die ältesten Nachrichten. Für ein neues Thema starte einen **Neuen Chat** – das spart auch Tokens.
- **Rückfragen beantworten:** Ist etwas unklar, fragt der Assistent nach. Eine kurze Antwort ist billiger als eine Korrektur.
- **Das passende Modell wählen:** **Sparsam** reicht für einfache Merkmale und kleine Änderungen; für umfangreiche Regeln und Preislogik nimm **Standard** oder **Maximal**.

## Fehlersuche

1. **Das KI-Panel fehlt** – der Assistent ist unter **Einstellungen → KI** ausgeschaltet.
2. **Der Assistent ändert eine andere Komponente nicht** – im Editor darf er nur die geöffnete Komponente ändern. Öffne die andere Komponente oder wechsle in die Komponenten-Übersicht.
3. **Die Datei lässt sich nicht anhängen** – nur PDF, Bilder, `.txt` und `.md` bis 10 MB. CSV- und Excel-Inhalte als Text einfügen.
4. **Der Shop zeigt die Änderungen nicht** – der Assistent veröffentlicht nicht. Klicke im Editor auf **Veröffentlichen**.
5. **Die Preistabelle liefert keinen Preis** – prüfe im Merkmal unter **Matrix-Einstellungen**, ob die Dimensionen auf die richtigen Merkmale zeigen, und teste in der Vorschau. Siehe [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv#fehlersuche-die-matrix-liefert-keinen-preis).
6. **Ein Chat ist verschwunden** – das **×** am Chat-Reiter löscht den Chat endgültig.
7. **Der Token-Bestand ist im Minus** – siehe [KI-Tokens](/docs/ki-tokens#wenn-alles-verbraucht-ist).

## Nächste Schritte

- [KI-Agent: Produktdaten importieren](/docs/ki-agent-daten-importieren)
- [KI-Agent: Regeln per Chat definieren](/docs/ki-agent-regeln-definieren)
- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [KI-Tokens](/docs/ki-tokens)

---

# KI-Agent: Produktdaten importieren

Source: https://configento.app/docs/ki-agent-daten-importieren
Section: Konfigurator aufbauen

Der KI-Assistent übernimmt Produktdaten, die du schon hast – Wertelisten aus Excel, Preistabellen, Staffeln oder PDF-Datenblätter – und legt daraus Merkmale, Werte, Preismatrizen und Staffelpreise an. Dieser Artikel zeigt, wie du die Daten am besten übergibst, welche Abläufe sich bewährt haben und wann der Import ohne KI schneller ist.

Wie du den Assistenten öffnest und bedienst, steht in [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen).

## So übergibst du deine Daten

| Quelle | So kommt sie in den Chat |
|---|---|
| **Excel-Tabelle** | Zellen in Excel markieren, kopieren und in das Chat-Feld einfügen. Bei mehreren Tabellenblättern jedes Blatt einzeln. |
| **CSV-Datei** | Inhalt in einem Texteditor öffnen und in den Chat einfügen – oder die Datei in `.txt` umbenennen und anhängen. |
| **PDF** (Datenblatt, Preisliste, Katalog) | Über die Büroklammer anhängen oder in den Chat ziehen. Der Assistent liest Text und Tabellen aus dem PDF. |
| **Bilder** (z. B. ein Foto einer Preistabelle) | Anhängen wie ein PDF |
| **Eigene Aufstellung** | Als Text in den Chat schreiben, z. B. als Liste |

Anhängen kannst du **PDF**, **Bilder** (JPG, PNG, GIF, WebP), `.txt` und `.md` bis **10 MB** pro Datei. **CSV- und Excel-Dateien direkt anzuhängen ist nicht möglich** – der Chat lehnt sie ab. Eingefügter Text ist auf 100.000 Zeichen pro Nachricht begrenzt; größere Tabellen teilst du auf mehrere Nachrichten auf.

![Leerer Chat im KI-Panel: im Eingabefeld eine aus Excel eingefügte Werteliste mit Merkmal, Wert und Aufpreis, links die Büroklammer zum Anhängen](/storage/app/media/docs/ki-agent-daten-importieren/01-tabelle-einfuegen.webp)

## Werte und Aufpreise importieren

**Beispiel – Werteliste aus Excel:**

```
Merkmal;Wert;Aufpreis
Farbe;Weiß;0
Farbe;Anthrazit;0
Farbe;RAL nach Wahl;45
Material;Aluminium;0
Material;Edelstahl;80
Material;Holz;35
```

> Hier ist meine Werteliste. Lege für jedes Merkmal eine Auswahl an und übernimm die Werte mit ihren Aufpreisen in Euro.

Der Assistent legt die Merkmale **Farbe** und **Material** mit ihren Werten an. Pro Wert übernimmt er **Bezeichnung**, **Wert** (den internen Wert für Formeln und Regeln) und **Aufpreis**.

**Nicht** per KI übernehmen lassen sich:

- **Artikelnummern** der Werte,
- **Bilder** und Vorschaubilder der Werte,
- **Informationen** zu den Werten.

Diese Daten pflegst du im Editor – oder du nutzt gleich den [Import ohne KI](#import-ohne-ki).

**Beispiel – Beschreibung als Text:**

> Mein Produkt hat folgende Merkmale:
> – Breite: Eingabefeld in cm, 50 bis 400, Pflichtfeld
> – Farbe: Auswahl – Weiß, Anthrazit, Bronze (+25 €), RAL-Sonderlack (+60 €)
> – Antrieb: Auswahl – Manuell, Elektrisch 230 V (+95 €), Solar (+140 €)

## Preismatrizen importieren

Für Preise, die von zwei Größen abhängen – typisch Breite × Höhe –, legt der Assistent ein Merkmal vom Typ **Preisliste** an, lädt die Tabelle hoch, verbindet die Achsen mit deinen Merkmalen und richtet den Staffelpreis ein, damit das Ergebnis im Gesamtpreis landet.

```
;80;100;120;140
100;29.90;34.90;39.90;44.90
120;34.90;39.90;44.90;49.90
140;39.90;44.90;49.90;54.90
```

> Das ist meine Preistabelle für das Modell Classic. Die Spalten sind die Breite in cm, die Zeilen die Höhe in cm, die Zellen der Preis in Euro. Bei Zwischenmaßen soll auf das nächste Tabellenmaß aufgerundet werden.

Sag dem Assistenten immer,

- welche Achse zu welchem Merkmal gehört (Spalten = Breite, Zeilen = Höhe),
- was bei Zwischenmaßen passieren soll (exakter Treffer, auf- oder abrunden),
- ob die Zellen der fertige Preis sind oder ein Wert, mit dem weitergerechnet wird.

Wie die Matrix intern funktioniert und wie du sie im Editor nachprüfst, steht in [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv).

### Eine Tabelle ersetzen

> Hier ist die neue Preistabelle für 2027. Ersetze die bestehende Tabelle im Merkmal Preis Classic.

Der Assistent ersetzt eine Tabelle, wenn er sie unter demselben Namen hochlädt. Prüfe danach im Merkmal unter **Matrixdaten**, dass nur noch **eine** Tabelle dort steht. Bleibt die alte als erste Tabelle stehen, rechnet die Matrix weiter mit ihr – lösche sie dann über das Papierkorb-Symbol.

Ist die Preisliste als **Baustein** verknüpft (**Zentral gepflegt als Baustein**), ändert der Assistent sie nicht. Ändere die Tabelle dann unter **Bausteine** in der Hauptnavigation.

## Staffelpreise importieren

Der Assistent setzt die Stufen eines **Staffelpreises** an einer Formel, einer Kombination oder einer Preisliste – immer alle Stufen auf einmal.

> Die Formel „Länge“ ergibt Meter. Preis pro Meter: bis 10 m 12,50 €, ab 10 m 11,00 €, ab 50 m 9,50 €.

Prüfe danach im Abschnitt **Staffelpreis** die **Bedingungen**. Nur mit `>=` rechnen die Frontend-Engines Legacy und V3 gleich – siehe [Preisberechnung einrichten](/docs/preisberechnung-einrichten#bedingungen-und-die-frontend-engine).

## Daten aus einem PDF übernehmen

Hängst du ein Datenblatt oder eine Preisliste als PDF an, liest der Assistent Text und Tabellen daraus. Sag ihm, welche Seite oder Tabelle er nehmen soll:

> Im angehängten Datenblatt stehen auf Seite 3 die verfügbaren Farben und auf Seite 4 die Preistabelle für Breite × Höhe. Lege daraus die Farbauswahl und die Preismatrix an.

Bei gescannten PDFs oder sehr dichten Tabellen kann der Assistent Zahlen falsch lesen. Kontrolliere die Preise deshalb stichprobenartig im Editor unter **Matrixdaten** und in der Vorschau.

## Daten aktualisieren

> Benenne den Wert „Anthrazit“ in „Anthrazitgrau RAL 7016“ um und setze den Aufpreis auf 5 €.

> Füge der Farbe diese Werte hinzu: Silbergrau, Dunkelbraun, Cremeweiß – jeweils ohne Aufpreis.

> Setze alle Aufpreise im Merkmal Antrieb um 10 % hoch und runde auf volle Euro.

## Import ohne KI

Für manche Daten ist der Import im Editor schneller, billiger und vollständiger:

| Was | Wo im Editor | Vorteil |
|---|---|---|
| **Lange Wertelisten** | Im Merkmal **↑ Werte importieren** (CSV, mit Bildern als ZIP) | Übernimmt auch Bilder, Informationen und Sortierung, verbraucht keine Tokens. Vorlage mit **↓ Werte exportieren** erzeugen. Siehe [Werte importieren und exportieren](/docs/merkmale-optionen-anlegen#werte-importieren-und-exportieren). |
| **Preistabellen** | Im Preislisten-Merkmal unter **Matrixdaten** die CSV hochladen | Mehrere Tabellen auf einmal, direkt im Editor nachbearbeiten. Siehe [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv#schritt-für-schritt). |
| **Eine ganze Komponente** | In der Komponenten-Übersicht **ZIP importieren** | Übernimmt eine Komponente, die mit **Komponente exportieren** gesichert wurde |

Eine gute Arbeitsteilung: Die **Struktur** – Merkmale, Datentypen, Matrix-Einstellungen, Regeln – lässt du den Assistenten anlegen. **Lange Listen** und **Bilder** importierst du per CSV oder ZIP.

## Ein bewährter Ablauf

1. **Struktur beschreiben:** Welche Merkmale gibt es, welcher Datentyp, welche Einheit?
2. **Werte übergeben:** Wertelisten als Text einfügen – oder per **↑ Werte importieren**.
3. **Preise übergeben:** Preistabellen und Staffeln, jeweils mit Erklärung der Achsen.
4. **Regeln beschreiben:** Siehe [KI-Agent: Regeln per Chat definieren](/docs/ki-agent-regeln-definieren).
5. **Prüfen:** Editor und Vorschau, einige typische Konfigurationen durchrechnen.
6. **Veröffentlichen:** Das machst du selbst – der Assistent veröffentlicht nicht.

## Tipps

- **Saubere Quelldaten:** Eine Kopfzeile, keine leeren Zeilen, keine verbundenen Zellen, keine Währungszeichen in den Preiszellen.
- **Einheiten nennen:** „Breite in mm“ oder „Breite in cm“ – sonst rät der Assistent.
- **Schrittweise vorgehen:** Lieber pro Nachricht ein Merkmal oder eine Tabelle als alles auf einmal. Das ist leichter zu prüfen und spart Tokens, wenn etwas korrigiert werden muss.
- **Interne Namen vorgeben**, wenn du Formeln schon geplant hast: „Lege die Breite mit dem internen Namen `breite` an.“

## Fehlersuche

1. **Die CSV- oder Excel-Datei lässt sich nicht anhängen** – nicht unterstützt. Inhalt als Text einfügen oder die CSV als `.txt` speichern.
2. **Die Nachricht ist zu lang** – mehr als 100.000 Zeichen. Teile die Tabelle auf mehrere Nachrichten auf oder lade sie im Editor unter **Matrixdaten** hoch.
3. **Nach dem Ersetzen gelten die alten Preise** – unter **Matrixdaten** stehen zwei Tabellen, und die alte ist die erste. Alte Tabelle löschen.
4. **Der Assistent ändert die Preisliste nicht** – sie ist als Baustein verknüpft. Unter **Bausteine** ändern.
5. **Artikelnummern oder Bilder fehlen** – übernimmt der Assistent nicht. Per **↑ Werte importieren** oder im Editor ergänzen.
6. **Die Matrix liefert keinen Preis** – siehe [Fehlersuche: Die Matrix liefert keinen Preis](/docs/preismatrizen-excel-csv#fehlersuche-die-matrix-liefert-keinen-preis).

## Nächste Schritte

- [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen)
- [KI-Agent: Regeln per Chat definieren](/docs/ki-agent-regeln-definieren)
- [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv)
- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [KI-Tokens](/docs/ki-tokens)

---

# KI-Agent: Regeln per Chat definieren

Source: https://configento.app/docs/ki-agent-regeln-definieren
Section: Konfigurator aufbauen

Regeln musst du nicht im Regel-Editor zusammenklicken – du kannst sie dem KI-Agenten beschreiben: „Wenn der Antrieb Solar ist, soll die Farbe Weiß nicht wählbar sein.“ Der Agent sucht die passenden Merkmale und Werte, legt die Regel an und erklärt dir bestehende Regeln. Dieser Artikel zeigt, was der Agent kann, wie du Regeln am besten formulierst und wo du selbst nachhelfen musst.

Wie Regeln grundsätzlich funktionieren, erklärt [Regelwerk aufbauen](/docs/regelwerk-aufbauen).

## Voraussetzungen

- Der **KI-Assistent** ist eingeschaltet (**Einstellungen → KI**, siehe [Globale Einstellungen](/docs/globale-einstellungen#ki)).
- Für den Chat brauchst du KI-Tokens – siehe [KI-Tokens](/docs/ki-tokens).
- Öffne die Komponente im Editor. Am unteren Rand liegt das Panel **KI-Assistent**; mit **Neuer Chat** beginnst du ein neues Gespräch.

Im Editor arbeitet der Agent nur an der geöffneten Komponente. Wie du den Agenten allgemein bedienst, steht in [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen).

## Was der Agent anlegen kann

| Regeltyp | Was du sagst | Was der Agent anlegt |
|---|---|---|
| **Blacklist** | „… soll nicht wählbar sein“, „… ausblenden“, „… nur wenn …“ | Blendet einzelne Werte oder ganze Merkmale aus |
| **Wertvorbelegung** | „… setze die Farbe auf Weiß“ | Setzt einen Wert, mit dem Modus **Immer anwenden** |
| **Fehler / Hinweis** | „… zeige die Meldung …“ | Eine Meldung mit dem **Meldungstyp** **Fehler** |

Dazu kann der Agent

- **Regelgruppen** anlegen, umbenennen und löschen und Regeln zwischen Gruppen verschieben,
- Regeln ändern und löschen,
- auf Wunsch eine **Gewichtung** setzen, wenn zwei Regeln dasselbe Merkmal vorbelegen (wirkt nur in V3).

Den Regeltyp **Mengenvorbelegung** und **Min/Max-Vorbelegung** legst du besser selbst im Regel-Editor an. Beide wirken ohnehin nur in Legacy – siehe [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Regeln beschreiben

Nenne Merkmale und Werte so, wie sie im Editor heißen. Der Agent schlägt sie in der Komponente nach – du musst keine internen Namen kennen.

![Regel-Editor der Carport-Demo mit einer Blacklist-Regel, unten im KI-Panel die Anfrage: Wenn die Dachform Flachdach ist, sollen Bitumenschindeln nicht wählbar sein](/storage/app/media/docs/ki-agent-regeln-definieren/01-regel-anfrage.webp)

**Werte ausblenden**

> „Wenn der Antrieb Solar ist, soll die Farbe Weiß nicht wählbar sein.“

**Ein ganzes Merkmal ausblenden**

> „Wenn der Antrieb Kurbel ist, blende das Merkmal Fernbedienung aus.“

**Ein Merkmal nur unter einer Bedingung zeigen**

> „Das Merkmal Motorleistung soll nur erscheinen, wenn der Antrieb Elektrisch ist.“

Regeln können Merkmale nur ausblenden, nicht einblenden. Der Agent dreht die Bedingung deshalb um: Er blendet Motorleistung aus, solange der Antrieb **nicht** Elektrisch ist.

**Einen Wert vorbelegen**

> „Wenn das Modell Basic ist, setze die Farbe auf Weiß.“

Der Agent nimmt dafür den Modus **Immer anwenden** – die Farbe wird auch dann auf Weiß gesetzt, wenn der Kunde schon eine andere gewählt hat. Soll die Wahl des Kunden erhalten bleiben, sag es dazu oder stelle den Modus im Regel-Editor auf **Keine Auswahl oder Standardwert**.

**Eine Meldung zeigen**

> „Wenn das Material Holz ist und die Breite über 180 cm liegt, zeige den Fehler ‚Holz ist bis 180 cm Breite lieferbar.‘“

Der Agent legt eine Regel vom Typ **Fehler / Hinweis** an. Soll der Kunde trotzdem bestellen können, stelle danach im Regel-Editor den **Meldungstyp** auf **Hinweis**.

**Und / oder**

> „Wenn das Material Aluminium ist und die Breite über 250 cm liegt, ist der Antrieb Manuell nicht möglich.“

> „Wenn der Antrieb Elektrisch oder Solar ist, blende die Kurbel aus.“

Bei „oder“ zwischen Werten desselben Merkmals entsteht in der Regel eine Bedingung **enthält** mit beiden Werten.

## Was es nicht als Regel gibt

| Wunsch | So geht es |
|---|---|
| „Ab 200 cm Breite ist das Verstärkungsprofil Pflicht“ | Es gibt keine Regel, die ein Merkmal zum Pflichtfeld macht. Bitte stattdessen um eine Fehler-Regel: „Wenn die Breite über 200 cm liegt und beim Verstärkungsprofil nichts gewählt ist, zeige den Fehler ‚Bitte wähle ein Verstärkungsprofil.‘“ |
| „Bei Solar höchstens 250 cm Breite“ | In **V3** als Fehler-Regel: „Wenn der Antrieb Solar ist und die Breite über 250 cm liegt, zeige einen Fehler.“ In **Legacy** zusätzlich möglich: **Min/Max-Vorbelegung**, im Regel-Editor angelegt. |
| „Alle RAL-Farben ausblenden“ | Eine Regel kennt keine Platzhalter wie „RAL*“, sondern nur einzelne Werte. Der Agent sucht die passenden Werte heraus und trägt sie einzeln ein. Kommen später neue RAL-Werte dazu, nimmt die Regel sie nicht automatisch auf – ergänze sie per Chat oder im Regel-Editor. |

## Viele Regeln auf einmal

Du kannst mehrere Regeln in einer Nachricht beschreiben, als Liste oder Tabelle:

> „Lege folgende Regeln in einer neuen Regelgruppe Antrieb an:
> 1. Solar: Farbe Weiß nicht wählbar
> 2. Kurbel: Fernbedienung ausblenden
> 3. Edelstahl: kein Solar-Antrieb“

Eine Tabelle fügst du als Text in den Chat ein, z. B. aus Excel kopiert:

```
Wenn Merkmal;Wert;Dann;Merkmal;Wert
Antrieb;Solar;ausblenden;Farbe;Weiß
Antrieb;Kurbel;ausblenden;Fernbedienung;
Material;Edelstahl;ausblenden;Antrieb;Solar
```

Als Datei nimmt der Chat nur PDF, Bilder, Markdown und Text (`.md`, `.txt`) bis 10 MB an – keine CSV- oder Excel-Dateien. Speichere eine Tabelle zur Not als `.txt` oder füge den Inhalt direkt ein.

Bei längeren Listen beschreibt der Agent meist zuerst, was er anlegen will. Prüfe den Plan, bevor du ihn loslegen lässt.

## Regeln abfragen

Der Agent beantwortet auch Fragen zu bestehenden Regeln:

> „Welche Regeln betreffen das Merkmal Farbe?“

> „Was macht die Regel Holz ohne RAL?“

> „Liste alle Regeln der Regelgruppe Antrieb.“

Er nennt dabei Regeln, Merkmale und Werte mit ihren Bezeichnungen. Im Editor siehst du dasselbe am Merkmal im Reiter **Referenziert in**.

## Regeln korrigieren und löschen

> „In der Regel Holz ohne RAL sollen Weiß und Braun wieder wählbar sein.“

> „Lösche die Regel Kurbel ohne Fernbedienung.“

Löscht der Agent eine Regelgruppe, verschwinden alle Regeln darin. Willst du Regeln behalten, sag ihm vorher, dass er sie in eine andere Gruppe verschieben soll.

## Kontrolle im Regel-Editor

Der Agent schreibt seine Änderungen direkt in den Entwurf der Komponente, der Editor lädt sie neu.

1. Speichere eigene Änderungen, bevor du den Agenten arbeiten lässt. Mit **Rückgängig** kommst du auf den Stand vor seiner Änderung zurück.
2. Prüfe die neuen Regeln im Reiter **Regeln**: Stimmen Bedingung, Regeltyp und Wirkung?
3. Teste typische Kombinationen in der **Vorschau**.
4. **Veröffentliche** die Komponente. Das kann nur du – der Agent veröffentlicht nie.

## Fehlersuche

1. **Die Regel greift nicht** – lass sie dir erklären: „Was macht die Regel …?“ Prüfe im Regel-Editor, ob Bedingung und ausgeblendete Werte stimmen. Im Shop gilt sie erst nach dem Veröffentlichen.
2. **Der Agent findet ein Merkmal nicht** – nenne die Bezeichnung genau so wie im Editor, oder die Gruppe dazu: „das Merkmal Farbe in der Gruppe Gehäuse“.
3. **Die Wahl des Kunden wird überschrieben** – die Wertvorbelegung steht auf **Immer anwenden**. Stelle den Modus um.
4. **Der Kunde kann trotz Meldung nicht bestellen** – die Meldung ist ein **Fehler**. Für einen Hinweis stelle den **Meldungstyp** um.
5. **Eine Min/Max- oder Mengenvorbelegung wirkt nicht** – die Komponente läuft mit V3, das diese Regeltypen nicht kennt. Nimm eine Fehler-Regel.
6. **Der Agent ändert eine andere Komponente nicht** – im Editor arbeitet er nur an der geöffneten Komponente. Öffne die andere Komponente.

## Nächste Schritte

- [Regelwerk aufbauen](/docs/regelwerk-aufbauen)
- [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen)
- [KI-Agent: Produktdaten importieren](/docs/ki-agent-daten-importieren)
- [KI-Tokens](/docs/ki-tokens)

---

# Bausteine & Preislisten

Source: https://configento.app/docs/bausteine-preislisten
Section: Preise & Regeln

Verwendest du dieselbe Preistabelle oder dieselbe Staffel in vielen Komponenten, musst du sie nicht in jeder einzeln pflegen. Unter **Bausteine** legst du sie einmal zentral an und verknüpfst sie mit den Merkmalen, die sie brauchen. Änderst du den Baustein, übernimmt configento.app die neue Fassung in alle verknüpften Komponenten – auf Wunsch gleich veröffentlicht. Dieser Artikel zeigt, wie das funktioniert.

## Was ein Baustein ist

Ein Baustein ist eine zentral gepflegte Preisliste. Es gibt zwei Arten:

| Art | Inhalt | Passt zu |
|---|---|---|
| **Preisliste** | Eine oder mehrere Tabellen, z. B. Preise nach Breite × Höhe | Merkmalen vom Datentyp **Preisliste** – ersetzt dort die **Matrixdaten** |
| **Staffelpreis** | Stufen mit Bedingung, Wert und Preis | Dem Abschnitt **Staffelpreis** von **Formel** und **Einfache Kombination** |

Zentral ist nur der Inhalt. Alles andere bleibt je Komponente eigenständig: bei der Preisliste die **Matrix-Einstellungen** (welche Merkmale Zeile und Spalte bestimmen, Operatoren), beim Staffelpreis der **Preis-Operator**.

Bausteine gehören zu einer Service Order. Sie stehen in allen Komponenten dieser Service Order zur Verfügung, aber nicht in anderen.

## Die Übersicht

Du erreichst die Bausteine über **Bausteine** in der Hauptnavigation. Die Liste zeigt je Baustein:

| Spalte | Bedeutung |
|---|---|
| **Name** | Name des Bausteins, ein Klick öffnet ihn |
| **Art** | **Preisliste** oder **Staffelpreis** |
| **Verwendet in** | Anzahl der verknüpften Komponenten |
| **Version** | Aktuelle Version, z. B. `v3` |
| **Letzter Lauf** | Ergebnis der letzten Übertragung: **alles erledigt**, **läuft …** oder die Zahl der Komponenten, die **fehlgeschlagen** oder **nicht veröffentlicht** sind |

## Einen Baustein anlegen

Es gibt zwei Wege.

**Aus einer bestehenden Komponente** – der übliche Weg, wenn die Liste schon gepflegt ist:

1. Öffne die Komponente und das Merkmal mit der Liste.
2. Klicke im Abschnitt **Matrixdaten** auf **Als zentrale Preisliste anlegen** bzw. im Abschnitt **Staffelpreis** auf **Als zentralen Staffelpreis anlegen**.
3. Vergib einen **Name des Bausteins** und klicke auf **Erstellen**.

Der Baustein übernimmt den Inhalt des Merkmals und ist sofort mit ihm verknüpft. Ist das Merkmal noch nicht gespeichert, erscheint „Bitte zuerst die Komponente speichern — das Merkmal ist noch nicht gespeichert.“

**Neu unter Bausteine:**

1. Klicke auf **Neuer Baustein**.
2. Gib einen **Name** ein und wähle **Preisliste** oder **Staffelpreis**.
3. Trage die Tabelle oder die Stufen ein und klicke auf **Erstellen**.

![Dialog „Neuer Baustein“: Name, Preisliste oder Staffelpreis, CSV hochladen oder leere Matrix anlegen](/storage/app/media/docs/bausteine-preislisten/01-neuer-baustein.webp)

## Komponenten verknüpfen

### Einzeln im Merkmal

Im Abschnitt **Matrixdaten** bzw. **Staffelpreis** wählst du **Mit zentraler Preisliste verknüpfen …** bzw. **Mit zentralem Staffelpreis verknüpfen …** und dann den Baustein aus der Liste. Die Liste im Merkmal wird dabei durch die zentrale ersetzt.

### Viele auf einmal im Baustein

Im Baustein öffnest du den Reiter **Verknüpfte Komponenten** und klickst auf **Weitere verknüpfen …**. configento.app durchsucht alle Komponenten der Service Order und gruppiert die passenden Merkmale:

| Gruppe | Bedeutung |
|---|---|
| **Inhaltsgleich** | Die Liste entspricht schon genau dem Baustein. Diese Merkmale sind vorausgewählt. |
| **Gleicher Name, anderer Inhalt** | Das Merkmal heißt wie ein Merkmal, das schon mit dem Baustein verknüpft ist, die Liste weicht aber ab – z. B. „weicht in 3 von 40 ab“ |
| **Übrige Merkmale dieser Art** | Alle anderen passenden Merkmale. Sie werden erst mit **… übrige Merkmale dieser Art anzeigen** eingeblendet. |

Über das Suchfeld filterst du nach Komponente oder Merkmal, mit **Alle auswählen** und **Keine auswählen** wählst du eine Gruppe ganz aus oder ab. Merkmale, die schon mit einem anderen Baustein verknüpft sind, tragen den Hinweis **anderswo verknüpft**.

Wähle, ob die betroffenen Komponenten gleich veröffentlicht werden sollen (**Betroffene Komponenten veröffentlichen**), und klicke auf **… verknüpfen**. Bei Merkmalen mit abweichendem Inhalt ist das eine Preisänderung: Ihre Liste wird durch den Baustein ersetzt.

Eine Preisliste lässt sich nur mit Merkmalen vom Datentyp **Preisliste** verknüpfen. Für einen Staffelpreis sucht **Weitere verknüpfen …** nur Merkmale, die schon mindestens eine Stufe haben; ein Merkmal ohne Staffel verknüpfst du einzeln im Merkmal.

Ein Merkmal vom Datentyp **Preisliste** verknüpft seine Tabelle als Baustein. Im Abschnitt **Staffelpreis** eines solchen Merkmals bietet der Editor deshalb keinen zentralen Staffelpreis an – pflege die Staffel dort in der Komponente. Scheitert das Verknüpfen eines neu angelegten Bausteins, entfernt der Editor den Baustein gleich wieder, damit keiner ohne Verwendung übrig bleibt.

### Woran du eine Verknüpfung erkennst

Ein verknüpftes Merkmal zeigt den Hinweis **Zentral gepflegt als Baustein:** mit dem Namen des Bausteins und den Links **Zentral bearbeiten** und **Verknüpfung lösen**.

## Den Inhalt ändern

Du kannst einen Baustein an zwei Stellen ändern – das Ergebnis ist dasselbe:

- **Im Baustein**, Reiter **Inhalt**: Name und Tabelle bzw. Stufen bearbeiten, dann **Speichern**.
- **Direkt im verknüpften Merkmal**: Die Tabelle bzw. Staffel ist dort bearbeitbar. Sobald du etwas änderst, erscheint „Diese Änderung gilt für alle … verknüpften Komponenten.“ mit **Zentral speichern** und **Verwerfen**.

In beiden Fällen entscheidest du mit **Betroffene Komponenten veröffentlichen**, ob die Komponenten gleich live gehen. Jede gespeicherte Änderung wird eine neue **Version** des Bausteins.

### Was mit den Komponenten passiert

configento.app überträgt die Änderung im Hintergrund in jede verknüpfte Komponente. Der Fortschritt erscheint als „… von … Komponenten“, am Ende steht ein Bericht:

| Ergebnis | Bedeutung |
|---|---|
| **aktualisiert und veröffentlicht** | Die Komponente ist mit der neuen Liste live. |
| **nur im Entwurf aktualisiert — sie haben unveröffentlichte Änderungen** | Die Komponente hatte eigene, noch nicht veröffentlichte Änderungen. Damit diese nicht ungefragt live gehen, steht die neue Liste nur im Entwurf. |
| **nur im Entwurf aktualisiert — noch nie veröffentlicht** | Die Komponente war noch nie veröffentlicht. |
| **nur im Entwurf aktualisiert — Veröffentlichen war nicht gewählt** | Du hast **Betroffene Komponenten veröffentlichen** abgewählt. |
| **unverändert — bereits aktuell** | Die Komponente hatte die Liste schon. |
| **fehlgeschlagen** | Die Komponente konnte nicht aktualisiert oder veröffentlicht werden, z. B. weil sie Fehler enthält, die das Veröffentlichen verhindern. |

Für die Fälle, die offen bleiben, bietet der Bericht:

- **Diese … jetzt veröffentlichen …** – veröffentlicht die Komponenten mit eigenen unveröffentlichten Änderungen. Vorher fragt configento.app nach, denn deren andere Änderungen gehen dabei mit live.
- **Fehlgeschlagene erneut versuchen** – startet die Übertragung für die fehlgeschlagenen Komponenten neu. Wurde das Veröffentlichen wegen Fehlern in der Komponente abgelehnt, behebe sie zuerst und veröffentliche die Komponente dann selbst.

Alle bisherigen Übertragungen findest du im Reiter **Läufe**, jeweils mit **Bericht anzeigen**.

## Versionen

Der Reiter **Versionen** listet alle Fassungen des Bausteins. Mit **Wiederherstellen** holst du eine ältere zurück: Sie wird zur neuen Version und in die verknüpften Komponenten übernommen – mit Veröffentlichen.

## Verknüpfung lösen und Baustein löschen

- **Verknüpfung lösen** im Merkmal oder im Reiter **Verknüpfte Komponenten**: Die Komponente behält ihre aktuelle Kopie der Liste. Ab dann pflegst du sie wieder in der Komponente, Änderungen am Baustein erreichen sie nicht mehr.
- **Löschen** im Baustein: Ist er noch verknüpft, fragt configento.app „… Komponenten lösen und löschen? Sie behalten ihre aktuelle Kopie.“ Die Preise in den Komponenten ändern sich dadurch nicht.

## Frontend-Engines und Rechte

Der Inhalt eines Bausteins wird in jede verknüpfte Komponente kopiert. Für den Shop ist eine verknüpfte Liste deshalb eine ganz normale Liste – Bausteine funktionieren mit **Legacy** und mit **V3**. Für Staffelpreise gelten dieselben Engine-Unterschiede wie sonst auch, siehe [Preisberechnung einrichten](/docs/preisberechnung-einrichten#bedingungen-und-die-frontend-engine).

Bausteine pflegt jeder, der den Admin der Service Order nutzt. Über die API brauchst du einen API-Schlüssel mit **Lesen & Schreiben**; damit betroffene Komponenten gleich veröffentlicht werden, zusätzlich **Veröffentlichen** – siehe [API-Einstieg](/docs/api-einstieg).

## Fehlersuche

1. **„Bitte zuerst die Komponente speichern — das Merkmal ist noch nicht gespeichert.“** – das Merkmal ist neu. Speichere die Komponente und versuche es noch einmal.
2. **Der Shop zeigt noch die alten Preise** – die Komponente wurde nur im Entwurf aktualisiert. Öffne den Bericht im Reiter **Läufe** und veröffentliche die offenen Komponenten.
3. **Ein Merkmal fehlt bei Weitere verknüpfen …** – es passt nicht zur Art des Bausteins (eine Preisliste nur zu Merkmalen vom Datentyp **Preisliste**, ein Staffelpreis nur zu Merkmalen, die schon eine Stufe haben), ist bereits mit diesem Baustein verknüpft oder gehört zu einer anderen Service Order. Prüfe auch **… übrige Merkmale dieser Art anzeigen**.
4. **Der Preis stimmt nach dem Verknüpfen nicht** – die **Matrix-Einstellungen** oder der **Preis-Operator** der Komponente passen nicht zur zentralen Liste. Sie werden nicht mit verknüpft.
5. **Eine Komponente ist fehlgeschlagen** – öffne sie über den Bericht, behebe die gemeldeten Fehler und klicke auf **Fehlgeschlagene erneut versuchen** oder veröffentliche sie selbst.

## Nächste Schritte

- [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv)
- [Preisberechnung einrichten](/docs/preisberechnung-einrichten)
- [Formeln & Berechnungen](/docs/preisformeln)

---

# Berechnungs-Merkmale

Source: https://configento.app/docs/berechnungs-merkmale
Section: Preise & Regeln

Nicht jedes Merkmal fragt den Kunden etwas. Merkmale der Datenkategorie **Berechnung** ermitteln einen Wert selbst – aus einer Formel, einer Tabelle, anderen Merkmalen, dem Shop-Produkt oder einer externen Adresse. Diesen Wert zeigst du an, verwendest ihn in Formeln und Regeln weiter oder machst daraus einen Preis. Dieser Artikel stellt die sechs Datentypen vor und zeigt, wann du welchen nimmst.

## Die sechs Datentypen im Überblick

Du wählst den Datentyp in den Grundeinstellungen des Merkmals unter **Berechnung**:

| Datentyp | Ergebnis | Typischer Einsatz | Kann einen Preis bilden |
|---|---|---|---|
| **Formel** | Zahl oder Text aus einem Rechenausdruck | Fläche, Gewicht, Preis nach eigener Logik | ja, über den **Staffelpreis** |
| **Preisliste** | Wert aus einer Tabelle | Preis nach Breite × Höhe | ja, über den **Staffelpreis** |
| **Einfache Kombination** | Summe, Produkt oder Text aus anderen Merkmalen | Gesamtlänge, zusammengesetzte Artikelbezeichnung | ja, über den **Staffelpreis** |
| **Produktattribut** | Feld des Shop-Produkts | Gewicht oder Grundmaß aus dem Shop | nur über eine Formel |
| **Webservice** | Wert von einer externen Adresse | Tageskurs, Materialpreis aus einem anderen System | nur über eine Formel |
| **Paket** | Schalter, der Werte in anderen Merkmalen auswählt | Ausstattungspaket „Komfort“ | ja, mit eigenem Paketpreis |

**Webservice** und **Paket** gibt es nur im Tarif **Ultimate** – siehe [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen#tarif-und-frontend-engine).

Berechnungs-Merkmale sind keine Pflichtfelder – der Schalter **Pflichtfeld** fehlt bei ihnen. Was der Kunde von ihnen sieht, steuerst du über **Sichtbarkeit**: **Ja (sichtbar)** zeigt das Ergebnis als Text an, **Nein (versteckt)** rechnet im Hintergrund mit. Für Hilfswerte, die nur andere Merkmale füttern, ist **versteckt** die übliche Wahl.

## Vom Ergebnis zum Preis

Formel, Preisliste und Einfache Kombination liefern zunächst nur einen Wert. Zum Preis wird er über den Abschnitt **Staffelpreis** und das Feld **Preis-Operator**:

| Preis-Operator | Was in den Preis fließt |
|---|---|
| **Preis** | Der Preis der passenden Staffelstufe |
| **Wert × Preis** | Das Ergebnis mal den Preis der passenden Stufe |

Ohne Staffelstufe fließt nichts in den Preis. Ist das Ergebnis selbst schon der Preis, legst du eine Stufe mit Bedingung `>=`, Wert `0` und Preis `1` an und wählst **Wert × Preis**. Fehlt die Stufe, obwohl ein Preis-Operator gesetzt ist, warnt die Prüfung beim Veröffentlichen. Ausführlich mit Beispielen: [Formeln & Berechnungen](/docs/preisformeln#ergebnis-in-den-preis-übernehmen) und [Preisberechnung einrichten](/docs/preisberechnung-einrichten#staffelpreis).

Produktattribut und Webservice haben keinen Staffelpreis. Ihren Wert holst du mit `$name` in eine Formel und machst dort den Preis daraus.

## Formel

Die **Formel** ist das vielseitigste Berechnungs-Merkmal: Unter **Formel-Einstellungen** schreibst du im Feld **Berechnung (Formel)** einen Ausdruck wie `$breite * $hoehe / 10000`. Dazu gehören **Preis-Operator** und **Dezimalstellen**.

![Merkmal mit Datentyp Formel: Formel-Einstellungen mit Berechnung, Preis-Operator und Dezimalstellen](/storage/app/media/docs/berechnungs-merkmale/01-formel.webp)

Syntax, Funktionen, leere Felder und Praxisbeispiele beschreibt [Formeln & Berechnungen](/docs/preisformeln).

## Preisliste

Die **Preisliste** schlägt einen Wert in einer Tabelle nach – etwa den Preis für 120 cm Breite und 200 cm Höhe. Sie hat die Abschnitte **Matrix-Einstellungen** (welche Merkmale die Zeile und die Spalte bestimmen, wie gesucht wird) und **Matrixdaten** (die Tabellen selbst) sowie einen **Staffelpreis**.

Alles zu Tabellenformat, Operatoren und mehreren Tabellen: [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv).

## Einfache Kombination

Die **Einfache Kombination** verknüpft mehrere Merkmale ohne Formel. Unter **Kombinations-Einstellungen** stellst du ein:

| Feld | Bedeutung |
|---|---|
| **Kombinierte Werte** | Die Merkmale, deren Werte verknüpft werden |
| **Wert-Operator** | **+ (Addition)** zählt die Werte zusammen, **\* (Multiplication)** multipliziert sie, **String** hängt sie als Text aneinander |
| **Preis-Operator** | Wie bei der Formel: **Preis** oder **Wert × Preis** |
| **Dezimalstellen** | Nachkommastellen des Ergebnisses |

Von einem Auswahl-Merkmal fließt der **Wert** des gewählten Werts ein, nicht seine Bezeichnung. Für „Breite + Zugabe“ müssen die Werte also Zahlen sein, z. B. `120`.

Beachte dabei:

- Bei **+** und **\*** müssen alle kombinierten Merkmale eine Zahl liefern. Ist eines leer oder Text, hat die Kombination kein Ergebnis.
- Ein Ergebnis aus **String** ist Text. Er eignet sich für Anzeige und Bestellung, aber nicht für einen Preis.
- Der Wert-Operator **Formel** liefert in beiden Engines kein Ergebnis. Brauchst du eine Rechnung, nimm den Datentyp **Formel**.
- **Mindestwert** und **Höchstwert** begrenzen das Ergebnis nicht.

Diskrete Merkmale wie Auswahl oder Radio Buttons haben unter **Kombination & Darstellung** einen eigenen Schalter **Kombination**. Er verknüpft das Merkmal selbst mit anderen – das ist etwas anderes als der Datentyp **Einfache Kombination**.

## Produktattribut

Das **Produktattribut** übernimmt einen Wert vom Produkt im Shop. Unter **Produktattribut-Einstellungen** trägst du im Feld **Produktattribut** den Code des Attributs ein, z. B. `weight`.

Wo das funktioniert:

| Integration und Engine | Ergebnis |
|---|---|
| **Magento 2** mit **Legacy** | Der Wert des Attributs am Produkt, über den Attribut-Code aus Magento |
| **Magento 2** mit **V3** | Der Wert des Attributs am Produkt, ab Version 5.0.0-beta18 der Magento-Erweiterung |
| **PrestaShop 9** (immer **V3**) | Ein Feld des Produkts, eine Eigenschaft oder ein Attribut der gewählten Kombination – siehe [PrestaShop-Plugin installieren](/docs/prestashop-plugin-installieren#produktdaten-in-formeln) |
| Shopware 6, Shopify, HTML-Snippet | Leer |

Zahlen übernimmt das Merkmal als Zahl, damit eine Formel damit rechnen kann. In der Vorschau im Admin gibt es kein Shop-Produkt – auch dort bleibt das Merkmal leer. Rechnet eine Formel mit dem Attribut, prüfe sie deshalb im Shop. Mehr zu den Engines: [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Webservice

Der **Webservice** holt beim Laden des Konfigurators einen Wert von einer externen Adresse. Unter **Webservice-Einstellungen** gibt es:

| Feld | Bedeutung |
|---|---|
| **Webservice-URL** | Die vollständige Adresse, z. B. `https://api.example.com/kurs` |
| **Rückgabe-Format** | **JSON** oder **XML** |
| **JSPath** / **XPath** | Wo der Wert in der Antwort steht, z. B. `$.data.value` bei JSON oder `//root/item` bei XML. Leer lassen übernimmt die ganze Antwort. |

So arbeitet der Webservice:

- Die Adresse wird **einmal** beim Laden abgerufen, nicht bei jeder Auswahl. Werte aus dem Konfigurator kannst du nicht in die Adresse einsetzen.
- Der Abruf läuft über den Server von configento.app. Deine Schnittstelle muss deshalb keine Browser-Zugriffe (CORS) erlauben, aber öffentlich erreichbar sein.
- Das Ergebnis steht in Formeln als `$name` zur Verfügung. Solange die Antwort fehlt, ist der Wert leer.
- V3 versteht bei JSON einfache Pfade wie `$.data.value`, `data.items[0].price` oder `data["preis"]`. Filter und Suchausdrücke kennt nur die Legacy-Engine.

## Paket

Das **Paket** ist ein Schalter für den Kunden. Schaltet er es ein, werden in anderen Merkmalen festgelegte Werte ausgewählt; schaltet er es aus, werden sie wieder abgewählt. Ein Paket kann einen eigenen Paketpreis haben.

Beides legst du in den Einstellungen des Merkmals fest: Unter **Paketpreis** trägst du den Aufpreis ein, der gilt, solange das Paket eingeschaltet ist. Unter **Merkmal zum Paket hinzufügen** wählst du ein Merkmal und darin die Werte, die das Paket auswählt – für jedes Merkmal, das zum Paket gehört. Die Zuordnung bleibt erhalten, wenn du Merkmale später umsortierst.

## Unterschiede zwischen den Engines

| Thema | Legacy | V3 |
|---|---|---|
| **Dezimalstellen** bei Formel und Kombination | Rundet das Ergebnis und rechnet gerundet weiter | Rundet nur die Anzeige |
| **Produktattribut** | Funktioniert in Magento 2 | Funktioniert in Magento 2 ab Version 5.0.0-beta18 der Erweiterung und in PrestaShop 9 |
| **Webservice**-Pfad bei JSON | Vollständiges JSONPath | Einfache Pfade |

Mehr dazu: [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Fehlersuche

1. **Das Ergebnis zählt nicht zum Preis** – der **Staffelpreis** fehlt. Lege eine Stufe an (`>=`, Wert `0`, Preis `1`) und wähle **Wert × Preis**.
2. **Die Kombination zeigt nichts** – eines der **Kombinierten Werte** ist leer oder keine Zahl, oder als **Wert-Operator** ist **Formel** gewählt.
3. **Das Produktattribut bleibt leer** – es funktioniert nur in Magento 2 (mit V3 ab Version 5.0.0-beta18 der Erweiterung) und in PrestaShop 9, nicht in der Vorschau. Prüfe auch den Attribut-Code.
4. **Der Webservice liefert keinen Wert** – öffne die Adresse im Browser und prüfe, ob die Antwort wirklich JSON oder XML ist und ob der Pfad zur Struktur passt. In V3 funktionieren nur einfache JSON-Pfade.
5. **Werte weichen um Cent-Beträge ab** – die Legacy-Engine rundet über **Dezimalstellen**, V3 nicht. Runde in der Formel selbst, siehe [Formeln & Berechnungen](/docs/preisformeln#dezimalstellen).
6. **Ein Berechnungs-Merkmal erscheint nicht im Konfigurator** – die **Sichtbarkeit** steht auf **Nein (versteckt)**, oder eine Regel blendet es aus.

## Nächste Schritte

- [Formeln & Berechnungen](/docs/preisformeln)
- [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv)
- [Preisberechnung einrichten](/docs/preisberechnung-einrichten)
- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)

---

# Preisberechnung einrichten

Source: https://configento.app/docs/preisberechnung-einrichten
Section: Preise & Regeln

Der Konfigurator rechnet den Preis bei jeder Auswahl neu aus. Dieser Artikel zeigt, aus welchen Quellen sich der Preis zusammensetzt, wo du sie einstellst und wie die Aufpreise angezeigt werden. Formeln und Preismatrizen haben eigene Artikel – hier findest du den Überblick und die Grundlagen.

## Wie sich der Preis zusammensetzt

Der Konfigurator addiert die Beiträge aller Merkmale:

| Quelle | Wo du sie pflegst | Typischer Einsatz |
|---|---|---|
| **Aufpreis an einem Wert** | Feld **Preis** am Wert | Farbe, Material, Zubehör |
| **Staffelpreis** | Abschnitt **Staffelpreis** an Formel, Einfacher Kombination oder Preisliste | Preis je Meter, Mengenrabatt |
| **Formel** | Merkmal vom Typ **Formel** | Fläche × Quadratmeterpreis |
| **Preismatrix** | Merkmal vom Typ **Preisliste** | Breite × Höhe aus einer Tabelle |
| **Preise für Wert aus Matrix** | Einstellung am Auswahl-Merkmal | Aufpreis je Farbe hängt von der Größe ab |

Eine Komponente hat **keinen eigenen Grundpreis**. Den Grundpreis liefert dein Shop, oder du bildest ihn selbst ab – etwa als Wert ohne Wahlmöglichkeit oder über eine Formel.

### Was der Shop daraus macht

| Integration | Preis im Warenkorb |
|---|---|
| **Magento 2, Engine Legacy** | Produktpreis aus Magento + Preis der Konfiguration |
| **Magento 2, Engine V3** | Der Gesamtpreis des Konfigurators **ersetzt** den Magento-Produktpreis |
| **Shopware 6** | Produktpreis aus Shopware + Preis der Konfiguration |
| **HTML-Snippet** | Nur der Preis der Konfiguration – einen Shop-Preis gibt es nicht |

Für Shopify siehe [Shopify-Plugin installieren](/docs/shopify-plugin-installieren). Was die Engines unterscheidet, erklärt [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Aufpreise an Werten

Die einfachste Preisquelle: Jeder Wert eines Auswahl-Merkmals bekommt einen Aufpreis.

1. Wähle im Strukturbaum das Merkmal aus.
2. Öffne rechts im Abschnitt **Werte** den gewünschten Wert.
3. Trage unter **Grundeinstellungen** im Feld **Preis** den Aufpreis ein, z. B. `45` oder `12.50`.

Wählt der Kunde den Wert, wird der Betrag addiert. Bei Mehrfachauswahl und Checkboxen werden alle gewählten Werte addiert. Ein negativer Betrag wirkt als Abschlag.

**Schreib Preise mit Punkt** (`12.50`), nicht mit Komma. Ein Komma (`12,50`) wird beim Rechnen nicht zuverlässig gelesen und kann den Aufpreis auf 12 oder 0 setzen.

### Mengen

| Merkmal | Wie die Menge wirkt |
|---|---|
| **Mehrfachauswahl mit Mengen** | Der Kunde gibt je Wert eine Menge ein. Aufpreis = Preis des Werts × Menge. Gilt in beiden Engines. |
| **Auswahl, Radio Buttons, Checkbox, Liste mit Bildern** mit Einstellung **Menge** = **Freie Eingabe** oder **Bereich** | Vor dem Wert erscheint ein Mengenfeld: bei **Freie Eingabe** ein Zahlenfeld, bei **Bereich** eine Auswahlliste von **Min. Menge** bis **Max. Menge**. Bei Checkbox gibt es je angehaktem Wert ein eigenes Feld. Aufpreis = Preis × Menge; eine leere Menge zählt als 1. In der Zusammenfassung steht z. B. „3x Eiche“. Gilt in beiden Engines. |

## Wie Aufpreise angezeigt werden

Wie der Aufpreis neben jedem Wert erscheint, stellst du für die ganze Komponente ein: Reiter **Einstellungen** → **Allgemein** → Abschnitt **Aufpreis**.

| Einstellung | Wirkung |
|---|---|
| **Preisanzeige** | Zeigt den Aufpreis neben den Werten und in der Zusammenfassung. Ausgeschaltet werden die Aufpreise nicht angezeigt – **gerechnet** wird trotzdem. |
| **Preistyp** | **Absolut**: der Aufpreis des Werts, z. B. „+45,00 €“. **Relativ**: der Unterschied zum gerade gewählten Wert – der gewählte Wert zeigt nichts, ein teurerer „+20,00 €“, ein günstigerer „-15,00 €“. |
| **Bei Null anzeigen** | Zeigt auch Werte ohne Aufpreis mit „0,00 €“. Aus: Werte ohne Aufpreis bleiben ohne Preisangabe. |
| **Preismuster** | Text rund um den Aufpreis. `$price` wird durch den fertigen Betrag ersetzt – mit Vorzeichen und Währung, z. B. `+45,00 €`. Beispiel: `[$price]` ergibt „[+45,00 €]“, `(Aufpreis $price)` ergibt „(Aufpreis +45,00 €)“. |

Positive Beträge bekommen immer ein „+“ davor. Schreib deshalb kein eigenes „+“ und kein Währungszeichen ins Muster.

**Gesamtpreis:** In der Engine V3 zeigt der Konfigurator unten eine Leiste mit dem Gesamtpreis und dem Zusatz „inkl. MwSt.“ oder „zzgl. MwSt.“. Die Leiste bleibt auch sichtbar, wenn **Preisanzeige** aus ist. In einem Shop zeigt in der Regel der Shop selbst den Gesamtpreis an der gewohnten Stelle.

## Staffelpreis

Formeln, Einfache Kombinationen und Preislisten liefern zunächst nur eine **Zahl**, z. B. eine Fläche oder einen Tabellenwert. Damit daraus ein Preis wird, braucht das Merkmal einen **Staffelpreis**.

1. Öffne beim Merkmal den Abschnitt **Staffelpreis**.
2. Lege mit **+ Stufe hinzufügen** eine oder mehrere Stufen an. Jede Stufe hat eine **Bedingung**, eine **Menge** und einen **Preis**.
3. Stelle den **Preis-Operator** ein:
   - **Preis**: Der Preis der passenden Stufe ist der Aufpreis.
   - **Wert × Preis**: Das Ergebnis des Merkmals wird mit dem Preis der passenden Stufe multipliziert.

**Beispiel Meterpreis mit Mengenrabatt** – eine Formel liefert die Länge in Metern, Preis-Operator **Wert × Preis**:

| Bedingung | Menge | Preis |
|---|---|---|
| `>=` | 0 | 12.50 |
| `>=` | 10 | 11.00 |
| `>=` | 50 | 9.50 |

Bei 24 Metern greift die Stufe ab 10: 24 × 11,00 = 264,00 €.

**Ein Ergebnis direkt als Preis übernehmen** – etwa bei einer Preismatrix mit Endpreisen: eine Stufe `>=` 0 mit Preis `1` und Preis-Operator **Wert × Preis**.

### Bedingungen und die Frontend-Engine

Neue Stufen werden mit `>=` angelegt. Das ist die einzige Bedingung, bei der beide Engines gleich rechnen:

- **V3** wertet jede Bedingung aus (`>=`, `>`, `=`, `<=`, `<`, `!=`). Passen mehrere Stufen, gewinnt die, deren Grenze am nächsten an der Eingabe liegt.
- **Legacy** ignoriert die Bedingung. Es nimmt immer die höchste Stufe, deren Menge kleiner oder gleich der Eingabe ist; liegt die Eingabe unter allen Stufen, gilt die kleinste.

Eine Stufe „`>` 10“ greift in V3 also erst ab 11, in Legacy schon ab 10. Bleib bei `>=`, wenn deine Komponente in beiden Engines gleich rechnen soll.

### Zentral gepflegter Staffelpreis

Verwendest du dieselbe Staffel in mehreren Komponenten, pflege sie als **Baustein**: Im Abschnitt **Staffelpreis** wählst du **Als zentralen Staffelpreis anlegen** oder **Mit zentralem Staffelpreis verknüpfen …**. Verknüpfte Merkmale zeigen **Zentral gepflegt als Baustein:**, geändert wird die Staffel dann unter **Bausteine** in der Hauptnavigation – für alle verknüpften Komponenten auf einmal. **Verknüpfung lösen** macht daraus wieder eine lokale Kopie.

## Formeln

![Formel-Merkmal: Berechnung (Formel), Preis-Operator „Wert × Preis“ und Dezimalstellen](/storage/app/media/docs/preisberechnung-einrichten/01-formel-preis-operator.webp)

Hängt der Preis von Eingaben ab, rechnest du ihn mit einem Merkmal vom Typ **Formel** aus. Merkmale sprichst du über ihren **Internen Namen (ID)** mit `$` an:

```
$breite * $hoehe / 10000
```

liefert z. B. die Fläche in m². Mit einem Staffelpreis (Preis-Operator **Wert × Preis**, eine Stufe `>=` 0 mit dem Quadratmeterpreis) wird daraus der Preis. Syntax, Funktionen und Beispiele: [Formeln & Berechnungen](/docs/preisformeln).

## Preismatrizen

Stehen deine Preise in einer Tabelle – Breite × Höhe, Auflage × Format –, lädst du sie als CSV in ein Merkmal vom Typ **Preisliste**. Auch die Aufpreise der Werte eines Auswahl-Merkmals kannst du mit **Preise für Wert aus Matrix** aus einer Tabelle holen. Alles dazu: [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv).

## Steuern

Steuersatz und Steuerbehandlung gelten für das ganze Konto: **Einstellungen** → **Lokalisierung**.

| Einstellung | Bedeutung |
|---|---|
| **Steuersatz** | Der Steuersatz (in %), mit dem deine Preise im Konfigurator gepflegt sind, z. B. `19` |
| **Preise inkl. Steuern** | An: Deine Preise enthalten die Steuer bereits (Brutto). Aus: Deine Preise sind Netto. |

So rechnet der Konfigurator:

- **Im HTML-Snippet** werden die Preise so angezeigt, wie du sie eingegeben hast.
- **In einem Shop** übergibt das Plugin den Steuersatz des Produkts. Der Konfigurator rechnet deine Preise dann auf diesen Satz um: Bruttopreise werden mit deinem **Steuersatz** auf Netto zurückgerechnet und mit dem Satz des Shops wieder auf Brutto. Nettopreise bekommen direkt den Satz des Shops aufgeschlagen.

Pflege die Preise deshalb so, wie du sie kalkulierst, und stelle **Steuersatz** und **Preise inkl. Steuern** passend dazu ein. Stimmen beide Sätze überein, ändert sich an Bruttopreisen nichts.

## Fehlersuche

1. **Ein Aufpreis wird nicht angezeigt, aber berechnet** – **Preisanzeige** ist aus, oder der Betrag ist 0 und **Bei Null anzeigen** ist aus.
2. **Eine Formel oder Preisliste trägt nichts zum Preis bei** – es fehlt der **Staffelpreis**. Ohne Stufe bleibt der Beitrag 0.
3. **Der Aufpreis ist 12 statt 12,50 oder 0** – im Feld **Preis** steht ein Komma. Schreib `12.50`.
4. **Die Staffel rechnet im Shop anders als in der Vorschau** – eine Stufe hat eine andere Bedingung als `>=`, und Vorschau und Shop laufen mit verschiedenen Engines. Siehe [Bedingungen und die Frontend-Engine](#bedingungen-und-die-frontend-engine).
5. **Mengen werden nicht multipliziert** – prüfe, ob beim Merkmal die Einstellung **Menge** auf **Freie Eingabe** oder **Bereich** steht, und veröffentliche die Komponente.
6. **Der Preis im Warenkorb ist zu hoch** – der Shop addiert seinen eigenen Produktpreis (Magento mit Legacy, Shopware). Setze den Produktpreis im Shop auf 0, wenn der Konfigurator den ganzen Preis liefert.
7. **Der Preis weicht um die Steuer ab** – **Steuersatz** oder **Preise inkl. Steuern** unter **Einstellungen** → **Lokalisierung** passen nicht zu deinen Preisen oder zum Steuersatz im Shop.
8. **Änderungen kommen im Shop nicht an** – der Shop zeigt den zuletzt **veröffentlichten** Stand.

## Nächste Schritte

- [Formeln & Berechnungen](/docs/preisformeln)
- [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [Regelwerk aufbauen](/docs/regelwerk-aufbauen)

---

# Preismatrizen aus Excel/CSV

Source: https://configento.app/docs/preismatrizen-excel-csv
Section: Preise & Regeln

Wenn deine Preise in Tabellen stehen – etwa Breite × Höhe oder Menge × Format –, musst du sie nicht in Formeln übersetzen. Du lädst die Tabelle als CSV hoch, legst fest, welche Merkmale die Zeile und die Spalte bestimmen, und der Konfigurator liest bei jeder Auswahl den passenden Preis aus.

## Wann eine Preismatrix sinnvoll ist

Eine Preismatrix lohnt sich, wenn der Preis von zwei Größen abhängt und sich nicht sauber als Formel schreiben lässt:

- **Sonnenschutz, Rollläden, Insektenschutz:** Breite × Höhe
- **Fenster und Türen:** Breite × Höhe, je Material eine eigene Tabelle
- **Druckprodukte:** Auflage × Format
- **Zuschnitt:** Länge × Breite oder Länge × Material

Hängt der Preis nur von **einer** Größe ab (z. B. „ab 100 Stück 2,10 €, ab 500 Stück 1,80 €“), reicht ein [Staffelpreis](/docs/preisberechnung-einrichten) – dafür brauchst du keine Matrix.

## So funktioniert es

Eine Preismatrix ist ein eigenes Merkmal vom Typ **Preisliste** (Kategorie *Berechnung*). Das Merkmal

1. liest die aktuellen Werte von zwei anderen Merkmalen – die **Dimensionen X und Y**,
2. sucht damit die passende Spalte (X) und Zeile (Y) in der Tabelle,
3. gibt den Inhalt dieser Zelle als Ergebnis zurück.

Das Ergebnis ist zunächst nur eine Zahl. Damit sie im Preis landet, gibst du dem Merkmal einen **Staffelpreis** (siehe [Preis übernehmen](#preis-in-den-gesamtpreis-übernehmen)). Alternativ rechnest du mit der Zahl in einer Formel weiter.

## Schritt für Schritt

1. Lege die Merkmale an, die die Tabelle steuern – z. B. **Breite** und **Höhe** als kleine Eingabefelder oder als Auswahl.
2. Lege ein neues Merkmal an und wähle als Typ **Preisliste**.
3. Vergib unter **Grundeinstellungen** einen **Internen Namen (ID)**, z. B. `preis_matrix`. Über diesen Namen kannst du die Matrix später in Formeln verwenden.
4. Öffne **Matrixdaten** und lade deine CSV hoch (Datei in das Feld ziehen oder klicken).
5. Stelle unter **Matrix-Einstellungen** die Dimensionen und Operatoren ein (siehe unten).
6. Lege unter **Staffelpreis** eine Stufe mit dem Wert `0` und dem Preis `1` an und setze den **Preis-Operator** auf **Wert × Preis**.
7. Setze die **Sichtbarkeit** auf **Nein (versteckt)**, wenn deine Kunden das Matrix-Ergebnis nicht als eigene Zeile sehen sollen.
8. Prüfe das Ergebnis in der Vorschau und veröffentliche die Komponente.

## Das CSV-Format

```
;80;100;120;140;160
100;29.90;34.90;39.90;44.90;49.90
120;34.90;39.90;44.90;49.90;54.90
140;39.90;44.90;49.90;54.90;59.90
160;44.90;49.90;54.90;59.90;64.90
```

- **Erste Zeile:** die Werte für **Dimension X** (Spalten). Die erste Zelle bleibt leer.
- **Erste Spalte:** die Werte für **Dimension Y** (Zeilen).
- **Alle übrigen Zellen:** das Ergebnis für diese Kombination, meist der Preis.

Im Beispiel liefert Breite 120 (X) und Höhe 140 (Y) den Wert **49.90**.

### Formatregeln

| Regel | Details |
|---|---|
| Trennzeichen | Semikolon (`;`) – andere Trennzeichen werden nicht erkannt |
| Zeichensatz | UTF-8 |
| Dezimalzeichen | Punkt (`29.90`) empfohlen. Ein einzelnes Komma (`29,90`) wird ebenfalls gelesen, Tausenderpunkte (`1.234,56`) nicht. |
| Achsenwerte | Zahlen oder kurze Codes aus Buchstaben, Ziffern, Unterstrich und Leerzeichen (z. B. `holz`, `alu_eloxiert`). Umlaute und Sonderzeichen vermeiden. |
| Leere Zellen | Ergeben kein Ergebnis – für diese Kombination wird kein Preis berechnet |

### Aus Excel exportieren

In Excel speicherst du die Tabelle über **Speichern unter → CSV UTF-8 (durch Trennzeichen getrennt)**. Ein deutsches Excel verwendet dabei automatisch das Semikolon. Prüfe nach dem Export in einem Texteditor, dass die erste Zelle leer ist und keine Währungszeichen (`€`) in den Zellen stehen.

## Die Matrix-Einstellungen

![Einstellungen eines Preisliste-Merkmals: Operatoren, Steuer-Liste, Preis-Operator und Dezimalstellen, darunter die Matrixdaten mit hochgeladener CSV-Datei](/storage/app/media/docs/preismatrizen-excel-csv/01-matrixdaten.webp)

| Einstellung | Bedeutung |
|---|---|
| **Dimension X** | Merkmal, dessen Wert die **Spalte** auswählt (erste Zeile der CSV) |
| **Operator X** | Wie der Wert in der ersten Zeile gesucht wird – siehe [Operatoren](#operatoren-exakt-nächstgrößer-nächstkleiner) |
| **Dimension Y** | Merkmal, dessen Wert die **Zeile** auswählt (erste Spalte der CSV) |
| **Operator Y** | Wie der Wert in der ersten Spalte gesucht wird |
| **Freie Eingabe** | Statt eines Merkmals einen festen Wert für die Dimension eintragen (Feld *Freie Eingabe X/Y*) |
| **Steuer-Liste** | Merkmal, das bei [mehreren Tabellen](#mehrere-tabellen-und-die-steuer-liste) bestimmt, welche verwendet wird |
| **Preis-Operator** | **Preis**: die Staffel-Stufe ist der Preis. **Wert × Preis**: Matrix-Ergebnis × Preis der Staffel-Stufe |
| **Dezimalstellen** | Anzahl Nachkommastellen bei der Anzeige des Ergebnisses (Standard: 2) |

### Welcher Wert wird nachgeschlagen?

Die Matrix verwendet den **Wert** des Dimensions-Merkmals, nicht die angezeigte Bezeichnung:

- **Auswahl, Radio Buttons, Liste mit Bildern:** das Feld **Wert** des gewählten Eintrags. Heißt ein Eintrag „Eiche massiv“ und hat den Wert `eiche`, muss in der CSV `eiche` stehen.
- **Eingabefelder:** die eingegebene Zahl.
- **Formeln und andere berechnete Merkmale:** ihr Ergebnis. So kannst du z. B. zuerst eine Fläche berechnen und sie als Dimension verwenden.

### Operatoren: exakt, nächstgrößer, nächstkleiner

| Operator | Verhalten | Typischer Einsatz |
|---|---|---|
| **Exakte Übereinstimmung** | Der Wert muss genau in der Tabelle stehen. Groß-/Kleinschreibung und Leerzeichen am Rand spielen keine Rolle, `19` und `19.0` gelten als gleich. | Auswahl-Merkmale wie Material oder Farbe |
| **Nächstgrößere Zahl** | Nimmt den kleinsten Tabellenwert, der **größer oder gleich** der Eingabe ist – rundet also **auf**. | Maße: Breite 95 cm wird mit der Spalte 100 berechnet |
| **Nächstkleinere Zahl** | Nimmt den größten Tabellenwert, der **kleiner oder gleich** der Eingabe ist – rundet also **ab**. | Mengenstaffeln: 750 Stück wird mit der Zeile 500 berechnet |

**Beispiel** mit der Tabelle oben, Operator X = *Nächstgrößere Zahl*:

| Eingabe Breite | verwendete Spalte |
|---|---|
| 80 | 80 |
| 95 | 100 |
| 160 | 160 |
| 170 | – (kein Preis) |

Es wird **nicht interpoliert**. Liegt eine Eingabe außerhalb der Tabelle, gibt es kein Ergebnis und damit keinen Preis. Begrenze deshalb die Eingabefelder mit Mindest- und Höchstwert auf den Bereich, den deine Tabelle abdeckt.

## Preis in den Gesamtpreis übernehmen

Das Matrix-Ergebnis fließt **nur über den Staffelpreis** in den Preis ein. Ohne Staffel-Stufe bleibt der Beitrag 0 – auch wenn die Matrix richtig rechnet.

**Fall 1 – die Tabelle enthält Endpreise** (häufigster Fall):

- Staffelpreis: eine Stufe, Bedingung `>=` (Vorgabe), Wert `0`, Preis `1`
- Preis-Operator: **Wert × Preis**

Ergebnis: Matrix-Wert × 1 = Matrix-Wert.

**Fall 2 – die Tabelle enthält einen Faktor oder eine Menge**, die mit einem Preis multipliziert werden soll: Trage unter Staffelpreis den Preis pro Einheit ein (z. B. Wert `0`, Preis `12.50`) und lass den Preis-Operator auf **Wert × Preis**.

Die Bedingung einer Stufe (`>=`, `>`, `=`, `<=`, `<`, `!=`) wertet nur die Frontend-Engine **V3** aus. Die Legacy-Engine nimmt immer die höchste Stufe, deren Wert kleiner oder gleich dem Ergebnis ist – mit `>=` verhalten sich beide gleich.

**Fall 3 – du willst mit dem Ergebnis weiterrechnen:** Lass den Staffelpreis leer und verwende die Matrix in einer [Formel](/docs/preisformeln) über ihren internen Namen, z. B. `$preis_matrix * 1.19` oder `$preis_matrix + $montage`. Den Preis gibt dann die Formel aus.

## Mehrere Tabellen und die Steuer-Liste

Du kannst einem Preislisten-Merkmal **mehrere CSV-Dateien** geben – etwa eine Tabelle je Material oder je Ausführung. Alle Tabellen haben denselben Aufbau, nur die Preise unterscheiden sich.

1. Lade alle CSV-Dateien unter **Matrixdaten** hoch – du kannst mehrere auf einmal auswählen. Die Reihenfolge der Liste ist die Nummerierung: die erste Tabelle hat die Nummer **0**, die zweite die **1** usw.
2. Lege ein Auswahl-Merkmal an (z. B. **Material**), dessen Einträge als **Wert** die Nummer der Tabelle tragen: Holz = `0`, Aluminium = `1`, Kunststoff = `2`.
3. Wähle dieses Merkmal unter **Steuer-Liste** aus.

Wählt dein Kunde „Aluminium“, rechnet die Matrix mit der zweiten Tabelle. Ist die Steuer-Liste leer oder passt die Nummer zu keiner Tabelle, wird die erste Tabelle verwendet.

**Alternative ohne mehrere Tabellen:** Wenn sich die Preise je Material nur durch einen Faktor unterscheiden, ist es oft einfacher, **eine** Tabelle zu pflegen und den Faktor in einer Formel anzuwenden.

## Preise für Werte aus einer Matrix

Statt eines eigenen Preislisten-Merkmals kannst du auch die **Aufpreise der Einträge eines Auswahl-Merkmals** aus einer Matrix holen. Beispiel: Jede Farbe kostet je nach Größe unterschiedlich viel.

1. Lege wie oben ein Preislisten-Merkmal mit der Tabelle an (Operatoren einstellen, Sichtbarkeit **Nein (versteckt)**, kein Staffelpreis nötig).
2. Öffne das Auswahl-Merkmal (z. B. **Farbe**) und setze **Preise für Wert aus Matrix** auf **Ja**.
3. Wähle unter **Option (Matrix)** das Preislisten-Merkmal.
4. Lege **Dimension X** und **Dimension Y** fest. Die Einstellung **– aktueller Auswahlwert –** steht für den Wert des jeweiligen Eintrags selbst.

Typisch ist: Dimension X = *aktueller Auswahlwert* (die Farbe), Dimension Y = das Merkmal **Größe**. Jeder Eintrag zeigt dann den Aufpreis aus seiner Spalte. Findet die Matrix keinen Wert, ist der Aufpreis 0.

## Tabellen im Editor bearbeiten

Unter **Matrixdaten** siehst du alle hochgeladenen Tabellen mit Dateinamen und Größe (Zeilen × Spalten).

- **Bearbeiten:** Ein Klick auf den Namen öffnet die Tabelle. Zellen änderst du per Klick, mit `Enter` oder `Tab` übernimmst du den Wert, mit `Esc` brichst du ab. Über **+ Zeile** und **+ Spalte** erweiterst du die Tabelle, das Papierkorb-Symbol am Zeilen- oder Spaltenkopf entfernt sie. **Übernehmen** speichert die Änderungen in die Komponente.
- **Ohne CSV starten:** **Leere Matrix anlegen** erzeugt eine leere Tabelle, die du direkt im Editor füllst.
- **Herunterladen:** Das Download-Symbol speichert die Tabelle als CSV – praktisch, um sie in Excel zu überarbeiten und wieder hochzuladen.
- **Löschen:** Das Papierkorb-Symbol entfernt die Tabelle.

Wie jede Änderung im Editor wird eine neue Tabelle erst nach dem **Veröffentlichen** in deinem Shop wirksam.

## Eine Preisliste in mehreren Komponenten verwenden

Verwendest du dieselbe Preistabelle in mehreren Komponenten, pflege sie als **Baustein**:

- Im Preislisten-Merkmal unter **Matrixdaten** auf **Als zentrale Preisliste anlegen** klicken und einen Namen vergeben – oder
- über **Mit zentraler Preisliste verknüpfen …** eine bestehende zentrale Preisliste übernehmen. Die Tabelle im Merkmal wird dabei durch die zentrale ersetzt.

Verknüpfte Merkmale zeigen den Hinweis **Zentral gepflegt als Baustein**. Geändert wird die Tabelle dann unter **Bausteine** in der Hauptnavigation. Die Änderung wird auf alle verknüpften Komponenten übertragen. Die Matrix-Einstellungen (Dimensionen, Operatoren) bleiben je Komponente eigenständig. Mit **Verknüpfung lösen** wird die Tabelle wieder zu einer lokalen Kopie, die du in der Komponente bearbeiten kannst.

## Mit dem KI-Agenten

Du kannst die Tabelle auch vom KI-Agenten einrichten lassen. CSV-Dateien nimmt der Chat nicht direkt an – füge den Inhalt der CSV als Text in den Chat ein oder speichere die Datei vorher als `.txt`. Beschreibe dazu, was die Achsen bedeuten:

> „Hier ist meine Preisliste für Plissees. Die Spalten sind die Breite in cm, die Zeilen die Höhe in cm. Bei Zwischenmaßen soll auf das nächste Tabellenmaß aufgerundet werden.“

Der Agent legt das Preislisten-Merkmal an, lädt die Tabelle hoch, verbindet die Dimensionen mit deinen Merkmalen und richtet den Staffelpreis ein. Kontrolliere das Ergebnis anschließend in der Vorschau mit einigen Testmaßen.

## Fehlersuche: Die Matrix liefert keinen Preis

Gehe diese Punkte der Reihe nach durch:

1. **Staffelpreis fehlt** – ohne Stufe (Wert `0`, Preis `1`) und Preis-Operator **Wert × Preis** fließt das Ergebnis nicht in den Preis.
2. **Dimension nicht gesetzt oder ohne Wert** – solange in einem der beiden Dimensions-Merkmale nichts ausgewählt oder eingegeben ist, gibt es kein Ergebnis.
3. **Wert statt Bezeichnung** – in der CSV muss der **Wert** des Eintrags stehen, nicht der angezeigte Text.
4. **Außerhalb der Tabelle** – bei *Nächstgrößere Zahl* liegt die Eingabe über dem größten Tabellenwert, bei *Nächstkleinere Zahl* unter dem kleinsten.
5. **Achsen vertauscht** – X ist die **erste Zeile** (Spalten), Y die **erste Spalte** (Zeilen).
6. **Falsches Trennzeichen** – die CSV muss Semikolons verwenden. Wird die Tabelle nach dem Hochladen als eine einzige Spalte angezeigt, war das Trennzeichen falsch.
7. **Nicht veröffentlicht** – dein Shop zeigt den zuletzt veröffentlichten Stand.

## Nächste Schritte

- [Preisberechnung einrichten](/docs/preisberechnung-einrichten)
- [Formeln & Berechnungen](/docs/preisformeln)
- [KI-Agent: Produktdaten importieren](/docs/ki-agent-daten-importieren)

---

# Formeln & Berechnungen

Source: https://configento.app/docs/preisformeln
Section: Preise & Regeln

Mit einer Formel rechnet der Konfigurator selbst: aus Breite und Höhe eine Fläche, aus Menge und Stückpreis einen Betrag, aus einer Auswahl einen Zuschlag. Eine Formel ist ein eigenes Merkmal, das die Werte anderer Merkmale liest und bei jeder Auswahl neu rechnet. Ihr Ergebnis kannst du anzeigen, in weiteren Formeln verwenden oder in den Preis übernehmen.

## So funktioniert es

1. Lege ein Merkmal an und wähle unter **Datenkategorie** die **Berechnung** und als **Datentyp** die **Formel**.
2. Vergib unter **Grundeinstellungen** einen sprechenden **Internen Namen (ID)**, z. B. `flaeche`. Über diesen Namen verwenden andere Formeln das Ergebnis.
3. Trage unter **Formel-Einstellungen** im Feld **Berechnung (Formel)** die Formel ein, z. B. `$breite * $hoehe / 10000`.
4. Soll das Ergebnis in den Preis einfließen, lege einen **Staffelpreis** an – siehe [Ergebnis in den Preis übernehmen](#ergebnis-in-den-preis-übernehmen).
5. Setze die **Sichtbarkeit** auf **Nein (versteckt)**, wenn deine Kunden das Ergebnis nicht sehen sollen.
6. Prüfe das Ergebnis in der Vorschau mit einigen Testwerten.

![Formel-Merkmal Statikzuschlag: Datenkategorie Berechnung, Datentyp Formel und in den Formel-Einstellungen die Berechnung eines Zuschlags ab 3500 mm Tiefe; links die verketteten Preisformeln](/storage/app/media/docs/preisformeln/01-formel-merkmal.webp)

Eine Formel ist **ein JavaScript-Ausdruck**. Du brauchst dafür keine Programmierkenntnisse – Grundrechenarten, Klammern und ein paar Funktionen reichen für fast alles.

## Merkmale in der Formel verwenden

Du sprichst ein Merkmal über seinen **Internen Namen (ID)** mit einem vorangestellten `$` an. Groß- und Kleinschreibung zählt.

| Schreibweise | Ergebnis |
|---|---|
| `$breite` | Der aktuelle Wert des Merkmals (siehe Tabelle unten) |
| `$farbe.price` | Der **Aufpreis** des gewählten Werts. Bei Mehrfachauswahl die Summe der gewählten Aufpreise. |
| `$farbe.originalPrice` | Der Aufpreis ohne Multiplikation mit einer Menge. In V3 identisch mit `.price`. |
| `$$breite` | Wie `$breite`. In der Legacy-Engine rechnet die Formel aber **nicht** neu, wenn sich nur dieses Merkmal ändert – nur wenn sich eines der anderen ändert. In V3 gibt es diesen Unterschied nicht. |

### Welcher Wert kommt heraus?

| Merkmal | `$name` liefert |
|---|---|
| **Auswahl, Radio Buttons, Liste mit Bildern** | Das Feld **Wert** des gewählten Eintrags – nicht die Bezeichnung. Ist der Wert eine Zahl (`120`), rechnet die Formel damit. Sonst ist es ein Text (`'holz'`). |
| **Mehrfachauswahl, Checkbox** | Legacy: eine Liste der gewählten Werte, z. B. `['led','dimmer']`. V3: leer. Für Aufpreise nimm `$name.price`. |
| **Kleines / Großes Eingabefeld** | Die Eingabe. Zahlen werden zu Zahlen, auch mit Dezimalkomma (`12,5` → 12.5). Alles andere bleibt Text. |
| **Formel, Preisliste, Einfache Kombination** | Ihr Ergebnis. So kannst du Formeln verketten. |
| **Nichts gewählt, nichts eingegeben, durch eine Regel ausgeblendet** | Leer (`''`) – siehe [Leere Felder](#leere-felder). |

## Rechnen, vergleichen, entscheiden

| Zeichen | Bedeutung | Beispiel |
|---|---|---|
| `+ - * /` | Grundrechenarten | `$breite * $hoehe` |
| `%` | Rest der Division | `$menge % 10` |
| `( )` | Klammern | `($breite + 10) * 2` |
| `== != < <= > >=` | Vergleich | `$breite > 200` |
| `&&` `!` | und, nicht | `$breite > 200 && $hoehe > 150` |
| `bedingung ? a : b` | Wenn – dann – sonst | `$breite > 200 ? 25 : 0` |

**Oder** schreibst du mit zwei senkrechten Strichen: `$breite > 200 || $hoehe > 150` trifft zu, wenn mindestens eine der beiden Bedingungen erfüllt ist.

**Achtung bei `^`:** Das ist in JavaScript **kein** Hochzeichen, sondern ein bitweises XOR. `2 ^ 3` ergibt 1, nicht 8. Für Potenzen nimm `Math.pow(2, 3)`.

**Wenn – dann** schreibst du immer mit `? :`. Mehrere Stufen kannst du verschachteln:

```
$menge >= 100 ? 7.90 : ($menge >= 50 ? 8.90 : 10.90)
```

**Gib immer eine Zahl zurück.** Ein reiner Vergleich wie `$breite > 200` ergibt in der Legacy-Engine 1 oder 0, in V3 aber kein Ergebnis. Schreib deshalb `$breite > 200 ? 1 : 0`.

## Funktionen

Die Funktionen mit `Math.` funktionieren in **beiden** Engines. Die Kurzformen ohne `Math.` gibt es nur in V3.

| Funktion | Bedeutung | Kurzform (nur V3) |
|---|---|---|
| `Math.round(x)` | Kaufmännisch auf eine ganze Zahl runden | `round(x)`, mit Nachkommastellen: `round(x, 2)` |
| `Math.ceil(x)` | Aufrunden | `ceil(x)` |
| `Math.floor(x)` | Abrunden | `floor(x)` |
| `Math.abs(x)` | Betrag ohne Vorzeichen | `abs(x)` |
| `Math.min(a, b, …)` | Kleinster Wert | `min(a, b, …)` |
| `Math.max(a, b, …)` | Größter Wert | `max(a, b, …)` |
| `Math.sqrt(x)` | Quadratwurzel | `sqrt(x)` |
| `Math.pow(x, y)` | x hoch y | `pow(x, y)` |
| `Math.log(x)` | Natürlicher Logarithmus | `log(x)` |
| `Math.exp(x)` | e hoch x | `exp(x)` |
| `Math.PI` | Kreiszahl π | `PI` |

**Auf Nachkommastellen runden** in beiden Engines: `Math.round(x * 100) / 100` (zwei Stellen) oder `Math.ceil(x * 2) / 2` (auf 0,5 aufrunden).

Die Großschreibweisen aus Tabellenkalkulationen (`ROUND`, `IF`, `MAX`) gibt es nicht.

## Eine Formel, ein Ausdruck

In **V3** besteht eine Formel aus genau **einem** Ausdruck. Zwischenvariablen (`var`), `if`-Blöcke, Schleifen und mehrere Anweisungen mit `;` liefern dort kein Ergebnis.

Die **Legacy**-Engine führt auch mehrzeilige Formeln aus. Damit eine Komponente in beiden Engines gleich rechnet, schreib trotzdem einen Ausdruck und teile lange Rechnungen auf mehrere Formel-Merkmale auf – etwa `flaeche` und darauf aufbauend `preis_flaeche`. Das ist auch leichter zu prüfen. Mehr dazu: [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Leere Felder

Solange ein Merkmal leer ist, setzt die Formel einen leeren Text ein. Beim Multiplizieren und Dividieren zählt das als 0 (`'' * 2` ergibt 0). Beim **Addieren** hängt JavaScript aber Texte aneinander: Ist `$a` gleich 5 und `$b` leer, ergibt `$a + $b` den Text „5“ statt der Zahl 5. Die V3-Engine übernimmt einen Text nicht in den Preis. Sicher bist du mit:

```
($a || 0) + ($b || 0)
```

`|| 0` setzt für ein leeres Feld 0 ein. Für Auswahl-Merkmale mit Text-Werten brauchst du das nicht – vergleiche dort direkt: `$farbe == 'rot' ? 20 : 0`.

Ergibt eine Formel einen Fehler (Tippfehler, unbekannte Funktion), ist ihr Ergebnis leer bzw. 0. Der Konfigurator läuft weiter.

## Ergebnis in den Preis übernehmen

Eine Formel liefert zunächst nur eine Zahl. In den Preis fließt sie über den **Staffelpreis** der Formel und den **Preis-Operator** – genau wie bei der [Preismatrix](/docs/preismatrizen-excel-csv#preis-in-den-gesamtpreis-übernehmen):

| Ziel | Staffelpreis | Preis-Operator |
|---|---|---|
| Die Formel **ist** der Preis (z. B. 49.90) | eine Stufe: Wert `0`, Preis `1` | **Wert × Preis** |
| Die Formel ist eine **Menge**, z. B. m², die mit einem Preis multipliziert wird | eine Stufe: Wert `0`, Preis = Preis pro Einheit, z. B. `45` | **Wert × Preis** |
| Preis pro Einheit hängt von der Menge ab | mehrere Stufen, z. B. `0` → 45, `5` → 42, `10` → 38 | **Wert × Preis** |
| Fester Zuschlag ab einer Grenze | eine Stufe mit der Grenze und dem Zuschlag | **Preis** |

Ohne Staffelpreis trägt die Formel nichts zum Preis bei. Wie Staffelpreise im Detail rechnen, steht unter [Preisberechnung einrichten](/docs/preisberechnung-einrichten).

### Dezimalstellen

Das Feld **Dezimalstellen** in den **Formel-Einstellungen** bestimmt, mit wie vielen Nachkommastellen das Ergebnis angezeigt wird. In der Legacy-Engine wird das Ergebnis dabei auch **gerundet weiterverwendet**, in V3 nur die Anzeige. Soll die Rundung den Preis beeinflussen, runde in der Formel selbst, z. B. mit `Math.round(x * 100) / 100`.

## Formeln an anderen Stellen

- **Preismatrix:** Eine Formel kann als **Dimension X** oder **Y** dienen – etwa eine berechnete Fläche als Zeile der Tabelle. Siehe [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv).
- **Einfache Kombination:** Wenn du nur zwei oder mehr Merkmale addieren, multiplizieren oder als Text verbinden willst, reicht der Datentyp **Einfache Kombination** – ganz ohne Formel.

## Praxisbeispiele

Alle Beispiele funktionieren in beiden Engines. Die Merkmalsnamen ersetzt du durch deine eigenen.

**Fläche in m² aus Zentimetern**

```
$breite * $hoehe / 10000
```

**Fläche mit Mindestfläche 0,5 m²**

```
Math.max($breite * $hoehe / 10000, 0.5)
```

**Fläche auf volle 0,5 m² aufrunden**

```
Math.ceil($breite * $hoehe / 10000 * 2) / 2
```

**Zuschlag ab einer Breite von 200 cm**

```
$breite > 200 ? 35 : 0
```

**Stückpreis mit Mengenrabatt × Menge**

```
$menge * ($menge >= 100 ? 7.90 : ($menge >= 50 ? 8.90 : 10.90))
```

**Zuschlag je nach Auswahl** – das Merkmal `material` hat die Werte `holz`, `alu`, `edelstahl`:

```
$material == 'edelstahl' ? 1.35 : ($material == 'holz' ? 1.2 : 1)
```

Diesen Faktor kannst du in einer zweiten Formel verwenden: `$flaeche * 45 * $faktor_material`.

**Aufpreise mehrerer Merkmale addieren**

```
$farbe.price + $antrieb.price
```

**Umfang eines runden Tischs aus dem Durchmesser**

```
Math.round(Math.PI * $durchmesser)
```

## Mit dem KI-Agenten

Der KI-Agent schreibt Formeln für dich, wenn du beschreibst, was gerechnet werden soll:

> „Der Preis soll Breite mal Höhe in m² mal 45 Euro sein, aber mindestens für 0,5 m².“

Er legt das Formel-Merkmal an und richtet den Staffelpreis ein. Prüfe das Ergebnis in der Vorschau mit ein paar Testmaßen, bevor du veröffentlichst.

## Fehlersuche

1. **Die Formel ergibt immer 0 oder nichts** – stimmt der **Interne Name (ID)** samt Groß- und Kleinschreibung? Ist das Merkmal ausgefüllt?
2. **Die Formel rechnet, der Preis bleibt gleich** – der **Staffelpreis** fehlt. Ohne Stufe (Wert `0`, Preis `1`) und Preis-Operator **Wert × Preis** zählt das Ergebnis nicht zum Preis.
3. **Summe fehlt im Preis, solange ein Feld leer ist** – das leere Feld wurde als Text addiert. Schreib `($a || 0) + ($b || 0)`.
4. **Vergleich mit einer Auswahl greift nie** – die Formel sieht den **Wert** des Eintrags, nicht seine Bezeichnung. `$farbe == 'Rot'` greift nicht, wenn der Wert `rot` ist.
5. **In V3 kein Ergebnis, in Legacy schon** – die Formel enthält `var`, `if` oder mehrere Anweisungen, eine Kurzform wie `round()` fehlt in Legacy, oder sie gibt einen reinen Vergleich zurück. Schreib einen Ausdruck mit `? :` und `Math.`-Funktionen.
6. **`2 ^ 3` ergibt 1** – `^` ist kein Hochzeichen. Nimm `Math.pow(2, 3)`.
7. **Preis weicht um Cent-Beträge ab** – runde in der Formel selbst statt über **Dezimalstellen**.

## Nächste Schritte

- [Preisberechnung einrichten](/docs/preisberechnung-einrichten)
- [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen)

---

# JavaScript-API-Referenz (V3)

Source: https://configento.app/docs/javascript-api-referenz
Section: Integrationen

Diese Referenz beschreibt jede Methode, jedes Ereignis und jede Einstellung, die die Frontend-Engine **V3** auf `window.Configento` bereitstellt – mit Signatur, Rückgabe, Fehlerfällen und einem kurzen Beispiel. Sie richtet sich an Entwickler von Shop-Themes, Plugins und eigenen Integrationen. Wie du typische Aufgaben löst und vom Legacy-Code umsteigst, zeigt der Leitfaden [JavaScript-Schnittstelle (V3)](/docs/javascript-schnittstelle).

Die Signaturen stehen in TypeScript-Schreibweise. Alles funktioniert auch in reinem JavaScript.

## Lebenszyklus

1. Die Seite lädt `https://cloud.configento.app/configento-v3/configento.js` (mit `defer`).
2. Das Skript legt `window.Configento` an, sucht **einmal** alle Elemente mit `data-configento` und registriert für jedes eine **Instanz**. Ihre `id` ist die `id` des Elements, sonst `configento-anon-<n>`.
3. Für jede Instanz startet sofort das Laden der Komponente (oder es wird die eingebettete genommen, siehe `component`).
4. Sobald eine Komponente geladen ist, bekommt ihre Instanz die Methoden unten. Vorher werfen sie `Configento instance not ready — await Configento.ready first.`
5. `Configento.ready` wird erfüllt, wenn **alle** Instanzen der Seite geladen sind.

Elemente, die erst nach Schritt 2 in die Seite kommen, werden nicht erkannt. Eine Instanz-Referenz bleibt über den Ladevorgang hinweg gültig: Wer `Configento.instances.get(id)` vor `ready` hält, bekommt danach am selben Objekt die echten Methoden.

## Global: `window.Configento`

| Eigenschaft / Methode | Typ | Beschreibung |
|---|---|---|
| `version` | `string` | Version der Engine, z. B. `3.0.0-alpha.0` |
| `frontendVersionTag` | `'v3'` | Kennung der Engine-Generation. Prüfe darauf, nicht auf `version`, wenn dein Code nur mit einer Generation funktioniert. |
| `ready` | `Promise<void>` | Erfüllt, wenn alle Instanzen geladen sind |
| `instances` | `ReadonlyMap<string, ConfiguratorInstance>` | Alle Instanzen, Schlüssel ist die Instanz-`id` |
| `first()` | `ConfiguratorInstance` oder `null` | Die erste Instanz der Seite |
| `forElement(el)` | `(el) => ConfiguratorInstance` (oder `null`); `el` ist ein `HTMLElement` oder ein `string` | Die Instanz zu einem Element oder CSS-Selektor; sucht auch nach außen (`closest('[data-configento]')`) |
| `loadAsset(id, opts?)` | `(id: string, opts?: { instance?: ConfiguratorInstance }) => Promise<AssetPayload>` | Liest eine gespeicherte Konfiguration, siehe [Speichern und laden](#speichern-und-laden) |
| `setModalAdapter(adapter?)` | `(adapter?: ModalAdapter) => void` | Eigenes Fenster für Bild-Großansichten, siehe [Modal-Adapter](#modal-adapter) |
| `registerRenderer(name, renderer)` | `(name: string, renderer: CharacteristicRenderer) => () => void` | Eigene Darstellung für Merkmale, siehe [Eigene Darstellung](#eigene-darstellung). Gibt eine Funktion zum Abmelden zurück. |
| `CloudError` | Klasse | Fehlerklasse von `storeAsset()` und `loadAsset()`, siehe [CloudError](#clouderror) |

```js
window.addEventListener('DOMContentLoaded', async () => {
  await Configento.ready;
  const k = Configento.forElement('#product-form');
});
```

## Instanz: `ConfiguratorInstance`

**Eigenschaften** (nur lesbar):

| Eigenschaft | Typ | Beschreibung |
|---|---|---|
| `id` | `string` | Instanz-`id` |
| `componentId` | `string` oder `null` | ID der Komponente |
| `element` | `HTMLElement` | Das Element mit `data-configento` |
| `config` | `WebshopConfig` oder `null` | Die Einstellungen beim Laden, eingefroren – siehe [Einbinden](#einbinden-attribute-und-json) |

Merkmale gibst du als **internen Namen** (`string`) oder numerische ID an (`CharacteristicRef`), Werte als Feld **Wert** (`string`) oder numerische ID (`ValueRef`). Ein unbekannter Name, ein unbekannter Wert oder ein unpassender Datentyp löst einen `Error` aus.

### Lesen

#### `getValue(characteristic): unknown`

Wert eines Merkmals in der Form, die auch [Formeln](/docs/preisformeln) sehen:

| Merkmal | Ergebnis | Leer |
|---|---|---|
| Auswahl, Radio Buttons, Liste mit Bildern | Feld **Wert** des gewählten Eintrags (ohne Wert: seine ID) | `null` |
| Mehrfachauswahl, Checkbox | Liste der Werte | `[]` |
| Eingabefelder | Text, ohne Leerzeichen am Rand | `''` |
| Mehrfachauswahl mit Mengen | `{ [Wert-ID]: Menge }` | `{}` |
| Formel, Preisliste, Kombination, Produktattribut, Webservice | Ergebnis der Berechnung | `null` |

Ein Merkmal, das eine Regel ausblendet, liefert immer „leer“.

```js
k.getValue('breite');      // → '120'
k.getValue('zubehoer');    // → ['kurbel', 'fernbedienung']
```

#### `getSelections(): SelectionsMap`

Die aktuelle Auswahl aller Merkmale als `{ [Merkmals-ID]: Auswahl }` – siehe [Auswahl](#auswahl). Merkmale, die eine Regel ausblendet, fehlen; gesperrte Werte sind entfernt.

#### `getState(): ConfiguratorSnapshot`

```ts
{
  selections: SelectionsMap;                     // wie getSelections()
  evaluated: Record<number, number | string | null>;  // Ergebnisse aller Berechnungen nach Merkmals-ID
  hiddenCharacteristics: number[];               // von Regeln ausgeblendete Merkmale
  blacklistedValues: number[];                   // von Regeln gesperrte Werte
  price: PriceSnapshot;                          // wie getPriceBreakdown()
}
```

Reine Abfrage – beliebig oft aufrufbar.

#### `getPriceBreakdown(): PriceSnapshot`

```ts
{ total: number; currency: string; priceIncludesTax: boolean }
```

`total` ist schon auf Steuersatz und Währung des Shops umgerechnet (`data-configento-tax-rate`, `data-configento-currency`).

#### `getSummary(opts?): string`

| Option | Standard | Wirkung |
|---|---|---|
| `format` | `'text'` | `'html'` liefert `<dl><dt>Merkmal</dt><dd>Wert</dd>…</dl>` |
| `includePrices` | `false` | Aufpreis hinter dem Wert |
| `separator` | `'; '` | Trenner im Textformat |

Enthält nur sichtbare Merkmale. Zeigt die Komponente die kombinierte Artikelnummer in der Zusammenfassung, steht sie am Ende.

```js
k.getSummary({ format: 'html', includePrices: true });
```

#### `getCombinedSku(): string`

Artikelnummer des konfigurierten Produkts aus den Artikelnummern der gewählten Werte, mit `-` verbunden, z. B. `CL-W-GR-TXT`. Je Merkmal in Reihenfolge der Komponente: die Artikelnummer des gewählten Werts (bei Mehrfachauswahl die erste vorhandene), sonst die des Merkmals. Leere Teile entfallen, ausgeblendete Merkmale zählen nicht. `''`, wenn nichts eine Artikelnummer trägt. Ist sie nicht leer, steht sie als `_combined_sku` auch in jeder Bestell-Payload.

#### `getAssetPayload(): AssetPayload | null`

Die Konfiguration als JSON, nach internen Namen geordnet – dieselbe Form wie `finalize().payload`, aber ohne Prüfung. `null`, solange nichts gewählt ist. Neben den Merkmalen enthält sie `_component_title`, `_locale`, bei Bedarf `_combined_sku` und – bei Komponenten mit Captcha – `altcha`.

#### `getHeaderValue(opts?): string | null`

Dieselbe Konfiguration Base64-kodiert (UTF-8-sicher) – die Form, die Shop-Plugins an den Warenkorb übergeben und Legacy im Feld `configurator1-header` hatte. Mit `opts.assets` (Ergebnis von `storeCombinedImage()` als `{ type: 'imgData', id, url, file }`) kommt die Bildliste dazu, aus der z. B. das Magento-Plugin das Warenkorbbild liest.

### Ändern

| Methode | Signatur | Für |
|---|---|---|
| `selectValue` | `(characteristic, value) => void`; `value` darf `null` sein | Auswahl, Radio Buttons, Liste mit Bildern. `null` leert. |
| `toggleValue` | `(characteristic, value) => void` | Checkbox, Mehrfachauswahl, Liste mit Bildern mit Mehrfachauswahl |
| `setText` | `(characteristic, text: string) => void` | Eingabefelder |
| `setQuantity` | `(characteristic, value, quantity: number) => void` | Mehrfachauswahl mit Mengen; negative Mengen werden 0 |
| `resetSelection` | `(characteristic) => void` | Alle Datentypen; Regeln dürfen das Merkmal danach wieder vorbelegen |
| `setProductAttributes` | `(attributes: Record<string, string>) => void` | Ersetzt die Werte der Produktattribute, z. B. nach einem Variantenwechsel. Auch vor `ready` aufrufbar. |
| `showLanguageSelect` | `() => void` | Zeigt die Sprachauswahl erneut (nur mit `languageSelect` und mehreren Sprachen), die Auswahl bleibt |

Jede Änderung wirkt wie eine Eingabe des Kunden: Regeln, Formeln und Preis rechnen neu, dann folgen `change` und – wenn sich der Preis ändert – `price`.

### Abschließen

#### `finalize(): Promise<FinalizeResult>`

Prüft die ganze Konfiguration wie ein Klick auf den [Aktions-Button](/docs/aktions-button) und zeigt Fehler am Merkmal an.

```ts
{
  ok: boolean;
  validationErrors: ValidationError[];
  payload?: AssetPayload;        // nur bei ok
  priceTotal: number;
  summary: string;               // Text, höchstens 1024 Zeichen
  combinedImage?: string;        // PNG als Data-URL, wenn die Komponente ein kombiniertes Bild hat
}
```

`finalize()` verschickt nichts und löst danach das Ereignis `finalize` aus.

### Speichern und laden

| Methode | Signatur | Beschreibung |
|---|---|---|
| `storeAsset` | `() => Promise<{ id: string; url: string }>` | Speichert die Konfiguration. `id` ist der Schlüssel für den Deep Link, `url` die Adresse der gespeicherten JSON-Datei. |
| `Configento.loadAsset` | `(id, { instance? }) => Promise<AssetPayload>` | Liest eine gespeicherte Konfiguration. Ohne `instance` gilt die erste. |
| `restoreFromAssetJson` | `(payload) => void` | Überträgt eine gelesene Konfiguration in die Instanz |
| `storeCombinedImage` | `() => Promise<{ id: string; url: string }>` (oder `null`) | Speichert das kombinierte Produktbild für Warenkorb oder Bestellung; `null`, wenn die Komponente keines hat |

Öffnet jemand die Produktseite mit `?dl=<id>` (oder `?configento_asset=<id>`), stellt V3 die Konfiguration im **ersten** Konfigurator von selbst wieder her. Für andere Parameter oder einen anderen Konfigurator rufst du `loadAsset()` und `restoreFromAssetJson()` selbst auf.

```js
const { id } = await k.storeAsset();
const link = new URL(location.href);
link.searchParams.set('dl', id);
```

`storeAsset()` und `loadAsset()` brauchen die Shop-Einstellungen (Kunden-ID, Token). In der Vorschau des Admins werfen sie deshalb `CONFIG_MISSING`. Der Konfigurator wiederholt fehlgeschlagene Uploads nicht selbst – sonst entstünden doppelte Einträge.

### Gruppen und Wizard

| Methode | Signatur | Beschreibung |
|---|---|---|
| `getGroups` | `() => GroupInfo[]` | Angezeigte Gruppen in Reihenfolge; von Regeln ausgeblendete fehlen |
| `getActiveGroup` | `() => ActiveGroup` (oder `null`) | Angezeigte Gruppe; `null` bei **Keine Gruppen** oder einer einzigen Gruppe |
| `setActiveGroup` | `(ref, opts?: { validate?: boolean }) => Promise<boolean>`; `ref` ist `number` oder `string` | Wechselt per ID oder internem Namen. Vorwärts prüft es jeden Schritt auf dem Weg (`validate: false` überspringt) und fragt den Step-Guard. `true`, wenn gewechselt wurde. |
| `nextGroup` | `() => Promise<boolean>` | Wie **Weiter** |
| `prevGroup` | `() => Promise<boolean>` | Wie **Zurück** – ohne Prüfung |
| `setStepGuard` | `(guard, opts?: { backward?: boolean }) => void`; `guard` ist `StepGuard` oder `null` | Eigene Prüfung vor dem Wechsel |

```ts
type GroupRef   = { id: number; key: string | null; index: number };
type GroupInfo  = GroupRef & { title: string };
type ActiveGroup = GroupRef & { total: number };

type StepGuard = (step: { from: GroupRef; to: GroupRef; direction: 'forward' | 'back' | 'jump' })
  => boolean | void | Array<{ characteristic: number | string; message: string }>
   | Promise<boolean | void | Array<{ characteristic: number | string; message: string }>>;
```

`key` ist der interne Name der Gruppe aus dem Editor, `index` die Position unter den angezeigten Gruppen. Der Step-Guard läuft nach der eingebauten Prüfung, standardmäßig nur vorwärts. `false` hält den Schritt ohne Meldung, eine Liste hält ihn und zeigt jede Meldung am Merkmal (Fehlercode `guard`). Solange ein Promise offen ist, sind **Weiter** und **Zurück** gesperrt. Wirft der Guard, wechselt der Schritt trotzdem.

Zusätzlich hält eine Fehler-Regel mit „Ausführen bei: Wizard“ und Meldungstyp **Fehler** den Schritt an, zu dem sie gehört.

## Ereignisse

`on(event, callback)` gibt eine Funktion zum Abmelden zurück. Listener bleiben angemeldet, auch wenn die Instanz intern neu verbunden wird (etwa wenn Webservice-Werte nachträglich eintreffen).

| Ereignis | Wann | Inhalt |
|---|---|---|
| `change` | Nach jeder Änderung der Auswahl | `{ selections: SelectionsMap }` – wie `getSelections()` |
| `price` | Wenn sich Gesamtpreis, Währung oder Steuerbasis ändern; einmal direkt nach dem Laden | `{ total, currency, priceIncludesTax, delta }` – `delta` zum vorigen Preis |
| `finalize` | Wenn `finalize()` fertig ist | `FinalizeResult` |
| `error` | Wenn Fehler am Merkmal erscheinen | `{ errors: ValidationError[] }` |
| `group` | Nach jedem Wechsel der angezeigten Gruppe, nicht beim ersten Anzeigen | `{ from, to, direction }`; `to` ist ein `GroupRef`, `from` ein `GroupRef` oder `null` |

`onChange(callback)` ist die ältere Form von `on('change', …)` ohne Inhalt und wird entfernt.

## Datentypen

### Auswahl

`SelectionsMap` ist `{ [Merkmals-ID]: Auswahl }`, eine Auswahl ist je nach Datentyp:

| `kind` | Felder | Merkmale |
|---|---|---|
| `single` | `valueId` (`number` oder `null`), `qty?: number` | Auswahl, Radio Buttons, Liste mit Bildern |
| `multi` | `valueIds: number[]`, `qtys?: { [Wert-ID]: number }` | Checkbox, Mehrfachauswahl |
| `text` | `value: string` | Eingabefelder |
| `quantities` | `quantities: { [Wert-ID]: number }` | Mehrfachauswahl mit Mengen |
| `files` | `files: Array<{ id, folder, type, … }>` | Dateiupload |
| `captcha` | `payload: string` | Captcha |

### ValidationError

```ts
{ characteristicId: number; altTitle: string; code: string; message: string }
```

`message` ist schon in die Sprache des Konfigurators übersetzt. `code` ist einer von: `required`, `pattern`, `range`, `length`, `numeric`, `integer`, `gt-zero`, `gte-zero`, `email`, `url`, `zip`, `phone`, `iban`, `bic`, `vat`, `code`, `alpha`, `alphanum`, `data`, `lowercase`, `uppercase`, `rule` (Fehler-Regel), `guard` (Step-Guard).

### CloudError

`storeAsset()` und `loadAsset()` lehnen mit einer `Configento.CloudError` ab: `code`, `retryable`, bei HTTP-Fehlern `status`.

| `code` | Bedeutung | `retryable` |
|---|---|---|
| `NO_SELECTIONS` | Noch nichts gewählt | nein |
| `CONFIG_MISSING` | Keine Shop-Einstellungen (Admin-Vorschau) oder keine Instanz | nein |
| `HTTP_4XX` | Abgelehnt, etwa Token oder Domäne | nein |
| `HTTP_5XX` | Serverfehler | ja |
| `BAD_RESPONSE` | Unerwartete Antwort | nein |
| `NETWORK` | Keine Verbindung, CORS, Zertifikat | ja |
| `NOT_FOUND` | Gespeicherte Konfiguration gibt es nicht | nein |

```js
try {
  await k.storeAsset();
} catch (err) {
  if (!(err instanceof Configento.CloudError)) throw err;
  if (err.retryable) planeNeuenVersuch();
}
```

## Einbinden: Attribute und JSON

Jede Einstellung geht als Attribut am Element mit `data-configento` oder als Schlüssel im JSON-Attribut `data-configento-config`. Steht beides da, gewinnt das JSON.

| Attribut | JSON-Schlüssel | Wert |
|---|---|---|
| `data-component-id` | `componentId` | ID der Komponente – Pflicht |
| `data-configento-customer` | `customer` | Kunden-ID |
| `data-configento-token` | `token` | Token aus der Karte **HTML5 (V3 Beta)** |
| `data-configento-token-endpoint` | `tokenEndpoint` | Adresse, die kurzlebige Tokens ausgibt (Shop-Plugins) |
| `data-configento-cloud-base-url` | `cloudBaseUrl` | `cloud.configento.app` |
| `data-configento-asset-base-url` | `assetBaseUrl` | Host für gespeicherte Konfigurationen (Shop-Plugins) |
| `data-configento-tax-rate` | `taxRate` | Steuersatz des Shops in Prozent |
| `data-configento-currency` | `currency` | Währungscode, z. B. `EUR` |
| `data-configento-currency-rates` | `currencyRates` | Kurse als JSON, z. B. `{"CHF": 0.94}` |
| `data-configento-locale` | `uiLocale` | Sprache, z. B. `de_DE` |
| `data-configento-content-locale` | `contentLocale` | Abweichende Sprache nur für die Texte der Komponente |
| `data-configento-embed-mode` | `embedMode` | `storefront` (Standard bei Attributen) oder `admin-preview` |
| `data-configento-price-mount` | `priceMount` | CSS-Selektor für den Gesamtpreis |
| `data-configento-summary-mount` | `summaryMount` | CSS-Selektor für die Zusammenfassung |
| `data-configento-summary-open` | `summaryOpen` | Zusammenfassung anfangs auf- oder zugeklappt |
| `data-configento-combined-image-mount` | `combinedImageMount` | CSS-Selektor für das kombinierte Produktbild |
| `data-configento-language-select` | `languageSelect` | Sprachauswahl vor dem Konfigurator |
| `data-configento-language-select-title` | `languageSelectTitle` | Text über der Sprachauswahl |
| `data-configento-languages` | `languages` | Angebotene Sprachen, durch Komma getrennt (JSON: Liste) |
| `data-configento-min-height` | `minHeight` | Höhe, die beim Laden frei bleibt, z. B. `640px` |
| `data-configento-min-height-keep` | `minHeightKeep` | Höhe auch nach dem Laden behalten |
| `data-configento-wizard-nav` | `wizardNav` | `full`, `buttons` oder `none` |
| `data-configento-component-json` | `component` | Die Komponente selbst, wie `GET /api/v3/components/{id}` sie liefert |
| – | `productAttributes` | Werte der Produktattribute, z. B. `{"breite": "120"}` |

Ja/Nein-Attribute akzeptieren `true`/`false`, `1`/`0`, `yes`/`no` oder das Attribut ohne Wert für „ja“. Unbekannte Werte lassen den Standard stehen und erzeugen eine Warnung in der Konsole.

**Darstellung beim Einbinden per Attribut:** Im Modus `storefront` zeigt der Konfigurator weder Gesamtpreis noch Zusammenfassung – der Shop hat eigene. Mit `price-mount` und `summary-mount` holst du sie an eine Stelle deiner Wahl. Findet ein Selektor kein Element, erscheint das Teil nirgends, statt doppelt im Konfigurator. `summary-open` wirkt nur zusammen mit `summary-mount`; dort startet die Zusammenfassung standardmäßig aufgeklappt.

**Token früher anfordern:** Mit `tokenEndpoint` fragt der Konfigurator erst nach dem Laden nach seinem Token. Schneller geht es, wenn die Seite diese Anfrage schon im `<head>` startet und das Promise unter `window.ConfigentoTokenPrefetch` ablegt, mit genau der URL aus `tokenEndpoint` als Schlüssel. Der Konfigurator nimmt dieses Ergebnis einmal. Liefert das Promise `null`, einen Fehler oder kein `token`, fragt er selbst. In die Seite kommt so nur die URL, nie ein Token – das verträgt sich mit Seiten-Caches. Das Magento-Plugin macht das ab Version 5.0.0-beta22 von selbst.

```html
<script>
  (window.ConfigentoTokenPrefetch ||= {})['https://shop.example/configento/v3/token/id/42/'] =
    fetch('https://shop.example/configento/v3/token/id/42/', { method: 'POST', credentials: 'omit' })
      .then((r) => (r.ok ? r.json() : null))
      .catch(() => null);
</script>
```

## Modal-Adapter

```ts
interface ModalAdapter {
  openOverlay(args: { title: string; container: HTMLElement; onClose: () => void }): { close(): void };
}
```

Der Konfigurator füllt `container`, nachdem `openOverlay` zurückkehrt. Dein Adapter hängt ihn in ein eigenes Fenster und ruft `onClose()`, wenn der Kunde es schließt. `close()` ruft der Konfigurator, wenn er das Fenster selbst schließt (z. B. nach der Auswahl). Setze den Adapter, sobald `window.Configento` existiert und bevor ein Fenster aufgeht; `setModalAdapter()` ohne Argument stellt das eingebaute Fenster wieder her.

## Kompatibilitäts-Skript

`https://cloud.configento.app/configento-v3/configento-compat.js` – vor `configento.js` geladen – bildet die globalen Objekte der Legacy-Engine (`Justselling_Configento_App_*`, `CONFIGENTO_PRODUCT.setPrice`, die Ereignisse `configentoUpdate…InDom…`) auf diese Schnittstelle ab. Was es im Einzelnen übernimmt und wie du alten Code umschreibst, steht im Leitfaden unter [Von Legacy umsteigen](/docs/javascript-schnittstelle#von-legacy-umsteigen).

## Eigene Darstellung

Mit `Configento.registerRenderer(name, renderer)` zeichnet dein Code ein Merkmal selbst. Steht `name` im Feld **CSS-Klasse** eines Merkmals, rendert der Konfigurator statt des Eingabeelements einen leeren Container (`div.cfg-custom` mit `data-configento-renderer="<name>"`). Seinen Inhalt fasst der Konfigurator nie an. Werte setzt dein Code über `ctx` – Regeln, Preis, Prüfung, Wizard, Zusammenfassung und Bestellung laufen wie bei einer Eingabe des Kunden.

```ts
interface CharacteristicRenderer {
  replace?: 'body' | 'all';     // Standard 'body'
  combine?: boolean;            // Standard false
  mount(el: HTMLElement, ctx: RendererContext): void;
  update?(ctx: RendererContext, el: HTMLElement): void;
  destroy?(el: HTMLElement): void;
}
```

| Teil | Bedeutung |
|---|---|
| `name` | Klassenname aus Kleinbuchstaben, Ziffern und `-`. Eine von mehreren Klassen im Feld **CSS-Klasse** genügt. Ein zweites `registerRenderer` mit demselben Namen ersetzt das erste. |
| `replace: 'body'` | Der Konfigurator zeigt weiter Titel, Pflicht-Stern, Infotext und Fehlermeldungen, der Container sitzt in `.cfg-char__body`. |
| `replace: 'all'` | Der Container ist das einzige Kind von `.cfg-char`. Titel und Fehler zeigst du selbst aus `ctx`. |
| `combine: true` | Alle sichtbaren Merkmale **derselben Gruppe** mit dieser Klasse werden ein Widget, an der Stelle des ersten. Die übrigen zeigen nichts, bleiben aber in Regeln, Prüfung, Preis und Bestellung. Ihre Fehler erscheinen gesammelt am Widget. |
| `mount` | Einmal, sobald der Container im DOM steht |
| `update` | Wenn sich etwas in `ctx` ändert: Auswahl, Fehler, erlaubte Werte, Preise, Sprache. Nicht bei Änderungen an anderen Merkmalen. |
| `destroy` | Bevor der Container verschwindet: Schrittwechsel im Wizard, eine Regel blendet aus, Abmelden. Danach wirken die Methoden dieses `ctx` nicht mehr. Kommt das Merkmal zurück, folgt ein neues `mount`. |

**`ctx`:**

| Eigenschaft / Methode | Inhalt |
|---|---|
| `characteristic` | Das Merkmal, bei `combine` das erste |
| `characteristics` | Alle Merkmale des Widgets, sonst nur `characteristic` |
| `locale` | Sprache des Konfigurators, z. B. `de_DE` |
| `instance` | Die Instanz, siehe oben. Ihre Methoden gehen erst nach `Configento.ready`. |
| `selectValue(wert, merkmal?)`, `toggleValue(wert, merkmal?)`, `setText(text, merkmal?)`, `setQuantity(wert, menge, merkmal?)`, `reset(merkmal?)` | Wie die gleichnamigen Methoden der Instanz. Ohne `merkmal` gilt `characteristic`, sonst nur ein Merkmal aus `characteristics`. |

Jedes Merkmal in `ctx` hat: `id`, `key` (interner Name), `type`, `title`, `info` (HTML), `required`, `selection` (wie `getValue()`), `errors` (`ValidationError[]`), `values` und bei Eingabefeldern `textConstraints` (`minLength`, `maxLength`, `validator`). `values` enthält nur die erlaubten Werte, von Regeln gesperrte fehlen. Jeder Wert hat `id`, `key` (Feld **Wert**), `label`, `info`, `image`, `price` (Aufpreis in Shop-Währung und -Steuerbasis), `priceLabel` (formatiert wie im Konfigurator, leer wenn keiner gezeigt wird) und `selected`.

**Registrieren vor dem Bundle:** Läuft dein Skript vor `configento.js`, leg den Renderer unter `(window.ConfigentoRenderers ||= {})[name] = renderer` ab. Später registrierte Renderer gehen ebenfalls: Bereits gezeigte Merkmale wechseln sofort.

**Rückfall:** Ist kein Renderer registriert – etwa in der Vorschau des Admins –, zeigt das Merkmal die eingebaute Darstellung. Wirft `mount` oder `update` einen Fehler, schreibt der Konfigurator ihn in die Konsole und zeigt für dieses Merkmal wieder das eingebaute Eingabeelement. Gilt nur für V3.

## Gestaltung mit CSS

Farben, Schrift und Ecken passt du über Variablen wie `--configento-color-accent` an, einzelne Elemente über zugesagte Klassen wie `.cfg-toggle-item__label`. Beides beschreibt die Seite [Design anpassen (CSS)](/docs/design-anpassen).

## Versionen und Zusagen

`Configento.version` folgt Semantic Versioning. Bis zur Version 3.0.0 können sich Fehlertexte und kleine Details noch ändern; die Methoden und Datentypen dieser Seite bleiben. Ab 3.0.0 gilt: Fehlerbehebungen ändern die letzte Stelle, neue Funktionen die mittlere, und nur eine neue erste Stelle bricht bestehenden Code – mit einer Anleitung zum Umstieg.

Verlass dich auf die Methoden, Ereignisse und Datentypen dieser Seite und auf die Variablen und Klassen unter [Design anpassen (CSS)](/docs/design-anpassen), nicht auf andere Klassen oder die übrige DOM-Struktur des Konfigurators. Außerdem stabil sind die Attribute `data-configento-group-id` und `data-configento-group-key`.

## Nächste Schritte

- [JavaScript-Schnittstelle (V3)](/docs/javascript-schnittstelle) – Leitfaden mit Beispielen
- [HTML-Snippet-Integration](/docs/html-snippet-integration)
- [Uploads & Deep Links](/docs/uploads-und-deep-links)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)

---

# JavaScript-Schnittstelle (V3)

Source: https://configento.app/docs/javascript-schnittstelle
Section: Integrationen

Mit der JavaScript-Schnittstelle verbindest du den Konfigurator mit deiner eigenen Logik auf der Seite: den Preis in deiner Kaufleiste zeigen, die Auswahl in ein eigenes Formular übernehmen, Werte von außen setzen oder eine Konfiguration speichern und später wieder öffnen. Die Frontend-Engine **V3** stellt dafür das Objekt `window.Configento` bereit – egal, ob sie über das [HTML-Snippet](/docs/html-snippet-integration) oder ein Shop-Plugin auf die Seite kommt. Dieser Leitfaden zeigt an fertigen Beispielen, wie du typische Aufgaben löst und Code für die Legacy-Engine auf V3 umstellst. Jede Methode mit Signatur, alle Ereignisse, Datentypen und Einstellungen stehen in der [JavaScript-API-Referenz (V3)](/docs/javascript-api-referenz).

## Wo die Schnittstelle verfügbar ist

`window.Configento` gibt es überall dort, wo die Seite die Engine V3 lädt:

| Integration | JavaScript-Schnittstelle |
|---|---|
| **HTML-Snippet** (Karte **HTML5 (V3 Beta)**) | Immer |
| **Shopify** | Immer |
| **PrestaShop** | Immer |
| **Magento 2** | Wenn die Komponente auf **V3 (Beta)** steht oder V3 braucht, siehe [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3) |
| **Shopware 6** und das klassische HTML5-Snippet | Nein – beide laden Legacy |

Die Plugins nutzen die Schnittstelle selbst, etwa um Preis und Konfiguration in den Warenkorb zu bringen. Dein eigener Code läuft daneben – du musst nichts abschalten.

## Erste Schritte

```html
<script>
  window.addEventListener('DOMContentLoaded', function () {
    Configento.ready.then(function () {
      var konfigurator = Configento.first();

      konfigurator.on('price', function (p) {
        document.querySelector('#mein-preis').textContent = p.total.toFixed(2) + ' ' + p.currency;
      });

      konfigurator.on('change', function () {
        console.log('Breite:', konfigurator.getValue('breite'));
      });
    });
  });
</script>
```

Drei Regeln, die fast alle Probleme vermeiden:

1. **Warte auf `Configento.ready`.** Erst dann sind alle Konfiguratoren der Seite geladen. Rufst du eine Methode vorher auf, meldet sie, dass der Konfigurator noch nicht bereit ist.
2. **`window.Configento` gibt es erst, wenn das Skript `configento.js` gelaufen ist.** Es wird mit `defer` geladen, also nach dem Aufbau der Seite. Starte deinen Code deshalb bei `DOMContentLoaded` oder später – nicht direkt in einem Skript im `<head>`.
3. **Der Konfigurator sucht seine Plätze nur einmal**, beim Laden: jedes Element mit `data-configento`. Elemente, die dein Code erst später einfügt, erkennt er nicht.

Merkmale sprichst du über ihren **internen Namen (ID)** an, Werte über das Feld **Wert**. Die numerischen IDs funktionieren ebenfalls.

## Schneller laden und Platz freihalten

Drei Einstellungen am Element mit `data-configento` helfen beim Seitenaufbau:

| Attribut | Wirkung |
|---|---|
| `data-configento-min-height="640px"` | Hält die Höhe frei, solange der Konfigurator lädt – die Seite darunter springt nicht, wenn der erste Schritt erscheint. Danach passt sich die Höhe wieder an. |
| `data-configento-min-height-keep` | Behält die Höhe auch danach bei |
| `data-configento-component-json='{…}'` | Die Komponente direkt in der Seite, genau so, wie `GET /api/v3/components/{id}` sie liefert. Dann entfällt der Abruf beim Laden. Nur sinnvoll, wenn deine Seite die veröffentlichte Fassung serverseitig aktuell hält – nach dem Veröffentlichen muss die Seite die neue Fassung ausliefern. |

Im JSON-Attribut `data-configento-config` heißen sie `minHeight`, `minHeightKeep` und `component`.

Außerdem lohnt im `<head>` ein Hinweis an den Browser, die Verbindung zur Cloud früh aufzubauen:

```html
<link rel="preconnect" href="https://cloud.configento.app" crossorigin>
```

Der Konfigurator lädt die Komponente gleich beim Start des Skripts. Wiederkehrende Besucher laden sie nicht erneut: Hat sie sich seit dem letzten Besuch nicht geändert, bestätigt der Server das nur noch kurz.

## Preis in deiner Kaufleiste zeigen

```js
window.addEventListener('DOMContentLoaded', function () {
  Configento.ready.then(function () {
    var k = Configento.first();
    var feld = document.querySelector('#kaufleiste-preis');
    k.on('price', function (p) {
      feld.textContent = p.total.toLocaleString('de-DE', { style: 'currency', currency: p.currency });
    });
  });
});
```

`price` kommt einmal direkt nach dem Laden und danach bei jeder Preisänderung. Ohne eigenen Code geht es auch mit `data-configento-price-mount="#kaufleiste-preis"` – dann zeichnet der Konfigurator den Preis selbst in dein Element.

## Auswahl in ein eigenes Formular übernehmen

Für eine Anfrage über dein eigenes Formular prüfst du die Konfiguration mit `finalize()` und schreibst das Ergebnis in versteckte Felder:

```html
<form id="anfrage" action="/anfrage" method="post">
  <input type="hidden" name="konfiguration">
  <input type="hidden" name="zusammenfassung">
  <input type="hidden" name="artikelnummer">
  <input type="hidden" name="preis">
  <button type="submit">Angebot anfordern</button>
</form>

<script>
  document.querySelector('#anfrage').addEventListener('submit', function (e) {
    e.preventDefault();
    var formular = e.target;
    var k = Configento.first();
    k.finalize().then(function (ergebnis) {
      if (!ergebnis.ok) return; // die Fehler stehen jetzt am Merkmal
      formular.konfiguration.value   = JSON.stringify(ergebnis.payload);
      formular.zusammenfassung.value = k.getSummary({ format: 'text', separator: '\n' });
      formular.artikelnummer.value   = k.getCombinedSku();
      formular.preis.value           = ergebnis.priceTotal;
      formular.submit();
    });
  });
</script>
```

`finalize()` zeigt fehlende Pflichtfelder und Fehler aus Regeln am Merkmal an, genau wie der [Aktions-Button](/docs/aktions-button), verschickt aber selbst nichts. `getCombinedSku()` liefert die [kombinierte Artikelnummer](/docs/komponente-einstellungen) aus den gewählten Werten, z. B. `CL-W-GR`; sie steht als `_combined_sku` auch in `ergebnis.payload`.

## Werte vorbelegen

Merkmale sprichst du über ihren internen Namen an, Werte über das Feld **Wert**:

```js
Configento.ready.then(function () {
  var k = Configento.first();
  k.selectValue('farbe', 'anthrazit');      // Auswahl, Radio Buttons, Liste mit Bildern
  k.toggleValue('zubehoer', 'kurbel');      // Checkbox, Mehrfachauswahl
  k.setText('breite', '120');               // Eingabefeld
  k.setQuantity('schrauben', 'm6', 4);      // Mehrfachauswahl mit Mengen
});
```

Jeder Aufruf wirkt wie ein Klick deines Kunden: Regeln, Formeln und Preis rechnen neu. Mit `resetSelection('farbe')` setzt du ein Merkmal zurück.

**Aus der Adresse:** `?farbe=anthrazit&breite=120` übernimmst du so:

```js
var parameter = new URLSearchParams(location.search);
if (parameter.has('breite')) k.setText('breite', parameter.get('breite'));
if (parameter.has('farbe'))  k.selectValue('farbe', parameter.get('farbe'));
```

**Variante im Shop gewechselt:** Hängen Formeln an [Produktattributen](/docs/berechnungs-merkmale) wie Breite oder Gewicht, gibst du die neuen Werte mit `k.setProductAttributes({ breite: '140' })` weiter. Die Auswahl bleibt, alles rechnet neu. Die Startwerte stehen beim Einbinden im JSON-Attribut als `"productAttributes"`.

## Sprache wechseln

Ist die [Sprachauswahl](/docs/html-snippet-integration) eingeschaltet, zeigt `showLanguageSelect()` die Fahnen erneut – etwa für einen Button „Sprache wechseln“:

```html
<button type="button" onclick="Configento.first().showLanguageSelect()">Sprache wechseln</button>
```

Die bisherige Auswahl im Konfigurator bleibt erhalten; nach der neuen Wahl läuft er in der neuen Sprache weiter. Ohne eingeschaltete Sprachauswahl oder bei einer Komponente mit nur einer Sprache passiert nichts. Die Methode darfst du auch aufrufen, bevor der Konfigurator geladen ist.

## Wizard und Gruppen steuern

Bei der Darstellung **Tabs** und im **Wizard** zeigt der Konfigurator immer eine Gruppe. Mit diesen Methoden baust du eine eigene Schrittanzeige:

```html
<ol id="schritte"></ol>

<script>
  Configento.ready.then(function () {
    var k = Configento.first();
    var liste = document.querySelector('#schritte');

    function zeichnen() {
      var aktiv = k.getActiveGroup();
      liste.innerHTML = '';
      k.getGroups().forEach(function (gruppe) {
        var punkt = document.createElement('li');
        punkt.textContent = gruppe.title;
        if (aktiv && gruppe.id === aktiv.id) punkt.className = 'aktiv';
        punkt.onclick = function () { k.setActiveGroup(gruppe.id); };
        liste.appendChild(punkt);
      });
    }

    zeichnen();
    k.on('group', zeichnen);   // nach jedem Schrittwechsel
    k.on('change', zeichnen);  // Regeln können Gruppen ein- und ausblenden
  });
</script>
```

`getGroups()` liefert die angezeigten Gruppen mit `id`, `key`, `index` und `title`, `getActiveGroup()` die aktuelle. `setActiveGroup()` wechselt per ID oder internem Namen und prüft vorwärts jeden Schritt auf dem Weg wie **Weiter**; `nextGroup()` und `prevGroup()` entsprechen **Weiter** und **Zurück**.

`key` ist der **interne Name** der Gruppe. Du vergibst ihn im Editor in den Einstellungen der Gruppe unter **Interner Name (ID)**, z. B. `fahrzeug`. Anders als die Position bleibt er gleich, wenn du Gruppen umsortierst oder eine Regel eine Gruppe ausblendet, und er liest sich im Code besser als eine Nummer. Das Element der angezeigten Gruppe trägt ihn zusätzlich als `data-configento-group-key`.

**Eigene Prüfung vor dem Schrittwechsel**

Mit `setStepGuard()` prüfst du selbst, bevor dein Kunde weiterkommt – etwa ein Geburtsdatum oder eine Fahrzeug-Identnummer. Die Prüfung läuft nach der eingebauten Pflichtfeld-Prüfung und nur vorwärts:

```js
k.setStepGuard(function (schritt) {
  if (schritt.from.key !== 'halter') return true;
  if (istVolljaehrig(k.getValue('geburtsdatum'))) return true;
  return [{ characteristic: 'geburtsdatum', message: 'Der Halter muss volljährig sein.' }];
});
```

`true` lässt den Kunden weiter, `false` hält ihn ohne Meldung, eine Liste hält ihn und zeigt jede Meldung am genannten Merkmal. Die Funktion darf auch ein Promise liefern, etwa für eine Prüfung über das Netz; bis zur Antwort sind **Weiter** und **Zurück** gesperrt. Wirft sie einen Fehler, wechselt der Schritt trotzdem – dein Kunde soll nicht hängen bleiben.

**Eingebaute Navigation abschalten**

Baust du die Schrittanzeige selbst, blendest du die eingebaute aus:

| `data-configento-wizard-nav` | Wirkung |
|---|---|
| `full` (Standard) | Tabs, Fortschrittsbalken, **Zurück** und **Weiter** |
| `buttons` | Nur **Zurück** und **Weiter** |
| `none` | Nichts davon – die Schritte steuert dein Code |

Dieselbe Einstellung gibt es im Editor unter **Einstellungen** → **Allgemein** → **Darstellung** → **Wizard-Navigation (V3)**; das Attribut am Element hat Vorrang.

## Konfiguration speichern und wieder öffnen

`storeAsset()` speichert die aktuelle Konfiguration und liefert `{ id, url }`. Mit der `id` baust du einen [Deep Link](/docs/uploads-und-deep-links#deep-link): die Adresse der Produktseite mit `?dl=` und der `id`. Öffnet jemand diese Adresse, stellt V3 die Konfiguration im ersten Konfigurator der Seite von selbst wieder her.

```js
k.storeAsset().then(function (gespeichert) {
  var link = new URL(location.href);
  link.searchParams.set('dl', gespeichert.id);
  navigator.clipboard.writeText(link.toString());
}).catch(function (fehler) {
  if (fehler instanceof Configento.CloudError && fehler.code === 'NO_SELECTIONS') {
    alert('Bitte zuerst etwas auswählen.');
  }
});
```

Selbst wiederherstellen – etwa in einem bestimmten von mehreren Konfiguratoren:

```js
Configento.loadAsset(id, { instance: k }).then(function (daten) {
  k.restoreFromAssetJson(daten);
});
```

In der Vorschau des Admins kann nichts gespeichert werden (`CONFIG_MISSING`); teste auf deiner Website oder im Shop. Alle Fehlercodes stehen in der [Referenz](/docs/javascript-api-referenz#clouderror).

## Eigenes Fenster für Bildauswahl

Manche Merkmale öffnen ein Fenster, etwa eine Liste mit Bildern in der Großansicht. Standardmäßig zeichnet V3 dieses Fenster selbst. Soll es wie die Fenster deines Shops aussehen, übergibst du einen Adapter:

```js
Configento.setModalAdapter({
  openOverlay: function (args) {
    // args.title, args.container (vom Konfigurator befüllt), args.onClose
    var fenster = meinShop.oeffneFenster(args.title, args.container, args.onClose);
    return { close: function () { fenster.schliessen(); } };
  }
});
```

Häng `args.container` in dein Fenster ein und ruf `args.onClose()` auf, wenn dein Kunde es schließt. `close()` ruft der Konfigurator auf, wenn er das Fenster selbst schließen will. Setze den Adapter, sobald `window.Configento` existiert und bevor dein Kunde ein Fenster öffnet. Das Magento-Plugin bringt bereits einen Adapter für die Magento-Fenster mit.

## Eigene Eingabe einbauen

Reicht keiner der Merkmalstypen für deine Eingabe – etwa ein Kfz-Kennzeichen, eine Farbauswahl auf einem Rad oder eine Skizze zum Anklicken –, zeichnest du das Merkmal selbst. Der Konfigurator gibt dir dafür einen leeren Container an der Stelle des Merkmals und fasst ihn nicht mehr an. Werte setzt du über die Methoden, die du bekommst; Regeln, Preis, Pflichtfelder, Wizard und Bestellung laufen weiter wie gewohnt.

**Beispiel: ein Kennzeichen aus drei Teilen.** Die Komponente hat drei Eingabefelder – Ort, Buchstaben, Ziffern – mit ihren eigenen Pflichtfeldern und Prüfungen. Alle drei bekommen im Editor im Feld **CSS-Klasse** den Eintrag `kennzeichen`. Dein Skript zeigt sie als ein Schild:

```js
(window.ConfigentoRenderers ||= {})['kennzeichen'] = {
  combine: true, // alle drei Merkmale werden ein Widget
  mount: function (el, ctx) {
    var schild = document.createElement('div');
    schild.className = 'kennzeichen';
    ctx.characteristics.forEach(function (teil) {
      var feld = document.createElement('input');
      feld.setAttribute('aria-label', teil.title);
      feld.value = teil.selection;
      feld.addEventListener('input', function () {
        ctx.setText(feld.value.toUpperCase(), teil.key);
      });
      schild.appendChild(feld);
    });
    el.appendChild(schild);
  },
  update: function (ctx, el) {
    // Werte von außen übernehmen, z. B. nach dem Öffnen einer gespeicherten Konfiguration
    el.querySelectorAll('input').forEach(function (feld, i) {
      var wert = ctx.characteristics[i].selection;
      if (feld !== document.activeElement && feld.value !== wert) feld.value = wert;
    });
  }
};
```

Über dem Schild zeigt der Konfigurator den Titel des ersten Teils – gib ihm also einen Titel wie „Kennzeichen“ –, darunter die Fehlermeldungen aller drei. Das Aussehen gestaltest du mit CSS für `.kennzeichen`.

Ein paar Regeln für eigene Darstellungen:

- **Der Wert gehört dem Konfigurator.** Im Wizard baut er deinen Container bei jedem Schrittwechsel ab und wieder auf. Lies den Stand deshalb in `mount` aus `ctx`, nicht aus einer eigenen Variablen.
- **Ein Renderer, mehrere Widgets.** Stehen zwei Konfiguratoren auf der Seite, ruft der Konfigurator `mount` zweimal auf. `update` und `destroy` bekommen deshalb den Container mit.
- **Ohne dein Skript geht nichts kaputt.** In der Vorschau des Admins oder wenn dein Skript fehlt, zeigt der Konfigurator die eingebauten Eingabefelder.
- **Nur Optik?** Dann reicht CSS, siehe [Design anpassen (CSS)](/docs/design-anpassen).

Alle Einzelheiten stehen in der [Referenz](/docs/javascript-api-referenz#eigene-darstellung).

## Von Legacy umsteigen

Für die Legacy-Engine gab es eine eigene, ältere Schnittstelle: Einstellungen im Objekt `_configentoSettings`, das Objekt `CONFIGENTO_PRODUCT`, globale Objekte wie `Justselling_Configento_App_Api` und jQuery-Ereignisse wie `configentoUpdateOptionsInDomAfter`. Wechselst du auf V3, ändern sich drei Dinge:

1. **Einbinden:** Statt `_configentoSettings` und `html5.js` nimmst du das V3-Snippet mit `data-configento-*`-Attributen. Wie, steht in [HTML-Snippet-Integration](/docs/html-snippet-integration). Das Token ist ein anderes, es kommt aus der Karte **HTML5 (V3 Beta)**.
2. **Eigener Code:** Er spricht künftig `window.Configento` an – oder läuft über das Kompatibilitäts-Skript weiter.
3. **Funktionen:** Was nur Legacy kann, steht in [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

### Einstellungen

| Legacy (`_configentoSettings`) | V3 |
|---|---|
| `_template` | `data-component-id` |
| `_customer` | `data-configento-customer` |
| `_token` | `data-configento-token` – neues Token aus der Karte **HTML5 (V3 Beta)** |
| `_cloudbase` | `data-configento-cloud-base-url` |
| `_taxrate` | `data-configento-tax-rate` |
| `_currencyCode` | `data-configento-currency` |
| `_cssPathCombinedImage` bzw. `.configento-combinedImage` | `data-configento-combined-image-mount` |
| Element `#configento-price` | `data-configento-price-mount` |
| Element `#configurator1` | Ein Element mit `data-configento` |
| `_loadjQuery`, `_loadChart`, `_loadDropzone` | Entfallen – V3 bringt alles mit und braucht kein jQuery |

`_debug`, `_development`, `_cloudport` und `_productOptionId` brauchst du nicht mehr.

### Weg 1: Kompatibilitäts-Skript

Vor allem Shop-Themes haben über Jahre Code angesammelt, der auf die alten Objekte zugreift. Damit er unter V3 weiterläuft, lädst du vor `configento.js` zusätzlich `configento-compat.js`:

```html
<script src="https://cloud.configento.app/configento-v3/configento-compat.js" defer></script>
<script src="https://cloud.configento.app/configento-v3/configento.js" defer></script>
```

Das Magento-Plugin lädt es bei V3 von selbst. Das Skript übernimmt:

| Legacy | Was das Skript daraus macht |
|---|---|
| Ereignisse `configentoUpdateOptionsInDomBefore`/`…After` und `configentoUpdateHeaderInDomBefore`/`…After` | Werden auf `document` ausgelöst – erreichbar mit jQuery `.on()` und mit `addEventListener`. `…Before` kommt bei jeder Änderung, `…After`, sobald die Änderung angezeigt wird, nach jedem Schrittwechsel und einmal nach dem ersten Anzeigen. Das Markup ist aber ein anderes als in Legacy: Code, der Elemente wie `#configurator1-…` sucht, findet sie nicht. |
| `CONFIGENTO_PRODUCT.setPrice(preis)` | Wird bei jeder Preisänderung mit dem Gesamtpreis aufgerufen – sofern deine Seite `CONFIGENTO_PRODUCT` definiert |
| Element `#configurator1` | Wird zum Platz für den Konfigurator; die Komponenten-ID kommt aus `CONFIGENTO_PRODUCT.getTemplateId()` |
| `Justselling_Configento_App_Helper.getConfigurator()`, `getBackendUrl()` | Liefern den V3-Konfigurator bzw. die Cloud-Adresse |
| `Justselling_Configento_App_Webshop.finalizeAction(fertig)` | Prüft mit `finalize()`, schreibt die Konfiguration in die versteckten Formularfelder des Warenkorbs und ruft danach `fertig` auf |
| `Justselling_Configento_App_CloudAsset.storeCloudAsset(…)` | Speichert mit `storeAsset()`. Der Rückruf bekommt nur die ID, nicht Ordner und Dateiname. |
| `Justselling_Configento_App_Wizard.validateForm()` und die anderen Prüf-Funktionen | Liefern immer `true` – geprüft wird beim Abschließen |
| `Justselling_Configento_App_Wizard.setActivateGroup(nr)` | Wechselt zur Gruppe an dieser Position, ohne Prüfung |
| `setDisableGroup`, `setEnableGroup`, `updateWizard` | Tun nichts |

Hat dein Code eines dieser Objekte schon selbst definiert, bleibt deine Fassung erhalten.

**Was das Skript nicht übernimmt:** Es liest `_configentoSettings` nicht und legt `CONFIGENTO_PRODUCT` nicht an – auf einer reinen HTML-Seite hat das bisher `html5.js` getan. Dort brauchst du also in jedem Fall die `data-configento-*`-Attribute. Ebenfalls nicht übernommen werden `Justselling_Configento_App_Api`, `Justselling_Configento_App_Summary` und alle übrigen Ereignisse. Dafür gibt es die Gegenstücke unten.

### Weg 2: Auf die neue Schnittstelle umschreiben

Auf Dauer ist Code mit `window.Configento` übersichtlicher: Er bekommt Inhalte mit den Ereignissen, wirft verständliche Fehler und hängt nicht an Element-IDs. So entsprechen sich alte und neue Aufrufe – alles Neue steht in `Configento.ready.then(…)` an einem Konfigurator `k = Configento.first()`:

| Legacy | V3 |
|---|---|
| `Justselling_Configento_App_Helper.getConfigurator()` | `Configento.first()` oder `Configento.forElement(…)` |
| `Justselling_Configento_App_Api.getOptionValue(merkmal)` | `k.getValue('merkmal')` |
| `Justselling_Configento_App_Api.setOptionValue(merkmal, wert)`, `setOptionValues([…])` | Je nach Datentyp `k.selectValue()`, `k.toggleValue()`, `k.setText()` oder `k.setQuantity()` |
| `Justselling_Configento_App_Api.setEventHook(…)` | `k.on('change', …)` – ebenso `price`, `finalize`, `error` und `group` |
| `setEventHook('configentoValidateGroupBefore', fn)` (Schritt verhindern) | `k.setStepGuard(fn)` |
| `getConfigurator().getActiveGroup()` | `k.getActiveGroup()` |
| `Justselling_Configento_App_Wizard.setActivateGroup(nr)` | `k.setActiveGroup(id oder interner Name)` |
| Ereignis `configentoSetActiveGroupAfter` | `k.on('group', …)` |
| `CONFIGENTO_PRODUCT.setPrice(preis)` | `k.on('price', function (p) { … p.total … })` – oder `data-configento-price-mount` |
| `Justselling_Configento_App_Summary.getSummaryAsText()` | `k.getSummary()` |
| `Justselling_Configento_App_Wizard.validateForm()` | `k.finalize()` → `ok` |
| `Justselling_Configento_App_Webshop.finalizeAction(fertig)` | `k.finalize().then(…)` |
| `Justselling_Configento_App_CloudAsset.storeCloudAsset(…)` | `k.storeAsset()` → `{ id, url }` |
| Feld `#configurator1-header` bzw. `generateHeaderValue()` | `k.getHeaderValue()` (Base64, wie bisher) oder `k.getAssetPayload()` (JSON) |
| Ereignisse `configentoUpdateOptionsInDomAfter`, `configentoUpdateHeaderInDomAfter`, `configentoApiSetOptionValueAfter` | `k.on('change', …)` |
| Markup des Konfigurators in `configentoUpdateOptionsInDomAfter` umbauen | Eigene Darstellung mit `Configento.registerRenderer()`, siehe [Eigene Eingabe einbauen](#eigene-eingabe-einbauen) – oder CSS, siehe [Design anpassen (CSS)](/docs/design-anpassen) |
| Ereignis `configentoRenderSummaryAfter` | `k.on('change', …)` und darin `k.getSummary()` |
| Ereignis `configentoFinalizeActionAfter` | `k.on('finalize', …)` |
| Ereignisse `configentoRenderAfter`, `configentoLoadTemplateAfter` | `Configento.ready` |
| Ereignisse zu Diagrammen, Vorschaubildern und Datei-Uploads | Kein Gegenstück |
| `?dl=…` und `?tb=1` in der Adresse | Unverändert |
| Merkmale über die Adresse vorbelegen, z. B. `?breite=120` | Nicht eingebaut – ein paar Zeilen, siehe [Werte vorbelegen](#werte-vorbelegen) |

Wie du Merkmale über die Adresse vorbelegst, zeigt [Werte vorbelegen](#werte-vorbelegen).

**Unterschied bei Ereignissen:** Die Legacy-Ereignisse lösten nur jQuery-Handler aus und lieferten meist keine Daten. Die V3-Ereignisse übergeben die neue Auswahl bzw. den neuen Preis direkt – du musst nichts mehr aus dem DOM lesen.

## Fehlersuche

1. **`Configento is not defined`** – dein Code läuft, bevor `configento.js` geladen ist. Starte ihn bei `DOMContentLoaded` und warte auf `Configento.ready`. Prüfe auch, ob die Seite überhaupt V3 lädt (siehe [oben](#wo-die-schnittstelle-verfügbar-ist)).
2. **`Configento instance not ready` beim Aufruf einer Methode** – der Konfigurator lädt noch. Rufe Methoden erst in `Configento.ready.then(…)` auf.
3. **`Configento.first()` liefert `null`** – auf der Seite gibt es kein Element mit `data-configento`, oder es wurde erst nach dem Laden eingefügt.
4. **Ein Aufruf wie `selectValue()` wirft einen Fehler** – der interne Name oder der Wert stimmt nicht, oder der Datentyp passt nicht zur Methode. Groß- und Kleinschreibung zählt; den Namen findest du im Editor unter **Interner Name (ID)**.
5. **`storeAsset()` meldet `CONFIG_MISSING`** – in der Vorschau des Admins kann nichts gespeichert werden. Teste auf deiner Website oder im Shop.
6. **Alter Theme-Code wirft Fehler wie `Justselling_Configento_App_Wizard is not defined`** – das Kompatibilitäts-Skript fehlt oder steht hinter `configento.js`.

## Nächste Schritte

- [JavaScript-API-Referenz (V3)](/docs/javascript-api-referenz)
- [HTML-Snippet-Integration](/docs/html-snippet-integration)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [Uploads & Deep Links](/docs/uploads-und-deep-links)
- [Der Aktions-Button](/docs/aktions-button)

---

# PrestaShop-Plugin installieren

Source: https://configento.app/docs/prestashop-plugin-installieren
Section: Integrationen

Mit dem PrestaShop-Modul erscheint dein configento.app-Konfigurator direkt auf der Produktseite deines PrestaShop-Shops. Deine Kunden stellen das Produkt zusammen, sehen den Gesamtpreis sofort und legen die fertige Konfiguration in den normalen Warenkorb. Bestellung, Steuer und Versand laufen danach ganz regulär über PrestaShop. Deine Komponenten bearbeitest du im eingebetteten Admin, ohne das Backoffice zu verlassen.

## Voraussetzungen

- **PrestaShop 9** (das Modul ist für PrestaShop ab 9.0 gebaut; ältere Versionen lassen sich nicht installieren)
- **Suchmaschinenfreundliche URLs (Friendly URLs)** müssen in deinem Shop eingeschaltet sein. Nur dann kann sich das Modul mit configento.app verbinden – siehe [Fehlersuche](#fehlersuche).
- Ein Zugang zum PrestaShop-Backoffice mit dem Recht, Module zu installieren
- Ein Login im [Service-Portal](https://service.configento.app) für den Dienst, mit dem du den Shop verbinden willst
- Mindestens eine **veröffentlichte** Komponente – unveröffentlichte Entwürfe kannst du im Shop nicht auswählen

## Welche Frontend-Engine läuft

Das PrestaShop-Modul lädt immer die **V3**-Engine. Die Einstellung **Frontend-Engine** in der Komponente spielt hier keine Rolle. Funktionen, die es nur in Legacy gibt – etwa Accordion, 360°-Ansicht, Autocomplete oder Mengenvorbelegung –, stehen in PrestaShop also nicht zur Verfügung. Die Übersicht findest du unter [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Modul herunterladen

Das Modul bekommst du in configento.app unter **Einstellungen → Integrationen**, Karte **PrestaShop 9**, Button **Modul herunterladen**. Du erhältst eine ZIP-Datei – entpacke sie **nicht**.

Ist der Tab gesperrt, akzeptiere zuerst unter **Einstellungen → Auftragsverarbeitung** den Vertrag zur Auftragsverarbeitung.

## Modul installieren

### Im Backoffice

1. Öffne die Modulverwaltung deines PrestaShop-Backoffice und lade die ZIP-Datei des Moduls hoch. Entpacke sie vorher **nicht**.
2. Installiere das Modul **configento.app**.

Bei der Installation legt das Modul einen eigenen Menüpunkt **configento.app** im Bereich **Katalog** an.

### Per Konsole

Wenn du Zugriff auf die Kommandozeile hast, kopiere den entpackten Ordner `configento` in das Verzeichnis `modules/` deines Shops und führe im Shop-Verzeichnis aus:

```bash
php bin/console prestashop:module install configento
```

Der technische Name des Moduls ist **configento**. Achte darauf, dass der Ordner danach dem Benutzer des Webservers gehört.

## Mit configento.app verbinden

Die Verbindung stellst du einmal aus dem Backoffice heraus her. Ein Token musst du dabei nicht kopieren.

1. Öffne **Katalog → configento.app**.
2. Du siehst die Karte **Mit configento.app verbinden**. Klicke auf **Verbinden**.
3. Du wirst zum Service-Portal weitergeleitet. Melde dich an und bestätige die Verbindung.
4. Danach kommst du zurück ins Backoffice, und der Admin von configento.app öffnet sich direkt in der Seite.

Beim Verbinden richtet das Modul zugleich alles ein, was die Produktseite braucht: Es holt die Zugangsdaten für deinen Shop und meldet die Domains deines Shops an configento.app (siehe [Shop-Domain freigeben](#shop-domain-freigeben)).

**Jeder Backoffice-Benutzer verbindet sich einzeln.** Die Verbindung gilt für das Benutzerkonto, das sie hergestellt hat, nicht für den ganzen Shop. Arbeitet ein Kollege mit einem eigenen Login, sieht er beim ersten Öffnen von **Katalog → configento.app** wieder die Karte **Mit configento.app verbinden**.

Über dem eingebetteten Admin steht die E-Mail-Adresse deines Portal-Logins und der Button **Verbindung trennen**.

## Komponenten im Backoffice bearbeiten

Nach dem Verbinden öffnet **Katalog → configento.app** den Admin von configento.app direkt im Backoffice. Dort legst du Komponenten an, pflegst Merkmale, Werte, Preise und Regeln und veröffentlichst sie – genau wie unter admin.configento.app. Die Grundlagen stehen in [Erste Komponente anlegen](/docs/erste-komponente-anlegen).

## Shop-Domain freigeben

Der Konfigurator lädt nur auf Domains, die für deinen Dienst freigegeben sind. Das Modul **meldet** die Domains deines Shops beim Verbinden, gibt sie aber nicht selbst frei:

1. Öffne im Admin von configento.app **Einstellungen → Domänen**.
2. Im Abschnitt **Von verbundenen Shops gemeldet** stehen die gemeldeten Domains deines PrestaShop-Shops.
3. Wähle den Typ, zum Beispiel **Produktion**, und klicke auf **In die Lizenz übernehmen**.

Gemeldet werden die aktiven Shop-Adressen, auch die weiteren Shops eines Multistores. Kommt später eine neue Domain dazu, trägst du sie unter **Einstellungen → Domänen** selbst ein oder verbindest das Modul neu. Mehr dazu: [Globale Einstellungen](/docs/globale-einstellungen#domänen).

## Produkt mit einer Komponente verknüpfen

1. Öffne im Backoffice das Produkt.
2. Im Produkt bindet das Modul den Abschnitt **configento.app** ein.
3. Wähle unter **Component** die Komponente aus der Liste. Über das Suchfeld darüber findest du sie nach Titel oder ID. Die Liste zeigt die veröffentlichten Komponenten deines verbundenen Dienstes.
4. Speichere das Produkt.

Ein Produkt hat genau **eine** Komponente. Zum Lösen wählst du **— not linked —** und speicherst.

Lässt sich die Liste nicht laden – etwa weil dein Benutzerkonto noch nicht verbunden ist –, zeigt der Abschnitt stattdessen ein einfaches Feld. Dort trägst du die ID der Komponente ein, wie sie auf ihrer Kachel in der Komponenten-Übersicht steht.

In einem Multistore gilt die Verknüpfung für den Shop, in dem du das Produkt gerade bearbeitest.

## Was im Shop passiert

### Auf der Produktseite

- Der Konfigurator erscheint direkt unter dem Preis, über dem Kaufbereich.
- **Preis:** Angezeigt wird der Preis des Produkts plus der Aufpreis aus der Konfiguration. Der Preis im Kaufbereich deines Themes läuft bei jeder Auswahl mit. Gerechnet wird mit dem Steuersatz, der in PrestaShop für dieses Produkt gilt.
- **Brutto oder netto:** Der Konfigurator zeigt Preise so an wie dein Shop. Sieht die Kundengruppe des Besuchers Preise ohne Steuer – etwa eine B2B-Gruppe – oder sind die Steuern im Shop ausgeschaltet, sind auch die Aufpreise netto, und PrestaShop schlägt die Steuer wie beim Produktpreis selbst auf. Sonst rechnet der Konfigurator brutto mit dem Steuersatz des Produkts. Dieselbe Komponente funktioniert so in Shops mit ganz unterschiedlichen Steuereinstellungen.
- **Währung:** Hat dein Shop mehrere Währungen, zeigt der Konfigurator den Gesamtpreis und die Aufpreise der einzelnen Werte in der Währung des Besuchers. Umgerechnet wird mit den Kursen deines Shops. Die Währung, in der die Komponente ihre Preise führt, muss dafür in deinem Shop angelegt sein.
- **Kombination:** Wählt der Kunde eine andere Kombination, etwa eine andere Größe, rechnet der Konfigurator mit deren Preis als Grundpreis und mit deren Attributen weiter. In den Warenkorb kommt die gewählte Kombination.
- **Produktbild:** Erzeugt deine Komponente ein kombiniertes Produktbild, erscheint es als eigenes, erstes Bild in der Bildergalerie deines Themes, mit eigenem Vorschaubild. Deine Kunden können zwischen ihren Fotos und der Konfiguration wechseln; sobald sie etwas ändern, springt die Ansicht zurück auf die Konfiguration. Themes ohne Bildergalerie zeigen das Bild an der Stelle des Produktfotos.
- **Menge:** Ändert der Kunde die Menge, bleibt die Konfiguration erhalten.

### In den Warenkorb legen

Der Knopf **In den Warenkorb** deines Themes legt die Konfiguration in den Warenkorb, nicht das nackte Produkt. Vorher prüft der Konfigurator die Pflichtfelder und springt zum ersten fehlenden Merkmal.

Den Preis berechnet configento.app beim Hinzufügen noch einmal auf dem Server. Was im Browser angezeigt wird, kann also nicht manipuliert in den Warenkorb gelangen. Danach geht es direkt in den Warenkorb.

### Warenkorb, Kasse und Bestellung

- An der Position stehen zwei Angaben: **Konfiguration** mit der Zusammenfassung der Auswahl und **Vorschau** mit dem kombinierten Produktbild.
- Warenkorb, Kasse, Bestellbestätigung und Bestellung zeigen das kombinierte Bild statt des Katalogfotos. Gäste ohne Kundenkonto sehen es über die Bestellreferenz ebenfalls.
- Der Aufpreis steckt im Preis der Position. PrestaShop rechnet die Steuer wie gewohnt.

### Konfiguration ändern

An jeder konfigurierten Warenkorbposition steht der Link **Konfiguration ändern**. Er führt zurück auf die Produktseite, der Konfigurator zeigt die gespeicherte Auswahl. Legt der Kunde die geänderte Konfiguration in den Warenkorb, ersetzt sie die alte Position.

### Produktlisten

In Kategorie- und Suchlisten blendet PrestaShop bei konfigurierbaren Produkten den Knopf zum direkten Kauf aus, damit niemand das Produkt ohne Konfiguration in den Warenkorb legt. Der Knopf zur Produktseite heißt dort **Jetzt konfigurieren**.

### Produktdaten in Formeln

Merkmale vom Datentyp **Produktattribut** lesen Werte des PrestaShop-Produkts, damit eine Formel etwa mit Breite, Gewicht oder Größe rechnen kann. Als Code trägst du im Merkmal ein:

| Quelle | Code | Beispiel |
|---|---|---|
| Feld des Produkts | Name des Felds in PrestaShop | `weight`, `width`, `height`, `depth`, `reference`, `ean13`, `price`, `manufacturer_name` |
| Eigenschaft (Feature) des Produkts | Name der Eigenschaft | `Material` |
| Attribut der gewählten Kombination | Name der Attributgruppe | `Größe` liefert z. B. `XL` |

Gibt es einen Code mehrfach, gewinnt die Quelle weiter oben in der Tabelle. Namen von Eigenschaften und Attributgruppen gelten in der Sprache des Besuchers – benenne sie in einem mehrsprachigen Shop deshalb in allen Sprachen gleich, sonst bleibt das Merkmal in den anderen Sprachen leer.

Wechselt der Kunde die Kombination, bekommen die Merkmale die Werte der neuen Kombination. Die Preisprüfung beim Hinzufügen zum Warenkorb rechnet mit denselben Werten. Einkaufspreis, Lieferantendaten, Lagerort und Beschreibungen gibt das Modul nie heraus, denn die Werte stehen im Quelltext der Produktseite. Mehr zum Datentyp: [Berechnungs-Merkmale](/docs/berechnungs-merkmale#produktattribut).

## Bestellungen im Backoffice

Auf der Bestellseite im Backoffice zeigt das Modul die Karte **Konfigurationen (configento.app)**. Für jede konfigurierte Position siehst du:

- Produkt und Menge, die Komponente und den **Geprüften Aufpreis** – den Preis, den configento.app beim Hinzufügen bestätigt hat
- alle Merkmale mit ihrem Wert, auch die, die der Kunde nicht gesehen hat, etwa versteckte Berechnungen. Sie tragen den Hinweis **für den Kunden nicht sichtbar**.
- das kombinierte Produktbild, wenn die Komponente eins erzeugt
- den Button **Konfiguration herunterladen (JSON)** mit der vollständigen Konfiguration als Datei, etwa für die Fertigung

## Abo-Status im Backoffice

Gibt es bei deinem configento.app-Abo etwas zu tun, zeigt das Modul oben auf jeder Backoffice-Seite einen Hinweis mit dem Link **Abo verwalten** ins Service-Portal:

| Hinweis | Bedeutung |
|---|---|
| **Dein Testzeitraum endet am …** | Der Testzeitraum läuft in den nächsten 7 Tagen ab. |
| **Dein Abo ist nicht mehr aktiv. Konfiguratoren funktionieren in deinem Shop noch bis …** | Das Abo ist beendet. Bis zum genannten Datum läuft der Konfigurator weiter. |
| **Dein Abo ist nicht mehr aktiv. Verlängere es, damit die Konfiguratoren in deinem Shop weiterlaufen.** (bzw. **Dein Testzeitraum ist abgelaufen. Schließe ein Abo ab, …**) | Abo oder Testzeitraum sind abgelaufen, der Konfigurator läuft aber noch. Verlängere, bevor er abgeschaltet wird. |
| **… Konfiguratoren sind in deinem Shop nicht mehr verfügbar.** | Testzeitraum oder Abo sind abgelaufen. |

Bedient configento.app deinen Shop nicht mehr, zeigen die Produktseiten statt des Konfigurators den Satz **Dieses Produkt kann derzeit nicht konfiguriert werden.** So steht kein Kunde vor einem Konfigurator, der nicht lädt. Den Status fragt das Modul höchstens einmal pro Stunde ab. Nach einer Verlängerung kann es also bis zu einer Stunde dauern, bis der Hinweis verschwindet.

## Verbindung trennen

Mit **Verbindung trennen** über dem eingebetteten Admin löst du die Verbindung deines Benutzerkontos – im Modul und im Service-Portal.

**Wichtig:** Solange noch ein anderer Backoffice-Benutzer verbunden ist, läuft der Konfigurator im Shop weiter. Trennt der **letzte** verbundene Benutzer, löscht das Modul auch die Zugangsdaten des Shops – der Konfigurator verschwindet dann von allen Produktseiten, bis sich wieder jemand verbindet.

## Modul deinstallieren

Beim Deinstallieren entfernt das Modul seine Verbindungen, die Verknüpfungen zwischen Produkten und Komponenten und die gespeicherten Konfigurationen offener Warenkörbe. Bestellungen behalten ihre Zusammenfassung und das Vorschaubild.

Löse vor dem Deinstallieren an jedem Produkt die Komponente (**— not linked —**) und klicke einmal auf **Verbindung trennen**. Sonst bleiben die Produkte für PrestaShop „konfigurierbar“, und die Freigabe im Service-Portal bleibt bestehen.

## Fehlersuche

1. **Nach „Verbinden“ kommt eine Fehlermeldung, oder das Portal lehnt die Verbindung ab** – prüfe, ob die suchmaschinenfreundlichen URLs (Friendly URLs) deines Shops eingeschaltet sind. Ohne sie kann das Modul die Rücksprungadresse nicht bilden, die das Service-Portal verlangt.
2. **„Verbunden, aber der Storefront-Token konnte nicht geholt werden“** – die Verbindung steht, aber die Zugangsdaten für die Produktseite fehlen. Trenne die Verbindung und verbinde dich neu.
3. **Auf der Produktseite erscheint kein Konfigurator** – entweder ist am Produkt keine Komponente verknüpft, oder es ist kein Backoffice-Benutzer mehr verbunden. Prüfe beides unter **Katalog → configento.app** und am Produkt.
4. **„Komponente konnte nicht geladen werden (HTTP 401)“** – die Domain deines Shops ist nicht freigegeben. Siehe [Shop-Domain freigeben](#shop-domain-freigeben).
5. **Die Komponentenliste am Produkt fehlt, es gibt nur ein Eingabefeld** – dein Benutzerkonto ist nicht verbunden oder das Service-Portal war gerade nicht erreichbar. Verbinde dich unter **Katalog → configento.app** oder trage die ID der Komponente direkt ein.
6. **„Der Preis konnte gerade nicht geprüft werden. Bitte versuchen Sie es in einem Moment erneut.“** – die Preisprüfung bei configento.app war kurz nicht erreichbar, oder die Währung der Komponente ist in deinem Shop nicht angelegt. Nichts ist im Warenkorb gelandet; der Kunde kann es gleich noch einmal versuchen. Kommt die Meldung immer wieder, such im Log deines Shops nach Einträgen mit „configento: Preisprüfung nicht verfügbar“.
7. **„Diese Konfiguration ist nicht mehr gültig. Bitte stellen Sie sie neu zusammen.“** – die Komponente wurde geändert, während der Kunde konfiguriert hat. Hier hilft nur, die Seite neu zu laden und die Konfiguration neu zusammenzustellen.
8. **Im Warenkorb fehlt das Bild der Konfiguration** – die Komponente erzeugt kein kombiniertes Produktbild. Dann zeigt der Warenkorb das Katalogfoto.
9. **„Dieses Produkt kann derzeit nicht konfiguriert werden.“** – dein configento.app-Abo bedient den Shop nicht mehr. Siehe [Abo-Status im Backoffice](#abo-status-im-backoffice).
10. **Ein Produktattribut-Merkmal bleibt leer** – der Code passt nicht, oder die Eigenschaft bzw. Attributgruppe heißt in der Sprache des Besuchers anders. Siehe [Produktdaten in Formeln](#produktdaten-in-formeln).

## Nächste Schritte

- [Erste Komponente anlegen](/docs/erste-komponente-anlegen)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [Preisberechnung einrichten](/docs/preisberechnung-einrichten)
- [Globale Einstellungen](/docs/globale-einstellungen)

---

# HTML-Snippet Integration

Source: https://configento.app/docs/html-snippet-integration
Section: Integrationen

Mit dem HTML-Snippet bindest du einen Konfigurator in jede Website ein – WordPress, TYPO3, Joomla, Jimdo oder selbst gebautes HTML. Du brauchst dafür kein Shop-Plugin und keinen Entwickler: ein `<script>`-Tag und ein `<div>` mit ein paar Attributen genügen. Das Snippet lädt immer die Frontend-Engine **V3**.

## Wann das HTML-Snippet passt

Das HTML-Snippet eignet sich, wenn du

- den Konfigurator auf einer normalen Webseite zeigen willst, etwa als Angebots- oder Anfrage-Werkzeug,
- ein CMS ohne Shop nutzt,
- die Anfrage über den [Aktions-Button](/docs/aktions-button) abschließt – als E-Mail, PDF oder an deine eigene URL.

Für Magento 2, Shopware 6 und Shopify gibt es fertige Plugins. Sie übernehmen Preis und Konfiguration in den Warenkorb – das kann das Snippet allein nicht. Siehe [Magento-Plugin installieren](/docs/magento-plugin-installieren), [Shopware-Plugin installieren](/docs/shopware-plugin-installieren) und [Shopify-Plugin installieren](/docs/shopify-plugin-installieren).

## Schritt 1: Token erzeugen

1. Öffne im Admin **Einstellungen** und dort den Reiter **Integrationen**.
2. Suche die Karte **HTML5 (V3 Beta)**.
3. Klicke auf **Erzeugen**. Du bekommst ein Token und darunter das **V3-JavaScript-Snippet** mit deiner Kunden-ID und deinem Token.
4. Kopiere das Snippet mit **Kopieren**.

Die Karte hat keinen Schalter – sobald ein Token existiert, funktioniert das Snippet.

**Erneuern** erzeugt ein neues Token und macht alle bisherigen sofort ungültig. Danach lädt der Konfigurator auf keiner Seite mehr, bis du dort das neue Snippet eingesetzt hast.

## Schritt 2: Domäne freigeben

Unter **Einstellungen → Domänen** trägst du die Domänen ein, auf denen der Konfigurator laufen darf – ohne `https://`, z. B. `www.meineseite.de`. Eine eingetragene Domäne gilt auch für ihre Unterdomänen. Änderungen wirken nach wenigen Minuten. Mehr dazu unter [Globale Einstellungen](/docs/globale-einstellungen#domänen).

Das ist keine Formalie: Dein Token steht im Quelltext deiner Seite und ist damit für jeden lesbar. Geschützt wird es durch diese Liste. Auf einer nicht eingetragenen Domäne zeigt der Konfigurator „Komponente konnte nicht geladen werden (HTTP 401)“ und darunter `Requesting host not authorized`. Testest du auf einer Staging-Domäne, trage auch diese ein.

## Schritt 3: Komponenten-ID herausfinden

Die ID steht in der Komponenten-Übersicht neben jeder Komponente, z. B. **ID 10722**. Steht dort **ID —**, ist die Komponente noch nicht veröffentlicht. Veröffentliche sie zuerst – das Snippet zeigt immer den zuletzt veröffentlichten Stand.

## Schritt 4: Snippet einfügen

Ersetze im kopierten Snippet `YOUR_TEMPLATE_ID` durch die ID der Komponente:

```html
<script src="https://cloud.configento.app/configento-v3/configento.js" defer></script>

<div
    data-configento
    data-component-id="10722"
    data-configento-customer="DEINE-KUNDEN-ID"
    data-configento-token="DEIN-TOKEN"
    data-configento-cloud-base-url="cloud.configento.app"
    data-configento-tax-rate="19"
    data-configento-locale="de_DE"
></div>
```

So funktioniert es: Das Skript sucht beim Laden jedes Element mit dem Attribut `data-configento` und baut dort einen Konfigurator auf. Alles Weitere liest es aus den `data-configento-*`-Attributen desselben Elements.

Füge das Snippet dort ein, wo dein CMS eigenen HTML-Code erlaubt – meist ein eigener HTML-Block oder ein HTML-Element. Viele CMS entfernen `<script>`-Tags aus normalen Textblöcken; nimm deshalb nicht den Fließtext-Editor.

Das `<script>`-Tag gehört nur einmal auf die Seite, auch wenn mehrere Konfiguratoren darauf liegen.

## Schritt 5: Testen

Öffne die Seite im Browser. Der Konfigurator erscheint mit allen Merkmalen. **Ohne weitere Attribute zeigt das Snippet keinen Preis, keine Zusammenfassung und keinen Titel** – siehe nächster Abschnitt. Klappt etwas nicht, hilft die [Fehlersuche](#fehlersuche).

## Preis, Zusammenfassung und Produktbild platzieren

Auf einer Webseite gehören Preis und Zusammenfassung meist an eine bestimmte Stelle im Layout, z. B. neben die Produktüberschrift. Deshalb zeigt das Snippet sie nur dort, wo du es sagst. Du legst eigene Elemente an und verweist per CSS-Selektor darauf:

```html
<div id="mein-bild"></div>
<h1>Mein Produkt</h1>
<div id="mein-preis"></div>
<div id="meine-zusammenfassung"></div>

<div
    data-configento
    data-component-id="10722"
    data-configento-customer="DEINE-KUNDEN-ID"
    data-configento-token="DEIN-TOKEN"
    data-configento-cloud-base-url="cloud.configento.app"
    data-configento-tax-rate="19"
    data-configento-locale="de_DE"
    data-configento-price-mount="#mein-preis"
    data-configento-summary-mount="#meine-zusammenfassung"
    data-configento-combined-image-mount="#mein-bild"
></div>
```

- **Preis** (`price-mount`): Gesamtpreis mit Steuerhinweis. Darunter erscheinen auch Fehler und Hinweise aus deinen [Regeln](/docs/regelwerk-aufbauen).
- **Zusammenfassung** (`summary-mount`): die gewählten Merkmale und Werte. An eigener Stelle ist sie anfangs aufgeklappt; mit `data-configento-summary-open="false"` startet sie zugeklappt.
- **Produktbild** (`combined-image-mount`): das kombinierte Produktbild. Ohne dieses Attribut erscheint es innerhalb des Konfigurators – der Selektor verschiebt es nur.

Alles aktualisiert sich live bei jeder Auswahl. Das Ziel-Element muss beim Laden der Seite schon im HTML stehen; ein Element, das erst später per JavaScript entsteht, findet der Konfigurator nicht. Findet der Selektor kein Element, bleibt die Anzeige weg – der Konfigurator selbst funktioniert trotzdem.

### Alles im Konfigurator zeigen

Willst du Titel, Preis und Zusammenfassung einfach im Konfigurator selbst haben, wie in der Vorschau im Admin, setze:

```html
data-configento-embed-mode="admin-preview"
```

Dann erscheinen Titel der Komponente, Preisleiste und Zusammenfassung innerhalb des Konfigurators. `price-mount` und `summary-mount` funktionieren zusätzlich und verschieben das jeweilige Element an deine Stelle.

## Sprachen

`data-configento-locale` legt die Sprache fest – für die Texte der Komponente und für die Beschriftungen des Konfigurators („Gesamt“, „Bitte wählen“). Fehlt ein Text in dieser Sprache, nimmt der Konfigurator dieselbe Sprache einer anderen Region (z. B. `en_US` statt `en_GB`), sonst eine andere vorhandene Übersetzung.

### Sprachauswahl vorschalten

Liegt deine Komponente in mehreren Sprachen vor, kann der Konfigurator den Besucher zuerst fragen. Er zeigt dann je Sprache eine Kachel mit Flagge und Sprachnamen und startet nach dem Klick in dieser Sprache.

```html
data-configento-language-select
```

Angeboten werden die Sprachen der Komponente. Für einen bestimmten Auftritt schränkst du sie ein:

```html
data-configento-language-select
data-configento-languages="de_DE, en_GB"
```

Einen Text über den Flaggen setzt du so:

```html
data-configento-language-select-title="Wähle jetzt deine Sprache"
```

Der Text erscheint genau so, wie du ihn schreibst. Da der Besucher noch keine Sprache gewählt hat, schreibst du ihn bei mehreren Märkten am besten in allen Sprachen, z. B. „Sprache wählen / Choose your language“.

Soll der Besucher die Sprache später wechseln können, rufst du `showLanguageSelect()` auf, etwa aus einem Button:

```html
<button type="button" onclick="Configento.first().showLanguageSelect()">Sprache wechseln</button>
```

Die Fahnen erscheinen erneut, die bisherige Auswahl im Konfigurator bleibt erhalten. Mehr dazu unter [JavaScript-Schnittstelle (V3)](/docs/javascript-schnittstelle).

Gut zu wissen:

- Bei nur einer Sprache erscheint keine Auswahl.
- Die Wahl gilt für die Browsersitzung: Wer die Seite neu lädt oder zurückkommt, wird nicht erneut gefragt.
- Die Wahl des Besuchers hat Vorrang vor `data-configento-locale`.

Zum Ausprobieren: [Demo „Mehrsprachigkeit“](/demo/mehrsprachigkeit).

## Alle Attribute

**Grundlagen**

| Attribut | Bedeutung |
|---|---|
| `data-configento` | Markiert das Element als Platz für einen Konfigurator. Ohne Wert. |
| `data-component-id` | ID der Komponente |
| `data-configento-customer` | Deine Kunden-ID – steht im Snippet |
| `data-configento-token` | Dein Token aus der Karte **HTML5 (V3 Beta)** |
| `data-configento-cloud-base-url` | `cloud.configento.app` – unverändert übernehmen |
| `data-configento-tax-rate` | Steuersatz, auf den der Konfigurator die Preise umrechnet, z. B. `19`. Entspricht er dem Steuersatz deiner Komponente, bleiben die Preise unverändert; `0` zeigt Nettopreise. Ohne das Attribut zeigt der Konfigurator die Preise so, wie sie in der Komponente angelegt sind. |
| `data-configento-locale` | Sprache, z. B. `de_DE` oder `en_GB` |

**Darstellung**

| Attribut | Bedeutung |
|---|---|
| `data-configento-price-mount` | CSS-Selektor für den Preis. Ohne dieses Attribut kein Preis. |
| `data-configento-summary-mount` | CSS-Selektor für die Zusammenfassung. Ohne dieses Attribut keine Zusammenfassung. |
| `data-configento-summary-open` | Zusammenfassung anfangs auf- (`true`) oder zugeklappt (`false`) |
| `data-configento-combined-image-mount` | CSS-Selektor für das kombinierte Produktbild |
| `data-configento-embed-mode` | `admin-preview` zeigt Titel, Preis und Zusammenfassung im Konfigurator |
| `data-configento-min-height` | Hält beim Laden die Höhe frei, z. B. `640px`, damit die Seite nicht springt. Mit `data-configento-min-height-keep` bleibt sie auch danach. |
| `data-configento-wizard-nav` | Navigation im Wizard: `full`, `buttons` oder `none` – siehe [Wizard und Gruppen steuern](/docs/javascript-schnittstelle#wizard-und-gruppen-steuern) |

**Sprachen**

| Attribut | Bedeutung |
|---|---|
| `data-configento-language-select` | Sprachauswahl vor dem Konfigurator. Ohne Wert. |
| `data-configento-language-select-title` | Text über den Flaggen der Sprachauswahl |
| `data-configento-languages` | Angebotene Sprachen, durch Komma getrennt |
| `data-configento-content-locale` | Sprache nur für die Texte der Komponente, wenn sie von den Beschriftungen abweichen soll. Selten nötig. |

**Selten gebraucht**

| Attribut | Bedeutung |
|---|---|
| `data-configento-config` | Alle Einstellungen als JSON (siehe unten) |
| `data-configento-currency` | Währungscode, z. B. `EUR`, wenn er von der Komponente abweichen soll |
| `data-configento-component-json` | Die Komponente direkt in der Seite statt Abruf beim Laden – siehe [Schneller laden](/docs/javascript-schnittstelle#schneller-laden-und-platz-freihalten) |

Weitere Attribute wie `data-configento-token-endpoint` und `data-configento-asset-base-url` setzen die Shop-Plugins. Im HTML-Snippet lässt du sie weg. Alle Attribute mit ihren JSON-Namen stehen in der [JavaScript-API-Referenz](/docs/javascript-api-referenz#einbinden-attribute-und-json).

Bei Ja/Nein-Attributen gilt das Attribut ohne Wert als „ja“. Erlaubt sind außerdem `true`/`false`, `1`/`0` und `yes`/`no`.

## Mehrere Konfiguratoren auf einer Seite

Du kannst beliebig viele `data-configento`-Elemente auf eine Seite setzen. Jedes lädt seine eigene Komponente und rechnet für sich. Das Skript bindest du nur einmal ein.

Gib jedem Element eine eigene `id` und verweise mit `price-mount` und den anderen Selektoren auf jeweils eigene Ziele. Über die `id` sprichst du die Konfiguratoren auch per JavaScript an.

## Einstellungen als JSON

Wenn dein CMS viele Attribute unhandlich macht, fasst du sie in einem Attribut zusammen:

```html
<div data-configento data-configento-config='{
    "componentId": "10722",
    "customer": "DEINE-KUNDEN-ID",
    "token": "DEIN-TOKEN",
    "cloudBaseUrl": "cloud.configento.app",
    "taxRate": "19",
    "uiLocale": "de_DE",
    "priceMount": "#mein-preis"
}'></div>
```

Die Namen im JSON: `componentId`, `customer`, `token`, `cloudBaseUrl`, `taxRate`, `uiLocale`, `contentLocale`, `currency`, `priceMount`, `summaryMount`, `summaryOpen`, `combinedImageMount`, `embedMode`, `languageSelect`, `languageSelectTitle`, `languages` (als Liste, z. B. `["de_DE", "en_GB"]`), `minHeight`, `minHeightKeep`, `wizardNav`, `productAttributes` und `component`. Steht eine Einstellung im JSON und zusätzlich als Einzelattribut, gilt das JSON.

Achte auf die einfachen Anführungszeichen außen, damit die doppelten im JSON erhalten bleiben.

## JavaScript-Schnittstelle

Für eigene Logik auf der Seite – etwa einen eigenen Anfrage-Knopf, ein Formular oder den Preis in deiner Kaufleiste – stellt der Konfigurator `window.Configento` bereit:

```html
<script>
  window.addEventListener('DOMContentLoaded', function () {
    Configento.ready.then(function () {
      var konfigurator = Configento.first();

      konfigurator.on('price', function (p) {
        console.log('Neuer Gesamtpreis:', p.total, p.currency);
      });
    });
  });
</script>
```

Alle Methoden und Ereignisse, das Speichern und Laden von Konfigurationen und den Umstieg von Legacy-Code beschreibt [JavaScript-Schnittstelle (V3)](/docs/javascript-schnittstelle).

## Das klassische Snippet

Konten mit der klassischen Cloud sehen unter **Integrationen** zusätzlich die Karte **HTML5**. Sie hat einen Schalter, ein eigenes Sicherheitstoken und im eingeschalteten Zustand ein **JavaScript-Snippet** (mit `_configentoSettings` und `html5.js`) und ein **iFrame-Snippet**. Beide laden die Frontend-Engine **Legacy**.

Bestehende Einbindungen mit dem klassischen Snippet laufen unverändert weiter. Für neue Einbindungen nimm das V3-Snippet: Nur dort gibt es Sprachauswahl, eigene Plätze für Preis, Zusammenfassung und Bild, die JavaScript-Schnittstelle und V3-Funktionen wie das Captcha.

Zum Umstellen ersetzt du das alte Snippet vollständig durch das neue – die beiden lassen sich nicht mischen. Die Kunden-ID bleibt gleich, das Token ist ein anderes: Es kommt aus der Karte **HTML5 (V3 Beta)**. Was sich mit dem Wechsel der Engine ändert, steht in [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3). Hast du eigenen JavaScript-Code für das klassische Snippet, hilft [Von Legacy umsteigen](/docs/javascript-schnittstelle#von-legacy-umsteigen).

## Fehlersuche

| Was du siehst | Ursache und Lösung |
|---|---|
| Gar nichts, kein Kasten | Das CMS hat das `<script>`-Tag entfernt. Nimm einen HTML-Block statt eines Textblocks. |
| „Komponente konnte nicht geladen werden (HTTP 401)“ mit `Requesting host not authorized` | Die Domäne fehlt unter **Einstellungen → Domänen** – auch Staging-Domänen eintragen. |
| „Komponente konnte nicht geladen werden (HTTP 401)“ mit `Token invalid` | Das Token stimmt nicht oder wurde mit **Erneuern** ersetzt. Kopiere das Snippet neu aus der Karte **HTML5 (V3 Beta)**. |
| „Komponente konnte nicht geladen werden (HTTP 404)“ | `YOUR_TEMPLATE_ID` nicht ersetzt, falsche ID oder Komponente noch nicht veröffentlicht |
| Konfigurator da, aber kein Preis | `data-configento-price-mount` fehlt, oder der Selektor findet kein Element. Alternativ `data-configento-embed-mode="admin-preview"`. |
| Preise zu niedrig, wie netto | `data-configento-tax-rate` steht auf `0` oder auf einem niedrigeren Steuersatz als in der Komponente |
| Änderungen aus dem Admin fehlen | Die Komponente ist nach der Änderung noch nicht veröffentlicht. |
| Sprachauswahl erscheint nicht | Die Komponente hat nur eine Sprache, oder der Besucher hat in dieser Sitzung schon gewählt. |
| Ein Merkmal zeigt „Unbekannter Merkmal-Typ“ | Die Komponente nutzt eine Funktion, die es nur in Legacy gibt – siehe [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3). |

Weitere Hinweise gibt die Browser-Konsole: Meldungen des Konfigurators beginnen mit `[Configento]`.

## Nächste Schritte

- [Der Aktions-Button](/docs/aktions-button)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [Globale Einstellungen](/docs/globale-einstellungen)
- [Erste Komponente anlegen](/docs/erste-komponente-anlegen)

---

# Magento-Plugin installieren

Source: https://configento.app/docs/magento-plugin-installieren
Section: Integrationen

Mit der Magento-Erweiterung läuft dein configento.app-Konfigurator direkt auf der Produktseite deines Magento-Shops. Deine Kunden konfigurieren, sehen den Preis sofort und legen das Produkt wie gewohnt in den Warenkorb. Bestellung, Steuer und Versand wickelt Magento ab. Die Konfiguration steht in Warenkorb, Bestellung, Bestell-E-Mail und Bestellansicht im Admin.

## Voraussetzungen

- **Magento Open Source oder Adobe Commerce 2.4**, bis einschließlich 2.4.9
- **PHP 7.4 bis 8.4**, mit den Erweiterungen `json` und `curl`
- **Composer** und Zugriff auf die Kommandozeile deines Magento-Servers
- Ein Login für das **Service-Portal** (service.configento.app) mit einer aktiven Service Order im Tarif **Professional** oder **Ultimate**. Im Tarif Basic lässt sich kein Shop-Plugin verbinden.
- Mindestens eine **veröffentlichte Komponente**. Dein Shop zeigt immer den zuletzt veröffentlichten Stand.

> **Magento 1** wird nicht mehr weiterentwickelt. Diese Anleitung gilt nur für Magento 2.

## So funktioniert es

1. Du installierst die Erweiterung per Composer.
2. Ein Magento-Admin meldet sich einmal mit seinem Service-Portal-Login bei Configento an. Danach sind Shop und Service Order verbunden – Kunden-ID, Schlüssel und Token trägt die Erweiterung selbst ein.
3. Du hängst an jedes konfigurierbare Produkt eine benutzerdefinierte Option vom Typ **configento.app** und wählst dort die Komponente.
4. Auf der Produktseite lädt der Konfigurator. Beim Klick auf **In den Warenkorb** übernimmt Magento den konfigurierten Preis.

## Schritt 1: Erweiterung installieren

Die Erweiterung kommt aus dem Composer-Repository von justSelling. Den passenden Befehl findest du auch im Configento-Admin unter **Einstellungen → Integrationen** in der Karte **Magento 2**.

Wechsle in das Hauptverzeichnis deiner Magento-Installation und führe aus:

```bash
composer config repositories.configento composer https://www.justselling.de/repo/mage2/
composer require justselling/configento:^5.0@beta
```

Die Version 5 ist aktuell als Beta freigegeben, deshalb der Zusatz `@beta`. Danach aktivierst du das Modul und baust Magento neu:

```bash
bin/magento maintenance:enable
bin/magento module:enable Justselling_Configento
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy de_DE en_US
bin/magento cache:flush
bin/magento maintenance:disable
```

- `setup:di:compile` und `setup:static-content:deploy` brauchst du nur im **Produktivmodus**. Gib bei `static-content:deploy` die Sprachen deiner Shops an.
- Im **Entwicklermodus** reichen `setup:upgrade` und `cache:flush`.

### Ohne Composer

Wenn du Composer nicht nutzen kannst, lädst du die ZIP-Datei der gewünschten Version unter [www.justselling.de/repo/mage2/](https://www.justselling.de/repo/mage2/index.html) herunter und entpackst sie nach `app/code/Justselling/Configento/`. Danach folgen dieselben `bin/magento`-Befehle wie oben. Updates musst du dann jedes Mal von Hand einspielen – Composer ist deshalb der empfohlene Weg.

## Schritt 2: Mit Configento verbinden

1. Öffne im Magento-Admin das Menü **justSelling → configento.app → configento.app**.
2. Beim ersten Aufruf erscheint **Mit Configento verbinden**. Klicke auf **Bei Configento anmelden**.
3. Du landest im Service-Portal. Melde dich mit deinem Portal-Login an.
4. Wähle unter **Welcher Kunde / welche Service-Order?** die Service Order, mit der der Shop arbeiten soll. Angeboten werden nur aktive Service Orders im Tarif Professional oder Ultimate.
5. Bestätige die Freigabe. Die Schaltflächen heißen derzeit noch englisch **Approve** (bestätigen) und **Deny** (ablehnen).
6. Zurück in Magento siehst du **Mit Configento als … verbunden.** und darunter den Configento-Admin. Hier legst du Komponenten an und bearbeitest sie, ohne Magento zu verlassen.

Beim ersten Verbinden trägt die Erweiterung die Zugangsdaten für den Shop automatisch ein und meldet die Aktivierung an configento.app. Du musst weder eine Kunden-ID noch einen Sicherheitstoken abtippen.

### Mehrere Admin-Benutzer

Die Anmeldung gilt **pro Magento-Admin-Benutzer**. Jeder, der den Configento-Admin in Magento öffnen will, meldet sich einmal selbst an. Damit siehst du später, wer verbunden ist, und kannst einzelne Zugänge entfernen (siehe [Verbindungen verwalten](#verbindungen-verwalten)).

### Klassische Anmeldung

Installationen, die schon vor Version 5 liefen, können bei der bisherigen Anmeldung mit Kunden-ID, Secure Key und Sicherheitstoken bleiben. Dazu stellst du in der Konfiguration **Klassische Anmeldung verwenden** auf **Ja**. Für neue Installationen lässt du die Einstellung aus.

## Schritt 3: Produkt mit einer Komponente verknüpfen

1. Öffne das Produkt im Magento-Admin.
2. Öffne den Abschnitt mit den benutzerdefinierten Optionen (**Customizable Options**) und füge eine Option hinzu.
3. Gib der Option einen Titel, z. B. „Konfiguration“. Er erscheint im Warenkorb vor der Zusammenfassung.
4. Wähle als **Option Type** den Eintrag **configento.app**.
5. Im Feld **Template** wählst du die Komponente. Die Liste zeigt die Komponenten deiner verbundenen Service Order mit ihrem Namen.
6. Speichere das Produkt.

Auf der Produktseite erscheint jetzt der Konfigurator. Eine Komponente lässt sich an beliebig viele Produkte hängen.

> **Liste leer?** Die Komponentenliste kommt von configento.app. Ist sie leer, ist der Shop noch nicht verbunden (Schritt 2) oder die Service Order hat noch keine Komponente.

## Was im Shop passiert

- **Produktseite:** Komponenten mit der Frontend-Engine **V3** werden direkt in die Seite eingebaut. Preis und Zusammenfassung zeigt der Shop an der gewohnten Stelle, Produktbilder landen in der Galerie. Komponenten mit der Engine **Legacy** laufen wie bisher. Beide Arten können im selben Shop nebeneinander laufen.
- **Warenkorb:** Der konfigurierte Preis gilt für Warenkorb, Steuer, Versand und Bestellung. Die Konfiguration wird als Liste unter dem Artikel angezeigt.
- **Wunschzettel und Sofortkauf:** Die Konfiguration wird mitgespeichert. Über **Bearbeiten** im Warenkorb oder Wunschzettel öffnet sich der Konfigurator wieder mit der gespeicherten Auswahl.
- **Bestellung:** Die Konfiguration steht in der Bestellbestätigung und in der Bestellansicht im Admin.

## Einstellungen der Erweiterung

Die Einstellungen öffnest du über **justSelling → configento.app → Konfiguration**. Einige Bezeichnungen erscheinen auch im deutschen Admin auf Englisch – wir nennen sie hier so, wie du sie siehst.

### Configento-Verbindungen

| Einstellung | Bedeutung |
|---|---|
| **Verbundene Configento-Benutzer** | Liste aller Magento-Admins, die sich bei Configento angemeldet haben, mit Portal-Benutzer und letzter Nutzung. **Trennen** widerruft eine Verbindung, z. B. bei ausgeschiedenen Mitarbeitern. |

### General

| Einstellung | Bedeutung |
|---|---|
| **Klassische Anmeldung verwenden** | Nur für bestehende Installationen, siehe oben. Blendet **Customer ID**, **Secure Key** und **Security Token** ein. |
| **Chart-Plugin laden** | Nur aktivieren, wenn deine Komponenten Diagramme verwenden. |
| **Dropzone-Plugin laden** | Aktivieren, wenn deine Komponenten Datei-Uploads enthalten. |
| **Debug-Modus** | Schreibt ausführliche Meldungen in die Browser-Konsole. Nur zur Fehlersuche, nicht dauerhaft im Live-Shop. |
| **CSS Path of combined Image Container** | CSS-Selektor des Bildbereichs, in dem das kombinierte Produktbild angezeigt werden soll – nur nötig, wenn dein Theme vom Standard abweicht. |

**Entwickler-Modus**, **Backend URL**, **Frontend URL**, **Cloud Base URL** und **CORS: Allow Private Network** sind für die Entwicklung gedacht und bleiben im Live-Shop aus bzw. leer.

### Product View

| Einstellung | Bedeutung |
|---|---|
| **Show summary in sidebar** | Zeigt die Zusammenfassung der Konfiguration in der Seitenleiste der Produktseite. |
| **Show summary product tab** | Zeigt die Zusammenfassung als eigenen Reiter auf der Produktseite. |
| **CMS Block Integration** | Stellt Inhalte von Magento-CMS-Blöcken für die Komponente bereit, z. B. für Infotexte. Geladen werden nur die Blöcke, die eine Komponente tatsächlich verwendet. |
| **CMS Block Integration Name-Filter** | Schränkt die Blöcke über den Anfang ihrer Kennung ein. Beispiel: `designer` übernimmt alle Blöcke, deren Kennung mit „designer“ beginnt. |

### Neuer Konfigurator (V3)

Ab Version 5.0.0-beta21. Gilt für Produkte, deren Komponente den neuen Konfigurator (V3) nutzt.

| Einstellung | Bedeutung |
|---|---|
| **Konfigurator früh laden** | Produktseiten mit Konfigurator verbinden sich schon im Seitenkopf mit configento.app und fordern den Zugangsschlüssel an, damit der Konfigurator früher bereit ist. Standard: an. Bis Version 5.0.0-beta21 hieß die Einstellung **Früh mit configento.app verbinden** und baute nur die Verbindung auf. |
| **Reservierte Höhe beim Laden** | Hält diese Höhe frei, bis der Konfigurator gezeichnet ist, damit Beschreibung und Footer darunter nicht springen, z. B. `640px` (eine reine Zahl gilt als Pixel). Leer: keine reservierte Höhe. Ungültige Werte werden ignoriert. |
| **Reservierte Höhe behalten** | Die Höhe bleibt auch danach als Mindesthöhe erhalten. |
| **Wizard-Navigation** | Was ein Wizard an eingebauter Navigation zeigt: **Wie in der Komponente eingestellt** (Standard), **Tabs, Fortschritt und Buttons**, **Nur Zurück/Weiter** oder **Keine** – für Themes, die mit der [JavaScript-Schnittstelle](/docs/javascript-schnittstelle#wizard-und-gruppen-steuern) eine eigene Schrittanzeige bauen. |

### Cart, Checkout and Backend

| Einstellung | Bedeutung |
|---|---|
| **Merkmal zu Warenkorb-Artikel** | Überträgt den Wert eines Merkmals in ein Feld des Warenkorb-Artikels, z. B. ein berechnetes Gewicht nach `weight`. Spalten: **Merkmal** (interner Name), **Wert**, **Spalte Warenkorbartikel**, **Wert im Warenkorbartikel**. Bleiben die Wert-Spalten leer, wird der Merkmalswert direkt übernommen. Die Reihenfolge der Zeilen zählt. |
| **SKU der Optionen an die Position** | Hängt die Artikelnummern der gewählten Werte an die SKU des Warenkorb-Artikels an. Standard: an. |
| **Produkte für Optionen** | Legt für jeden gewählten Wert mit bekannter Artikelnummer zusätzlich ein einfaches Produkt in der Bestellung an – praktisch für Stücklisten und Warenwirtschaft. |

### Asset Synchronisation

| Einstellung | Bedeutung |
|---|---|
| **Activate Asset Sync?** | Lädt Dateien, die Kunden im Konfigurator hochladen, tagsüber etwa alle zwei Stunden (4:30 Uhr, dann 8:30 bis 22:30 Uhr) in ein geschütztes Verzeichnis deiner Magento-Installation (`pub/media/order/asset/`). Braucht Speicherplatz und einen laufenden Magento-Cron. |

### Preisprüfung

Den Preis berechnet der Konfigurator im Browser. Mit der Preisprüfung lässt dein Shop jeden Preis beim Hinzufügen zum Warenkorb von configento.app mit demselben Rechenweg nachrechnen. So kann niemand einen manipulierten Preis in den Warenkorb schicken.

| Stufe | Verhalten |
|---|---|
| **Aus — keine Prüfung** | Standard. Der Preis aus dem Browser wird übernommen. |
| **Beobachten — nur prüfen und protokollieren** | Der Shop rechnet nach und schreibt Abweichungen ins Magento-Log. Der Warenkorb bleibt unverändert. |
| **Erzwingen — geprüften Preis verwenden** | Der nachgerechnete Preis wird verwendet. Kann er nicht bestätigt werden, lehnt der Shop das Hinzufügen ab und zeigt dem Kunden „Der Preis für Ihre Konfiguration konnte nicht bestätigt werden. Bitte versuchen Sie es in einem Moment erneut.“ |

So stellst du um:

1. Starte mit **Beobachten** und lass den Shop einige Tage normal laufen.
2. Suche im Magento-Log nach `configento.v3.price.divergence`. Jeder Eintrag ist eine Konfiguration, bei der Browser und Server unterschiedlich gerechnet haben – Ursache ist meist ein abweichender Steuersatz oder ein Wert, den nur der Shop kennt.
3. Erst wenn keine Abweichungen mehr auftauchen, schaltest du auf **Erzwingen**.

Geprüft werden nur Komponenten mit der Frontend-Engine **V3**. Komponenten mit der Engine Legacy werden übersprungen und wie bisher berechnet.

## Verbindungen verwalten

- **In Magento:** Unter **Configento-Verbindungen** in der Konfiguration siehst du alle verbundenen Admin-Benutzer und trennst einzelne Verbindungen mit **Trennen**.
- **Im Service-Portal:** Unter **Verbindungen** siehst du alle verbundenen Shops deiner Service Order mit Shop-Host, Plugin, verbindendem Benutzer und letzter Nutzung. **Widerrufen** trennt dort einen Shop vollständig.

## Update

Mit Composer holst du die neueste Version so:

```bash
composer update justselling/configento
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy de_DE en_US
bin/magento cache:flush
```

Die installierte Version siehst du oben in der Konfiguration der Erweiterung. Was sich in jeder Version geändert hat, steht in den Release Notes, die mit der Erweiterung ausgeliefert werden.

## Fehlersuche

Gehe diese Punkte der Reihe nach durch:

1. **„Das Shop-Plugin kann nur mit einer Professional- oder Ultimate-Order verbunden werden“** – deine Service Order hat den Tarif Basic oder ist nicht aktiv. Wechsle im Service-Portal den Tarif oder wähle eine andere Service Order.
2. **Der Configento-Admin in Magento zeigt nur „Mit Configento verbinden“** – dieser Admin-Benutzer hat sich noch nicht angemeldet. Die Anmeldung gilt pro Benutzer.
3. **Das Feld „Template“ zeigt keine Komponente** – der Shop ist noch nicht verbunden, oder die Service Order hat noch keine Komponente.
4. **Der Konfigurator erscheint nicht auf der Produktseite** – prüfe, ob das Produkt die Option vom Typ **configento.app** hat und die Komponente veröffentlicht ist. Leere danach den Magento-Cache und lade die Seite ohne Browser-Cache neu.
5. **Änderungen an der Komponente kommen nicht im Shop an** – der Shop zeigt den zuletzt veröffentlichten Stand. Veröffentliche die Komponente im Configento-Admin.
6. **Fehler beim Kompilieren oder nach dem Update** – führe `setup:upgrade`, `setup:di:compile` und `cache:flush` erneut aus. Im Produktivmodus fehlen nach einem Update sonst die neuen Klassen.
7. **„Der Preis für Ihre Konfiguration konnte nicht bestätigt werden“** – die Preisprüfung steht auf **Erzwingen**, und configento.app war nicht erreichbar oder konnte die Komponente nicht berechnen. Stelle auf **Beobachten** zurück und prüfe das Log.
8. **Weitere Hinweise** – aktiviere den **Debug-Modus** und sieh in die Browser-Konsole. Die Erweiterung schreibt außerdem in `var/log/configento.log`, Meldungen zur Anmeldung in `var/log/configento-oauth.log`.

Hilft das alles nicht, erreichst du den Support über den Chat im Service-Portal. Schick die Version der Erweiterung und die passenden Log-Einträge gleich mit.

## Nächste Schritte

- [Erste Komponente anlegen](/docs/erste-komponente-anlegen)
- [Shopware-Plugin installieren](/docs/shopware-plugin-installieren)
- [HTML-Snippet Integration](/docs/html-snippet-integration)
- [JavaScript-Schnittstelle (V3)](/docs/javascript-schnittstelle)

---

# Shopify-Plugin installieren

Source: https://configento.app/docs/shopify-plugin-installieren
Section: Integrationen

Mit der App **configento.app** aus dem Shopify App Store zeigst du deine Konfiguratoren direkt auf deinen Shopify-Produktseiten. Deine Kunden stellen ihr Produkt zusammen, sehen Preis und Produktbild bei jeder Auswahl und kaufen über den normalen Shopify-Checkout. Die Konfiguration steht im Warenkorb, im Checkout, in der Bestellung und in der Bestellbestätigung.

Im Shop läuft immer die Frontend-Engine **V3** – unabhängig davon, was in der Komponente eingestellt ist. Was V3 anders macht als Legacy, steht in [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Voraussetzungen

- Ein Shopify-Shop mit einem Theme, das App-Blöcke unterstützt (Online Store 2.0, z. B. Dawn, Horizon, Sense, Refresh, Origin und die meisten aktuellen Themes).
- Kein Shopify Plus nötig – die App funktioniert auf allen Shopify-Plänen.
- Ein configento.app Konto brauchst du vorher nicht. Du kannst es bei der Einrichtung anlegen lassen oder ein bestehendes verbinden.

## Installation

1. Öffne im Shopify App Store die App **configento.app** und installiere sie.
2. Bestätige die Berechtigungen, die Shopify dir anzeigt.
3. Shopify öffnet die App danach im Shopify-Admin. Du findest sie später jederzeit unter deinen Apps als **configento.app**.

Oben rechts in der App führt der Link **Anleitung** zu diesem Artikel.

## Die App im Überblick

Die App hat vier Reiter:

| Reiter | Wofür |
|---|---|
| **Einrichtung** | Abo, Verbindung mit deinem configento.app Konto, Beispielkomponenten |
| **Produkte** | Welches Produkt welche Komponente zeigt |
| **Preise** | Währung, Steuer und Umrechnung zwischen configento.app und Shopify |
| **Theme-Block** | Konfigurator und Warenkorb-Erweiterung im Theme einschalten, Bestellbestätigung anpassen |

**Produkte**, **Preise** und **Theme-Block** sind erst nach der Verbindung mit einem Konto anklickbar. Danach trägt der Reiter **Einrichtung** ein Häkchen.

Die App erscheint in der Sprache, die du im Shopify-Admin eingestellt hast (Deutsch, Englisch, Spanisch oder Französisch, sonst Englisch). Fehlermeldungen aus dem Hintergrund – etwa „invalid or expired code“ – sind derzeit immer englisch.

## Schritt 1: Plan auswählen

Ohne aktives Abo zeigt die App statt der Reiter den Hinweis **Abo erforderlich**: „Für diesen Shop ist kein aktives Configento-Abo hinterlegt. Wähle einen Plan, um den Konfigurator zu nutzen — die ersten 14 Tage sind kostenlos.“

Klicke auf **Plan auswählen**. Shopify öffnet die Plan-Seite, dort bestätigst du den Plan. Abgerechnet wird über deine Shopify-Rechnung. Das Abo schaltet den Leistungsumfang **Professional** frei.

Ohne aktives Abo lädt auch der Konfigurator im Shop nicht.

## Schritt 2: configento.app Konto verbinden

Im Reiter **Einrichtung** fragt die App: **Nutzt du Configento bereits?**

### Noch kein Konto

Klicke auf **Nein — Konto jetzt anlegen**. configento.app legt dein Konto an und schickt eine Einladung an die E-Mail-Adresse deines Shopify-Shops. Über die Einladung vergibst du dein Passwort für das Service-Portal. Das dauert meist nur einen Moment – klicke danach auf **Neu laden**.

### Bestehendes Konto

Klicke auf **Ja — ich habe schon ein Konto**. Du brauchst einen 6-stelligen Verbindungscode:

1. Öffne das Service-Portal (`service.configento.app`) und melde dich an.
2. Klicke beim Dienst, dem der Shop zugeordnet werden soll, auf **Verwalten**. Der Admin öffnet sich.
3. Gehe zu **Einstellungen → Integrationen** und scrolle zur Karte **Shopify**.
4. Hast du mehrere Dienste, wähle unter **Shopify-Shop mit Service Order verknüpfen** den richtigen aus.
5. Klicke auf **Verbindungs-Code generieren**. Der **Verknüpfungs-Code** ist 24 Stunden gültig (**Gültig bis**).
6. Füge den Code in der App ein und klicke auf **Verbinden**.

Danach zeigt der Reiter **Einrichtung** „Mit Configento-Kunde … verknüpft.“

**Wichtig:** Das Shopify-Abo ist ein eigener Dienst in deinem Kundenkonto. Verbindest du ein bestehendes Konto, legt das Service-Portal dafür einen neuen Dienst mit einem eigenen, zunächst leeren Arbeitsbereich an; die App arbeitet danach mit diesem Arbeitsbereich. Deine bisherigen Komponenten bleiben in ihrem Dienst. Brauchst du sie im Shop, exportierst du sie dort und importierst sie im neuen Arbeitsbereich mit **ZIP importieren** (siehe [Erste Komponente anlegen](/docs/erste-komponente-anlegen#schritt-2-komponente-anlegen)).

Ein Shop ist immer mit genau einem Konto verbunden. Soll er zu einem anderen gehören, deinstalliere die App und installiere sie neu.

## Schritt 3: Beispielkomponenten (optional)

Ist dein Arbeitsbereich noch leer, fragt der Reiter **Einrichtung**: „Sollen wir vier Beispielkomponenten anlegen?“ Mit **Ja, anlegen** bekommst du vier Komponenten – kombiniertes Produktbild, Kombimerkmale mit Formeln, ein Regelwerk und grafische Icons. Sie werden automatisch veröffentlicht; das dauert einen Moment. Danach kannst du sie im Reiter **Produkte** zuordnen und im Admin wie jede andere Komponente bearbeiten oder löschen.

Eigene Komponenten legst du im Admin an, den du aus dem Service-Portal mit **Verwalten** öffnest. Zuordnen kannst du nur **veröffentlichte** Komponenten – siehe [Erste Komponente anlegen](/docs/erste-komponente-anlegen#schritt-8-veröffentlichen).

## Schritt 4: Produkte zuordnen

Im Reiter **Produkte**:

1. Suche unter **Produkt hinzufügen** nach dem Produktnamen.
2. Wähle in der Zeile des Produkts die Komponente (**Komponente wählen…**) und klicke auf **+**.
3. Das Produkt erscheint oben unter **Produkte mit Konfigurator**. Dort wechselst du die Komponente oder entfernst die Zuordnung mit **−**.

Änderungen werden sofort gespeichert. Shopify hält Shop-Seiten einige Minuten im Cache – eine neue Zuordnung erscheint deshalb mit kurzer Verzögerung.

Direkt nach der Installation baut Shopify einen Index für die Zuordnungen auf. Solange zeigt der Reiter „Shopify baut den Produktindex für diese App auf.“ und listet noch keine Produkte. Bereits gemachte Zuordnungen bleiben erhalten. Lade die Seite nach einigen Minuten neu oder klicke auf **Erneut prüfen**.

**Ohne die App zuordnen:** Die Zuordnung ist ein Produkt-Metafeld. Im Shopify-Admin findest du es am Produkt als **Configento Component ID** (Namespace `configento`, Key `component_id`). Als Wert trägst du die ID einer veröffentlichten Komponente ein. Produkte ohne diesen Wert zeigen keinen Konfigurator.

## Schritt 5: Theme einrichten

Im Reiter **Theme-Block** schaltest du zwei Dinge ein – einmal pro Theme. Neben jedem Punkt steht, ob er in deinem **veröffentlichten** Theme **Aktiv** oder **Nicht aktiviert** ist.

### Konfigurator-Block

1. Klicke auf **Konfigurator-Block einbauen**. Shopify öffnet den Theme-Editor mit der Produktvorlage und fügt den Block **Configento Configurator** hinzu.
2. Shopify setzt neue Blöcke ans Ende. Das macht nichts: Mit der Einstellung **Konfigurator automatisch über dem Preis platzieren** (Standard: an) springt der Konfigurator beim Laden direkt vor den Preis. Alternativ ziehst du den Block über den Button „In den Einkaufswagen“.
3. **Speichern**.

Einstellungen des Blocks im Theme-Editor:

| Einstellung | Standard | Bedeutung |
|---|---|---|
| **Configento-Backend-URL** | `https://admin.configento.app` | Nur ändern, wenn Configento dir ausdrücklich einen anderen Host nennt |
| **CSS-Selector des Theme-Preises (optional)** | leer | Leer = automatische Erkennung (Dawn, Sense, Refresh, Origin, Horizon und die meisten Premium-Themes). Mehrere Selektoren durch Komma trennen |
| **CSS-Selector der Produktbild-Galerie (optional)** | leer | Leer = automatische Erkennung (Dawn und davon abgeleitete Themes). Dort ersetzt das kombinierte Produktbild das Produktfoto, solange die Komponente Bildebenen liefert |
| **Konfigurator automatisch über dem Preis platzieren** | an | Schiebt den Block beim Laden vor das Preiselement, egal wo er im Theme-Editor steht |
| **Zusammenfassung der Konfiguration anzeigen** | aus | Zeigt unter dem Konfigurator eine Zusammenfassung der Auswahl. An die Bestellung geht sie in jedem Fall |
| **Lade-Text (leer lassen für automatische Sprachwahl)** | leer | Leer = „Konfigurator wird geladen …“ in der Sprache des Shops (DE, EN, ES, FR, sonst Englisch) |

Der Konfigurator übernimmt Schrift, Farben und Eckenradien aus Themes der Dawn-Familie.

### Warenkorb-Erweiterung „Configento Cart“

**Configento Cart** ist eine App-Einbettung. Sie zeigt im Warenkorb und in der Warenkorb-Schublade für jede konfigurierte Position das Bild der Konfiguration, die Auswahl des Käufers und einen Link **Bearbeiten**. Außerdem gibt sie das Bild der Konfiguration an Checkout, Bestellung und Bestellbestätigung weiter.

App-Einbettungen sind in Shopify ausgeschaltet, bis du sie einschaltest – die App kann das nicht selbst.

1. Klicke auf **Configento Cart aktivieren**. Shopify öffnet den Theme-Editor mit bereits eingeschalteter Einbettung.
2. **Speichern**.

Der Schalter gilt **pro Theme**. Nach einem Theme-Wechsel oder einer Neuinstallation der App schaltest du ihn erneut ein. Ist er aus, warnt der Reiter: „„Configento Cart“ ist in deinem veröffentlichten Theme nicht aktiviert.“

Ohne **Configento Cart** funktioniert der Kauf trotzdem – Preis und Konfiguration stimmen. Warenkorb, Checkout und Bestellung zeigen dann aber das Produktfoto statt des Bilds der Konfiguration, und es gibt keinen **Bearbeiten**-Link.

## Schritt 6: Bild in der Bestellbestätigung (optional)

Die Bestellbestätigung per E-Mail enthält die Konfiguration automatisch. Das Produktbild darin kommt aber aus der Mail-Vorlage deines Shops, und die kann eine App nicht ändern. Damit statt des Produktfotos das Bild der Konfiguration erscheint, passt du die Vorlage einmal an. Der Reiter **Theme-Block** führt dich unter **Konfigurationsbild in der Bestellbestätigung (optional)** durch die Schritte und bietet die Texte zum **Kopieren** an:

1. **Bestellbestätigung bearbeiten** öffnet den Code der Vorlage.
2. Suche im Code (Strg+F / Cmd+F) nach dieser Zeile:
   `{% if parent_line_item and parent_line_item.image %}`
3. Ersetze **jedes** Vorkommen dieser Zeile durch den folgenden Block. Die Standardvorlage enthält die Zeile mehrmals, einmal pro Lieferabschnitt.

```liquid
{%- comment -%} Configento: show the configuration's combined image {%- endcomment -%}
{%- assign configento_image = '' -%}
{%- for configento_part in line_item_group.components -%}
  {%- for configento_prop in configento_part.properties -%}
    {%- if configento_prop.first == '_configento_image' -%}{%- assign configento_image = configento_prop.last -%}{%- endif -%}
  {%- endfor -%}
{%- endfor -%}
{% if configento_image != blank %}
  <img src="{{ configento_image }}{% if configento_image contains '?' %}&{% else %}?{% endif %}width=120&height=120&crop=center" align="left" width="60" height="60" class="order-list__product-image" alt="">
{% elsif parent_line_item and parent_line_item.image %}
```

4. Speichere die Vorlage. Die nächste Bestellbestätigung zeigt das Bild der Konfiguration.

Findest du die Zeile nicht, wurde deine Vorlage angepasst. Dann setzt dein Entwickler oder der Configento-Support den Block an die Stelle, an der das Produktbild eines Bundles ausgegeben wird.

## Eigene Domain freigeben

Bei der Verbindung trägt die App die Shopify-Adresse deines Shops (`….myshopify.com`) automatisch als freigegebene Domäne ein. Läuft dein Shop unter einer **eigenen Domain**, trägst du sie selbst ein: im Admin unter **Einstellungen → Domänen** mit **Domäne hinzufügen**, Modus **Produktion**. Sonst lädt der Konfigurator auf dieser Domain nicht. Mehr dazu: [Globale Einstellungen](/docs/globale-einstellungen#domänen).

## Preise, Währung und Steuern

Den Reiter **Preise** musst du meist nicht anfassen. Die App liest Währung und Steueranzeige deines Shops bei jedem Aufruf live aus Shopify und rechnet passend um. Der Reiter zeigt unter **Währung & Steuer** beide Seiten nebeneinander: **Configento (Preisquelle)** und **Shopify (Storefront, live)**.

- **Steuer:** Zeigt dein Shop Preise **ohne** Steuer, kommen die Aufpreise netto in den Shop, und Shopify rechnet die Steuer an der Kasse auf. Zeigt dein Shop Preise **mit** Steuer, rechnet die App mit dem Steuersatz, den Shopify für dieses Produkt berechnet. Ist der nicht zu ermitteln, bleiben die Preise auf der Basis, auf der sie in der Komponente angelegt sind.
- **Währung:** Nutzen beide Seiten dieselbe Währung, wird nichts umgerechnet („Beide Seiten nutzen EUR. Keine Umrechnung nötig.“). Bei unterschiedlichen Währungen nimmt die App den Wechselkurs aus Shopify Markets.
- **Manueller Umrechnungskurs:** Wird nur verwendet, wenn Shopify Markets keinen Kurs liefert. Bei gleicher Währung bleibt er wirkungslos, und der Reiter weist darauf hin. Mit **Manuellen Wert entfernen** löschst du ihn.

Der Aufpreis im Warenkorb entspricht dem Betrag, den der Konfigurator auf der Produktseite anzeigt.

## Was der Käufer sieht

1. **Produktseite:** Der Konfigurator lädt mit dem Produkt. Bis er bereit ist, ist der Button zum Warenkorb gesperrt – so landet kein Produkt ohne Konfiguration im Warenkorb. Preis und – sofern die Komponente Bildebenen hat – das kombinierte Produktbild in der Galerie folgen jeder Auswahl.
2. **In den Warenkorb:** Die Konfiguration wird gespeichert und die Position mit dem vollen Preis angelegt. Das Bild der Konfiguration kommt etwa eine halbe Minute später dazu (über **Configento Cart**).
3. **Warenkorb:** Bild der Konfiguration, die Auswahl und der Link **Bearbeiten**. Der Link führt zurück zur Produktseite mit der bisherigen Auswahl; nach dem erneuten Hinzufügen ersetzt die neue Konfiguration die alte Position.
4. **Checkout:** Eine Position mit dem Titel „Produkt – Wert, Wert, …“. Aufgeklappt zeigt sie die Bestandteile: das Produkt zum Grundpreis und **Konfiguration** mit dem Aufpreis. Zahlungsarten, Rabattcodes und andere Shopify-Funktionen bleiben unverändert.
5. **Bestellbestätigung:** Die Position mit der Konfiguration im Titel und ihren Bestandteilen – mit Bild der Konfiguration, wenn du Schritt 6 umgesetzt hast.

## Die Bestellung im Shopify-Admin

Eine konfigurierte Bestellung zeigt ihre Bestandteile: das **Produkt** zum Grundpreis und die Position **Konfiguration** mit dem Aufpreis. Die Auswahl des Käufers steht als Eigenschaften an der Position **Konfiguration**.

## Was die App in deinem Shop anlegt

- **Zwei Entwurfsprodukte „Konfiguration“** (Name in der Hauptsprache deines Shops: Konfiguration, Configuration, Configuración): Sie tragen den Aufpreis im Warenkorb – eines für versandpflichtige, eines für nicht versandpflichtige Produkte. Im Shop sind sie nicht sichtbar. **Nicht löschen, veröffentlichen oder umbenennen.**
- **Bilder der Konfigurationen** (`configento-….png`) in den Dateien deines Shops. Warenkorb und Checkout zeigen nur Bilder von Shopify selbst, deshalb legt die App jedes Konfigurationsbild dort ab.
- **Metafelder:** **Configento Component ID** an zugeordneten Produkten und Shop-Metafelder für die beiden Aufpreis-Produkte.

**Berechtigungen:** Die App liest und schreibt Produkte (Zuordnung, Aufpreis-Produkte), Warenkorb-Transformationen (Aufpreis), Entwurfsbestellungen (nur zur Berechnung des Steuersatzes, es entstehen keine Entwürfe) und Dateien (Konfigurationsbilder) und liest die Sprachen deines Shops. Kommt mit einem Update eine Berechtigung hinzu, bestätigst du sie beim nächsten Öffnen der App.

## Abrechnung und KI-Tokens

- **Das Abo** läuft über Shopify und erscheint auf deiner Shopify-Rechnung. Im Service-Portal steht der Dienst ohne **Dienst umstellen** und **Dienst kündigen** – siehe [Service-Portal](/docs/service-portal-uebersicht#über-shopify-gebuchte-dienste).
- **KI-Tokens:** Ein monatliches Kontingent für den KI-Assistenten ist im Abo enthalten. Zusätzliche Tokens kannst du für einen über Shopify gebuchten Dienst nicht kaufen. Mehr zu Tokens: [KI-Tokens](/docs/ki-tokens).

## Deinstallieren und neu installieren

Eine Kündigung gibt es in Shopify nicht als eigenen Knopf: Mit der **Deinstallation** der App endet das Abo, Shopify rechnet nicht weiter ab, und der Dienst im Service-Portal wird beendet.

Bei der Deinstallation entfernt Shopify alles, was der App am Shop gehört – Einbettungen, Warenkorb-Transformation, Shop-Metafelder. Die Zuordnungen an deinen Produkten bleiben stehen.

Nach einer **Neuinstallation**:

1. wählst du wieder einen Plan,
2. verbindest du wieder ein Konto (das kann auch ein anderes sein),
3. schaltest du **Configento Cart** im Reiter **Theme-Block** erneut ein,
4. prüfst du im Reiter **Produkte** die Zuordnungen. Hast du ein anderes Konto verbunden, gehören die alten Komponenten-IDs nicht mehr dazu – ordne neu zu.

## Fehlersuche

1. **Auf der Produktseite erscheint gar nichts** – das Produkt hat keine Komponente zugeordnet, oder der Konfigurator-Block fehlt in der Produktvorlage. Prüfe den Reiter **Produkte** und im Reiter **Theme-Block** den Status von **Konfigurator-Block**. Eine frische Zuordnung braucht wegen des Shopify-Caches einige Minuten.
2. **„Configurator could not be loaded.“** – der Konfigurator konnte nicht starten (die Meldung ist immer englisch). Ursachen: kein aktives Abo, der Shop ist mit keinem Konto verbunden, oder configento.app hat nicht innerhalb von 8 Sekunden geantwortet.
3. **„Komponente konnte nicht geladen werden (HTTP 401)“** – der Shop läuft unter einer eigenen Domain, die nicht freigegeben ist. Siehe [Eigene Domain freigeben](#eigene-domain-freigeben).
4. **„Komponente konnte nicht geladen werden (HTTP 404)“** oder mit einem anderen Code – die zugeordnete Komponente ist nicht veröffentlicht oder gehört nicht zum verbundenen Konto. Ordne im Reiter **Produkte** eine veröffentlichte Komponente zu.
5. **Der Button „In den Warenkorb“ bleibt kurz grau** – Absicht: Er ist gesperrt, bis der Konfigurator bereit ist, höchstens 20 Sekunden.
6. **Warenkorb zeigt das Produktfoto, kein „Bearbeiten“** – **Configento Cart** ist im veröffentlichten Theme aus, etwa nach einem Theme-Wechsel. Reiter **Theme-Block** → **Configento Cart aktivieren** → speichern.
7. **Checkout oder Bestellung zeigen das Produktfoto** – ebenfalls **Configento Cart** prüfen. Das Bild kommt erst etwa eine halbe Minute nach dem Hinzufügen; wer sofort zur Kasse geht, sieht unter Umständen noch das Produktfoto. Fehlt das Bild dauerhaft, öffne die App und bestätige angefragte Berechtigungen.
8. **Kein Aufpreis im Warenkorb** – die Warenkorb-Transformation ist nicht aktiv. Öffne die App im Shopify-Admin; hilft das nicht, wende dich an den Configento-Support. Lösche außerdem keines der beiden Produkte „Konfiguration“.
9. **Preis auf der Produktseite anders als im Shop erwartet** – Reiter **Preise** prüfen: Steueranzeige und Währung beider Seiten, bei gleicher Währung einen manuellen Kurs entfernen.
10. **Bestellbestätigung zeigt das Produktfoto** – die Mail-Vorlage ist nicht angepasst (Schritt 6).
11. **„invalid or expired code“ beim Verbinden** – der Code ist älter als 24 Stunden, schon benutzt oder vertippt. Generiere im Admin einen neuen.
12. **„shop already linked“** – der Shop ist schon mit einem Konto verbunden. Für ein anderes Konto: App deinstallieren und neu installieren.
13. **„Abo erforderlich“** – kein aktiver Plan. **Plan auswählen**.
14. **„Diese Sitzung konnte nicht autorisiert werden.“** – lade die Seite neu. Bleibt die Meldung, deinstalliere die App und installiere sie neu.

## Nächste Schritte

- [Erste Komponente anlegen](/docs/erste-komponente-anlegen)
- [Preisberechnung einrichten](/docs/preisberechnung-einrichten)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [Magento-Plugin installieren](/docs/magento-plugin-installieren)
- [Shopware-Plugin installieren](/docs/shopware-plugin-installieren)
- [JavaScript-Schnittstelle (V3)](/docs/javascript-schnittstelle)

---

# Shopware-Plugin installieren

Source: https://configento.app/docs/shopware-plugin-installieren
Section: Integrationen

Mit dem Shopware-Plugin erscheint dein Konfigurator direkt auf der Produktseite deines Shopware-Shops. Deine Kunden stellen das Produkt zusammen, sehen den Preis sofort und legen die fertige Konfiguration in den normalen Shopware-Warenkorb. Die Bestellung läuft danach ganz regulär über Shopware.

## Voraussetzungen

- **Shopware 6.7** (das aktuelle Plugin ist für 6.7 gebaut)
- **PHP 8.2 bis 8.5**
- Ein Zugang zum Shopware-Admin mit dem Recht, Erweiterungen zu installieren
- Ein Login im [Service-Portal](https://service.configento.app) für den Dienst, mit dem du den Shop verbinden willst
- Mindestens eine **veröffentlichte** Komponente – unveröffentlichte Entwürfe kannst du im Shop nicht auswählen

Du nutzt eine ältere Shopware-6-Version? Dann melde dich beim Support, bevor du installierst.

## Plugin herunterladen

Das Plugin bekommst du in configento.app unter **Einstellungen → Integrationen**.

Ist der Tab gesperrt, akzeptiere zuerst unter **Einstellungen → Auftragsverarbeitung** den Vertrag zur Auftragsverarbeitung.

Welche Karte du dort siehst, hängt von deinem Konto ab:

| Du siehst … | Das bedeutet | Anmeldung im Plugin |
|---|---|---|
| eine Karte **Shopware 6.7** mit dem Button **Plugin herunterladen** | Dein Shop verbindet sich über dein Service-Portal-Login. Ein Sicherheitstoken brauchst du nicht. | **Mit Configento verbinden** (empfohlen) |
| eine Karte **Shopware 6** mit Schalter, Sicherheitstoken und dem Link **Plugin herunterladen** | Dein Konto nutzt noch die klassische Anmeldung. | Kunden-ID, Secure Key und Security Token von Hand eintragen – siehe [Klassische Anmeldung](#klassische-anmeldung) |

Lade die ZIP-Datei herunter und entpacke sie **nicht**.

## Plugin installieren

### Im Shopware-Admin

1. Öffne **Erweiterungen → Meine Erweiterungen**.
2. Lade die ZIP-Datei über **Erweiterung hochladen** hoch.
3. Installiere und aktiviere das Plugin **configento.app Plugin**.
4. Leere den Shopware-Cache.

### Per Konsole

Wenn du Zugriff auf die Shopware-Konsole hast, kopiere den entpackten Ordner `JustsellingProductConfigurator` nach `custom/plugins/` und führe im Shopware-Verzeichnis aus:

```bash
bin/console plugin:refresh
bin/console plugin:install --activate JustsellingProductConfigurator
bin/console cache:clear
```

Der technische Name des Plugins ist **JustsellingProductConfigurator**. Ältere Anleitungen nennen hier einen anderen Namen, der nicht funktioniert.

## Mit Configento verbinden

Die Verbindung stellst du einmal aus dem Shopware-Admin heraus her. Ein Token musst du dabei nicht kopieren.

1. Öffne die Konfiguration des **configento.app Plugin** in der Erweiterungsverwaltung.
2. In der Karte **Allgemein** steht unter **Configento-Verbindung** der Button **Mit Configento verbinden**. Klicke darauf.
3. Du wirst zum Service-Portal weitergeleitet. Melde dich an und bestätige die Verbindung.
4. Danach kommst du zurück in den Shopware-Admin. Unter **Configento-Verbindung** steht jetzt **Verbunden als** mit deinem Portal-Login.

Lass den Schalter **Klassische Anmeldung verwenden** dabei **aus**.

Beim Verbinden trägt das Plugin die Zugangsdaten für die Produktseite selbst ein. Du findest sie in der Karte **Allgemein** als Kunden-ID, Secure Key und Security Token. Ändern musst du dort nichts.

**Jeder Admin-Benutzer verbindet sich einzeln.** Die Verbindung gilt für den Shopware-Benutzer, der sie hergestellt hat. Arbeitet ein Kollege mit einem eigenen Shopware-Login, sieht er beim ersten Öffnen des Konfigurators die Meldung **Mit Configento verbinden** und klickt auf **Jetzt verbinden**.

Die bestehende Verbindung prüfst du jederzeit mit **Verbindung testen**.

## Komponenten im Shopware-Admin bearbeiten

Nach dem Verbinden gibt es im Katalog-Bereich des Shopware-Hauptmenüs den Eintrag **Produktkonfigurator Cloud**. Dort öffnet sich configento.app direkt im Shopware-Admin. Du bearbeitest deine Komponenten also, ohne den Shop zu verlassen.

## Produkt mit einer Komponente verknüpfen

1. Öffne im Shopware-Admin das Produkt.
2. Wechsle in den Tab **Produktkonfigurator**.
3. Klicke auf **Komponente hinzufügen**.
4. Wähle unter **Komponenten-Name** die Komponente aus. Die Liste zeigt die Komponenten deines verbundenen Dienstes mit ihrem Namen.
5. Optional: Trage eine **Überschrift** ein. Sie steht über der Zusammenfassung der Konfiguration auf der Produktseite (siehe [Plugin-Einstellungen](#plugin-einstellungen)).
6. Speichere das Produkt.

Ein Produkt hat genau **eine** Komponente. Ist schon eine verknüpft, verschwindet der Button **Komponente hinzufügen**. Willst du eine andere Komponente verknüpfen, entferne die alte mit **Komponente entfernen** und füge danach die neue hinzu.

Erscheint eine Komponente nicht in der Liste, ist sie meist noch nicht veröffentlicht. Veröffentliche sie in configento.app und öffne das Produkt neu.

## Was im Shop passiert

1. Der Kunde öffnet die Produktseite. Der Konfigurator erscheint im Kaufbereich und ersetzt dort den normalen Warenkorb-Button.
2. Der Kunde stellt das Produkt zusammen. Der Preis wird bei jeder Auswahl neu berechnet.
3. Mit **In den Warenkorb** landet das Produkt samt Konfiguration im Shopware-Warenkorb. Die gewählten Merkmale stehen unter dem Produkt.
4. Shopware wickelt die Bestellung normal ab. In der Bestellung im Shopware-Admin siehst du die Konfiguration an der Bestellposition.

Der Warenkorbpreis ergibt sich aus dem **Preis des Shopware-Produkts plus den Aufpreisen der Konfiguration**. Trägst du in Shopware einen Grundpreis ein, wird er also zum Konfigurationspreis addiert. Soll der Konfigurator den kompletten Preis bestimmen, setze den Shopware-Preis auf 0.

Der Shop zeigt immer den zuletzt **veröffentlichten** Stand der Komponente. Änderungen, die du nur gespeichert hast, sehen deine Kunden erst nach dem Veröffentlichen.

### Konfiguration in der Bestellbestätigung

Die Shopware-Bestellbestätigung zeigt die gewählten Merkmale nicht von selbst. Ergänze dafür in der E-Mail-Vorlage **Bestellbestätigung** innerhalb der Schleife über die Bestellpositionen diesen Block.

In der HTML-Version:

```twig
{% if nestedItem.payload.justselling_options is defined and nestedItem.payload.justselling_options|length >= 1 %}
    <div>
        {% for option in nestedItem.payload.justselling_options %}
            {{ option.group }}: {{ option.option }}
            {% if nestedItem.payload.justselling_options|last != option %}<br>{% endif %}
        {% endfor %}
    </div>
{% endif %}
```

In der Text-Version:

```twig
{% if lineItem.payload.justselling_options is defined and lineItem.payload.justselling_options|length >= 1 %}, {% for option in lineItem.payload.justselling_options %}{{ option.group }}: {{ option.option }}{% if lineItem.payload.justselling_options|last != option %}{{ " | " }}{% endif %}{% endfor %}{% endif %}
```

Die Variablennamen `nestedItem` und `lineItem` müssen zu deiner Vorlage passen. Verwendet deine Schleife einen anderen Namen, ersetze sie entsprechend.

## Plugin-Einstellungen

Alle Einstellungen findest du in der Konfiguration des **configento.app Plugin**.

### Einstellungen

| Einstellung | Wirkung | Standard |
|---|---|---|
| **Chart-Plugin laden** | Einschalten, wenn deine Komponenten Merkmale mit Diagrammen enthalten | aus |
| **Dropzone-Plugin laden** | Einschalten, wenn deine Komponenten Datei-Uploads enthalten. Ohne diese Option funktioniert der Upload im Shop nicht. | aus |
| **jQuery laden** | Lädt jQuery für den Konfigurator. Nur ausschalten, wenn dein Theme jQuery schon selbst lädt und es Konflikte gibt. | an |
| **Stückliste bei Bestellung erstellen** | Statt eines konfigurierten Produkts werden bei der Bestellung die einzelnen Shopware-Produkte bestellt, die zu den gewählten Werten gehören. Dafür muss die **Artikelnummer (SKU)** eines Werts in configento.app der **Produktnummer** eines Shopware-Produkts entsprechen. | aus |
| **CSS-Pfad für den Container für kombinierte Produktbilder** | CSS-Selektor des Bereichs auf der Produktseite, in dem das kombinierte Produktbild erscheinen soll | leer |

### Preisprüfung

Ab Plugin-Version 5.0.1 rechnet configento.app den Aufpreis jeder Konfiguration auf dem eigenen Server nach. So landet ein im Browser manipulierter Preis nicht im Warenkorb.

| Modus | Wirkung |
|---|---|
| **Aus** | Keine Prüfung. Der Warenkorb übernimmt den Preis aus dem Konfigurator. |
| **Beobachten** (Standard) | Der Warenkorb übernimmt weiter den Preis aus dem Konfigurator. Jede Abweichung steht als `configento.price.divergence` im Shopware-Log. |
| **Erzwingen** | Der Warenkorb berechnet den geprüften Preis. Liegt keiner vor, etwa weil configento.app nicht erreichbar ist, sperrt Shopware die Bestellung mit einem Hinweis für den Kunden. |

Lass das Plugin nach dem Update einige Tage auf **Beobachten** laufen. Stehen im Log keine Abweichungen, stellst du auf **Erzwingen** um.

### Produkt-Ansicht

| Einstellung | Wirkung | Standard |
|---|---|---|
| **Zusammenfassung im Tab auf Produkt-Seite anzeigen** | Zeigt die gewählte Konfiguration im Beschreibungs-Tab der Produktseite | aus |
| **Zusammenfassung unter dem Preis auf Produkt-Seite anzeigen** | Zeigt die gewählte Konfiguration unter dem Preis, mit der **Überschrift** aus der Produktverknüpfung | aus |

### Entwickler-Einstellungen

**Debug-Modus**, **Entwickler-Modus** und die URL-Felder darunter sind für die Fehlersuche mit dem Support gedacht. Lass sie im Live-Shop aus und leer.

## Klassische Anmeldung

Konten, die unter **Einstellungen → Integrationen** die Karte **Shopware 6** mit Sicherheitstoken sehen, verbinden das Plugin über drei Zugangsdaten:

| Feld im Plugin | Wo du den Wert findest |
|---|---|
| **Kunden-ID** | Service-Portal, Seite **Dienste**: der Wert hinter **Kunde** beim jeweiligen Dienst |
| **Secure Key** | Service-Portal, Seite **Dienste**: der **Sicherheitsschlüssel** beim jeweiligen Dienst |
| **Security Token** | configento.app, **Einstellungen → Integrationen**, Karte **Shopware 6**. Schalte die Karte ein, damit ein Token erzeugt wird. |

Schalte in der Plugin-Konfiguration **Klassische Anmeldung verwenden** ein, trage die drei Werte ein und speichere. Mit **Verbindung testen** prüfst du die Zugangsdaten. Stimmen sie, erscheint **Klassische Cloud-Verbindung OK**. Mit **Neues Token** erzeugst du ein neues Token. Danach musst du es auch im Plugin austauschen.

## Plugin aktualisieren

Lade die neue ZIP-Datei wie bei der Installation unter **Erweiterungen → Meine Erweiterungen** hoch und führe das Update aus. Per Konsole kopierst du den neuen Ordner über den alten und rufst auf:

```bash
bin/console plugin:refresh
bin/console plugin:update JustsellingProductConfigurator
bin/console cache:clear
```

Verbindung, Einstellungen und Produktverknüpfungen bleiben beim Update erhalten.

## Verbindung trennen

**Verbindung trennen** steht unter **Configento-Verbindung** in der Plugin-Konfiguration.

> **Achtung:** Trennen wirkt für den **ganzen Shop**, nicht nur für deinen Admin-Benutzer. Dabei werden **alle Verknüpfungen zwischen Produkten und Komponenten** im Shop gelöscht und die gespeicherten Zugangsdaten zurückgesetzt. Die Komponenten selbst in configento.app bleiben erhalten. Nach einer neuen Verbindung musst du sie aber wieder mit den Produkten verknüpfen.

Trenne die Verbindung also nur, wenn der Shop configento.app nicht mehr nutzen oder mit einem anderen Dienst arbeiten soll. Für einen Wechsel des Admin-Benutzers ist das nicht nötig.

Im Service-Portal siehst du unter **Verbindungen** alle verbundenen Shops: Shop-Host, Plugin, Dienst, **Verbunden von** und **Zuletzt verwendet**. Dort kannst du eine Verbindung auch **widerrufen**, etwa wenn du keinen Zugriff mehr auf den Shop hast.

## Fehlersuche

**Die Komponentenliste im Produkt-Tab ist leer**
- Ist dein Admin-Benutzer verbunden? Öffne die Plugin-Konfiguration und prüfe, ob dort **Verbunden als** steht.
- Ist die Komponente veröffentlicht? Entwürfe erscheinen nicht.

**Unter Produktkonfigurator Cloud erscheint eine Fehlermeldung**
- „Gespeicherte Configento-Verbindung ist beschädigt“: Klicke auf **Verbindung trennen** und verbinde neu. Bedenke, dass dabei die Produktverknüpfungen gelöscht werden.
- „Configento-Service-Portal konnte aktuell kein Token ausstellen“: Versuche es nach einigen Minuten mit **Erneut versuchen**.
- „Plugin ist noch nicht mit Configento verbunden“: Klicke auf **Jetzt verbinden**.

**Der Konfigurator erscheint nicht auf der Produktseite**
- Ist im Tab **Produktkonfigurator** des Produkts eine Komponente gewählt und das Produkt gespeichert?
- Leere den Shopware-Cache und lade die Seite im Browser neu.
- Bei der klassischen Anmeldung: Stimmen Kunden-ID, Secure Key und Security Token? Ist die Karte **Shopware 6** unter **Einstellungen → Integrationen** eingeschaltet?

**Datei-Upload oder Diagramm funktioniert im Shop nicht**
Schalte **Dropzone-Plugin laden** bzw. **Chart-Plugin laden** ein und leere den Cache.

**Der Preis im Warenkorb ist zu hoch**
Der Shopware-Produktpreis wird zum Konfigurationspreis addiert. Setze ihn auf 0, wenn der Konfigurator den ganzen Preis liefert.

**Der Shop zeigt einen alten Stand**
Veröffentliche die Komponente in configento.app. Der Shop zeigt nur veröffentlichte Stände.

Hilft das alles nicht, wende dich über den Chat im Service-Portal an den Support. Schreib dazu die Shopware-Version, die Plugin-Version und den Link zur betroffenen Produktseite.

## Shopware 5

Shopware 5 wird von Shopware selbst nicht mehr weiterentwickelt. Auch das configento.app-Plugin für Shopware 5 bekommt keine neuen Funktionen mehr. Für neue Shops verwende Shopware 6.7.

## Nächste Schritte

- [Erste Komponente anlegen](/docs/erste-komponente-anlegen)
- [Magento-Plugin installieren](/docs/magento-plugin-installieren)
- [HTML-Snippet Integration](/docs/html-snippet-integration)

---

# KI-Assistenten per MCP verbinden

Source: https://configento.app/docs/ki-assistenten-mcp
Section: API

Mit dem MCP-Server von configento.app bearbeitest du deine Komponenten direkt aus deinem eigenen KI-Assistenten heraus – etwa aus Claude Desktop, claude.ai oder Claude Code. Du beschreibst in deinen Worten, was du brauchst („Leg eine Gruppe Stoffe mit drei Farben an“, „Erhöhe alle Preise der Gruppe Motoren um 5 %“), und der Assistent liest und ändert die Komponente für dich.

MCP (Model Context Protocol) ist ein offener Standard, über den KI-Assistenten auf Werkzeuge und Daten zugreifen. Jeder Assistent, der MCP-Server mit Anmeldung unterstützt, funktioniert mit configento.app.

Anders als beim [KI-Assistenten im Admin](/docs/ki-agent-konfigurator-aufbauen) rechnet hier das Sprachmodell deines Assistenten. Es werden **keine [KI-Tokens](/docs/ki-tokens)** von configento.app verbraucht.

## Was der Assistent kann

- **Lesen**: Komponenten, Gruppen, Merkmale, Werte, Regeln, Staffelpreise und Preislisten nachsehen, zwei Komponenten oder Versionen vergleichen, die Komponente auf Fehler prüfen und die Nutzerdokumentation lesen.
- **Entwürfe bearbeiten**: Komponenten anlegen; Gruppen, Merkmale, Werte, Regeln, Staffelpreise und Preislisten anlegen, ändern und löschen; Aktions-Buttons einrichten; eigenes CSS und JavaScript der Komponente ändern.
- **Veröffentlichen**: den Entwurf einer Komponente im Shop live schalten.

Nicht möglich sind: Komponenten löschen, Bilder hochladen, Einstellungen, API-Schlüssel und Integrationen ändern sowie KI-Tokens kaufen. Das bleibt dem Admin vorbehalten.

Ein Assistent arbeitet immer in **genau einer Service Order** – der, die du beim Verbinden wählst. Für eine zweite Service Order verbindest du den Assistenten ein zweites Mal.

## Verbinden

Die Server-URL findest du im configento-Admin unter **Einstellungen → Integrationen** in der Karte **KI-Assistenten (MCP)**:

```
https://admin.configento.app/mcp
```

### Claude (claude.ai und Claude Desktop)

1. Öffne in Claude **Einstellungen → Konnektoren** und lege über **Hinzufügen** einen **benutzerdefinierten Konnektor** an. Gib einen Namen ein, z. B. „configento“, und die Server-URL. Bei **Authentifizierung** bleibt **Jetzt anmelden**, beim **OAuth-Client** **Automatisch registrieren** – beides erkennt Claude selbst.
2. Claude öffnet die Anmeldung im **Service-Portal**. Melde dich mit deinem gewohnten Login an.
3. Auf der Bestätigungsseite wählst du die **Service Order** und was der Assistent darf (siehe [Rechte](#rechte)). Mit **Zulassen** ist die Verbindung fertig.

### Claude Code

```bash
claude mcp add --transport http configento https://admin.configento.app/mcp
```

Rufe danach in Claude Code `/mcp` auf und wähle **configento** zum Anmelden. Der Browser öffnet das Service-Portal; weiter wie oben ab Schritt 2.

### Mit API-Schlüssel statt Anmeldung

Für Skripte und Automatisierungen kannst du statt der Anmeldung einen [API-Schlüssel](/docs/api-einstieg#api-schlüssel-erstellen) mitschicken:

```bash
claude mcp add --transport http configento https://admin.configento.app/mcp \
  --header "Authorization: Bearer DEIN_API_SCHLUESSEL"
```

Dann bestimmen die Berechtigungen des Schlüssels, was der Assistent darf: **Nur lesen**, **Lesen & Schreiben**, optional mit **Veröffentlichen**. Das Recht **KI** braucht der MCP-Server nicht.

## Rechte

| Recht | Der Assistent darf |
|---|---|
| **Komponenten lesen** | Immer dabei: alles nachsehen, vergleichen und prüfen |
| **Entwürfe bearbeiten** | Zusätzlich Komponenten anlegen und Entwürfe ändern |
| **Im Shop veröffentlichen** | Zusätzlich Entwürfe live schalten – nur zusammen mit **Entwürfe bearbeiten** |

Was ein Assistent nicht darf, bekommt er gar nicht erst angeboten. Willst du die Rechte ändern, trenne die Verbindung und verbinde neu.

## Entwurf und Veröffentlichung

Alle Änderungen landen im **Entwurf**, genau wie im Editor. Dein Shop zeigt weiter den veröffentlichten Stand, bis jemand veröffentlicht – im Admin oder, mit dem passenden Recht, der Assistent auf deine ausdrückliche Anweisung. Mehr dazu: [Entwurf, Vorschau und Veröffentlichen](/docs/entwurf-vorschau-veroeffentlichen).

Prüfe größere Änderungen in der Vorschau des Editors, bevor du veröffentlichst. Jede Änderung des Assistenten erscheint in den Versionen der Komponente; über eine frühere Version machst du sie rückgängig.

Erzeugt eine Änderung einen strukturellen Fehler – etwa eine Preisliste ohne Konfiguration –, lehnt configento.app sie ab und lässt den Entwurf unverändert. Der Assistent bekommt die Fehlermeldung und kann es neu versuchen.

Hast du die Komponente gleichzeitig im Editor offen, warnt dich der Editor beim Speichern, dass der Entwurf inzwischen geändert wurde.

## Verbindung trennen

- **Mit Anmeldung**: Entferne den Connector in deinem Assistenten. Wirst du aus dem Team der Service Order entfernt, endet der Zugriff spätestens nach einer Minute.
- **Mit API-Schlüssel**: Widerrufe den Schlüssel unter **Einstellungen → API**; das wirkt sofort.

## Kosten

Während der Testphase deiner Service Order ist der MCP-Server inklusive. Danach brauchst du das Add-on **MCP** – buchbar zu jeder Edition, auch zu Basic:

1. Öffne im [Service-Portal](https://service.configento.app/dashboard) **Dienste**.
2. Beim Dienst, mit dem der Assistent arbeiten soll, steht der Bereich **Add-ons**. Klicke bei **MCP** auf **Buchen**.
3. Wähle **25 € pro Monat** oder **250 € pro Jahr** (zzgl. MwSt.) und klicke auf **Jetzt buchen**.

Der erste Zeitraum wird sofort über deine hinterlegte Zahlungsmethode abgerechnet. Buchst du noch in der Testphase, kommt die erste Rechnung erst zum Ende der Testphase. Ohne Zahlungsmethode und Firmenadresse lässt sich das Add-on nicht buchen.

Kündigen kannst du jederzeit über **Add-on kündigen** beim Dienst. MCP bleibt bis zum Ende des bezahlten Zeitraums aktiv. Kündigst du den Dienst selbst, endet das Add-on mit ihm. Im Admin siehst du unter **Einstellungen → Integrationen** in der Karte **KI-Assistenten (MCP)**, ob das Add-on gebucht ist.

### Bei Shopify

Bezahlst du configento.app über den Shopify App Store, gibt es MCP nicht als Add-on im Service-Portal, sondern als eigenen Plan: **configento.app MCP** für **159 US$ pro Monat** – alle Funktionen des Plans für 129 US$ plus MCP, abgerechnet über Shopify. In der 14-tägigen Testphase ist MCP bei beiden Plänen inklusive.

So wechselst du den Plan:

1. Öffne in deinem Shopify-Admin die App **configento.app**.
2. Klicke im Bereich **Einrichtung** in der Karte **KI-Assistenten (MCP)** auf **Plan ändern**.
3. Wähle auf der Planseite von Shopify **configento.app MCP** und bestätige.

Danach zeigt die Karte, dass dein Plan MCP enthält. Wechselst du zurück auf den Plan für 129 US$, endet der Zugriff über MCP.

## Tipps für gute Ergebnisse

- Nenne die Komponente beim Namen: „In der Komponente Markise Classic …“.
- Lass den Assistenten zuerst nachsehen, bevor er ändert: „Zeig mir alle Regeln, die das Merkmal Antrieb ausblenden.“
- Bitte um eine Prüfung am Ende: „Prüf die Komponente und nenn mir Fehler und Warnungen.“
- Viele Assistenten bieten die vorbereiteten Vorlagen von configento.app an – **Create configurator** (Konfigurator anlegen), **Review component** (Komponente prüfen), **Update prices** (Preise ändern) und **Translate component** (Übersetzen). Bei **Update prices** zeigt der Assistent alle betroffenen Preise alt und neu, bevor er speichert.

## Nächste Schritte

- [API — Einstieg & Übersicht](/docs/api-einstieg)
- [Der KI-Assistent im Admin](/docs/ki-agent-konfigurator-aufbauen)
- [Globale Einstellungen](/docs/globale-einstellungen)

---

# API — Einstieg & Übersicht

Source: https://configento.app/docs/api-einstieg
Section: API

Mit der configento.app API pflegst du deine Komponenten aus anderen Systemen heraus: Gruppen, Merkmale, Werte, Regeln, Staffelpreise und Preismatrizen lesen, anlegen und ändern – und Änderungen veröffentlichen. Typische Einsätze sind ein PIM oder ERP, das Werte und Preise überträgt, oder ein Skript, das viele Komponenten auf einmal anpasst.

Dieser Artikel zeigt den Einstieg. Alle Endpunkte mit sämtlichen Feldern findest du in der [API-Referenz](https://admin.configento.app/docs/api).

## Was die API kann – und was nicht

Die API arbeitet mit denselben Daten wie der Editor im Admin. Was du dort anlegst, kannst du auch über die API anlegen, und umgekehrt.

Nicht über die API möglich:

- **API-Schlüssel verwalten**, **KI-Tokens kaufen** und **Zugangsdaten der Shop-Integrationen** lesen oder erneuern – das bleibt dem Admin vorbehalten.
- **Webhooks**: configento.app benachrichtigt dein System nicht über Änderungen. Wenn du Änderungen erkennen willst, frag die Versionen einer Komponente ab (siehe [Versionen](#versionen-und-veröffentlichen)).
- **Den veröffentlichten Stand lesen**: Die API liefert immer den **Entwurf** – also das, was gerade im Editor steht. Siehe [Entwurf und Veröffentlichung](#entwurf-und-veröffentlichung).

Die Referenz listet auch Endpunkte unter `/storefront/…`, `/plugin/…` und `/webhooks/…`. Diese nutzen die Shop-Plugins und das Service-Portal mit eigenen Zugangsdaten; mit einem API-Schlüssel kannst du sie nicht aufrufen.

## API-Schlüssel erstellen

Jede Anfrage braucht einen **API-Schlüssel**. Du erstellst ihn im Admin unter **Einstellungen → API**:

1. **Name des Schlüssels** eingeben, z. B. „PIM“ oder „ERP-Sync“.
2. **Berechtigung** wählen – **Nur lesen** oder **Lesen & Schreiben**.
3. Bei **Lesen & Schreiben** optional **Veröffentlichen** und/oder **KI** anhaken.
4. Optional ein Datum unter **Gültig bis (optional)** setzen.
5. **Erstellen** klicken. Der Schlüssel wird **nur einmal** angezeigt – kopiere ihn sofort und bewahre ihn sicher auf.

Wichtig:

- Ein Schlüssel gehört zu der **Service Order**, in der du ihn erstellt hast, und arbeitet nur mit deren Komponenten. Die Liste **Aktive Schlüssel** zeigt nur die Schlüssel dieser Service Order.
- Ein Schlüssel handelt in deinem Namen. Verlierst du den Zugriff auf die Service Order – etwa weil du aus dem Team entfernt wirst –, antworten deine Schlüssel mit `403`.
- Mit Ablaufdatum funktioniert ein Schlüssel bis zum Ende dieses Tages (deutsche Zeit) und antwortet danach mit `401`. Über **Ändern** verschiebst oder entfernst du das Datum – auch ein abgelaufener Schlüssel wird so wieder gültig.
- **Widerrufen** sperrt einen Schlüssel sofort.
- Lege am besten einen Schlüssel pro Integration an. Dann kannst du einen einzelnen widerrufen, ohne die anderen zu stören.

Mehr zum Reiter **API**: [Globale Einstellungen](/docs/globale-einstellungen#api).

## Berechtigungen

| Berechtigung | Erlaubt |
|---|---|
| **Nur lesen** | Nur `GET`-Anfragen. Alles andere antwortet mit `403` „This API key is read-only.“ |
| **Lesen & Schreiben** | Zusätzlich Entwürfe anlegen, ändern und löschen: Komponenten, Gruppen, Merkmale, Werte, Regeln, Staffelpreise, Preismatrizen, Tags |
| + **Veröffentlichen** | Zusätzlich Komponenten veröffentlichen (`POST /components/{id}/publish`) und löschen (`DELETE /components/{id}`) – beides wirkt sofort im Shop |
| + **KI** | Zusätzlich den KI-Assistenten über die API nutzen (`/ai/…`) – das verbraucht [KI-Tokens](/docs/ki-tokens) |

**Veröffentlichen** und **KI** gibt es nur zusammen mit **Lesen & Schreiben**; beim Erstellen sind beide aus. So kann zum Beispiel ein PIM Werte und Preise im Entwurf pflegen, während ein Mensch im Admin prüft und veröffentlicht. Änderst du die Berechtigungen eines Schlüssels, gelten sie ab der nächsten Anfrage.

## Basis-URL und Header

```
https://admin.configento.app/api/v1
```

Jede Anfrage sendet den Schlüssel als Bearer-Token:

```http
Authorization: Bearer DEIN_API_SCHLUESSEL
Accept: application/json
Content-Type: application/json
```

## Der erste Aufruf

Komponenten auflisten:

```bash
curl https://admin.configento.app/api/v1/components \
  -H "Authorization: Bearer DEIN_API_SCHLUESSEL" \
  -H "Accept: application/json"
```

Die Antwort enthält pro Komponente nur die Eckdaten:

```json
{
  "data": [
    { "id": 123, "title": { "de_DE": "Carport" }, "edition": null, "requires_bundle": null, "tags": [] },
    { "id": -4,  "title": { "de_DE": "Terrassendach (neu)" }, "edition": null, "requires_bundle": null, "tags": [] }
  ],
  "sync_running": false
}
```

Eine Komponente vollständig lesen – mit Gruppen, Merkmalen, Werten und Regeln:

```bash
curl https://admin.configento.app/api/v1/components/123 \
  -H "Authorization: Bearer DEIN_API_SCHLUESSEL" \
  -H "Accept: application/json"
```

## Das Datenmodell

```
Komponente
├── groups[]                 Gruppen
│   └── characteristics[]    Merkmale
│       └── values[]         Werte
├── rules[]                  Regeln
└── rulesgroups[]            Regelgruppen
```

- **Interner Name:** Jedes Merkmal hat in `alt_title` seinen internen Namen (nur Buchstaben, Ziffern und `_`). Über ihn sprichst du das Merkmal in Formeln an.
- **Texte pro Sprache:** Bezeichnungen wie `title` sind Objekte mit einem Eintrag pro Sprache, z. B. `{ "de_DE": "Farbe", "en_US": "Colour" }`. Die Schlüssel sind die Sprachcodes deiner Komponente.
- **IDs:** Gruppen- und Merkmal-IDs gelten nur innerhalb einer Komponente. Deshalb stehen alle Pfade unter `/components/{id}/…`.

## Entwurf und Veröffentlichung

- **Alles landet im Entwurf.** Jede schreibende Anfrage ändert den Entwurf – genau wie Speichern im Editor. Dein Shop sieht davon nichts, bis die Komponente veröffentlicht wird.
- **Lesen liefert den Entwurf.** `GET /components/{id}` zeigt den aktuellen Entwurf, nicht den Stand, der im Shop läuft.
- **Jede Änderung ist eine Version.** Jede schreibende Anfrage legt eine neue Version an. Für viele Änderungen auf einmal nimm deshalb die Sammel-Endpunkte (z. B. alle Werte eines Merkmals in einer Anfrage) statt vieler Einzelaufrufe.
- **Negative IDs:** Eine Komponente, die noch nie veröffentlicht wurde, hat eine **negative ID** (z. B. `-4`). Beim ersten Veröffentlichen bekommt sie eine **positive ID**. Ab dann gilt nur noch die neue ID – übernimm sie aus der Statusabfrage (`final_component_id`).

## Die wichtigsten Endpunkte

### Komponenten

```http
GET    /components                     # Alle Komponenten (Eckdaten)
GET    /components/{id}                # Komponente mit Gruppen, Merkmalen, Werten, Regeln
POST   /components                     # Neue leere Komponente anlegen
PUT    /components/{id}                # Eckdaten der Komponente ändern
POST   /components/{id}/duplicate      # Komponente kopieren (als neuer Entwurf)
DELETE /components/{id}                # Komponente löschen – auch im Shop! Braucht „Veröffentlichen“
```

`POST /components` erwartet `title` als Text und optional `default_locale` (Standard `de_DE`). Die Antwort enthält die neue, negative ID.

### Gruppen und Merkmale

```http
POST   /components/{id}/groups                              # Gruppe anlegen
PUT    /components/{id}/groups/{gid}                        # Gruppe ändern
DELETE /components/{id}/groups/{gid}                        # Gruppe löschen
POST   /components/{id}/groups/{gid}/characteristics        # Merkmal anlegen
PUT    /components/{id}/groups/{gid}/characteristics/{cid}  # Merkmal ändern
DELETE /components/{id}/groups/{gid}/characteristics/{cid}  # Merkmal löschen
```

### Werte

```http
POST   /components/{id}/characteristics/{cid}/values         # Einen Wert anlegen
PUT    /components/{id}/characteristics/{cid}/values         # Alle Werte auf einmal ersetzen
PUT    /components/{id}/characteristics/{cid}/values/{vid}   # Einen Wert ändern
DELETE /components/{id}/characteristics/{cid}/values/{vid}   # Einen Wert löschen
```

### Preise

```http
GET    /components/{id}/characteristics/{cid}/pricelist        # Staffelpreise lesen
PUT    /components/{id}/characteristics/{cid}/pricelist        # Staffelpreise ersetzen
POST   /components/{id}/characteristics/{cid}/matrix/upload    # Tabelle an eine Preismatrix anhängen
DELETE /components/{id}/characteristics/{cid}/matrix/values    # Alle Tabellen einer Preismatrix löschen
```

### Regeln

```http
GET    /components/{id}/rules                # Regeln lesen
POST   /components/{id}/rules                # Regel anlegen
PUT    /components/{id}/rules/{rid}          # Regel ändern
DELETE /components/{id}/rules/{rid}          # Regel löschen
GET    /components/{id}/rulesgroups          # Regelgruppen lesen
```

Den Regeltyp bestimmt `validation_type`: `blacklist`, `predefine_values` (Wertvorbelegung) oder `error` (Fehler). Mehr zu den Regeltypen: [Regelwerk aufbauen](/docs/regelwerk-aufbauen).

### Versionen und Veröffentlichen

```http
GET    /components/{id}/versions                     # Versionen, neueste zuerst
POST   /components/{id}/versions/{version}/restore   # Version als Entwurf wiederherstellen
GET    /components/{id}/validate                     # Prüfen, ob der Entwurf veröffentlicht werden kann
POST   /components/{id}/publish                      # Entwurf veröffentlichen – braucht „Veröffentlichen“
GET    /components/{id}/publish/status               # Fortschritt der Veröffentlichung
```

## Beispiel: Merkmal mit Werten anlegen

Merkmal „Farbe“ in Gruppe `5` der Komponente `123` anlegen:

```http
POST /components/123/groups/5/characteristics
Authorization: Bearer DEIN_API_SCHLUESSEL
Content-Type: application/json

{
  "alt_title": "farbe",
  "title": { "de_DE": "Farbe", "en_US": "Colour" },
  "type": "select",
  "is_required": "1"
}
```

Die Antwort ist das neue Merkmal mit seiner `id` (hier `42`). Neue Werte legst du dann einzeln an – jeder bekommt dabei seine ID:

```http
POST /components/123/characteristics/42/values
Authorization: Bearer DEIN_API_SCHLUESSEL
Content-Type: application/json

{ "title": { "de_DE": "Anthrazit" }, "value": "anthrazit", "price": 15.00, "sku": "FARBE-ANT" }
```

`value` ist der Wert, den Formeln, Regeln und der Warenkorb sehen; `price` ist der Aufpreis.

Bestehende Werte kannst du in **einer** Anfrage aktualisieren, z. B. neue Preise aus dem PIM. Schick dafür die vollständige Liste **mit der `id` jedes Werts** mit:

```http
PUT /components/123/characteristics/42/values
Authorization: Bearer DEIN_API_SCHLUESSEL
Content-Type: application/json

{
  "values": [
    { "id": 301, "title": { "de_DE": "Weiß" },      "value": "weiss",     "price": 0 },
    { "id": 302, "title": { "de_DE": "Anthrazit" }, "value": "anthrazit", "price": 19.00 }
  ]
}
```

Achtung: Diese Anfrage **ersetzt alle** Werte des Merkmals. Werte, die in der Liste fehlen, werden gelöscht. Lass die `id` nicht weg – Werte ohne ID lassen sich in Regeln und Vorbelegungen nicht ansprechen. Hol dir die IDs vorher mit `GET /components/123`.

## Beispiel: Preismatrix hochladen

```http
POST /components/123/characteristics/77/matrix/upload
Authorization: Bearer DEIN_API_SCHLUESSEL
Content-Type: application/json

{
  "name": "Preise 2026",
  "csv": ";500;1000;1500\n500;89;119;149\n1000;129;169;209",
  "delimiter": ";"
}
```

Die erste Zeile enthält die Werte der X-Achse, die erste Spalte die Werte der Y-Achse. Das Merkmal muss vom Typ Preismatrix (`matrixvalue`) sein. Alternativ lädst du eine CSV-Datei bis 2 MB als `multipart/form-data` im Feld `file` hoch.

Der Upload **hängt** eine weitere Tabelle an – vorhandene Tabellen bleiben. Willst du eine Tabelle ersetzen, lösche vorher alle mit `DELETE …/matrix/values` und lade dann neu hoch. Mehr dazu: [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv).

## Beispiel: Veröffentlichen

```http
POST /components/123/publish
Authorization: Bearer DEIN_API_SCHLUESSEL
```

Vorher prüft der Server den Entwurf. Hat er Fehler, kommt sofort `422` mit den Fehlern in `message` zurück. Sonst läuft die Veröffentlichung im Hintergrund, und die Antwort `202 Accepted` enthält in `job_status_url` die Adresse für die Statusabfrage:

```bash
curl https://admin.configento.app/api/v1/components/123/publish/status \
  -H "Authorization: Bearer DEIN_API_SCHLUESSEL" \
  -H "Accept: application/json"
```

Das Feld `state` durchläuft `queued`, `uploading` und `pushing` und endet mit `done` oder `failed`. Bei `done` steht in `final_component_id` die ID der veröffentlichten Komponente – bei einer ersten Veröffentlichung ist das die neue, positive ID.

## Fehlercodes

Fehler kommen als JSON mit einer Meldung in `message`, z. B. `{"message": "Unauthenticated."}`. Bei ungültigen Daten nennt `errors` zusätzlich die betroffenen Felder.

| Status | Bedeutung |
|---|---|
| `401` | Kein, ungültiger, widerrufener oder abgelaufener Schlüssel |
| `403` | Der Schlüssel darf das nicht – z. B. „This API key is read-only.“, „This API key may not publish or delete components.“ oder ein Endpunkt, der nur im Admin geht. Auch: Du hast keinen Zugriff mehr auf die Service Order des Schlüssels |
| `404` | Komponente, Gruppe, Merkmal oder Wert gibt es nicht – oder er gehört zu einer anderen Service Order |
| `409` | Für diese Komponente läuft bereits eine Veröffentlichung |
| `422` | Ungültige Daten, oder der Entwurf hat Fehler, die das Veröffentlichen verhindern |
| `429` | Zu viele Anfragen an den KI-Assistenten (höchstens 20 pro Minute) |

## Die API-Referenz

Alle Endpunkte mit Feldern und Beispielen findest du unter [admin.configento.app/docs/api](https://admin.configento.app/docs/api) – im Admin auch über **Einstellungen → API → API-Dokumentation**. Dort kannst du Anfragen direkt ausprobieren: Endpunkt öffnen, rechts **Send API Request** wählen und im Bereich **Auth** deinen Schlüssel einfügen.

Die Referenz ist auf Englisch und verwendet die englischen Begriffe: *component* (Komponente), *group* (Gruppe), *characteristic* (Merkmal), *value* (Wert), *rule* (Regel).

## Nächste Schritte

- [Globale Einstellungen – API](/docs/globale-einstellungen#api)
- [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen)
- [Preismatrizen aus Excel/CSV](/docs/preismatrizen-excel-csv)
- [Regelwerk aufbauen](/docs/regelwerk-aufbauen)

---

# Zahlungsarten & Rechnungen

Source: https://configento.app/docs/zahlungsarten-verwalten
Section: Konto & Abrechnung

Damit dein Dienst nach dem Test weiterläuft und Rechnungen bezahlt werden, brauchst du im Service-Portal zwei Dinge: eine **Rechnungsanschrift** und mindestens eine aktive **Zahlungsart**. Beides pflegst du im Menü **Abrechnung**. Dieser Artikel zeigt die Reihenfolge, alle drei Zahlungsarten, deine Rechnungen und was passiert, wenn eine Zahlung fehlschlägt.

Zahlungsarten und Rechnungsanschrift dürfen die Rollen **Inhaber**, **Admin** und **Buchhaltung** bearbeiten. Rechnungen ansehen dürfen zusätzlich **Nur-Lesen**-Mitglieder.

## Zuerst die Rechnungsanschrift

Ohne Rechnungsanschrift lassen sich keine Zahlungsarten anlegen – die Seite **Zahlungsarten** zeigt dann nur „Bitte hinterlege zunächst deine Rechnungsadresse bevor du deine Zahlungsmethoden hier hinterlegst.“ mit dem Link **Rechnungsadresse eingeben**.

1. Öffne **Abrechnung → Rechnungen**.
2. Fülle oben die **Rechnungsanschrift** aus:

| Feld | Pflicht | Hinweis |
|---|---|---|
| **Firma** | ja | |
| **Strasse**, **Hausnummer** | ja | |
| **Adresszusatz** | nein | |
| **Postleitzahl**, **Stadt** | ja | |
| **Land** | ja | |
| **E-Mail** | nein | Neue Rechnungen werden an diese E-Mail-Adresse gesendet. Bleibt sie leer, gehen sie an die E-Mail-Adresse deines Benutzers. |
| **Umsatzsteuer-ID** | nein | Wird beim Speichern geprüft |

3. Klicke auf **Adresse speichern**.

## Zahlungsart hinterlegen

Unter **Abrechnung → Zahlungsarten** stehen oben drei Kacheln – **Kreditkarte**, **SEPA**, **PayPal**. Ein Klick springt zum jeweiligen Abschnitt. Ein grüner Haken auf der Kachel zeigt, dass diese Zahlungsart aktiv ist.

Abgewickelt werden alle Zahlungen über unseren Zahlungsdienstleister Stripe.

### Kreditkarte

1. Gib im Abschnitt **Kreditkarte** die Kartendaten ein.
2. Klicke auf **Kreditkarte speichern**.

Danach siehst du **Gespeicherte Kreditkarte** mit Kartenmarke, „Endet mit …“ und „gültig bis …“. Mit **Kreditkarte löschen** entfernst du sie wieder.

Läuft deine Karte bald ab oder ist sie abgelaufen, bekommt der Inhaber eine E-Mail.

### SEPA-Lastschrift

Im Abschnitt **SEPA Lastschrift von deinem Bankkonto**:

1. Lies den Mandatstext. Mit dem Mandat erlaubst du justSelling und Stripe, Beträge von deinem Konto einzuziehen; eine Lastschrift kannst du innerhalb von 8 Wochen bei deiner Bank zurückfordern. Über künftige Abbuchungen wirst du spätestens 2 Tage vorher informiert.
2. Fülle **Kontoinhaber**, **Name der Bank** und **IBAN** aus. Weicht die Adresse des Kontoinhabers von deiner Firmenadresse ab, trage sie unter **Adresse des Kontoinhabers** ein.
3. Klicke auf **Mandat erteilen**.

Danach steht dort **Erteiltes SEPA Mandat für Konto …**. Mit **Mandat widerrufen** beendest du es.

### PayPal

1. Klicke im Abschnitt **PayPal** auf **PayPal verbinden**.
2. Melde dich bei PayPal an und bestätige die Zahlungsvereinbarung.

Danach siehst du das **Verbundene PayPal-Konto**. Mit **PayPal widerrufen** beendest du die Vereinbarung.

### Zahlungsarten ein- und ausschalten

Vor jeder Überschrift steht ein Haken. Damit schaltest du eine gespeicherte Zahlungsart vorübergehend aus, ohne sie zu löschen – sie wird dann nicht mehr belastet, bis du sie wieder einschaltest.

### Welche Zahlungsart wird belastet?

Hast du mehrere Zahlungsarten aktiv, belastet configento.app in dieser Reihenfolge die erste aktive:

1. **Kreditkarte**
2. **SEPA-Lastschrift**
3. **PayPal**

Willst du zum Beispiel per SEPA zahlen, obwohl auch eine Karte gespeichert ist, schalte die Karte aus.

## Rechnungen

Unter **Abrechnung → Rechnungen** stehen unter **Rechnungsübersicht** alle Rechnungen, nach Jahren gruppiert, mit Datum, Rechnungsnummer und Betrag. Ein Klick auf die Nummer öffnet die Rechnung als PDF.

Jede Rechnung trägt einen Status:

| Status | Bedeutung |
|---|---|
| **neu** | Erstellt, noch nicht abgebucht |
| **ausstehend** | Abbuchung läuft oder wird erneut versucht |
| **bezahlt** | Erledigt |
| **Fehler** | Zahlung ist endgültig fehlgeschlagen |

Jede neue Rechnung wird zusätzlich per E-Mail verschickt – an die E-Mail-Adresse aus der Rechnungsanschrift oder, wenn dort keine steht, an deinen Benutzer. Im Portal erscheint der Hinweis „Die neue Rechnung … wurde angelegt.“

## Wenn eine Zahlung fehlschlägt

1. Schlägt eine Abbuchung fehl, wird sie **bis zu dreimal** versucht. Die Rechnung steht so lange auf **ausstehend**.
2. Klappt es auch beim dritten Mal nicht, steht die Rechnung auf **Fehler**, und die verwendete Zahlungsart wird **deaktiviert**. Oben im Portal erscheint: „Deine Bezahlmethode wurde deaktiviert, weil eine Bezahlung wiederholt nicht durchgeführt werden konnte. Bitte hinterlege eine valide Bezahlmethode um die Sperrung deiner Dienste zu vermeiden.“
3. **Fünf Tage** danach wird der Dienst **temporär deaktiviert**. Dein Konfigurator ist dann im Shop nicht mehr verfügbar.

Eine eigene E-Mail zur fehlgeschlagenen Zahlung gibt es nicht – achte auf die Hinweise oben im Portal.

**So aktivierst du den Dienst wieder:** Hinterlege eine funktionierende Zahlungsart oder schalte eine andere ein. Offene Rechnungen werden dann sofort erneut abgebucht. Sobald die Zahlung durch ist, ist der Dienst wieder aktiv.

Auch ein Dienst, bei dem bei Fälligkeit **Rechnungsanschrift oder Zahlungsart fehlen**, wird temporär deaktiviert – das betrifft vor allem das Ende des Testzugangs.

## Fehlersuche

1. **Ich kann keine Zahlungsart anlegen** – zuerst die Rechnungsanschrift unter **Abrechnung → Rechnungen** speichern.
2. **Die Postleitzahl wird nicht angenommen** – das Feld erlaubt höchstens 5 Zeichen. Bei längeren ausländischen Postleitzahlen wende dich an den Support.
3. **Die Umsatzsteuer-ID wird abgelehnt** – sie wird beim Speichern geprüft. Achte auf das Länderkürzel am Anfang (z. B. `DE…`).
4. **Es wird die falsche Zahlungsart belastet** – siehe [Reihenfolge](#welche-zahlungsart-wird-belastet). Schalte die Zahlungsart aus, die nicht belastet werden soll.
5. **Mein Dienst ist „temporär deaktiviert“** – siehe [Wenn eine Zahlung fehlschlägt](#wenn-eine-zahlung-fehlschlägt).
6. **Ich sehe „Zahlungsarten“ oder „Rechnungen“ nicht** – Zahlungsarten sehen nur Inhaber, Admin und Buchhaltung; Rechnungen zusätzlich Nur-Lesen. Bearbeiter sehen unter **Abrechnung** nur die KI-Tokens. Frag den Inhaber, wenn du eine andere Rolle brauchst.

## Nächste Schritte

- [Service-Portal — Überblick](/docs/service-portal-uebersicht)
- [KI-Tokens](/docs/ki-tokens)
- [Team verwalten](/docs/team-verwalten)

---

# KI-Tokens

Source: https://configento.app/docs/ki-tokens
Section: Konto & Abrechnung

Der **KI-Assistent** im Admin – der Chat am unteren Rand, der für dich Merkmale, Regeln und Preistabellen anlegt – rechnet in **KI-Tokens** ab. Jeder Tarif enthält ein Kontingent, und wenn es nicht reicht, kaufst du Tokens dazu. Dieser Artikel erklärt, wie Tokens verbraucht werden, woher sie kommen und wie du sie im Blick behältst.

## Was ein Token ist

Ein Token ist ein kleines Textstück, etwa ein Wortteil. Bei jeder Anfrage an den Assistenten zählt das Sprachmodell, wie viele Tokens es gelesen (deine Nachricht, der Stand deiner Komponente, angehängte Dateien) und wie viele es geschrieben hat. Daraus ergibt sich der Verbrauch:

**Verbrauch = (gelesene Tokens + 5 × geschriebene Tokens) × Faktor des KI-Modells**

- Geschriebene Tokens zählen **fünffach**, weil sie beim Modellanbieter entsprechend teurer sind.
- Der **Faktor** hängt vom gewählten KI-Modell ab (siehe unten).

Lange Chats, große Komponenten und angehängte PDFs oder Bilder verbrauchen deshalb mehr als eine kurze Frage.

## Das KI-Modell wählen

Im Admin unter **Einstellungen → KI** wählst du bei **KI-Modell**, wie leistungsfähig der Assistent arbeitet:

| Stufe | Hinweis im Admin |
|---|---|
| **Sparsam** | Verbraucht das 0,5-Fache des Kontingents |
| **Standard** | Verbraucht das Kontingent 1:1 |
| **Maximal** | Verbraucht das 2-Fache des Kontingents |

„Leistungsfähigere Modelle antworten besser und verbrauchen mehr von deinem monatlichen KI-Kontingent.“ Für das Anlegen einfacher Merkmale reicht oft **Sparsam**; für umfangreiche Komponenten oder knifflige Regeln lohnt sich **Standard** oder **Maximal**.

Dort schaltest du unter **KI-Assistent** den Assistenten auch ganz aus. Dann ist das Chat-Fenster ausgeblendet, und es werden keine Daten an den KI-Dienstleister (Anthropic) übertragen.

## Woher die Tokens kommen

Dein Bestand setzt sich aus bis zu drei Töpfen zusammen. Verbraucht wird in dieser Reihenfolge:

1. **Test-Tokens** – ein eigenes Kontingent für den Testzugang, sofern dein Testzugang eines enthält. Es verfällt mit dem Ende des Tests und beim Wechsel in den kostenpflichtigen Vertrag.
2. **Monatliches Kontingent** – im Tarif enthalten. Es wird mit jeder bezahlten Rechnung neu aufgefüllt; **nicht verbrauchte Tokens verfallen** dann.
3. **Aufgebuchte Tokens** – zusätzlich gekaufte Tokens. Sie **verfallen nie** und werden erst angegriffen, wenn das monatliche Kontingent aufgebraucht ist.

### Kontingent je Tarif

| Tarif | Monatliche Zahlung | Jährliche Zahlung |
|---|---|---|
| **Basic** | 1,4 Mio. Tokens pro Monat | 14 Mio. Tokens pro Jahr |
| **Professional** | 2,2 Mio. Tokens pro Monat | 22 Mio. Tokens pro Jahr |
| **Ultimate** | 2,8 Mio. Tokens pro Monat | 28 Mio. Tokens pro Jahr |

Bei jährlicher Zahlung bekommst du das **Zehnfache** des Monatskontingents für das ganze Jahr – also zwei Monate geschenkt. Das Jahreskontingent wird einmal mit der Jahresrechnung zugeteilt und verfällt am Ende des Jahres.

### Wenn alles verbraucht ist

Der Assistent bricht eine laufende Arbeit nicht ab. Reicht der Bestand nicht, wird der Rest von den aufgebuchten Tokens abgezogen, die dann **ins Minus** gehen (rote Zahl). Der nächste Kauf gleicht das Minus zuerst aus.

## Den Bestand im Portal sehen

Im Service-Portal unter **Abrechnung → KI-Tokens** steht dein **KI-Token-Bestand**:

| Anzeige | Bedeutung |
|---|---|
| **Monatliches Kontingent** | Was vom Kontingent übrig ist, „von“ der zugeteilten Menge, „bis“ zum Ende des Zeitraums |
| **Aufgebuchte Tokens** | Gekaufte Tokens – „Bleibt erhalten, läuft nicht ab“ |
| **Gesamt verfügbar** | Summe aller Töpfe |
| **Verbraucht in dieser Periode** | Verbrauch des monatlichen Kontingents in Tokens und Prozent, als Balken (grün, ab 70 % orange, ab 90 % rot) |

Unter **Letzte Aktivitäten** stehen die letzten 20 Buchungen mit Datum und Menge: **Monatliche Zuteilung**, **Verfall am Periodenende**, **Aufgebuchte Tokens** (Kauf), **Verbrauch** und **Korrektur**.

Die Seite **KI-Tokens** sehen die Rollen Inhaber, Admin, Bearbeiter und Buchhaltung, sofern KI-Tokens für dein Konto freigeschaltet sind.

### Warnung bei 90 %

Hast du mehr als **90 %** des monatlichen Kontingents verbraucht,

- erscheint auf der Seite der Hinweis „Du hast über 90 % deines monatlichen Kontingents verbraucht. Buche unten weitere Tokens dazu.“,
- geht eine E-Mail „Deine KI-Tokens werden knapp“ an die Rechnungs-E-Mail-Adresse,
- zeigt der Admin im KI-Assistenten einen Hinweis mit **Tokens kaufen**.

Die Warnung kommt einmal pro Zeitraum und wird mit der nächsten Zuteilung zurückgesetzt.

## Tokens kaufen

### Im Service-Portal

1. Öffne **Abrechnung → KI-Tokens**.
2. Wähle unter **Zusätzliche Tokens kaufen** ein Paket:

| Paket | Preis |
|---|---|
| **7 Mio Tokens** | 25,00 € zzgl. MwSt. |
| **14 Mio Tokens** | 50,00 € zzgl. MwSt. |
| **28 Mio Tokens** | 100,00 € zzgl. MwSt. |

3. Klicke auf **Jetzt kaufen**.

Der Betrag wird sofort über deine aktive [Zahlungsart](/docs/zahlungsarten-verwalten) abgebucht, und die Tokens stehen direkt unter **Aufgebuchte Tokens**. Die Rechnung kommt per E-Mail. Ohne Rechnungsanschrift ist der Kauf gesperrt („Bitte hinterlege zunächst eine Rechnungsadresse, bevor du Tokens kaufst.“).

### Im Admin

Am rechten Ende der Leiste des KI-Assistenten zeigt der Admin deinen Bestand (verbleibendes Monatskontingent / Monatskontingent + aufgebuchte Tokens). Ein Klick darauf öffnet **KI-Tokens kaufen** mit denselben Paketen. Nach **Kauf bestätigen** wird über deine im Portal hinterlegte Zahlungsart abgebucht. Fehlt sie, verweist der Dialog mit **Service-Portal öffnen** dorthin.

Kaufen dürfen die Rollen Inhaber, Admin, Bearbeiter und Buchhaltung.

## Wie viele Tokens brauche ich?

Das hängt davon ab, wie viel du den Assistenten arbeiten lässt. Ein guter Weg: Nutze ihn eine Woche normal und sieh dann unter **Letzte Aktivitäten** nach, wie viel einzelne Anfragen gekostet haben. Sparen kannst du, indem du

- für Routinearbeit die Stufe **Sparsam** wählst,
- für ein neues Thema einen **neuen Chat** beginnst, statt einen langen Chat weiterzuführen,
- nur die Dateien anhängst, die der Assistent wirklich braucht.

## Fehlersuche

1. **Ich sehe „KI-Tokens“ im Portal nicht** – KI-Tokens sind für dein Konto noch nicht freigeschaltet, oder deine Rolle ist Nur-Lesen.
2. **Der Kauf ist gesperrt** – hinterlege eine Rechnungsanschrift unter **Abrechnung → Rechnungen**.
3. **„Zahlung fehlgeschlagen“** – prüfe deine Zahlungsart unter **Abrechnung → Zahlungsarten**.
4. **Das Monatskontingent ist plötzlich wieder voll, die Reste sind weg** – mit jeder bezahlten Rechnung beginnt ein neuer Zeitraum; nicht verbrauchte Tokens verfallen. Gekaufte Tokens bleiben.
5. **Der Bestand ist rot** – du hast mehr verbraucht als vorhanden. Der nächste Kauf gleicht das aus.

## Nächste Schritte

- [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen)
- [Globale Einstellungen](/docs/globale-einstellungen)
- [Zahlungsarten & Rechnungen](/docs/zahlungsarten-verwalten)

---

# Team verwalten

Source: https://configento.app/docs/team-verwalten
Section: Konto & Abrechnung

Arbeiten mehrere Personen an deinem configento.app-Konto, gibst du jeder einen eigenen Zugang mit passender **Rolle** – statt ein gemeinsames Passwort zu teilen. Die Rolle legt fest, wer Konfiguratoren bearbeitet, wer Zahlungsdaten sieht und wer das Team verwaltet. Dieser Artikel zeigt alle Rollen, das Einladen und was du später ändern kannst.

Das Team verwalten dürfen **Inhaber** und **Admin**. Nur sie sehen den Menüpunkt **Team**.

## Rollen und Rechte

| Recht | Inhaber | Admin | Bearbeiter | Buchhaltung | Nur-Lesen |
|---|:-:|:-:|:-:|:-:|:-:|
| Dienste ansehen | ✓ | ✓ | ✓ | ✓ | ✓ |
| Admin öffnen (**Verwalten**), Dienst umstellen, kündigen, Zahlweise ändern | ✓ | ✓ | ✓ | – | – |
| Verbindungen ansehen | ✓ | ✓ | ✓ | – | ✓ |
| Verbindungen widerrufen, Shop-Plugins verbinden | ✓ | ✓ | ✓ | – | – |
| Rechnungen ansehen | ✓ | ✓ | – | ✓ | ✓ |
| Rechnungsanschrift bearbeiten | ✓ | ✓ | – | ✓ | – |
| Zahlungsarten ansehen und bearbeiten | ✓ | ✓ | – | ✓ | – |
| KI-Tokens ansehen und kaufen | ✓ | ✓ | ✓ | ✓ | – |
| Team verwalten | ✓ | ✓ | – | – | – |

**Inhaber und Admin** haben dieselben Rechte. Der Unterschied: Es gibt genau **einen Inhaber**, und an ihn gehen die E-Mails zum Konto – etwa die Erinnerung vor Ende des Testzugangs, Hinweise zu ablaufenden Kreditkarten und die Bestätigung einer Kündigung. Rechnungen gehen an die Rechnungs-E-Mail-Adresse, siehe [Zahlungsarten & Rechnungen](/docs/zahlungsarten-verwalten#zuerst-die-rechnungsanschrift).

Typische Zuordnung:

- **Bearbeiter** – wer Konfiguratoren baut und Shops anbindet, aber nichts mit Zahlungen zu tun hat.
- **Buchhaltung** – wer Rechnungen braucht und Zahlungsdaten pflegt, aber keine Konfiguratoren bearbeitet.
- **Nur-Lesen** – wer einen Überblick über Dienste, Verbindungen und Rechnungen braucht.

## Die Seite „Team“

Unter **Team** stehen drei Bereiche:

- **Mitglieder** – alle Mitglieder des gewählten Kunden mit **Name**, **E-Mail** und **Rolle**.
- **Offene Einladungen** – verschickte, noch nicht angenommene Einladungen mit **E-Mail**, **Rolle**, **Eingeladen von** und **Läuft ab**.
- **Mitglied einladen** – das Formular für neue Einladungen.

Bist du für mehrere Kunden tätig, gilt die Seite immer für den Kunden, der oben rechts gewählt ist.

## Mitglied einladen

1. Gib unter **Mitglied einladen** die **E-Mail**-Adresse ein.
2. Wähle die **Rolle** (vorausgewählt ist **Bearbeiter**).
3. Klicke auf **Einladen**.

Die Person bekommt eine E-Mail „Einladung zu … auf configento.app“. Die Einladung ist **5 Tage** gültig und erscheint so lange unter **Offene Einladungen**.

Dort kannst du sie

- mit **Erneut senden** noch einmal verschicken – die 5 Tage beginnen dann neu,
- mit **Abbrechen** zurückziehen (Rückfrage **Einladung löschen?**).

Für eine E-Mail-Adresse, die schon Mitglied ist oder eine offene Einladung hat, lässt sich keine zweite Einladung anlegen.

## Einladung annehmen

Was die eingeladene Person nach dem Klick auf den Link sieht, hängt davon ab, ob sie schon ein Konto hat:

- **Noch kein Konto:** Sie füllt das Formular **Konto erstellen und beitreten** aus (Name, Anrede, Rolle im Unternehmen, Passwort) und ist danach direkt angemeldet und Mitglied.
- **Schon ein Konto:** Sie meldet sich an und wählt **Einladung annehmen** oder **Ablehnen**.

Die Einladung gilt nur für die E-Mail-Adresse, an die sie geschickt wurde. Ist die Person mit einem anderen Konto angemeldet, sieht sie **Falsches Konto** und muss sich ab- und mit der richtigen Adresse anmelden. Ist die Einladung abgelaufen, bittet die Seite darum, sie erneut senden zu lassen.

## Rolle ändern

Die Rolle eines Mitglieds änderst du direkt in der Mitgliederliste über die Auswahl in der Spalte **Rolle**. Die Änderung gilt sofort; das Mitglied bekommt eine E-Mail darüber.

## Inhaber übertragen

Wählst du bei einem Mitglied die Rolle **Inhaber**, fragt das Portal „Inhaber-Rolle an … übertragen?“. Nach **Übertragen**

- ist dieses Mitglied der neue Inhaber,
- wird der bisherige Inhaber zum **Admin**.

Beide werden per E-Mail informiert. Der einzige Inhaber kann seine Rolle nicht einfach abgeben – er muss sie zuerst an jemand anderen übertragen.

## Mitglied entfernen

Klicke beim Mitglied auf **Entfernen** und bestätige **Mitglied entfernen?**. Der Zugriff auf diesen Kunden endet sofort, und die Person bekommt eine E-Mail. Ihr eigenes Benutzerkonto bleibt bestehen – ist sie bei keinem Kunden mehr Mitglied, sieht sie nach der Anmeldung **Kein Kundenzugriff**.

Den einzigen Inhaber kannst du nicht entfernen. Entfernst du dich selbst, landest du auf der Seite **Dienste**.

## Fehlersuche

1. **Ich sehe den Menüpunkt „Team“ nicht** – nur Inhaber und Admins verwalten das Team.
2. **Die Einladung kommt nicht an** – Spam-Ordner prüfen, dann **Erneut senden**. Läuft sie ab, ebenfalls **Erneut senden**.
3. **„Falsches Konto“** – die eingeladene Person ist mit einer anderen E-Mail-Adresse angemeldet. Abmelden und mit der eingeladenen Adresse anmelden oder registrieren.
4. **„Du bist der einzige Inhaber“** – übertrage die Inhaber-Rolle zuerst an ein anderes Mitglied, dann kannst du deine eigene Rolle ändern.
5. **Ein Mitglied sieht einen Bereich nicht** – siehe die Tabelle [Rollen und Rechte](#rollen-und-rechte) und prüfe, ob oben rechts der richtige Kunde gewählt ist.

## Nächste Schritte

- [Login und Account-Navigation](/docs/login-und-account-navigation)
- [Service-Portal — Überblick](/docs/service-portal-uebersicht)
- [Zahlungsarten & Rechnungen](/docs/zahlungsarten-verwalten)

---

# Design anpassen (CSS)

Source: https://configento.app/docs/design-anpassen
Section: Einstellungen

Der Konfigurator soll aussehen wie dein Shop: Farben, Schrift, Ecken, die Optik der Auswahlfelder. Das alles passt du mit CSS an, ganz ohne JavaScript. Diese Seite gilt für die Frontend-Engine **V3**. Legacy erzeugt anderes HTML, dort greifen die Variablen und Klassen unten nicht.

## Was der Konfigurator schon vom Shop übernimmt

In einem Shop – über ein Shop-Plugin oder das [HTML-Snippet](/docs/html-snippet-integration) – übernimmt der Konfigurator **Schrift, Schriftgröße und Textfarbe** von deinem Theme. Dafür musst du nichts tun. Anpassen musst du nur, was der Konfigurator selbst mitbringt: Akzentfarbe, Rahmen, Hintergründe, Ecken.

Bindest du ihn mit `data-configento-embed-mode="admin-preview"` ein, zeigt er Titel, Preis und Zusammenfassung selbst und nutzt auch für Texte seine eigenen Farben. Die Schrift erbt er auch dann von der Seite.

## Wo dein CSS hingehört

Du hast zwei Orte:

- **Das Theme deines Shops** – richtig, wenn alle Konfiguratoren gleich aussehen sollen.
- **Benutzerdefiniertes CSS** in den [Komponenten-Einstellungen](/docs/komponente-einstellungen) unter **Design** – richtig für eine einzelne Komponente. Es wird mit dem Konfigurator geladen, im Shop und in der Vorschau im Admin.

Schreibe vor Regeln für einzelne Elemente `[data-configento]`, z. B. `[data-configento] .cfg-toggle-item__price`. Der Konfigurator lädt sein eigenes CSS nach deinem Theme; mit dem Zusatz gewinnt deine Regel trotzdem. Für die Variablen unten ist das nicht nötig.

## Farben, Schrift und Ecken

Die einfachste Anpassung: Variablen auf `:root` setzen. Sie wirken im ganzen Konfigurator und auch in der Bild-Großansicht und den Info-Fenstern, die außerhalb des Konfigurators geöffnet werden.

```css
:root {
  --configento-color-accent: #1d3c78;
  --configento-color-border: #c8d0e0;
  --configento-radius-md: 0;
}
```

| Variable | Standard | Wirkt auf |
|---|---|---|
| `--configento-color-accent` | `#2563eb` | Gewählte Werte, Radio Buttons und Checkboxen, gewählte Bilder, aktiver Reiter, Fortschrittsbalken, **Weiter**-Button, Links in Texten |
| `--configento-color-accent-fg` | `#ffffff` | Text auf Flächen in der Akzentfarbe, z. B. im **Weiter**-Button |
| `--configento-color-accent-soft` | `#dbeafe` | Helle Hinterlegung in der Akzentfarbe, z. B. beim aktiven Reiter |
| `--configento-color-border` | `#e2e8f0` | Rahmen und Trennlinien |
| `--configento-color-border-strong` | `#cbd5e1` | Rahmen von Eingabefeldern und Buttons |
| `--configento-color-bg` | `#ffffff` | Hintergrund des Konfigurators |
| `--configento-color-bg-subtle` | `#f8fafc` | Leicht abgesetzte Flächen |
| `--configento-color-bg-elevated` | `#ffffff` | Gruppen, Auswahllisten, Buttons und Fenster |
| `--configento-color-fg` | `#0f172a` | Text – nur mit `admin-preview`, im Shop kommt er vom Theme |
| `--configento-color-fg-muted` | `#64748b` | Nebentexte – nur mit `admin-preview` |
| `--configento-color-error` | `#b91c1c` | Fehlermeldungen und fehlerhafte Felder |
| `--configento-color-error-soft` | `#fee2e2` | Helle Hinterlegung von Fehlern |
| `--configento-color-success`, `--configento-color-success-soft` | `#059669`, `#d1fae5` | Erfolgsmeldungen |
| `--configento-color-warning`, `--configento-color-warning-soft` | `#b45309`, `#fef3c7` | Warnungen |
| `--configento-radius-sm`, `-md`, `-lg` | `4px`, `8px`, `12px` | Ecken: kleine Elemente, Felder und Kacheln, Fenster |
| `--configento-font-family` | Schrift der Seite | Schrift – nur nötig, wenn der Konfigurator eine andere Schrift als die Seite haben soll |

Die Namen dieser Variablen bleiben in allen 3.x-Versionen gleich.

**Aktivfarbe:** Ist in den Komponenten-Einstellungen unter **Design** eine **Aktivfarbe** gesetzt, gilt sie für diese Komponente statt `--configento-color-accent`. Lass das Feld leer, wenn die Farbe aus deinem CSS kommen soll.

**Andere Schrift:** Soll der Konfigurator eine andere Schrift als die Seite nutzen, setze sie am Element mit `data-configento`. Die Schrift muss auf der Seite geladen sein, etwa über dein Theme.

```css
[data-configento] { font-family: 'Source Sans 3', sans-serif; }
```

## Einzelne Elemente gestalten

Für Gestaltung über die Variablen hinaus gibt es Klassen und Attribute, die wir **zusagen**: Sie bleiben in allen 3.x-Versionen gleich, eine Änderung gibt es nur mit einer neuen ersten Versionsstelle. Andere Klassen und die übrige HTML-Struktur können sich ändern.

**Rahmen jedes Merkmals**

| Klasse / Attribut | Element |
|---|---|
| `.cfg-char` | Das ganze Merkmal. Trägt auch die Klassen aus dem Feld **CSS-Klasse** des Merkmals. |
| `[data-configento-char-id]`, `[data-configento-char-type]` | Am selben Element: ID und Datentyp des Merkmals, z. B. `radiobuttons`, `checkbox`, `text`, `area`, `select` |
| `[data-configento-invalid]` | Am selben Element, solange eine Fehlermeldung angezeigt wird |
| `.cfg-char__head` | Kopfzeile mit Titel |
| `.cfg-char__title` | Titel |
| `.cfg-char__required` | Pflichtfeld-Stern im Titel |
| `.cfg-char__info` | Infotext unter dem Titel |
| `.cfg-char__body` | Das Eingabeelement mit allem, was dazugehört |
| `.cfg-char__errors`, `.cfg-char__error` | Liste der Fehlermeldungen und jede einzelne Meldung |

**Radio Buttons und Checkboxen**

| Klasse / Attribut | Element |
|---|---|
| `.cfg-toggle-list` | Liste aller Werte |
| `.cfg-toggle-item` mit `[data-configento-value-id]` | Ein Wert, mit seiner ID |
| `.cfg-toggle-item__label` | Das `label` um die ganze Zeile. Das `input` (`type="radio"` bzw. `type="checkbox"`) ist sein direktes Kind. |
| `.cfg-toggle-item__image` | Bild des Werts |
| `.cfg-toggle-item__text` | Text-Block mit Bezeichnung und Infotexten |
| `.cfg-toggle-item__label-text` | Bezeichnung des Werts |
| `.cfg-toggle-item__info` | Infotext des Werts |
| `.cfg-toggle-item__price` | Aufpreis |

Den gewählten Zustand erreichst du über das `input`, z. B. `.cfg-toggle-item__label:has(input:checked)`.

**Eingabefelder und Auswahllisten**

| Klasse | Element |
|---|---|
| `input.cfg-input` | Einzeiliges Eingabefeld |
| `textarea.cfg-textarea` | Mehrzeiliges Eingabefeld |
| `select.cfg-select` | Auswahlliste |

Reicht CSS nicht, weil ein Merkmal ganz anders aussehen und sich anders verhalten soll – etwa als Kfz-Kennzeichen –, zeichnest du es mit einer [eigenen Darstellung](/docs/javascript-schnittstelle#eigene-eingabe-einbauen) per JavaScript.

Ein bestimmtes Merkmal sprichst du am einfachsten über eine eigene Klasse an: Trag sie im Editor im Feld **CSS-Klasse** des Merkmals ein, sie landet am Element `.cfg-char`.

## Beispiele

**Eigene Radio Buttons** – Kreis per CSS statt Browser-Standard, gewählte Zeile hervorgehoben:

```css
[data-configento] [data-configento-char-type="radiobuttons"] .cfg-toggle-item__label > input {
  appearance: none;
  width: 1.25rem;
  height: 1.25rem;
  border: 2px solid var(--configento-color-accent);
  border-radius: 50%;
}
[data-configento] [data-configento-char-type="radiobuttons"] .cfg-toggle-item__label > input:checked {
  background: radial-gradient(var(--configento-color-accent) 45%, transparent 50%);
}
[data-configento] .cfg-toggle-item__label:has(input:checked) {
  background: var(--configento-color-accent-soft);
}
```

Setze dafür `--configento-color-accent` und `--configento-color-accent-soft` auf `:root`, wie oben gezeigt.

**Fehler deutlicher zeigen:**

```css
[data-configento] .cfg-char[data-configento-invalid] .cfg-char__title { color: var(--configento-color-error); }
[data-configento] .cfg-char[data-configento-invalid] .cfg-input { border-color: var(--configento-color-error); }
```

**Aufpreise ausblenden**, etwa wenn dein Shop sie anders zeigt:

```css
[data-configento] .cfg-toggle-item__price { display: none; }
```

## Fehlersuche

| Problem | Ursache und Lösung |
|---|---|
| Deine Regel wirkt nicht | Der Konfigurator lädt sein CSS nach deinem Theme. Schreibe `[data-configento]` vor den Selektor. |
| Farbe wirkt im Konfigurator, nicht aber in der Bild-Großansicht | Die Variable steht auf einem Element statt auf `:root`. Die Großansicht öffnet außerhalb des Konfigurators. |
| Akzentfarbe aus dem CSS wird ignoriert | In der Komponente ist eine **Aktivfarbe** gesetzt. Leere das Feld. |
| Textfarbe ändert sich nicht | Im Shop kommt die Textfarbe vom Theme. `--configento-color-fg` wirkt nur mit `admin-preview`. |
| Nach dem Umstellen auf V3 sieht alles anders aus | Legacy hat andere Klassen. Baue dein CSS mit den Variablen und Klassen dieser Seite neu auf und prüfe es in der Vorschau. |

## Nächste Schritte

- [Komponenten-Einstellungen](/docs/komponente-einstellungen) – Aktivfarbe und benutzerdefiniertes CSS
- [HTML-Snippet-Integration](/docs/html-snippet-integration)
- [JavaScript-Schnittstelle (V3)](/docs/javascript-schnittstelle) – wenn du über die Optik hinaus eingreifen willst
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)

---

# Globale Einstellungen

Source: https://configento.app/docs/globale-einstellungen
Section: Einstellungen

Die globalen Einstellungen gelten für alle Komponenten deiner Service Order: Sprachen, Währung und Steuer, die Domänen, auf denen der Konfigurator laufen darf, das Aussehen von PDFs und E-Mails, der E-Mail-Versand, die Shop-Integrationen, API-Schlüssel und der KI-Assistent. Du findest sie im Admin unter **Einstellungen** in der Hauptnavigation.

Einstellungen einer einzelnen Komponente – Darstellung, Preisanzeige, Bilder, Design – stehen dagegen im Editor der Komponente: [Komponenten-Einstellungen](/docs/komponente-einstellungen).

## Die Reiter im Überblick

| Reiter | Inhalt |
|---|---|
| **Lokalisierung** | Standardsprache, Standardwährung, Steuersatz, Preise inkl. Steuern, aktive Sprachen |
| **Domänen** | Domänen, auf denen dein Konfigurator laden darf |
| **Branding** | Logo, Farbe, Schrift, Kopf- und Fußzeile, Impressum für PDFs und E-Mails |
| **E-Mail-Versand** | Dein SMTP-Server für E-Mails des Aktions-Buttons |
| **Integrationen** | HTML-Snippets und Shop-Plugins |
| **API** | API-Schlüssel |
| **KI** | KI-Assistent ein/aus, KI-Modell, was sich der Assistent gemerkt hat |
| **Auftragsverarbeitung** | Vereinbarung zur Auftragsverarbeitung |

> **Gesperrte Reiter:** Wurde eine neue Fassung der Vereinbarung zur Auftragsverarbeitung veröffentlicht und du hast sie noch nicht akzeptiert, sind alle Reiter außer **Auftragsverarbeitung** gesperrt. Während einer Testphase gilt die Sperre nicht. Siehe [Auftragsverarbeitung](#auftragsverarbeitung).

## Lokalisierung

![Einstellungen → Lokalisierung: Standardsprache, Standardwährung, Steuersatz, Preise inkl. Steuern und aktive Sprachen](/storage/app/media/docs/globale-einstellungen/01-lokalisierung.webp)

| Feld | Wirkung |
|---|---|
| **Standardsprache** | Die Hauptsprache deiner Inhalte. Neue Komponenten verwenden sie, wenn bei der Komponente **Globale Einstellungen verwenden** gewählt ist. |
| **Standardwährung** | Die Währung, in der Preise angezeigt werden. |
| **Steuersatz** | Der Steuersatz in Prozent, mit dem deine Preise gerechnet sind, z. B. 19. |
| **Preise inkl. Steuern** | Angehakt: Die Preise, die du in Komponenten einträgst, sind Bruttopreise. Nicht angehakt: Nettopreise. |
| **Aktive Sprachen** | Die Sprachen, in denen du Inhalte pflegst. Mit **Sprache hinzufügen…** kommt eine Sprache dazu, mit **×** entfernst du sie. Im Editor erscheinen die aktiven Sprachen als **Inhaltssprache:**. |

Speichere mit **Einstellungen speichern**. Wie Steuersatz und Shop-Steuer zusammenwirken, erklärt [Preisberechnung einrichten](/docs/preisberechnung-einrichten).

## Domänen

Dein Konfigurator lädt nur auf Domänen, die hier eingetragen sind. Das gilt auch für die Aktionen des Aktions-Buttons (PDF, E-Mail). So kann niemand deinen Konfigurator auf einer fremden Seite einbinden.

**Domäne hinzufügen:**

1. Trage unter **Domäne** den Namen ohne `https://` ein, z. B. `www.meinshop.de`.
2. Wähle den **Modus**: **Produktion**, **Staging** oder **Entwicklung**.
3. Klicke auf **Hinzufügen**.

Eine eingetragene Domäne gilt auch für ihre Unterdomänen. Änderungen wirken nach wenigen Minuten.

**Kontingent:** Oben rechts siehst du, wie viele Domänen dein Tarif erlaubt und wie viele belegt sind – getrennt nach **Produktion** und **Staging** / **Entwicklung**.

> Verwende keine Staging- oder Entwicklungsdomänen für Live-Systeme. Der Admin weist ausdrücklich darauf hin: Andernfalls wird das gesamte Konto gesperrt.

### Von verbundenen Shops gemeldet

Verbundene Shop-Plugins melden die Domänen, auf denen sie laufen. Diese erscheinen in einer eigenen Liste mit **Gemeldet von**, **Zuletzt gesehen** und **Typ**. Die Meldung allein erlaubt noch nichts:

- **In die Lizenz übernehmen** trägt die Domäne in deine Domänen ein – erst dann lädt der Konfigurator dort.
- Das Entfernen aus dieser Liste lässt deine eingetragenen Domänen unberührt.

## Branding

Das Branding bestimmt das Aussehen der PDFs und E-Mails, die der [Aktions-Button](/docs/aktions-button) erzeugt. Den Konfigurator selbst gestaltest du in der Komponente im Reiter **Design**.

| Feld | Wirkung |
|---|---|
| **Logo** | PNG, JPG oder WebP, max. 2 MB. Mit **Datei wählen** hochladen, mit **Logo entfernen** löschen. |
| **Primärfarbe** | Farbe für Überschriften, Links und die Linie unter der Kopfzeile |
| **Schrift** | Inter, Arial, Helvetica, Times New Roman, Georgia oder Verdana |
| **Kopfzeile** | Kopfbereich – für jede aktive Sprache einzeln |
| **Fußzeile** | Fußbereich – für jede aktive Sprache einzeln |
| **Impressum** | Deine Pflichtangaben – ein Text für alle Sprachen |

Änderungen am Branding wirken sofort auf alle künftigen PDFs und E-Mails.

## E-Mail-Versand

E-Mails des Aktions-Buttons verschickt configento.app über **deinen eigenen SMTP-Server**. Ohne vollständige Einstellungen hier können keine E-Mails versendet werden.

**Schnelleinrichtung:** Wähle deinen Anbieter, dann sind Host, Port und Verschlüsselung ausgefüllt: Gmail, Microsoft 365, GMX, web.de, iCloud, SendGrid, Postmark, Mailgun, AWS SES oder Mailtrap (nur zum Testen – die Mails landen im Mailtrap-Postfach, nicht beim Empfänger). Zu jedem Anbieter zeigt der Admin einen Hinweis, z. B. dass Gmail ein App-Passwort braucht.

| Feld | Wirkung |
|---|---|
| **Host**, **Port** | Adresse und Port des SMTP-Servers |
| **Verschlüsselung** | **STARTTLS (üblicherweise Port 587)**, **SSL/TLS (üblicherweise Port 465)** oder **Keine Verschlüsselung** |
| **Benutzername**, **Passwort** | Zugangsdaten. Ein gespeichertes Passwort wird nicht angezeigt; mit **Ändern** gibst du ein neues ein. |
| **Absender-Adresse**, **Absender-Name** | Von wem die E-Mails kommen |

Mit **Verbindung testen** prüfst du die Einstellungen. Trägst du unter **Test-E-Mail senden an** eine Adresse ein, wird zusätzlich eine Test-E-Mail verschickt. Wann zuletzt erfolgreich getestet wurde, steht unter **Zuletzt geprüft**.

## Integrationen

Hier bekommst du die HTML-Snippets und die Shop-Plugins. Welche Karten du siehst, hängt von deinem Konto ab.

### Konten ohne klassische Cloud

Oben steht: „Shop-Plugins verbinden sich über das Service-Portal — ein Sicherheitstoken ist hier nicht nötig.“

| Karte | Inhalt |
|---|---|
| **Magento 2** | Die beiden Composer-Befehle zum Kopieren. Verbunden wird die Erweiterung danach in Magento mit deinem Service-Portal-Login – siehe [Magento-Plugin installieren](/docs/magento-plugin-installieren). |
| **Shopware 6.7** | **Plugin herunterladen** für das Plugin-ZIP – siehe [Shopware-Plugin installieren](/docs/shopware-plugin-installieren). |
| **Shopify** | Code zum Verknüpfen (siehe unten) |
| **HTML5 (V3 Beta)** | Token und Snippet für jede Website (siehe unten) |

### Konten mit klassischer Cloud

Oben steht: „Integrationen aktivieren und Sicherheitstoken je Plattform verwalten.“ Für **HTML5**, **Magento 1.x**, **Magento 2.x**, **Shopware 5.x** und **Shopware 6** gibt es je eine Karte mit

- einem Schalter, der die Integration aktiviert,
- dem **Sicherheitstoken** mit **Kopieren** und **Neues Token** (das alte Token wird dabei ungültig – trage das neue auch im Plugin ein),
- **Plugin herunterladen** (bei Magento 2.x führt der Link zur Download-Seite des Composer-Repositorys).

Die Karte **HTML5** zeigt im eingeschalteten Zustand ein **JavaScript-Snippet** und ein **iFrame-Snippet**. Ersetze darin `YOUR_TEMPLATE_ID` durch die ID der Komponente. Bei diesen Konten braucht auch die **Vorschau** im Admin die eingeschaltete Karte **HTML5**.

Dazu kommen die Karten **Shopify** und **HTML5 (V3 Beta)**.

### Shopify

Installiere die Configento-App in deinem Shopify-Shop. Klicke hier auf **Verbindungs-Code generieren** und gib den sechsstelligen **Verknüpfungs-Code** im Shopify-Admin ein. Der Code ist nur kurz gültig (**Gültig bis**); mit **Neuen Code generieren** holst du einen neuen. Darunter steht, mit welcher Service Order der Shop verknüpft wird. Mehr dazu: [Shopify-Plugin installieren](/docs/shopify-plugin-installieren).

### HTML5 (V3 Beta)

Für jede Website ohne Shop-Plugin, mit der Frontend-Engine V3:

1. Klicke auf **Erzeugen** – du bekommst ein Token und das **V3-JavaScript-Snippet**.
2. Kopiere das Snippet in deine Seite und ersetze `YOUR_TEMPLATE_ID` durch die ID der Komponente.

**Erneuern** erzeugt ein neues Token und macht alle bisherigen ungültig – danach musst du das Snippet auf deinen Seiten austauschen. Alle Attribute des Snippets erklärt [HTML-Snippet Integration](/docs/html-snippet-integration).

## API

Hier erstellst du **API-Schlüssel** für den Zugriff auf die configento.app API.

**Schlüssel erstellen:**

1. **Name des Schlüssels** eingeben, z. B. den Namen der Integration („PIM“, „ERP-Sync“).
2. **Berechtigung** wählen – **Nur lesen** oder **Lesen & Schreiben**.
3. Bei **Lesen & Schreiben** optional **Veröffentlichen** und/oder **KI** anhaken.
4. Optional ein Datum unter **Gültig bis (optional)** wählen – ohne Datum läuft der Schlüssel nie ab.
5. **Erstellen** klicken. Der Schlüssel wird **nur einmal** angezeigt – kopiere ihn sofort und bewahre ihn sicher auf.

| Berechtigung | Erlaubt |
|---|---|
| **Nur lesen** | Daten abrufen, nichts ändern, veröffentlichen oder löschen |
| **Lesen & Schreiben** | Entwürfe anlegen, ändern und löschen |
| + **Veröffentlichen** | Änderungen live schalten und Komponenten löschen – beides wirkt sofort im Shop |
| + **KI** | Den KI-Assistenten über die API nutzen – das verbraucht KI-Tokens |

**Gut zu wissen:**

- Ein Schlüssel gilt nur für die Service Order, in der du ihn erstellt hast.
- In der Liste **Aktive Schlüssel** siehst du zu jedem Schlüssel **Erstellt**, **Zuletzt verwendet** und die Gültigkeit. Berechtigungen und Datum änderst du dort über **Ändern**.
- Ein Schlüssel mit Ablaufdatum funktioniert bis zum Ende dieses Tages. Danach steht er als **Abgelaufen** in der Liste; über **Ändern** wird er wieder gültig.
- **Widerrufen** sperrt einen Schlüssel sofort.
- Kein API-Schlüssel kann Schlüssel verwalten, KI-Tokens kaufen oder Integrations-Zugangsdaten lesen.

Mehr zur API: [API — Einstieg & Übersicht](/docs/api-einstieg).

## KI

| Einstellung | Wirkung |
|---|---|
| **KI-Assistent** | Schalter für den ganzen Assistenten. Ausgeschaltet verschwindet das KI-Panel im Admin, und es werden keine Daten an den KI-Dienstleister übertragen. Jederzeit wieder einschaltbar. |
| **KI-Modell** | **Sparsam**, **Standard** oder **Maximal**. Leistungsfähigere Modelle antworten besser und verbrauchen mehr von deinem monatlichen KI-Kontingent – derzeit Sparsam das 0,5-Fache, Standard 1:1, Maximal das 2-Fache. Der Admin zeigt den aktuellen Faktor an jeder Stufe. |

### Was sich der Assistent merkt

Im Abschnitt **Was wir über dich wissen** stehen Informationen über dein Unternehmen, die der Assistent in jedem neuen Chat automatisch verwendet – etwa Fachbegriffe oder Namenskonventionen.

- Merkt sich der Assistent etwas Neues, fragt er dich zuerst. Noch nicht bestätigte Punkte stehen unter **Wartet auf Bestätigung** – mit **Bestätigen** übernimmst du sie.
- **Anpassen** ändert einen gemerkten Punkt, **Vergessen** löscht ihn.

Mehr zum Assistenten: [KI-Agent: Konfigurator per Chat aufbauen](/docs/ki-agent-konfigurator-aufbauen) und [KI-Tokens](/docs/ki-tokens).

## Auftragsverarbeitung

Hier steht die Vereinbarung zur Auftragsverarbeitung zwischen dir und justSelling.

- **PDF herunterladen** lädt die Vereinbarung als PDF.
- Zum Akzeptieren trägst du unter **Unterschrift Auftraggeber** deinen **Name** ein (das **Datum** wird automatisch gesetzt) und klickst auf **Hiermit akzeptiere ich die vorliegende Vereinbarung**. Name, Datum und Version werden gespeichert und erscheinen auf dem ausgedruckten Dokument.
- Wird eine neue Fassung veröffentlicht, musst du sie erneut akzeptieren. Bis dahin sind die übrigen Reiter der Einstellungen gesperrt – außer während einer Testphase.

## Fehlersuche

1. **Alle Reiter außer „Auftragsverarbeitung“ sind grau** – akzeptiere die neue Fassung der Vereinbarung.
2. **Der Konfigurator lädt auf meiner Seite nicht** – die Domäne fehlt unter **Domänen** oder ist nur gemeldet, aber nicht **In die Lizenz übernommen**.
3. **E-Mails des Aktions-Buttons kommen nicht an** – der E-Mail-Versand ist nicht vollständig eingerichtet. Prüfe mit **Verbindung testen** und sende eine Test-E-Mail.
4. **Ein Shop-Plugin verbindet sich nicht mehr** – du hast bei der Karte **Neues Token** oder bei HTML5 (V3 Beta) **Erneuern** geklickt. Trage das neue Token bzw. Snippet ein.
5. **Die Vorschau im Editor bittet, HTML5 zu aktivieren** – schalte unter **Integrationen** die Karte **HTML5** ein.
6. **Eine Sprache fehlt im Editor** – füge sie unter **Lokalisierung** bei **Aktive Sprachen** hinzu und speichere.

## Nächste Schritte

- [Komponenten-Einstellungen](/docs/komponente-einstellungen)
- [Der Aktions-Button](/docs/aktions-button)
- [HTML-Snippet Integration](/docs/html-snippet-integration)
- [API — Einstieg & Übersicht](/docs/api-einstieg)
- [KI-Tokens](/docs/ki-tokens)

---

# Komponenten-Einstellungen

Source: https://configento.app/docs/komponente-einstellungen
Section: Einstellungen

Jede Komponente hat eigene Einstellungen für Darstellung, Preisanzeige, Bilder, Design und Auswertung. Du findest sie im Editor links im Reiter **Einstellungen**. Dazu kommt die Kopfleiste über dem Editor mit Inhaltssprache, Speichern, Zurücksetzen und Veröffentlichen sowie der Reiter **Versionen**. Dieser Artikel erklärt alle Felder.

Einstellungen, die für dein ganzes Konto gelten – Sprachen, Steuersatz, Domänen, E-Mail-Versand –, stehen dagegen unter **Einstellungen** in der Hauptnavigation: [Globale Einstellungen](/docs/globale-einstellungen).

## Der Editor auf einen Blick

| Bereich | Inhalt |
|---|---|
| **Links** | Die Reiter **Merkmale**, **Regeln**, **Einstellungen** und **Versionen** |
| **Mitte** | Umschalter **Bearbeiten** / **Vorschau** |
| **Rechts** | Die Einstellungen des ausgewählten Merkmals, der Gruppe oder Regel |
| **Oben** | Die Kopfleiste (siehe unten) |

Wie du Merkmale und Werte anlegst, erklärt [Merkmale & Werte anlegen](/docs/merkmale-optionen-anlegen), Regeln stehen in [Regelwerk aufbauen](/docs/regelwerk-aufbauen).

## Die Kopfleiste

| Element | Wirkung |
|---|---|
| **Inhaltssprache:** | Erscheint, wenn dein Konto mehrere Sprachen aktiv hat. Du wählst, in welcher Sprache du Texte bearbeitest. Die Standardsprache ist mit **(Standard)** markiert. In jeder anderen Sprache zeigt der Editor den Hinweis **Übersetzungsmodus – nur übersetzbare Felder sichtbar** und blendet alles aus, was nicht übersetzt wird. |
| **Rückgängig** | Nimmt die letzte Änderung zurück. Mehrfach klickbar, solange es Änderungen gibt. |
| **Zurücksetzen** | Verwirft alle Änderungen seit dem letzten Veröffentlichen und lädt die veröffentlichte Fassung neu. Vorher fragt der Admin nach: **Auf veröffentlichte Version zurücksetzen?** Das lässt sich nicht rückgängig machen. Bei einer Komponente, die noch nie veröffentlicht wurde, gibt es den Knopf nicht. |
| **Noch nicht live** | Steht da, solange dein gespeicherter oder ungespeicherter Stand von der veröffentlichten Fassung abweicht. Die Shops zeigen bis zum Veröffentlichen weiter die alte Fassung. |
| **Veröffentlichen** | Prüft die Komponente, speichert offene Änderungen und gibt den Stand für die Shops frei. Der Knopf erscheint nur, wenn es etwas zu veröffentlichen gibt. |
| **Speichern** | Erscheint über dem rechten Bereich, sobald es ungespeicherte Änderungen gibt. Speichern legt einen Entwurf an – deine Shops sehen ihn noch nicht. |

### Veröffentlichen im Detail

1. Klicke auf **Veröffentlichen**. Ungespeicherte Änderungen werden dabei zuerst gespeichert.
2. Der Admin prüft die Komponente. **Fehler** blockieren das Veröffentlichen: **Veröffentlichen blockiert – diese Fehler müssen behoben werden:**. **Warnungen** werden angezeigt, das Veröffentlichen bleibt aber möglich: **Warnungen (Veröffentlichen trotzdem möglich):**.
3. Hat seit dem Öffnen jemand anderes die Komponente gespeichert, erscheint **Gleichzeitige Bearbeitung erkannt!**. Veröffentlichst du trotzdem, überschreibst du dessen Änderungen.
4. Bestätige mit **Ja, veröffentlichen**.

## Reiter „Einstellungen“ → Allgemein

![Komponenteneinstellungen, Reiter Allgemein: Grundeinstellungen, Min/Max Anzeige, Kombiniertes Produktbild, Aufpreis und Darstellung](/storage/app/media/docs/komponente-einstellungen/01-allgemein.webp)

### Grundeinstellungen

| Feld | Wirkung |
|---|---|
| **Titel** | Name der Komponente in der Übersicht und in den Shop-Plugins. Pro Sprache pflegbar. |
| **Überschrift** | Optionale Überschrift über dem Konfigurator. Pro Sprache pflegbar. |
| **Standardsprache für diese Komponente** | Die Sprache, in der du die Inhalte pflegst. **Globale Einstellungen verwenden** übernimmt die Standardsprache des Kontos. |

### Zusammenfassung

| Feld | Wirkung |
|---|---|
| **Kombinierte Artikelnummer anzeigen** | Zeigt am Ende der Zusammenfassung die Artikelnummer des konfigurierten Produkts, z. B. „Artikelnummer: CL-W-GR“. Nur V3. |

Die kombinierte Artikelnummer setzt sich aus den **Artikelnummern** der gewählten Werte zusammen, in der Reihenfolge der Merkmale und getrennt mit „-“. Hat ein gewählter Wert keine Artikelnummer, zählt die des Merkmals. Bei einer Mehrfachauswahl zählt die erste vorhandene. Merkmale, die eine Regel ausblendet, zählen nicht mit. Dieselbe Nummer übernehmen die Shop-Plugins in den Warenkorb, und in PDF und E-Mail des [Aktions-Buttons](/docs/aktions-button) steht sie über `{{combined_sku}}` bereit. In der **Vorschau** blendest du sie mit der Checkbox **Kombinierte Artikelnummer** ein, auch wenn sie in der Zusammenfassung ausgeschaltet ist.

### Min/Max Anzeige

| Feld | Wirkung |
|---|---|
| **Min/Max anzeigen** | Zeigt bei Eingabefeldern mit Mindest- und Höchstwert den erlaubten Bereich an. |
| **Min/Max Muster** | Format dieser Anzeige. `$min` und `$max` werden durch die Grenzen ersetzt, z. B. `($min - $maxcm)` → „(40 - 240cm)“. |

### Kombiniertes Produktbild

| Feld | Wirkung |
|---|---|
| **Kombiniertes Bild** | **Nein**, **Kombiniertes Produktbild** (die Bilder der gewählten Werte werden übereinandergelegt) oder **360° kombiniertes Produktbild** (drehbare Ansicht, nur Legacy). |
| **Animation 360** | Nur bei 360°: **Keine Ladeanimation**, **Ladeanimation ohne Fortschrittsanzeige**, **Ladeanimation mit Fortschrittsanzeige** oder **Nur Fortschrittsanzeige**. |
| **Start-Sequenz in der 360°-Ansicht** | Nur bei 360°: mit welchem Bild die Drehung beginnt. |
| **3D-Icon anzeigen nach (CSS-Selektor)** | Nur bei 360°: hinter welchem Element der Seite das 3D-Symbol erscheint. |

Wie du die Bilder dafür hinterlegst: [Bildvisualisierung & Bilder hochladen](/docs/bildvisualisierung-bilder).

### Aufpreis

| Feld | Wirkung |
|---|---|
| **Preisanzeige** | Zeigt die Aufpreise der Werte im Konfigurator an. |
| **Preistyp** | **Absolut**: der Aufpreis des Werts. **Relativ**: der Unterschied zum gerade gewählten Wert. |
| **Bei Null anzeigen** | Zeigt auch Aufpreise von 0 an. |
| **Preismuster** | Format der Anzeige. `$price` wird durch den Betrag mit Vorzeichen und Währung ersetzt, z. B. `[$price]` → „[+15,00 €]“. |

Mehr zur Preislogik: [Preisberechnung einrichten](/docs/preisberechnung-einrichten).

### Darstellung

| Feld | Wirkung |
|---|---|
| **Darstellung** | Wie die Gruppen angezeigt werden: **Keine Gruppen**, **Tabs** oder **Accordion** (nur Legacy). |
| **Wizard** | Erscheint, wenn nicht **Keine Gruppen** gewählt ist. Führt Schritt für Schritt durch die Gruppen. |
| **Auto-Scroll bei Tab-Wechsel** | Nur mit Wizard: scrollt beim Schrittwechsel nach oben zum Konfigurator. |
| **Versatz oben für Auto-Scroll** | Nur mit Wizard: Abstand in Pixeln zum oberen Rand, z. B. für eine feste Kopfzeile des Shops. Vorgabe 80. |
| **Wizard-Navigation (V3)** | Nur mit Wizard: **Tabs, Fortschritt und Buttons** (Standard), **Nur Zurück/Weiter** oder **Keine**, wenn die Shopseite die Schritte selbst steuert. Gilt nur für V3. |
| **Position Merkmalbilder** | Wo das Bild eines Merkmals neben dem Merkmal steht: **Links**, **Rechts** oder **Nicht anzeigen**. |

Gruppen, Tabs und Wizard im Detail: [Merkmalsgruppen & Wizard](/docs/merkmalsgruppen-wizard).

### Frontend-Engine

| Feld | Wirkung |
|---|---|
| **Engine** | **Legacy (Standard)** oder **V3 (Beta)**. Bestimmt, welcher Konfigurator im Shop läuft. |

Enthält die Komponente ein Merkmal, das nur V3 kann (derzeit das Captcha), erscheint oben in den Einstellungen der Hinweis **Benötigt Frontend V3**. Was die Engines unterscheidet und wo welche läuft: [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3).

## Reiter „Einstellungen“ → Design

| Feld | Wirkung |
|---|---|
| **Aktivfarbe** | Farbe für gewählte Werte und aktive Elemente. Leer lassen, wenn die Farbe aus deinem CSS kommen soll. |
| **Ladeanimationsfarbe** | Farbe der Ladeanimation. In Legacy nur beim kombinierten Produktbild verwendet. |
| **Benutzerdefiniertes CSS** | Eigenes CSS, das mit dem Konfigurator geladen wird – für Anpassungen an dein Shop-Design. |
| **Benutzerdefiniertes JavaScript** | Eigenes JavaScript, das mit dem Konfigurator geladen wird. |

> Eigenes CSS und JavaScript greifen auf die Struktur des Konfigurators zu. Legacy und V3 erzeugen unterschiedliches HTML – stellst du die Engine um, prüfe deine Anpassungen in der Vorschau. Wie du V3 per CSS an dein Shop-Design anpasst und welche Klassen dauerhaft gleich bleiben, steht unter [Design anpassen (CSS)](/docs/design-anpassen).

## Reiter „Einstellungen“ → Reporting

Das Reporting schickt Aufrufe und Auswahlen an Google Analytics. Es läuft nur in der **Legacy**-Engine.

| Feld | Wirkung |
|---|---|
| **Reporting aktivieren** | Schaltet das Reporting ein und blendet die weiteren Felder ein. |
| **Google Analytics ID** | Deine Analytics-Kennung. |
| **Seitenpfad** | Pfad, unter dem die Aufrufe gemeldet werden. Vorgabe `/pcc`. |
| **Vollständige Konfiguration verfolgen** | Meldet bei jeder Änderung zusätzlich die komplette Konfiguration. |
| **Merkmale ausblenden** | Interne Namen von Merkmalen, die nicht gemeldet werden sollen, durch Komma getrennt. |

> Das Reporting nutzt das alte Messprotokoll von Google Analytics (Universal Analytics). Prüfe in deinem Analytics-Konto, ob dort Daten ankommen, bevor du dich darauf verlässt.

## Reiter „Einstellungen“ → Benutzerdefinierte Felder

Hier legst du **eigene Zusatzfelder** an, die danach an jedem Merkmal bzw. jedem Wert erscheinen – etwa eine interne Materialnummer oder ein Lieferanten-Code.

- **Felder für Merkmale** und **Felder für Werte**: Mit **Feld hinzufügen** legst du ein Feld an und gibst ihm einen **Name**. Der Typ ist immer **Text**.
- Die Werte trägst du danach am Merkmal bzw. Wert im Abschnitt **Benutzerdefinierte Felder** ein.
- In der Legacy-Engine wandern die Werte mit der Konfiguration in den Warenkorb und die Bestellung, sodass ein Shop oder eine Warenwirtschaft sie auswerten kann. Für deine Kunden sind sie nicht sichtbar.

Benutzerdefinierte Felder sind **keine** Eingabefelder für deine Kunden. Name, E-Mail oder Firma fragst du mit normalen Merkmalen ab, z. B. mit einem kleinen Eingabefeld.

## Reiter „Versionen“

Jedes Speichern legt eine Version an, jedes Veröffentlichen eine Version mit der Markierung **Veröffentlicht**. Im Reiter **Versionen** kannst du

- eine Version mit **Mit Entwurf vergleichen** deinem aktuellen Stand gegenüberstellen,
- zwei Versionen **Auswählen** und **Vergleichen**,
- eine Version **Wiederherstellen**. Sie ersetzt deinen aktuellen Entwurf, wird aber erst nach dem **Veröffentlichen** im Shop sichtbar.

Gibt es noch keine Version, speichere die Komponente einmal.

## Fehlersuche

1. **Eine Änderung kommt im Shop nicht an** – steht oben **Noch nicht live**, klicke auf **Veröffentlichen**. Speichern allein reicht nicht.
2. **Der Knopf „Zurücksetzen“ fehlt** – die Komponente wurde noch nie veröffentlicht. Es gibt keine Fassung, auf die zurückgesetzt werden könnte.
3. **Ich sehe nur einen Teil der Felder** – du bearbeitest gerade eine andere Sprache als die Standardsprache. Wechsle bei **Inhaltssprache:** auf die Sprache mit **(Standard)**.
4. **Accordion wirkt nicht** – die Komponente läuft mit V3. V3 kennt kein Accordion und zeigt die Merkmale ohne Gruppen.
5. **Das 360°-Bild dreht sich nicht** – die 360°-Ansicht gibt es nur in Legacy.
6. **Reporting liefert keine Daten** – Reporting läuft nur in Legacy und nutzt das alte Analytics-Protokoll (siehe oben).
7. **Die kombinierte Artikelnummer fehlt in der Zusammenfassung** – keiner der gewählten Werte und keines der Merkmale hat eine Artikelnummer, oder die Komponente läuft mit Legacy.

## Nächste Schritte

- [Merkmalsgruppen & Wizard](/docs/merkmalsgruppen-wizard)
- [Bildvisualisierung & Bilder hochladen](/docs/bildvisualisierung-bilder)
- [Frontend-Engine: Legacy oder V3](/docs/frontend-engine-legacy-v3)
- [Globale Einstellungen](/docs/globale-einstellungen)