NAME

Quiq::Zugferd - Generiere das XML von ZUGFeRD-Rechnungen

BASE CLASS

Quiq::Hash

DESCRIPTION

Diese Klasse dient der Generung des XMLs von E-Rechnungen nach dem ZUGFeRD/Factur-X-Standard. Sie kapselt die Profile des Standards, sowohl die XSD-Dateien (XML-Schemadefinition) als auch fertige Templates.

Die Generierung eines Rechnungs-XMLs erfolgt durch Einsetzung der Rechnungswerte in das Template des jeweiligen Profils.

EXAMPLES

Zeige das Template des Profils EN16931:

$ perl -MQuiq::Zugferd -E 'print Quiq::Zugferd->new("en16931")->template'

Zeige den Template-Baum des Profils EN16931:

$ perl -MQuiq::Zugferd -MQuiq::Dumper -E '$t = Quiq::Zugferd->new("en16931")->tree; say Quiq::Dumper->dump($t)'

METHODS

Konstruktor

new() - Instantiiere Objekt

Synopsis

$zug = $class->new($profile,%options);

Arguments

$profile

Name des ZUGFeRD-Profils. Es existieren die ZUGFeRD-Profile: minimum, basicwl, basic, en16931, extended.

Options

-version => $version (Default: '2.3.2')

Die ZUGFeRD-Version.

Returns

Object

Description

Instantiiere ein ZUGFeRD-Objekt des Profils $profile und der ZUGFeRD-Version $version und liefere dieses zurück.

Objektmethoden

checkAttributes() - Prüfe die Attribute des Rechnungsobjekts

Synopsis

$msg = $zug->checkAttributes($rch);

Arguments

$rch

(Object) Das Rechnungsobjekt

Returns

(String) Prüfungsbericht

Description

Prüfe die Felder des Rechnungsobjekts auf mögliche Fehler und liefere einen Bericht über das Ergebnis. Falls keine Fehler festgestellt wurden, lieferet die Methode einen Leerstring ('').

combine() - Erzeuge ZUGFeRD PDF

Synopsis

$zug->combine($pdfFile,$xmlFile,$zugferdFile);

Arguments

$pdfFile

(String) Der Pfad zum PDF der Rechnung

$xmlFile

(String) Der Pfad zum ZUGFeRD XML der Rechnung

$zugferdFile

(String) Der Pfad zur resultierenden ZUGFeRD Rechnung

Description

Füge das Rechnungs-PDF $pdfFile und das ZUGFeRD XML $xmlFile zusammen und schreibe das Ergebnis nach $zugferdFile.

createInvoice() - Erzeuge das XML einer ZUGFeRD-Rechnung (abstrakt)

Synopsis

$xml = $zug->createInvoice(@args);

Arguments

@args

Beliebige Argumente, die für das Ausfüllen des ZUGFeRD XML-Templates benötigt werden.

Returns

(String) XML

processSubTree() - Verarbeite Subbaum

Synopsis

$treeA = $zug->processSubTree($name,\@arr,sub {
    my ($zug,$t,$h,$i) = @_;
    ...
    $t->resolvePlaceholders(
        ...
    );

    return $t;
});

Arguments

$zug

ZUGFeRD-Objekt

$name

Name des Subbaums

@arr

Liste der Elemente, über die iteriert wird, um Teilbäume (mit ersetzten Platzhaltern) zu erzeugen.

sub {}

Subroutine, die die Einsetzung in jeweils einen Subbaum vornimmt

Returns

(Object) (Sub-)Baum mit ersetzen Platzhaltern

Description

Ersetze im Subbaum $name die Platzhalter aus den Elementen von @arr.

resolvePlaceholders() - Ersetze Platzhalter im Template

Synopsis

$xml = $zug->resolvePlaceholders(@keyVal,%options);

Arguments

@keyVal

Liste der Platzhalter/Wert-Paare

Options

-label => $text (Default: '')

Versieh den Abschnitt der Platzhalter (bei -showPlaceHolders=>1) mit der Beschriftung $label.

-showPlaceholders => $bool (Default: 0)

Gibt die Liste der Platzhalter auf STDOUT aus

-showTree => $bool (Default: 0)

Gib den resultierenden ZUGFeRD-Baum auf STDOUT aus.

-subTree => $tree (Default: undef)

Führe die Ersetzung auf dem Teilbaum $tree aus.

-validate => $bool (Default: 0)

Aktiviere die Validierung durch XML::Compile

Returns

(String) XML nach Platzhalter-Ersetzung

Description

Ersetze die Platzhalter im Template des ZUGFeRD-Profils und liefere das resultierende XML zurück.

template() - Liefere das ZUGFeRD-Template

Synopsis

$xml = $zug->template;

Returns

(String) XML

toXml() - Liefere das Zugferd-XML einer Rechnung

Synopsis

$xml = $zug->toXml($rch,%options);

Arguments

$rch

(object) Rechnung

Options

-debug => $bool (Default: 0)

Gib Detailinformation auf STDOUT aus.

Returns

(String) XML

Description

Erzeuge eine ZUGFeRD XML Repräsentation des Rechnungs-Objekts $rch und liefere diese zurück.

tree() - Liefere den ZUGFeRD-Baum

Synopsis

$tree = $zug->tree;

Returns

(Object) Baum

Example

$ perl -MQuiq::Zugferd -MQuiq::Dumper -E '$t = Quiq::Zugferd->new("en16931")->tree; say Quiq::Dumper->dump($t)'

Information

bg() - Business Group

Synopsis

$bg = $zug->bg($name);

Arguments

$name

Name der Business Group. Beispiel: BG-25 (Rechnungsposition)

Returns

(Object) Business Group

Description

Liefere die Business Group $name. Ist die Business Group nicht definiert, wirf eine Exception.

Das Objekt hat die Attribute:

name

Name der Business Group.

text

Kurzbeschreibung der Business Group.

path

Pfad zum Knoten im ZUGFeRD-Baum.

Example

$ perl -MQuiq::Zugferd -E 'say Quiq::Zugferd->new("en16931")->bg("BG-25")->path'
SupplyChainTradeTransaction.IncludedSupplyChainTradeLineItem

bt() - Business Term(s)

Synopsis

%bt | $btH = $zug->bt;
$bt = $zug->bt($name);

Arguments

$name

Name des Business Terms. Beispiel: BT-1 (Rechnungsnummer)

Returns

(Object) Business Term

Description

Liefere den Business Term $name. Ist der Business Term nicht definiert, wirf eine Exception.

Das Objekt hat die Attribute:

name

Name des Business Terms.

mandatory

Pflichtfeldstatus. 0=optional, 1=XSD-Pflicht, 2=Mustang-Pflicht

text

Kurzbeschreibung des Business Terms.

attribute

Name des Objektattributs

path

Pfad zum Blattknoten im ZUGFeRD-Baum.

Example

$ perl -MQuiq::Zugferd -E 'say Quiq::Zugferd->new("en16931")->bt("BT-1")->text'
Rechnungsnummer

zugferdDir() - Pfad des ZUGFeRD-Verzeichnisses

Synopsis

$path = $zug->zugferdDir;
$path = $zug->zugferdDir($subPath);

Arguments

$subPath

Subpfad ins Verzeichnis

Returns

(String) Dateipfad

Description

Liefere den Dateipfad des ZUGFeRD-Verzeichnisses, optional ergänzt um Subpfad $subPath.

DETAILS

Vorgehen bei der Generierung einer ZUGFeRD E-Rechnung

Der Inhalt einer Rechnung setzt sich aus verschiedenen Bestandteilen zusammen:

• Rechnungsdaten

  • Allgemeine Rechnungsdaten

  • Rechnungsreferenzen

• Verkäufer

  • Informationen zum Verkäufer

  • Steuervertreter des Verkäufers

  • Postanschrift des Verkäufers

  • Kontaktdaten des Verkäufers

  • Vom Verkäufer abweichender Zahlungsempfänger

• Käufer

  • Informationen zum Käufer

  • Postanschrift des Käufers

  • Kontaktdaten des Käufers

  • Lieferinformation

• Rechnungspositionen

  • Rechnungsposition

  • Weitere Daten zur Position

  • Nachlässe auf Ebene der Rechnungsposition

  • Zuschläge auf Ebene der Rechnungsposition

• Rechnungsbeträge

  • Nachlässe auf Ebene der Rechnung

  • Zuschläge auf Ebene der Rechnung

  • Aufschlüsselung der Umsatzsteuer auf Ebene der Rechnung

  • Rechnungsbeträge

• Zahlungsdaten

  • Zahlungsdaten

  • Zahlungsmittel: Überweisung

  • Zahlungsmittel: Lastschrift

• Anhänge

• Verweise

• Empfänger

• Texte auf Rechnungs- und Positionsebene

VERSION

1.230

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2025 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Quiq

perl -MCPAN -e shell
install Quiq