Rechnungspositionen mit Trade_Item-Eigenschaften lesen und ändern

Thema

VB.NET

SDK-Mitglieder

FillZUGFeRD_Structure() Trade_ItemTradeBuyerAssignedID Trade_ItemTradeDescription Trade_ItemTradeProduct Trade_ItemTradeProductName Trade_ItemTradeSellerAssignedID TradeItemsCount

Business Terms

BG-31 Artikelinformationen BT-153 Artikelname BT-154 Artikelbeschreibung BT-155 Artikelkennung des Verkäufers BT-156 Artikelkennung des Käufers BG-25 Rechnungsposition BT-157 Kennung eines Artikels nach registriertem Schema BT-158 Kennung der Artikelklassifizierung

Codebeispiele

VB.NET

Veröffentlicht

7. Oktober 2026

Mit AddProduct_Comfort legen Sie eine Rechnungsposition (BG-25) an. Wollen Sie eine Position danach noch ändern oder aus einer eingelesenen Rechnung auslesen, nutzen Sie die Trade_Item-Eigenschaften des Aloaha ZUGFeRD SDK. Sie erwarten als Argument den Index der Position und greifen direkt auf deren Daten zu. Dieser Artikel behandelt die Artikelinformationen (BG-31): Name, Beschreibung und Artikelnummern. Preis, Menge, Steuer und Zeitraum der Position beschreibt der Artikel Preis, Menge, Steuer und Zeitraum einer Position ändern.

Übersicht

Alle Eigenschaften sind lesbar und schreibbar. Der Index beginnt bei 0; die letzte Position hat den Index TradeItemsCount - 1.

Lesen

Nach dem Einlesen einer Rechnung mit FillZUGFeRD_Structure (XML oder ZUGFeRD-PDF) durchlaufen Sie die Positionen:

Dim alo As New Aloaha_ZUGFeRD.XML(Aloaha_ZUGFeRD.iXML.ZUGFeRDProfile.comfort, False, "IHR-LIZENZSCHLUESSEL")
If alo.FillZUGFeRD_Structure("C:\Rechnungen\eingang.xml", "IHR-LIZENZSCHLUESSEL") Then
    For i As Integer = 0 To alo.TradeItemsCount - 1
        Console.WriteLine("Position " & (i + 1))
        Console.WriteLine("  Artikelnummer:  " & alo.Trade_ItemTradeSellerAssignedID(i))
        Console.WriteLine("  Kunden-Nr.:     " & alo.Trade_ItemTradeBuyerAssignedID(i))
        Console.WriteLine("  Name:           " & alo.Trade_ItemTradeProductName(i))
        Console.WriteLine("  Beschreibung:   " & alo.Trade_ItemTradeDescription(i))
    Next
End If

Die vier String-Eigenschaften liefern nie Nothing: Fehlt ein Wert in der Rechnung, erhalten Sie eine leere Zeichenkette.

Ändern

Die String-Eigenschaften schreiben den Wert direkt in die Position. Im folgenden Beispiel wurde Position 0 zuvor mit AddProduct_Comfort angelegt:

alo.Trade_ItemTradeProductName(0) = "Kopierpapier A4, 80 g/m²"
alo.Trade_ItemTradeDescription(0) = "Karton mit 5 Paketen à 500 Blatt"
alo.Trade_ItemTradeSellerAssignedID(0) = "ART-100"
alo.Trade_ItemTradeBuyerAssignedID(0) = "K-4711"       ' Artikelnummer aus der Bestellung des Kunden

Der Wert wird unverändert gespeichert; beim Erzeugen der XML entfernt das SDK führende und folgende Leerzeichen und lässt leere Felder weg. Eine leere Zeichenkette löscht ein Feld also. Beim Artikelnamen (BT-153) sollten Sie das nicht tun, denn er ist Pflicht.

Die ganze Artikelinformation: Trade_ItemTradeProduct

Trade_ItemTradeProduct liefert die vollständige Struktur iXML.TradeProduct mit den Feldern Name.Value, Description.Value, SellerAssignedID, BuyerAssignedID, GlobalID (BT-157 mit Schema), OriginTradeCountry (BT-159) sowie den Arrays DesignatedProductClassification (BT-158) und ApplicableProductCharacteristics (BG-32).

Wichtig: TradeProduct ist eine .NET-Structure, also ein Werttyp. Die Eigenschaft gibt eine Kopie zurück. Eine Änderung an der Kopie wirkt erst, wenn Sie die Struktur wieder zuweisen – lesen, ändern, zurückschreiben:

Dim p As Aloaha_ZUGFeRD.iXML.TradeProduct = alo.Trade_ItemTradeProduct(0)
p.Name.Value = "Kopierpapier A4, 80 g/m²"
p.GlobalID.GlobalID = "4012345678901"          ' BT-157: GTIN
p.GlobalID.GlobalID_schemeID = "0160"          ' BT-157-1: Schema GTIN
alo.Trade_ItemTradeProduct(0) = p              ' zurückschreiben

Eine direkte Zuweisung wie alo.Trade_ItemTradeProduct(0).Name.Value = "…" lehnt der VB.NET-Compiler ab („Der Ausdruck ist ein Wert und kann daher nicht das Ziel einer Zuweisung sein“), in C# ebenso. Beim Zurückschreiben ersetzt das SDK die gesamte Artikelinformation der Position – lesen Sie die Struktur deshalb immer zuerst aus, statt eine neue, leere Struktur zuzuweisen, sonst gehen Klassifizierung, Herkunftsland und Attribute verloren.

Die Arrays in der Struktur können Nothing sein, wenn die Position keine Klassifizierung oder keine Attribute hat. Prüfen Sie das vor einer Schleife:

Dim prod As Aloaha_ZUGFeRD.iXML.TradeProduct = alo.Trade_ItemTradeProduct(0)
If prod.ApplicableProductCharacteristics IsNot Nothing Then
    For Each c As Aloaha_ZUGFeRD.iXML.TradeProductCharacteristic In prod.ApplicableProductCharacteristics
        Console.WriteLine(c.Description & ": " & c.CharacteristicsValue)
    Next
End If

Zum Hinzufügen von Klassifizierung, Herkunftsland und Attributen gibt es eigene Methoden, siehe Artikelmerkmale, Klassifizierung und Herkunftsland.

Ungültiger Index

Die Eigenschaften werfen keine Ausnahme und setzen keinen Fehlertext. Ist der Index zu groß oder negativ oder enthält die Rechnung keine Positionen,

• liefern die String-Eigenschaften eine leere Zeichenkette,
• liefert Trade_ItemTradeProduct eine leere Struktur, deren Felder Nothing sind,
• wird eine Zuweisung stillschweigend ignoriert. Eine neue Position entsteht dadurch nicht; neue Positionen legen Sie mit AddProduct_Comfort an.

Begrenzen Sie Schleifen deshalb immer mit TradeItemsCount.

VBA, VB6 und Access

Die vier String-Eigenschaften funktionieren auch über COM, weil sie nur Zeichenketten übergeben:

Dim i As Long
For i = 0 To alo.TradeItemsCount - 1
    Debug.Print alo.Trade_ItemTradeSellerAssignedID(i), alo.Trade_ItemTradeProductName(i)
Next i
alo.Trade_ItemTradeBuyerAssignedID(0) = "K-4711"

Die Struktur aus Trade_ItemTradeProduct und deren verschachtelte Felder lassen sich in VBA dagegen nicht zuverlässig verwenden. Warum das so ist und welche Aufrufe stattdessen helfen, erklärt Positionswerte in VBA/Access auslesen.

Profile

Den Artikelnamen (BT-153) gibt es in allen Profilen ab BASIC. Beschreibung (BT-154) sowie die Artikelkennungen von Verkäufer und Käufer (BT-155, BT-156) sieht der Standard ab dem Profil EN 16931 (COMFORT) vor. Die Trade_Item-Eigenschaften schalten das Profil nicht um; erstellen Sie die Rechnung daher mindestens im Profil COMFORT, wenn Sie diese Felder nutzen.

Business Terms in diesem Artikel: BG-31 BT-153 BT-154 BT-155 BT-156 BG-25 BT-157 BT-158 BT-159 BG-32 BG-26 BG-29 BG-30