# Lizenzschlüssel und digitale Produkte: Dokumentation DataFirefly License Keys

> Installation Installieren Sie das Modul über Module > Modulmanager > Modul hochladen mit der ZIP-Datei, oder kopieren Sie den Ordner dflicensekeys in das Verzeichnis /modules/ des Shops und klicken Sie…

- Seite: <https://www.datafirefly.com/de/documentation/dflicensekeys/>
- Sprache: de
- Aktualisiert am: 2026-09-23
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dflicensekeys/index.md), [en](https://www.datafirefly.com/en/documentation/dflicensekeys/index.md), [es](https://www.datafirefly.com/es/documentation/dflicensekeys/index.md), [it](https://www.datafirefly.com/it/documentation/dflicensekeys/index.md), [pl](https://www.datafirefly.com/pl/documentation/dflicensekeys/index.md), [nl](https://www.datafirefly.com/nl/documentation/dflicensekeys/index.md), [pt](https://www.datafirefly.com/pt/documentation/dflicensekeys/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

## Installation

Installieren Sie das Modul über **Module > Modulmanager > Modul hochladen** mit der ZIP-Datei, oder kopieren Sie den Ordner `dflicensekeys` in das Verzeichnis `/modules/` des Shops und klicken Sie auf Installieren. Die PHP-Erweiterung `openssl` ist erforderlich.

Bei der Installation legt das Modul seine Tabellen an, registriert seine Hooks und fügt das Menü **Katalog > Lizenzschlüssel** hinzu. Außerdem erzeugt es ein shopeigenes Verschlüsselungs-Secret.

Die Schlüssel werden mit einem Schlüssel verschlüsselt, der den Cookie-Schlüssel von PrestaShop (Datei `app/config/parameters.php`) mit diesem Secret kombiniert. Behalten Sie diese Parameterdatei bei einem Umzug oder einer Kopie des Shops: Ohne sie sind die Schlüssel nicht mehr lesbar. Ein rotes Banner weist Sie darauf hin.

Bei der Deinstallation bleiben Schlüssel, Auslieferungen und Secret erhalten, damit ein Zurücksetzen des Moduls Ihren Bestand nicht leert. Aktivieren Sie **Alle Schlüssel, Auslieferungen und Dateien bei der Deinstallation löschen** nur, wenn Sie alles entfernen möchten.

## Moduleinstellungen

### Auslieferung

- **Ausliefern, wenn die Bestellung diesen Status erreicht**: Als bezahlt markierte Status (Zahlung eingegangen, Fernzahlung akzeptiert, Versendet, Zugestellt…) werden bei der Installation ausgewählt. Ein Wechsel auf einen dieser Status löst die Auslieferung aus. Die Verarbeitung ist idempotent: Ein erneuter Wechsel auf einen dieser Status sendet keine neuen Schlüssel.
- **Hinweis auf sofortige Auslieferung auf Produktseiten anzeigen**: kleiner Kasten unter dem Preis digitaler Produkte.
- **Eine Kopie der Auslieferungs-E-Mails an die Warnadresse senden**: Blindkopie an die erste Warnadresse.

### Stornierungen und Erstattungen

Mit aktivem automatischem Widerruf werden bei einer Bestellung im Status Storniert oder Erstattet (Standardstatus) die Schlüssel widerrufen und die Downloads gesperrt. Widerrufene Schlüssel gehen nie von selbst in den Bestand zurück.

### Schlüsselbestand

- **Produktmenge mit den verfügbaren Schlüsseln synchronisieren**: Die PrestaShop-Menge entspricht den tatsächlich freien Schlüsseln, also den verfügbaren Schlüsseln abzüglich der für noch nicht ausgelieferte Bestellungen reservierten (etwa eine ausstehende Überweisung) und abzüglich der fehlenden Schlüssel wartender Bestellungen. Bei mehreren Schlüsseln pro Einheit wird die Menge entsprechend geteilt.
- **Warnschwelle für niedrigen Bestand** (Standard 5) und **E-Mail-Adresse(n) für Warnungen**: Eine Warnung geht raus, wenn die verfügbaren Schlüssel auf diese Schwelle fallen oder eine Bestellung auf Schlüssel wartet, höchstens einmal pro Tag und Produkt.

### Standardwerte für neue digitale Produkte

**Download-Limit** (Standard 5, 0 = unbegrenzt) und **Gültigkeit des Links** in Tagen (0 = kein Ablauf), übernommen bei der Aktivierung eines Produkts.

### Lizenz-API und Aktivierungen

Siehe Abschnitt API weiter unten. **Kunden dürfen Aktivierungen in ihrem Konto freigeben** ist standardmäßig aktiviert.

## Ein digitales Produkt einrichten

Öffnen Sie die Produktseite, Tab **Module**, Block **Digitale Auslieferung und Lizenzschlüssel**. Der Block wird mit seinem eigenen Button **Digitale Einstellungen speichern** gespeichert, unabhängig vom Produktformular. Bis zum Klick wird „Nicht gespeicherte Änderungen“ angezeigt.

Legen Sie das Produkt als **virtuelles Produkt** an, damit beim Bezahlen kein Versand abgefragt wird. Der Block erinnert Sie daran, falls nicht.

### Lizenzschlüssel

- **Schlüsselquelle**: nur importierter Bestand; importierter Bestand, danach automatische Generierung, wenn er leer ist; immer automatisch generiert.
- **Schlüsselmuster**: für den Generator. `X` = Buchstabe oder Ziffer, `A` = Buchstabe, `9` = Ziffer, andere Zeichen bleiben unverändert. Mindestens 8 Zufallszeichen, höchstens 128 Zeichen. Verwechselbare Zeichen (0, O, 1, I) werden nie gezogen.
- **Gültigkeit der Lizenz (Tage)**: 0 = unbefristete Lizenz. Das Enddatum wird bei der Auslieferung jedes Schlüssels berechnet.
- **Maximale Aktivierungen pro Schlüssel**: 0 = unbegrenzt. Wird von der Lizenz-API durchgesetzt.
- **Schlüssel pro bestellter Einheit**: 5 für ein 5er-Lizenzpaket, zum Beispiel.
- **Warnschwelle für niedrigen Bestand**: leer lassen, um die globale Einstellung zu verwenden.
- **Für jede Kombination einen eigenen Schlüsselbestand verwalten**: nützlich für „1 Jahr“ und „3 Jahre“ oder „Windows“ und „Mac“.

Bei automatischer Generierung geht der Bestand nie aus: Die Produktmenge wird nicht mehr synchronisiert. Geben Sie eine hohe Menge an oder erlauben Sie Bestellungen ohne Lagerbestand.

### Herunterladbare Datei

Laden Sie die Datei hoch (Installer, PDF, Archiv). Sie wird im Ordner `/download/` von PrestaShop unter einem zufälligen Namen gespeichert und ist nie direkt erreichbar. Legen Sie das **Download-Limit pro Bestellposition** und die **Gültigkeit des Links** fest. Das Ersetzen der Datei kommt auch bereits belieferten Kunden zugute.

### Aktivierungsanleitung

Optionaler Text pro Sprache, der mit den Schlüsseln in der E-Mail und im Kundenkonto erscheint. Ein grüner Punkt markiert die ausgefüllten Sprachen.

## Schlüssel importieren und generieren

Auf der Produktseite (Block **Schlüssel zum Bestand hinzufügen**) oder unter **Katalog > Lizenzschlüssel > Schlüssel importieren**:

- Fügen Sie die Schlüssel ein, einer pro Zeile, oder wählen Sie eine TXT-Datei (ein Schlüssel pro Zeile) oder eine CSV-Datei (Schlüssel in der ersten Spalte, Trennzeichen `;`, `,` oder Tabulator). Haken Sie bei Bedarf **Die erste Zeile der Datei ist eine Kopfzeile** an.
- Bei einem Produkt mit Bestand pro Kombination wählen Sie die Kombination.
- Die **Chargenbezeichnung** (etwa die Lieferantenrechnung) hilft, diese Schlüssel später zu finden oder zu exportieren.

Duplikate, die für dieses Produkt schon im Bestand sind oder in der Liste doppelt vorkommen, werden übersprungen. Schlüssel mit mehr als 1000 Zeichen werden abgelehnt. Ein noch nicht eingerichtetes Produkt wird mit den Standardeinstellungen aktiviert. Bestellungen, die auf Schlüssel warten, werden direkt nach dem Import ausgeliefert, die ältesten zuerst.

Um eine Charge in den Bestand zu generieren (bis zu 10.000 Schlüssel), geben Sie Anzahl und Muster ein und klicken auf **Generieren**. Praktisch, um Ihr eigenes Lizenzsystem oder einen Wiederverkäufer über den CSV-Export zu beliefern.

## Was der Kunde erhält

- **Auslieferungs-E-Mail** in der Sprache der Bestellung: Schlüssel, Gültigkeit, Download-Button mit der verbleibenden Anzahl, Aktivierungsanleitung. Eine neue E-Mail geht raus, sobald neue Schlüssel zugewiesen werden (verzögerte Auslieferung oder Ersatz).
- **Bestellbestätigung**: Bei sofortiger Zahlung erscheinen die Schlüssel direkt, sonst weist ein Hinweis darauf hin, dass sie nach Zahlungseingang gesendet werden.
- **Mein Konto > Meine Lizenzschlüssel**: alle Schlüssel aller Bestellungen mit Kopieren-Button, Download-Links, Gültigkeit und aktivierten Geräten. Der Link erscheint nur bei Kunden, die mindestens eine Auslieferung erhalten haben.
- **Bestelldetail und Gastbestellverfolgung**: die Schlüssel und Downloads der Bestellung. Ein Gastkunde erhält den Link zur Bestellverfolgung in der E-Mail.

Ein abgelaufener oder aufgebrauchter Download-Link zeigt eine klare Meldung, die den Kunden bittet, Sie zu kontaktieren.

## Eine Bestellung im Back-Office verwalten

Auf der Bestellseite zeigt das Panel **Lizenzschlüssel und Downloads** jede digitale Position mit ihren Schlüsseln, deren Gültigkeit, den aktivierten Geräten, den Downloads und den letzten fünf Zugriffen (Datum, IP).

- **Jetzt ausliefern / erneut versuchen**: verarbeitet die Bestellung unabhängig vom Status. Nützlich für eine Bestellung, die vor der Aktivierung des Produkts aufgegeben wurde, oder wenn der Mitarbeiter, der den Status geändert hat, keine Berechtigung für das Modul hat (PrestaShop führt die Hooks des Moduls dann nicht aus).
- **E-Mail erneut senden**.
- Einen Schlüssel **ersetzen**: Er wird widerrufen und der Kunde erhält einen neuen.
- **Downloads zurücksetzen**: setzt den Zähler auf null und verlängert den Link um die Gültigkeit des Produkts.
- **Aktivierungen zurücksetzen** für einen Schlüssel.
- **Alles widerrufen** und **Reaktivieren**: Die Reaktivierung stellt die mit der Bestellung widerrufenen Schlüssel wieder her, nicht die von Hand ersetzten.

## Seite Katalog > Lizenzschlüssel

### Schlüssel

Die Tabelle **Bestand pro Produkt** zeigt für jedes Produkt die verfügbaren, ausgelieferten und widerrufenen Schlüssel sowie die wartenden Positionen. Produkte mit niedrigem Bestand sind hervorgehoben. Die Schlüsselliste lässt sich nach Produkt, Status, exaktem Schlüssel, Bestellreferenz oder -ID und Charge filtern. Schlüssel sind standardmäßig maskiert (Augen-Button zum Anzeigen, Kopieren-Button). Aktionen: widerrufen und ersetzen, widerrufenen Schlüssel zurück in den Bestand, verfügbaren oder widerrufenen Schlüssel löschen, Aktivierungen zurücksetzen, CSV-Export der gefilterten Schlüssel.

### Auslieferungen

Alle ausgelieferten oder wartenden Positionen, wartende zuerst, filterbar nach Status, Bestellreferenz oder -ID und Kunden-E-Mail. Aktionen: erneut versuchen, erneut senden, Downloads zurücksetzen.

## Lizenz-API

Aktivieren Sie **Lizenz-API aktivieren** in den Einstellungen. Die Konfigurationsseite zeigt die Adresse der API, ein curl-Beispiel und die Liste der Fehlercodes.

Endpunkt: `https://ihr-shop.de/module/dflicensekeys/api` (POST oder GET). Parameter:

- `action`: `validate`, `activate` oder `deactivate`.
- `license_key`: der vom Kunden eingegebene Schlüssel.
- `instance`: eindeutige Kennung des Geräts, der Domain oder der Installation, erforderlich für activate und deactivate.
- `label`: optionaler lesbarer Name für den Kunden („Büro-PC“).
- `product_id`: optional, beschränkt die Prüfung auf ein Produkt.
- `secret`: nur erforderlich, wenn **API-Secret verlangen** aktiv ist. Aktivieren Sie es, wenn nur Ihr Server die API aufruft, nicht wenn die Software sie vom Rechner des Kunden aus aufruft.

Die JSON-Antwort enthält `success`, `error` und ein Objekt `license`: `status` (active, revoked, expired), `product_id`, `product_name`, `purchased_at`, `expires_at`, `max_activations`, `activations`, `activated`.

```
curl -X POST "https://ihr-shop.de/module/dflicensekeys/api"
  -d action=activate
  -d license_key=ABCD-EFGH-JKLM-NPQR
  -d instance=7f3c9a1e-arbeitsplatz
  -d label="Büro-PC"
```

Fehlercodes: 404 `invalid_license` (unbekannter oder noch nicht verkaufter Schlüssel), 403 `license_revoked` oder `license_expired`, 403 `activation_limit_reached`, 400 `missing_instance` oder `unknown_action`, 401 `invalid_secret`, 429 `too_many_failed_attempts` (mehr als 30 Fehlversuche pro Stunde von derselben IP).

Rufen Sie `activate` bei der ersten Eingabe des Schlüssels auf und danach `validate` mit derselben `instance` beim Start der Software. Eine bereits für dieses Gerät erfasste Aktivierung wird nie doppelt gezählt.

## DSGVO und Hooks für Entwickler

Mit dem offiziellen Modul psgdpr enthält der Datenexport eines Kunden seine Schlüssel, deren Daten, die Downloads und die aktivierten Geräte. Beim Löschen eines Kunden werden seine Auslieferungen und Aktivierungen anonymisiert und das Download-Protokoll gelöscht: Die Schlüssel bleiben gültig, da sie bezahlt wurden.

Zwei Hooks binden ein CRM oder einen externen Lizenzserver an:

- `actionDfLicenseKeysDelivered`: id_order, id_order_detail, id_customer, id_product, id_product_attribute, new_keys, keys (Schlüssel im Klartext).
- `actionDfLicenseKeysRevoked`: id_order.

## Fehlerbehebung

### Der Kunde hat seine Schlüssel nicht erhalten

Prüfen Sie, ob der Bestellstatus unter **Ausliefern, wenn die Bestellung diesen Status erreicht** ausgewählt ist, und klicken Sie in der Bestellung auf **Jetzt ausliefern / erneut versuchen**. Zeigt das Panel ausgelieferte Schlüssel, klicken Sie auf **E-Mail erneut senden** und prüfen Sie die E-Mail-Konfiguration von PrestaShop.

### Bestellungen bleiben auf „Wartet auf Schlüssel“

Der Bestand des Produkts (oder der Kombination) ist leer. Importieren Sie Schlüssel: Wartende Bestellungen gehen automatisch raus. Prüfen Sie, ob die Option pro Kombination zur Kombination passt, in die Sie importieren.

### Schlüssel erscheinen als „[?]“ mit rotem Banner

Der Cookie-Schlüssel des Shops oder die Einstellung `DFLK_SECRET` hat sich geändert, oft nach einem Umzug. Stellen Sie die vorherige Datei `parameters.php` wieder her.

### Der Download-Link meldet, dass die Datei nicht verfügbar ist

Die Datei wurde vom Produkt entfernt oder aus dem Ordner `/download/` gelöscht. Laden Sie sie im Tab Module des Produkts erneut hoch.

### Die Produktmenge ist negativ

Bestellungen warten auf mehr Schlüssel, als der Bestand enthält. Importieren Sie Schlüssel, die Menge steigt von selbst wieder.

## Kompatibilität

- PrestaShop 8.0 bis 9.x, dieselbe ZIP deckt beide Zweige ab, alte und neue Produktseite.
- Architektur ModuleAdminController, ohne Composer-Abhängigkeit, PHP 7.2 und höher, Erweiterung openssl.
- Oberfläche und E-Mails auf Französisch, Englisch, Spanisch, Deutsch, Italienisch, Niederländisch, Polnisch und Portugiesisch.
