Shortcodes für Rechnungen & Lieferscheine

Shortcodes stellen ein mächtiges Werkzeug dar, um dynamische Informationen im Dokument zu platzieren. Germanized Pro stellt Shortcodes speziell für Dokumente zur Verfügung. Dabei gibt es, je nach Position im Dokument, verschiedene Shortcodes, die verwendet werden können. Grundsätzlich können mit Hilfe von Shortcodes Daten aus dem jeweiligen Dokument, oder dessen Referenz (z.B. der dazugehörigen Bestellung oder im Falle eines Lieferscheins auch der Sendung) ausgegeben werden. Das funktioniert im Normalfall natürlich erst, wenn ein konkretes Dokument erzeugt wird. Für die Vorschau im Editor gibt es nur eine begrenzte Anzahl unterstützter Shortcodes. Dazu erfährst du hier mehr.

Achtung: Wenn du die Shortcodes hier kopierst und direkt in den Editor einfügst, kann es passieren, dass das HTML-Markup mit eingefügt wird. Nutze den Plain-Text-Einfügen-Modus (z.B. Shift + CMD + V für Mac).

Attribute der Shortcodes

Das Attribut data ist die Bezeichnung des abzurufenden Datensatzes. Beispielsweise enthält jede Rechnung und jeder Lieferschein das Attribut first_name (der Vorname des Empfängers). Wenn du diese Daten abfragen möchtest, ginge das über das Attribut folgendermaßen: data="first_name".

Das Attribut format kann optional ein spezielles Datenformat übergeben. Handelt es sich z.B. um ein Datum, wird das Standard-Datumsformat von WordPress verwendet. Möchtest du dein Datum mit einem speziellen Datumsformat formatieren, ginge das über das Attribut folgendermaßen: format="d.m.Y".

Daten des Dokuments [document]

Je nach Dokumententyp (z.B. Rechnung, Stornierung, Lieferschein oder rechtl. Hinweisseite) gibt es unterschiedliche Shortcodes (bzw. Daten) die für das Dokument zur Verfügung stehen. Eine Rechnung besitzt natürlich ganz andere Daten, als ein Lieferschein.

Zusätzlich dazu, kann ein Dokument (oder eine Referenz, z.B. eine Bestellung) beliebige Meta-Daten besitzen (die z.B. von Drittanbieter-Plugins zusätzlich gespeichert werden), sodass eine vollständige Liste verfügbare Shortcode-Kombinationen nicht angegeben werden kann. Dennoch möchten wir euch natürlich ein paar Beispiele präsentieren.

Rechnungen und Stornierungen

• [document data="total"] Gibt den Gesamtbetrag aus.
• [document data="total_tax"] Gibt den MwSt.-Gesamtbetrag aus.
• [document data="total_net"] Gibt den Netto-Gesamtbetrag aus.
• [document data="vat_id"] Gibt die USt.-ID aus.
• [document data="payment_method_title"] Gibt die Zahlungsart aus.
• [document data="payment_transaction_id"] Gibt die Transaktionsnummer aus.
• [document data="date_paid"] Gibt das Datum der Zahlung aus.
• [document data="date_due"] Gibt das Datum der Fälligkeit aus.
• [document data="date_created"] Gibt das Erstellungsdatum aus.
• [document data="date_of_service"] Gibt den Anfang des Leistungszeitraums aus.
• [document data="date_of_service_end"] Gibt das Ende des Leistungszeitraums aus.
• [document data="date_of_service_period"] Gibt (falls verfügbar) den Leistungszeitraum (von – bis) bzw. den Start aus.
• [document data="order_number"] Gibt die Bestellnummer aus.
• [document data="total" format="price"] Gibt den formatierten Gesamtbetrag aus.

Rechnungen, Stornierungen und Lieferscheine

• [document data="formatted_number"] Gibt die formatierte, fortlaugende Nummer aus.
• [document data="first_name"] Gibt den Vornamen aus.
• [document data="last_name"] Gibt den Nachnamen aus.
• [document data="email"] Gibt die E-Mail-Adresse aus.
• [document data="phone"] Gibt die Telefonnummer, falls verfügbar, aus.
• [document data="formatted_full_name"] Gibt den kompletten Namen aus.
• [document data="formatted_address"] Gibt die formatierte Adresse aus.

Daten der Position [document_item]

Mit Positionen sind die einzelnen Zeilen bzw. Produkte in einem Dokument gemeint. Dieser Shortcode ist nur gültig innerhalb des Positionen Tabelle Blocks, d.h. der Shortcode kann nur dort ausgeführt werden, wo auch wirklich eine konkrete Position ausgegeben wird (anderenfalls wüsste das Plugin nicht, welche Position gemeint ist).

Rechnungen, Stornierungen und Lieferscheine

• [document_item data="total"] Gibt den Gesamtbetrag aus.
• [document_item data="price"] Gibt den Preis aus.
• [document_item data="quantity"] Gibt die Anzahl aus.
• [document_item data="sku"] Gibt die Artikelnummer aus.

Daten der Positionen-Referenz [document_item_reference]

Jede Position innerhalb eines Dokuments besitzt eine Referenz auf ein spezielles Objekt. Das kann im Falle der Rechnung z.B. eine Bestellposition (Produkt, Gebühr, Versand) sein. Im Falle des Lieferscheins handelt es sich um eine Referenz auf die Position der dazugehörigen Sendung.

Dieser Shortcode besitzt nur innerhalb des Blocks Positionen-Tabelle Gültigkeit, da es sich um Daten handelt, die sich auf eine spezielle Position beziehen.

Rechnungen und Stornierungen

• [document_item_reference data="total"] Gibt den Gesamtbetrag der Bestellposition aus.
• [document_item_reference data="custom_key"] Greift auf Meta-Daten der Bestellposition mit dem Schlüssel custom_key zurück.

Daten des Produkts [document_item_product]

Positionen eines Dokuments (abgesehen von Versand und Gebühren) besitzen im Normalfall (d.h. insofern das dazugehörige Produkt noch besteht) eine Verbindung zu einem konkreten Produkt. Dabei handelt es sich um das Produkt, das der Kunde bestellt hat. Manchmal ist es sinnvoll, Meta-Daten oder allg. Produktdaten in der Positionen-Tabelle auszugeben, z.B. wenn du eigene Daten zum Produkt verwaltest und diese auf der Rechnung oder auf dem Lieferschein mit abdrucken möchtest.

Dieser Shortcode besitzt nur innerhalb des Blocks Positionen-Tabelle Gültigkeit, da es sich um Daten handelt, die sich auf eine spezielle Position beziehen.

• [document_item_product data="sku"] Gibt die Artikelnummer des Produktes aus.
• [document_item_product data="custom_key"] Greift auf Meta-Daten des Produktes mit dem Schlüssel custom_key zurück.

Daten des Gesamtbetrags [document_total]

Rechnungen und Stornierungen besitzen eine Auflistung der Gesamtbeträge unterhalb der Tabelle. Diese Auflistung besteht aus mehreren, einzelnen Zeilen, die jeweils unterschiedliche Daten ausgeben. Innerhalb dieser Zeilen kann der Shortcode verwendet werden, um spezielle Daten dieser Zeile auszugeben.

• [document_total data="formatted_total"] Gibt den Gesamtbetrag aus.
• [document_total data="formatted_label"] Gibt die Beschriftung aus.
• [document_total data="rate"] Gibt, falls verfügbar, den Steuersatz aus.

Bestelldaten [order]

Rechnungen, Stornierungen und Lieferscheine haben eine direkte Referenz zu einer WooCommerce Bestellung. Insofern die Bestellung existiert (d.h. nicht gelöscht wurde) kann via Shortcode auf Bestelldaten zugegriffen werden. Dadurch das einige der Daten ebenfalls in dem eigentlichen Dokument existieren (d.h. synchronisiert werden), ist die Nutzung dieses Shortcodes nicht immer notwendig.

• [order data="total"] Gibt den Gesamtbetrag aus.
• [order data="order_number"] Gibt die Bestellnummer aus.
• [order data="payment_method_title"] Gibt die Zahlungsart aus.
• [order data="date_created"] Gibt das Datum aus.
• [order data="customer_note"] Gibt die Notiz des Kunden beim Kauf aus.
• [order data="shipping_method"] Gibt die verwendete Versandmethode aus.

Sendungsdaten [shipment]

Lieferscheine haben eine direkte Referenz zu einer Sendung. Diese Sendung kann spezielle Daten enthalten (z.B. Datum zum Versanddienstleister, zum Gewicht, zur Größe usw.). Insofern diese Daten beim Erstellen des Lieferscheins vorliegen, können sie via Shortcode einfach auf dem Lieferschein platziert werden.

• [shipment data="weight"] Gibt das Gesamtgewicht aus.
• [shipment data="shipment_number"] Gibt die Nummer der Sendung aus.
• [shipment data="formatted_dimensions"] Gibt die Größe aus.
• [shipment data="height"] Gibt die Höhe aus.
• [shipment data="shipping_provider_title"] Gibt den Versanddienstleister aus.
• [shipment data="tracking_id"] Gibt die Nummer zur Sendungsverfolgung aus.
• [shipment data="tracking_url"] Gibt die URL zur Sendungsverfolgung aus.

Kundendaten [customer]

Rechnungen und Stornierungen können einem bestimmten Kunden (User) zugeordnet werden, falls die Rechnung nicht an einen Gast ausgestellt wurde. Dieser Shortcode funktioniert also nur dann, wenn der zum Dokument gehörende Kunde auch ein Kundenkonto bei dir im Shop besitzt.

• [customer data="id"] Gibt die (eindeutige) ID des Kundenkontos aus.
• [customer data="nickname"] Gibt den Spitznamen aus.

Bedingte Abfragen

Alle hier aufgeführten Shortcodes können in einen bedingten Shortcode überführt werden.

Shortcodes, die einen vergleichenden Charakter haben, d.h. dafür genutzt werden um bedingte Unterscheidungen zu treffen, besitzen zusätzlich noch weitere Attribute. Du erkennst diese Shortcodes daran, dass sie mit einem if_ Präfix beginnen.

Das Attribut value gibt deinen Vergleichswert an. Wenn du z.B. prüfen möchtest, ob der Status einer Rechnung cancelled ist (d.h. storniert), kannst du value="cancelled" als Vergleichswert übergeben.

Das Attribut compare gibt an, wie du den Vergleich aufbauen möchtest. Du kannst dort folgende Werte übergeben: e (für equal, gleich), ne (für not equal, nicht gleich), empty (leer), nempty (nicht leer), lt (für lesser than, kleiner als) oder gt (greater than, größer als). Damit kannst du also so gut wie jeden Vergleich auf Basis der Daten durchführen.

Damit lassen sich Abfragen dynamisch erstellen. Man kann damit z.B. prüfen, ob für eine Rechnung ein Kundenkonto hinterlegt ist und nur in diesem Fall die Kundennummer ausgeben. Beispiel:

[if_document data="customer_id" compare="nempty"]
   Kundennummer: [document data="customer_id"]
[/if_document]

Jeder der o.g. Shortcodes kann also in einen If-Shortcode überführt werden. Wichtig ist, dass es sich bei diesen Shortcodes nicht um selbst-schließende Shortcodes handelt. Deshalb muss nach dem Öffnen des Shortcodes, der Shortcode auch wieder geschlossen werden. Als data Attribut kann hier theoretisch, wie oben in den einzelnen Shortcodes erläutert, jede Art von Datensatz abgefragt werden. So lässt sich z.B. auf dem Lieferschein abfragen, ob für eine Sendung ein bestimmter Versanddienstleister zugeordnet ist. Falls das korrekt ist, kann ein festgelegter Text ausgegeben werden:

[if_shipment data="shipping_provider" value="dhl"]
  Versand via DHL.
[/if_shipment]

Zahlungsstatus der Rechnung ausgeben

Der Zahlungsstatus der Rechnung kann recht schön per bedingtem Shortcode ausgeben werden. Dabei lässt sich das Attribut payment_status der Rechnung abfragen:

Zahlungsstatus der Rechnung: [if_document data="payment_status" value="complete"]Bezahlt[/if_document][if_document data="payment_status" value="complete" compare="nequals"]Offen[/if_document]

Hierbei wird entweder Bezahlt oder Offen ausgegeben, je nachdem welchen Status die Rechnung besitzt.

Zahlungsziel für unbezahlte Rechnungen angeben

Auf Rechnungen, die noch nicht bezahlt sind (d.h. die Rechnung wurde zu einem Zeitpunkt erstellt, zu dem noch keine Zahlung zur Bestellung verfügbar war) macht es Sinn ein Zahlungsziel anzugeben. Um zu prüfen, ob die Rechnung noch nicht bezahlt ist, eignet sich ein bedingter Shortcode:

[if_document data="is_paid" value="false"]Zahlbar innerhalb von 14 Tagen ab Rechnungsdatum[/if_document]

Zusätzlich könnte man auch das konkrete Fälligkeitsdatum ausgeben, das dynamisch für die Rechnung berechnet wird. Die Einstellungen zur Berechnung des Fälligkeitsdatum findest du in den Germanized-Einstellungen unter Rechnungen & Lieferscheine > Rechnungen > Fälligkeitsdatum.

[if_document data="is_paid" value="false"]Zahlbar bis zum [document data="date_paid" format="d.m.Y"].[/if_document]

Hinweis für spezielle Zahlungsarten einfügen

Manchmal kann es nützlich sein, für bestimmte Zahlungsarten Hinweise auf der Rechnung zu platzieren (z.B. für die Zahlungsart Kauf auf Rechnung). Auch hier helfen die bedingten Shortcodes weiter. Um die Prüfung vorzunehmen, musst du für die zu prüfende Zahlungsart herausfinden, wie dessen technische Bezeichnung (oder auch ID) lautet. Das geht am Einfachsten, indem du unter WooCommerce > Einstellungen > Zahlungen die Einstellungsseite der Zahlungsart aufrufst und dann die URL in der Adresszeile des Browsers prüfst.

Interessant dabei ist der Parameter &section=XYZ. In diesem Fall würde der Bezeichner der Zahlungsart beispielsweise XYZ lauten. In einem konkreten Fall lautet der Bezeichner z.B. bacs für Banküberweisung oder invoice für die Zahlung auf Rechnung. Die Abfrage per bedingtem Shortcode sähe dann folgendermaßen aus:

[if_document data="payment_method_name" value="invoice"]Bezahlbar per Rechnung innerhalb von X. Tagen.[/if_document]

Shortcodes individuell erweitern

Es gibt viele Anwendungsfälle, die eine Anpassung bzw. Erweiterung der verfügbaren Shortcodes bedürfen. Über die von Germanized zur Verfügung gestellten Filter, kannst du die Shortcodes beliebig erweitern.

Beispielhaft möchten wir hier darstellen, wie es möglich wäre, via Erweiterung des [document_item_product] Shortcodes den Wert einer bestimmten Produkteigenschaften abzurufen. Dieses Produkteigenschaften (die nicht zu Varianten gehören) sind nicht Teil des Produktattribute Blocks.

Über den Filter storeabill_document_item_product_data_shortcode_result lässt sich die Rückgabe des Shortcodes anpassen. Für andere von Germanized Pro zur Verfügung gestellte Shortcodes, sieht der Filter fast gleich aus. Nur der Teil document_item_product entscheidet sich entsprechend.

add_filter( 'storeabill_document_item_product_data_shortcode_result', 'my_child_adjust_document_item_product_shortcode', 10, 4 );

function my_child_adjust_document_item_product_shortcode( $result, $atts, $document, $shortcodes ) {
   if ( $atts['data'] !== 'my_product_attribute' ) {
      return $result;
   }

   if ( $product = $shortcodes->get_document_item_product() ) {
      if ( $product->is_callable( 'get_attribute' ) ) {
          return $result;
      }
      $result = $product->get_attribute( $atts['data'] );
   }

   return $result;
}

Dieses Snippet für die functions.php des Child-Themes prüft zuerst, ob es sich um den Slug des gewünschten Produktattribut handelt (my_product_attribute). Nur in diesem Fall wird der restliche Code ausgeführt. Innerhalb des Codes nutzen wir die Rückgabe der Methode get_attribute um den Wert des Attributs zu erhalten. Wenn ihr den Code nutzt, solltet ihr also das von euch gewünschte Produktattribut in der If-Abfrage ersetzen. Dann könnt ihr den folgenden Shortcode innerhalb der Positionen-Tabelle platzieren: [document_item_product data="my_product_attribute"].

Eigene Shortcodes registrieren

Natürlich kannst du auch neue, eigene Shortcodes speziell für Dokumente registrieren und nutzen. Für jeden Dokumententyp (z.B. Rechnung, Lieferschein) kannst du spezielle Shortcodes registrieren. Du kannst auch unabhängig vom Dokumententyp einen Shortcode registrieren. Folgende Filter stehen dafür zur Verfügung:

• storeabill_invoice_shortcodes
• storeabill_packing_slip_shortcodes
• storeabill_document_shortcodes (Für alle Dokumententypen)

Diese Filter erhalten zwei Parameter. Eine Liste der registrierten Shortcodes mit dazugehörigem Callback und die Instanz des Shortcode-Klasse \Vendidero\StoreaBill\Document\Shortcodes.

Nachfolgend ein kleines Beispiel, wie ihr einen eigenen Shortcode registrieren könnt und über entsprechende Helper-Methoden z.B. das globale Dokument abrufen könnt um daraus Daten zu entnehmen. Der Shortcode kann anschließend via [my_custom_shortcode] beliebig im Dokument platziert werden.

/**
 * @var array $shortcodes
 */
add_filter( 'storeabill_document_shortcodes', function( $shortcodes, $shortcode_instance ) {
  /**
   * @param array $atts
   * @var \Vendidero\StoreaBill\Document\Shortcodes $shortcode_instance
   *
   * @return string
   */
  $shortcodes['my_custom_shortcode'] = function( $atts, $content = '' ) use ( $shortcode_instance ) {
    $document = $shortcode_instance->get_document();

    if ( $document->get_first_name() === 'Max' ) {
      $content = 'Der Kunde heißt Max.';
    } else {
      $content = 'Der Kunde heißt nicht Max.';
    }

    return $content;
  };

  return $shortcodes;
}, 10, 2 );