M0120 PDF-Gutscheine für Gambio
Handbuch und Technikübersicht
1. WAS DIESES MODUL LEISTET - UND WARUM
Gutscheine sind ein starkes Umsatzinstrument - aber der Weg von der Bestellung zum fertigen, einlösbaren Gutschein ist im Alltag lästig: Man muss einen Code erzeugen, ihn im Shop hinterlegen, ein ansprechendes Dokument gestalten und es dem Kunden zustellen. Genau diese Kette nimmt Ihnen unser Modul ab.
Aus einer Bestellung, die einen Gutschein-Artikel enthält, erzeugt das Modul auf Knopfdruck ein gestaltetes PDF: mit dem Betrag, einem echten, im Shop einlösbaren Gutschein-Code, dem Datum und optional dem Namen des Beschenkten - alles auf einer von Ihnen gestalteten Hintergrundvorlage. Das PDF können Sie ausdrucken (z. B. zum Beilegen) oder automatisch per E-Mail an den Kunden versenden. Der zugehörige Code wird dabei als vollwertiger Gambio-Gutschein angelegt.
Der Grundgedanke ist, dass Sie sich um die Gestaltung genau einmal kümmern und danach jeder Gutschein ohne Handarbeit entsteht - einzeln, im Stapel oder vollautomatisch über eine zeitgesteuerte Aufgabe.
2. DER ABLAUF IM ÜBERBLICK
Damit die einzelnen Kapitel im Zusammenhang stehen, hier zunächst der rote Faden:
- Einmalig einrichten: Einen oder mehrere Gutschein-Artikel im Shop anlegen (Kapitel 3), eine PDF-Hintergrundvorlage hochladen und die Felder darauf positionieren (Kapitel 5), im Setup die Grundwerte setzen (Kapitel 8).
- Der Kunde bestellt: Er legt den Gutschein-Artikel in den Warenkorb, bestimmt den Betrag und schließt die Bestellung ab.
- Sie erzeugen den Gutschein: Sobald die Bestellung im passenden (bezahlten) Status ist, drucken oder versenden Sie den Gutschein - aus der Bestellung, aus der Übersicht oder automatisch per Cronjob (Kapitel 6).
- Das Modul erledigt den Rest: Es erzeugt den Code als echten Gutschein, füllt die Vorlage, legt das PDF ab und markiert die Position als erledigt, damit nichts doppelt entsteht.
3. GUTSCHEIN-ARTIKEL: WELCHE ARTIKEL ERZEUGEN GUTSCHEINE?
Das Modul muss wissen, welche Ihrer Artikel überhaupt Gutscheine sind. Dafür gibt es zwei Wege, die sich ergänzen:
- Über das Artikel-Modell: Jeder Artikel, dessen Artikel-Nummer (Modell) mit GIFT_ beginnt, gilt automatisch als Gutschein-Artikel. Das ist der schnellste Weg und braucht keine weitere Einstellung.
- Über die Setup-Liste: Zusätzlich können Sie im Setup unter "Gutschein-Artikel" beliebige weitere Artikel-Nummern kommagetrennt hinterlegen. So machen Sie auch Artikel ohne GIFT_-Präfix zu Gutscheinen.
Ob ein Gutschein-Artikel seinen Wert über die Menge kumuliert (ein Gutschein über Preis × Menge) oder je Stück einen eigenen Gutschein ergibt, steuern Sie am Artikel. Damit lässt sich sowohl ein Wertgutschein mit frei wählbarem Betrag als auch ein fester Gutschein (z. B. "25-€-Gutschein") abbilden.
4. DEN BETRAG BESTIMMEN LASSEN
4.1 Betrag über die Menge (empfohlen)
Der einfachste und sicherste Weg, dem Kunden einen frei wählbaren Betrag zu ermöglichen, ist die Menge: Bei einem Gutschein-Artikel mit dem Grundpreis 1,00 € wählt der Kunde die Menge - 50 Stück ergeben einen 50-€-Gutschein. Der große Vorteil: Der bezahlte Preis und der Gutscheinwert stimmen automatisch überein, weil die Menge beides gleichzeitig festlegt.
4.2 Mehrere Gutscheine, gleiche Beträge: der GX-Customizer
Möchte ein Kunde in einer Bestellung mehrere Gutscheine kaufen, entsteht im Standard-Warenkorb ein bekanntes Problem: Zwei gleiche Artikel werden zu einer Position mit summierter Menge zusammengefasst - aus einem 50-€- und einem 20-€-Gutschein würde ein einzelner 70-€-Gutschein.
Die saubere Lösung ist der GX-Customizer von Gambio. Legen Sie am Gutschein-Artikel ein Customizer-Set mit mindestens einem Eingabefeld an (z. B. für den Empfängernamen). Sobald ein Artikel ein Customizer-Set trägt, behandelt Gambio jede Hinzufügung als eigenständige, personalisierte Position - selbst bei identischen Eingaben. Dadurch bleiben mehrere Gutscheine im Warenkorb getrennt und werden zu getrennten PDFs, während der Betrag weiterhin sauber über die Menge bestimmt wird.
4.3 Empfängername auf dem Gutschein
Nutzen Sie ein Customizer-Feld für den Namen des Beschenkten, kann das Modul diesen Namen auf den Gutschein drucken. Im Setup hinterlegen Sie dazu unter "GX-Customizer: Empfängerfelder", wie das Eingabefeld heißt (mehrsprachig, kommagetrennt). Ist das Feld beim Kunden befüllt, hat dieser Name Vorrang vor der allgemeinen Einstellung "Druck Begünstigter"; bleibt es leer, greift wieder die allgemeine Einstellung.
5. PDF-VORLAGEN UND DIE FELD-POSITIONIERUNG
Eine Vorlage besteht aus zwei Teilen: dem gestalteten Hintergrund-PDF (Ihr Layout, Logo, Rahmen) und der Feld-Konfiguration, die festlegt, wo Name, Betrag, Code und Datum daraufgedruckt werden.
Die Hintergrund-PDFs legen Sie per FTP im Vorlagen-Verzeichnis des Moduls ab; einige fertige Farbvorlagen sind bereits enthalten. Im Modul-Bereich "Vorlagen" verbinden Sie ein solches PDF mit einer Feld-Konfiguration: Für jedes der vier Felder legen Sie Position (X/Y in Millimetern), Schriftgröße und Schriftart fest.
Damit Sie die Positionen nicht raten müssen, gibt es zwei Hilfen: den Objekt-Editor, in dem Sie die Felder mit der Maus auf der Vorlage an die richtige Stelle ziehen, und die Voransicht, die ein Muster-PDF mit Ihren aktuellen (auch noch nicht gespeicherten) Werten erzeugt. Für exakte Positionen sollte der Browser-Zoom auf 100 % stehen.
Welche Vorlage für eine Bestellung genutzt wird, lässt sich flexibel steuern: es gibt eine Standard-Vorlage für den ganzen Shop, optional eine Vorlage je Artikel und optional eine Auswahl über Varianten/Optionen oder Eigenschaften. Zusätzlich kann je Sprache eine eigene Variante der Vorlage hinterlegt werden.
6. DRUCKEN UND VERSENDEN
Gutscheine entstehen nie automatisch beim Bestelleingang, sondern immer bewusst - entweder von Ihnen ausgelöst oder über eine von Ihnen eingerichtete zeitgesteuerte Aufgabe. So behalten Sie die Kontrolle, wann ein Code erzeugt und eine Mail verschickt wird.
6.1 Aus der einzelnen Bestellung
In der Bestellansicht finden Sie einen eigenen Bereich "PDF-Gutscheine" mit den Schaltflächen Gutscheine drucken und Gutscheine versenden. Wurden für die Bestellung bereits Gutscheine erzeugt, listet der Bereich diese zusätzlich auf - jeweils mit einem Link zum Öffnen des PDFs, dem Code und dem Versanddatum. So können Sie erzeugte Gutscheine jederzeit noch einmal ansehen und prüfen.
6.2 Aus der Bestellübersicht (Einzeln und Sammel)
In der Bestellübersicht kennzeichnet ein Symbol Bestellungen, die Gutscheine enthalten, und zeigt an, ob diese bereits erzeugt wurden bzw. ob die Bestellung als bezahlt gilt. Über die Zeilen-Aktion versenden Sie den Gutschein einer einzelnen Bestellung; über die Sammelaktion verarbeiten Sie mehrere ausgewählte Bestellungen auf einmal (drucken oder versenden).
6.3 Automatisch per Cronjob
Für den Vollautomatik-Betrieb bringt das Modul eine zeitgesteuerte Aufgabe mit. Ist sie aktiv, prüft das Modul regelmäßig alle passenden, bezahlten Bestellungen, erzeugt die Gutscheine und versendet sie - ganz ohne Ihr Zutun. Sie aktivieren und konfigurieren die Aufgabe im Bereich "Toolbox" ▶ "Zeitgesteuerte Aufgaben".
6.4 Der Testmodus (Admin-Mode)
Zum Einrichten und Justieren der Vorlagen gibt es den Admin-Mode. Ist er aktiv, wird jeder Gutschein bei jedem Klick neu erzeugt, es wird kein echter Code angelegt (statt eines Codes erscheint ein Test-Platzhalter), nichts wird als erledigt markiert, und alle Mails gehen an den Shopinhaber statt an den Kunden. So können Sie beliebig ausprobieren, ohne echte Gutscheine zu verbrauchen.
7. GUTSCHEINE IM KUNDENKONTO
Auf Wunsch kann der Kunde seine Gutschein-PDFs auch selbst im Kundenkonto herunterladen (Einstellung "Download im Konto"). Der Download ist abgesichert: Jeder Kunde erhält ausschließlich die zu seinen eigenen Bestellungen gehörenden Gutscheine, und die Dateien tragen einen nicht erratbaren Namen. So kann niemand durch Ausprobieren an fremde Gutscheine gelangen.
8. DAS MODUL-SETUP: ALLE WERTE IM DETAIL
Die folgenden Einstellungen finden Sie im Modul-Setup. Der jeweils vorgeschlagene Auslieferungswert steht in Klammern.
| Einstellung | Bedeutung |
|---|---|
| Modulstatus (Standard: eingeschaltet) | Schaltet das Modul komplett ein oder aus. Ist es aus, laufen keinerlei Gutschein-Prozesse und die Bedienelemente erscheinen nicht. |
| Admin-Mode (Standard: eingeschaltet) | Testmodus (siehe 6.4). Für den Livebetrieb ausschalten. |
| Mindest-Bestell-Nr (Standard: leer) | Wichtiger Parameter. Bis zu dieser Bestellnummer (einschließlich) gelten alle Bestellungen als bereits erledigt und werden nicht mehr verarbeitet. Verhindert, dass Alt-Bestellungen nachträglich Gutscheine erhalten. Ohne einen Wert verarbeitet das Modul nichts. |
| PDF-Vorlage (Standard: leer) | Dateiname der Standard-Hintergrundvorlage, die genutzt wird, wenn am Artikel keine eigene Vorlage hinterlegt ist. |
| Gutschein-Artikel (Standard: leer) | Zusätzliche Artikel-Nummern (kommagetrennt), die als Gutschein gelten. Artikel mit GIFT_-Präfix sind ohnehin immer eingeschlossen. |
| GX-Customizer: Empfängerfelder (Standard: recipient, Voucherrecipient, Gutscheinempfänger) | Feld-Bezeichnungen des Customizers, die den Empfängernamen enthalten - inkl. Sprachvarianten. Bei Treffer wird dieser Name gedruckt. |
| GX-Customizer: Betragsfelder (Standard: leer) | Optional und in der Regel leer lassen. Nur für Sonderfälle, in denen der Betrag über ein Customizer-Feld erfasst wird - mit dem in 4.2 genannten Preis-Vorbehalt. |
| Default-Schriftgröße (Standard: 20) | Schriftgröße, wenn in der Feld-Konfiguration nichts anderes gesetzt ist. |
| Default-Schrift (Standard: courier) | Schriftart, wenn in der Feld-Konfiguration nichts anderes gesetzt ist. |
| Anzeige nach Versand (Standard: nein) | Ob die erzeugten Gutschein-PDFs direkt nach dem Versand aus der Übersicht heraus geöffnet werden. |
| Status nach Versand (Standard: leer) | Bestellstatus, der nach dem Versand automatisch gesetzt wird (optional). |
| Kommentar nach Versand (Standard: nein) | Ob beim Statuswechsel ein Kommentar in der Bestellhistorie erzeugt wird. |
| Druck Begünstigter (Standard: nein) | Ob der kaufende Kunde als Begünstigter aufgedruckt wird. Ein befülltes Customizer-Empfängerfeld hat Vorrang. |
| Download im Konto (Standard: nein) | Ob Kunden ihre Gutschein-PDFs im Kundenkonto herunterladen dürfen. |
| PDF-Konfiguration (Standard: leer) | Optionaler Bereich für Zusatzkonfigurationen wie eigene Schriften (siehe Handbuch-Hinweise zu Zusatzschriften). |
9. HÄUFIGE STOLPERSTEINE
- Es passiert nichts beim Verarbeiten. Meist ist die Mindest-Bestell-Nr nicht gesetzt (dann verarbeitet das Modul bewusst nichts) oder die Bestellung ist noch nicht im als "bezahlt" geltenden Status.
- Codes fehlen, Mails kommen beim Shopinhaber an. Dann ist der Admin-Mode noch aktiv - für den Livebetrieb ausschalten.
- Zwei gleiche Gutscheine werden zusammengefasst. Ohne ein Customizer-Set fasst der Warenkorb identische Positionen zusammen. Legen Sie am Artikel ein Customizer-Set an (Kapitel 4.2).
- Der Gutscheinwert ist höher als der bezahlte Preis. Dann wurde der Betrag über ein Customizer-Textfeld erfasst - dieses ist nicht preiswirksam. Betrag über die Menge bestimmen (Kapitel 4.1).
- Der Empfängername erscheint nicht. Prüfen Sie, ob die Feld-Bezeichnung im Setup unter "Empfängerfelder" exakt (in allen genutzten Sprachen) hinterlegt ist.
- Fehlermeldung zu fehlender Vorlage oder Konfiguration. Das Hintergrund-PDF fehlt im Vorlagen-Verzeichnis oder es ist noch keine Feld-Konfiguration dazu gespeichert.
- Felder sitzen leicht daneben. Für exakte Positionen im Objekt-Editor und in der Voransicht den Browser-Zoom auf 100 % stellen.
10. GROBE TECHNISCHE INFOS
Dieser Abschnitt richtet sich an technisch interessierte Betreiber und Support. Für die tägliche Bedienung ist er nicht nötig.
- Einstellungen: liegen in der Xycons-Konfigurationstabelle des Shops (nicht in der Gambio-Standardkonfiguration).
- Eigene Tabelle: Das Modul legt eine Tabelle für die Vorlagen an, in der je Vorlage die Feld-Positionen, -Größen und -Schriften gespeichert sind.
- Genutzte Gambio-Standarddaten: Bestellungen und Bestellpositionen (zum Ermitteln der Gutscheine und Beträge), die Gutschein-/Coupon-Tabellen (dort wird der einlösbare Code angelegt) sowie der allgemeine Zusatzdatenspeicher, in dem je Bestellposition vermerkt wird, welcher Gutschein erzeugt und wann er versandt wurde. Diese Merker verhindern doppelte Erzeugung.
- GX-Customizer: Ist am Artikel ein Customizer-Set aktiv, liest das Modul die eingegebenen Werte (z. B. Empfängername) aus den zugehörigen Customizer-Bestelldaten je Bestellposition.
- Ablage der PDFs: Die erzeugten Gutschein-PDFs liegen im Export-Verzeichnis des Shops und tragen einen zufälligen Namensbestandteil. Der Kunden-Download erfolgt ausschließlich über eine geschützte Auslieferung mit Besitzprüfung, sodass niemand fremde Gutscheine über die Adresse erraten kann.
- Schutz der Bedienung: Alle auslösenden Backend-Aktionen sind gegen Fremdauslösung (CSRF) abgesichert; Datei-Uploads für Vorlagen sind auf PDF beschränkt.
- Zeitsteuerung: Die automatische Verarbeitung läuft über eine zeitgesteuerte Aufgabe unter Toolbox ▶ Zeitgesteuerte Aufgaben.
(c) Xycons GmbH & Co. KG - www.xycons.de · Handbuch zu den PDF-Gutscheinen · Stand 2026-07-23
