# Punkte-Import (CSV)

Mit dem **Punkte-Import** buchst du Treuepunkte per CSV-Datei für bestehende Kundenkonten. Jede gültige Zeile erzeugt eine manuelle Gutschrift (Transaktionstyp „manuelle Zufuhr“); die Punkte werden anschließend wie gewohnt freigegeben.

## Wo du die Funktion findest

{% stepper %}
{% step %}
In der **Shopware-Administration** öffnest du das Loyalty-Dashboard (Menü **Marketing** – der Eintrag entspricht dem Loyalty-Plugin, z. B. Treuepunkte / Punkte-Transaktionen, je nach Übersetzung).
{% endstep %}

{% step %}
Wechsle auf die Registerkarte **„Erweiterte Funktionen“** (engl. *Premium features*).
{% endstep %}

{% step %}
Im Bereich **„Punkte Import“** klickst du auf **„Punkte importieren“**.
{% endstep %}
{% endstepper %}

Es öffnet sich ein Dialog: Datei wählen, Optionen setzen, Import starten.

## Voraussetzungen

* **Loyalty** muss für den **Verkaufskanal** des jeweiligen Kunden aktiv sein. Ist das Programm dort ausgeschaltet, schlägt die Zeile mit einer entsprechenden Meldung fehl.
* Es werden nur **registrierte Kunden** berücksichtigt (**keine Gastkonten**). Die Zuordnung erfolgt über die **Kundennummer** aus Shopware (`customer.customerNumber`).
* **Punkte** müssen als **positive Ganzzahl** größer als **0** angegeben werden (keine negativen Buchungen über diesen Import).

## CSV-Datei: Aufbau und Regeln

### Pflicht- und optionale Spalten

| Inhalt       | Pflicht | Erlaubte Spaltennamen (Groß/Kleinschreibung egal)           |
| ------------ | ------- | ----------------------------------------------------------- |
| Kundennummer | Ja      | `Kundennummer`, `customerNumber`, `customer_number`, `kdnr` |
| Punkte       | Ja      | `Punkte`, `points`                                          |
| Beschreibung | Nein    | `Beschreibung`, `description`, `desc`                       |

Ohne **Beschreibung** setzt das System den Text **`CSV Import`** in der Transaktion.

### Format

* **Erste Zeile** = Kopfzeile mit den Spaltennamen, **mindestens eine Datenzeile** darunter.
* **Trennzeichen** wird automatisch erkannt: **Semikolon** oder **Komma** (je nachdem, welches Zeichen in der Kopfzeile häufiger vorkommt).
* **UTF-8** inkl. **UTF-8-BOM** wird unterstützt (typisch für Excel-Exporte).

### Beispiel (Semikolon)

```csv
Kundennummer;Punkte;Beschreibung
10001;50;Migration Altshop Q1
10002;25;Kulanz
```

### Beispiel (Komma)

```csv
customerNumber,points,description
10001,50,Migration Altshop Q1
```

## Optionen im Import-Dialog

* **„Loyalty-Profil erstellen, wenn noch keins für den Kunden vorhanden ist“**\
  Ist kein Loyalty-Profil vorhanden und die Option **aus**, wird die Zeile **übersprungen** (Zähler „Übersprungen“). Ist die Option **an**, wird ein Profil angelegt, sofern Loyalty für den Kanal aktiv ist bzw. die Kombination mit Opt-In zulässig ist.
* **„Profile automatisch für Loyalty-Programm aktivieren (Opt-In setzen)“**\
  Steuert bei der **Profil-Anlage** im Rahmen des Imports, ob das Programm für den Kunden aktiv gesetzt wird. (Technisch relevant v. a., wenn noch kein Profil existiert.)

Hast du einen Kunden mit **Newsletter-Opt-in**, kann beim neu angelegten Profil zusätzlich der **Newsletter-Hinweis** am Profil gesetzt werden (wie in der bestehenden Shop-Logik).

## Nach dem Import

Die Auswertung zeigt u. a.:

* **Importiert** – erfolgreich gebuchte Zeilen
* **Profile erstellt** – neu angelegte Loyalty-Profile (falls zutreffend)
* **Übersprungen** – Zeilen ohne Import, z. B. weil kein Profil existierte und „Profil erstellen“ deaktiviert war
* **Fehler** – z. B. unbekannte Kundennummer, ungültige Punkte, Kunde nicht gefunden, Loyalty im Kanal inaktiv

Fehlermeldungen sind **zeilenbezogen** (Angabe der Zeilennummer in der CSV).

## Typische Fehlerquellen

| Problem                   | Hinweis                                                                             |
| ------------------------- | ----------------------------------------------------------------------------------- |
| Kunde wird nicht gefunden | Kundennummer exakt wie in Shopware; Tippfehler oder führende Leerzeichen vermeiden. |
| Zeile „ungültige Daten“   | Kundennummer leer oder Punkte ≤ 0.                                                  |
| Loyalty nicht aktiv       | Programm im jeweiligen Verkaufskanal aktivieren oder Kundenkanal prüfen.            |
| Gastkunden                | Werden nicht importiert (Filter `guest = false`).                                   |

## Technischer Hintergrund (Kurz)

* Pro erfolgreicher Zeile wird eine **Punkte-Transaktion** vom Typ manuelle Zufuhr erzeugt; anschließend läuft die **Freigabe der Punkte** über die bestehende Task-Logik.
* Die Administration sendet den Import in **Batches** (z. B. 25 Zeilen) an die API, damit große Dateien stabil verarbeitet werden.

*Hinweis: Wenn du die CSV in Excel bearbeitest, achte auf ein konsistentes Trennzeichen und speichere als CSV (UTF-8), damit Umlaute und die Kopfzeile zuverlässig gelesen werden.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.codegiganten.de/plugin-documentation/apps/enterprise-loyalty-bonus-programm/punkte-import-csv.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.