PDF-Rechnungen: Template und Variablen
Das Rechnungs-Template des PDF-Rechnungen Moduls für OXID eShop 7.x: Aufbau, Zahlungsart-Blöcke, vollständige Liste der Template-Variablen und Hinweise zur Anpassung.
PDF-Rechnungen: Template und Variablen
Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.
Das Aussehen der Rechnung wird von einem einzigen Twig-Template bestimmt. Diese Seite beschreibt den Aufbau, die Zahlungsart-Blöcke und die Variablen, die das Modul an das Template übergibt.
Das Rechnungs-Template
| Eigenschaft | Wert |
|---|---|
| Datei im Modul | views/twig/pdf/invoice.html.twig |
| Template-Name im Modul | @mmd_pdfinvoice/pdf/invoice |
| PDF-Engine | Dompdf (A4 hochkant, Standardschrift DejaVu Sans) |
Das Modul rendert immer genau dieses Template unter dem festen Namen @mmd_pdfinvoice/pdf/invoice. Eine Einstellung, um ein anderes Template auszuwählen, gibt es nicht.
Das Template enthält die Beschriftungen fest auf Deutsch (zum Beispiel "Rechnungsnummer", "Zwischensumme (netto)", "Vielen Dank für Ihren Einkauf!"). Die PDF-Rechnung wird daher unabhängig von der Shop-Sprache auf Deutsch erstellt.
Aufbau der Rechnung
- Kopfbereich mit Logo (oder Shop-Name, wenn kein Logo gefunden wird) und Firmenanschrift
- Adressfeld mit Absenderzeile und Rechnungsadresse des Kunden
- Rechnungsdaten neben dem Adressfeld: Rechnungsnummer, Rechnungsdatum, Bestellnummer, Bestelldatum, USt-IdNr. des Kunden (falls vorhanden), Zahlungsart
- Positionen mit Art.-Nr., Bezeichnung (mit gewählter Variante), Menge, Einzelpreis, MwSt.-Satz und Gesamt (jeweils netto)
- Summen mit Zwischensumme (netto), MwSt.-Aufschlüsselung, Versandkosten, Zahlungsartkosten, Rabatt und Gesamtbetrag
- Zahlungsinformationen, abhängig von der Zahlungsart
- Fußzeile mit Firmendaten, Kontaktdaten, Steuerangaben und Bankverbindung
Versandkosten, Zahlungsartkosten und Rabatt erscheinen nur, wenn der jeweilige Betrag größer als 0 ist. Die Lieferadresse und die Bestellnotiz werden zwar an das Template übergeben, das mitgelieferte Template gibt sie aber nicht aus.
Zahlungsart-Blöcke
Der Block "Zahlungsinformationen" hängt von der OXID-Zahlungsart-ID ab (payment.type):
| Zahlungsart-ID | Ausgabe |
|---|---|
oxidpayadvance (Vorauskasse) |
Bitte Betrag innerhalb von 7 Tagen auf das Konto des Shops überweisen (Bankname, IBAN, Verwendungszweck) |
oxidinvoice (Rechnung) |
Bitte Betrag innerhalb von 14 Tagen auf das Konto des Shops überweisen (Bankname, IBAN, Verwendungszweck) |
oxiddebitnote (Lastschrift) |
Hinweis auf den SEPA-Einzug mit Betrag, Datum und IBAN des Kunden, Gläubiger-ID, Mandatsreferenz und Kontoinhaber |
| alle anderen | kein eigener Zahlungsblock, nur die Zahlungsart in den Rechnungsdaten |
Beim SEPA-Block gelten diese Rückfallwerte des Templates:
- Einzugsdatum:
invoice.debit_date, wenn es nicht gesetzt ist (das Modul setzt es nicht), das Rechnungsdatum - Mandatsreferenz:
payment.mandate_ref, wenn es nicht gesetzt ist (das Modul setzt es nicht), der TextBESTELL-gefolgt von der Bestellnummer - Gläubiger-ID: wird nur ausgegeben, wenn sie in den Moduleinstellungen hinterlegt ist
Template anpassen
Das Modul bietet keinen eigenen Mechanismus für ein ausgetauschtes Template. Änderungen erfolgen direkt in views/twig/pdf/invoice.html.twig im Modulverzeichnis (source/modules/mmd/pdf-invoice).
Änderungen an der Template-Datei im Modulverzeichnis gehen bei einem Update über Composer verloren. Sichere deine angepasste Datei und spiele sie nach jedem Update wieder ein.
Nach einer Änderung leerst du den Cache (vendor/bin/oe-console oe:cache:clear). Bereits erstellte Rechnungen ändern sich dadurch nicht. Erst der Button "PDF neu generieren" in der Bestellung rendert das PDF mit dem aktuellen Template neu.
Verfügbare Variablen
Die Variablen in den folgenden Tabellen stehen sowohl bei der Erstellung einer Rechnung als auch bei der Neugenerierung aus dem Snapshot zur Verfügung. Zusätzliche Variablen, die nur bei der Neugenerierung vorhanden sind, findest du im Abschnitt "Nur bei der Neugenerierung verfügbar".
Rechnung (invoice.)
| Variable | Beschreibung |
|---|---|
invoice.number |
Rechnungsnummer |
invoice.date |
Rechnungsdatum, Format TT.MM.JJJJ |
Bestellung (order.)
| Variable | Beschreibung |
|---|---|
order.number |
Bestellnummer |
order.date |
Bestelldatum, Format TT.MM.JJJJ |
order.currency |
Währung, zum Beispiel EUR |
order.remark |
Bestellnotiz des Kunden (vom mitgelieferten Template nicht ausgegeben) |
Rechnungsadresse (billing.)
| Variable | Beschreibung |
|---|---|
billing.salutation |
Anrede |
billing.company |
Firma |
billing.firstname |
Vorname |
billing.lastname |
Nachname |
billing.street |
Straße |
billing.streetnr |
Hausnummer |
billing.addinfo |
Adresszusatz |
billing.zip |
PLZ |
billing.city |
Ort |
billing.country |
Land |
billing.vatid |
USt-IdNr. des Kunden |
Lieferadresse (delivery.)
Die Variable delivery ist leer (null), wenn in der Bestellung kein Nachname der Lieferadresse hinterlegt ist. Sonst enthält sie salutation, company, firstname, lastname, street, streetnr, addinfo, zip, city und country mit derselben Bedeutung wie bei der Rechnungsadresse.
Positionen (items)
items ist eine Liste. Jedes Element enthält:
| Variable | Beschreibung |
|---|---|
item.artnum |
Artikelnummer |
item.title |
Artikelbezeichnung |
item.selvariant |
Gewählte Variante |
item.amount |
Menge |
item.nprice |
Einzelpreis netto (Feld oxnprice) |
item.netprice |
Gesamtpreis der Position netto (Feld oxnetprice) |
item.brutprice |
Gesamtpreis der Position brutto (Feld oxbrutprice) |
item.price |
Einzelpreis aus dem Feld oxprice der Bestellposition |
item.vatpercent |
MwSt.-Satz in Prozent |
Summen (totals.)
| Variable | Beschreibung |
|---|---|
totals.netsum |
Nettosumme der Artikel |
totals.brutsum |
Bruttosumme der Artikel |
totals.totalsum |
Gesamtbetrag der Bestellung |
totals.delcost |
Versandkosten |
totals.paycost |
Zahlungsartkosten |
totals.discount |
Rabatt |
totals.vat_breakdown |
Liste der MwSt.-Beträge, je Eintrag rate (Satz) und amount (Betrag) |
Zahlung (payment.)
| Variable | Beschreibung |
|---|---|
payment.type |
OXID-Zahlungsart-ID, zum Beispiel oxidpayadvance |
payment.name |
Bezeichnung der Zahlungsart |
payment.debit.iban |
IBAN des Kunden (nur bei Lastschrift) |
payment.debit.owner |
Kontoinhaber (nur bei Lastschrift) |
payment.debit.bic |
BIC bzw. Bankleitzahl des Kunden (nur bei Lastschrift) |
payment.debit.bankname |
Bankname des Kunden (nur bei Lastschrift) |
Die payment.debit.*-Werte sind nur vorhanden, wenn die Zahlungsart oxiddebitnote ist und die Bankdaten in der Bestellung gefunden wurden.
Shop (shop.)
Diese Werte stammen aus den Stammdaten des aktiven Shops. Sie werden bei jeder Erzeugung oder Neugenerierung des PDFs neu gelesen.
| Variable | Beschreibung |
|---|---|
shop.name |
Shop-Name |
shop.company |
Firmenname |
shop.street |
Straße |
shop.zip |
PLZ |
shop.city |
Ort |
shop.country |
Land |
shop.phone |
Telefon |
shop.fax |
Fax |
shop.email |
E-Mail-Adresse |
shop.vatid |
USt-IdNr. |
shop.taxnumber |
Steuernummer |
shop.hrb |
Handelsregisternummer |
shop.court |
Registergericht |
shop.bank_name |
Bankname |
shop.bank_code |
Bankleitzahl |
shop.bank_account |
Kontonummer |
shop.iban |
IBAN |
shop.bic |
BIC |
shop.creditor_id |
SEPA-Gläubiger-ID aus den Moduleinstellungen |
Sonstiges
| Variable | Beschreibung |
|---|---|
config.logo |
Absoluter Dateipfad (file://...) des Logos, oder leer, wenn kein Logo gefunden wurde |
locale |
Sprachkürzel der aktuellen Shop-Sprache, zum Beispiel de |
Die Variablen
invoice.debit_dateundpayment.mandate_refwerden vom Modul nicht gesetzt. Sie sind im mitgelieferten Template nur als optionale Werte mit Rückfallwert vorgesehen.
Nur bei der Neugenerierung verfügbar
Bei der Neugenerierung ("PDF neu generieren") gibt das Modul die gespeicherten Snapshot-Daten für Adressen und Positionen unverändert an das Template. Der Snapshot enthält dabei einige Felder, die beim ersten Erstellen der Rechnung nicht an das Template übergeben werden. Diese Variablen sind nur verfügbar, wenn das PDF aus dem Snapshot neu erzeugt wird:
| Variable | Beschreibung |
|---|---|
billing.country_id |
ID des Landes der Rechnungsadresse |
billing.state |
ID des Bundeslands der Rechnungsadresse |
billing.phone |
Telefon der Rechnungsadresse |
billing.fax |
Fax der Rechnungsadresse |
billing.email |
E-Mail-Adresse der Rechnungsadresse |
delivery.country_id |
ID des Landes der Lieferadresse |
delivery.state |
ID des Bundeslands der Lieferadresse |
delivery.phone |
Telefon der Lieferadresse |
delivery.fax |
Fax der Lieferadresse |
item.shortdesc |
Kurzbeschreibung des Artikels |
item.vat |
MwSt.-Betrag der Position (Feld oxvatprice) |
item.bprice |
Bruttoeinzelpreis (Feld oxbprice) |
item.weight |
Gewicht der Position |
Das mitgelieferte Template verwendet diese Variablen nicht. Wenn du sie in einem angepassten Template nutzt, bleiben sie bei einer neu erstellten Rechnung leer, solange das PDF nicht neu generiert wurde.
Eigene Zahlungsart ergänzen
Für eine weitere Zahlungsart ergänzt du im Template einen zusätzlichen Zweig. Die ID entspricht der OXID-Zahlungsart-ID aus oxpayments.OXID:
{% elseif payment.type == 'ihre_zahlungsart_id' %}
<div class="payment-info">
<h4>Zahlungsinformationen</h4>
<p>Ihre spezifischen Zahlungsinformationen hier...</p>
</div>
Weiterführende Seiten
- Konfiguration: Logo, Gläubiger-ID und Speicherpfad
- Technik: Ablauf der PDF-Erzeugung und Snapshot-Aufbau