Freitexte zur Rechnung und Position (BG-1, BT-22, BT-127)

Thema

VB.NET

SDK-Mitglieder

Add_Trade_ItemTradeNote() AddDocumentNote() DocumentNotesCount FillZUGFeRD_Structure() getDocumentNote() SetIncludedNote() Trade_ItemTradeNotes TradeItemNoteLine TradeItemNotesCount TradeItemsCount

Business Terms

BG-1 Freitext zur Rechnung BT-21 Code zur Qualifizierung des Freitextes zur Rechnung BT-22 Freitext zur Rechnung BT-127 Freitext zur Rechnungsposition BG-25 Rechnungsposition

Codebeispiele

VB.NET

Veröffentlicht

7. Oktober 2026

Eine E-Rechnung kann Freitexte an zwei Stellen tragen: auf Rechnungsebene in der Gruppe Freitext zur Rechnung (BG-1) – etwa Hinweise auf AGB, Registerangaben oder den Grund einer Korrektur – und je Rechnungsposition als Freitext zur Rechnungsposition (BT-127), zum Beispiel für eine Seriennummer. Dieser Artikel zeigt, wie Sie beide mit der Aloaha ZUGFeRD SDK schreiben, ersetzen und wieder auslesen.

Felder

Die Gruppe BG-1 darf mehrfach vorkommen. Die Codes für BT-21 und ihre Bedeutung beschreibt der Artikel Angabe rechnungsrelevanter Freitexte.

Freitext zur Rechnung schreiben

Zum Hinzufügen eines Freitextes dient AddDocumentNote: Jeder Aufruf hängt einen weiteren Freitext an. SetIncludedNote dagegen ersetzt alle vorhandenen Freitexte durch genau einen – praktisch, wenn Sie eine eingelesene oder per CSV erzeugte Rechnung übernehmen und den Text neu setzen wollen.

VB.NET

Dim alo As New Aloaha_ZUGFeRD.XML(Aloaha_ZUGFeRD.iXML.ZUGFeRDProfile.comfort, False, "IHR-LIZENZSCHLUESSEL")
' ... Rechnungskopf, Verkäufer, Käufer und Positionen setzen ...

' zwei Freitexte anhängen
alo.AddDocumentNote("Es gelten unsere AGB in der Fassung vom 01.01.2026.", "AAI")
alo.AddDocumentNote("Musterfirma GmbH, HRB 12345, Amtsgericht Musterstadt", "REG")

' alle bisherigen Freitexte durch einen einzigen ersetzen
alo.SetIncludedNote("Die Lieferung erfolgte in zwei Teilsendungen.", "AAI")

Verhalten von SetIncludedNote im Detail:

• Ist Content leer, übernimmt die SDK den Text des bisher ersten Freitextes; alle weiteren Freitexte entfallen. Gibt es keinen Freitext, ändert sich nichts. So können Sie zum Beispiel nur den Code neu setzen: alo.SetIncludedNote("", "SUR").
• Der optionale dritte Parameter ContentCode existiert nur in ZUGFeRD EXTENDED. Ist er gefüllt, stellt die SDK das Profil automatisch auf EXTENDED um.

Freitext zur Rechnungsposition schreiben

Add_Trade_ItemTradeNote hängt einer Position einen Freitext an. Der erste Parameter ist der Index der Position, beginnend bei 0. Der Rückgabewert ist der Index des neuen Freitextes innerhalb der Position oder -1, wenn die Position nicht existiert – auch bei negativem Index oder wenn die Rechnung noch keine Positionen hat. In diesem Fall ändert die SDK nichts, auch nicht das Profil.

' Position 0 wurde zuvor angelegt, z. B. mit AddProduct_Comfort
Dim NoteIndex As Integer = alo.Add_Trade_ItemTradeNote(0, "Seriennummer SN-2026-4711")
If NoteIndex < 0 Then
    Console.WriteLine("Position 0 existiert nicht.")
End If

Die optionalen Parameter ContentCode und SubjectCode gibt es auf Positionsebene nur in EXTENDED; sobald einer davon gefüllt ist und die Position existiert, schaltet die SDK auf EXTENDED um. In älteren Versionen der SDK schaltete auch ein Aufruf mit ungültigem Index um, und ohne angelegte Positionen konnte eine Ausnahme auftreten.

Freitexte auslesen

Nach dem Einlesen mit FillZUGFeRD_Structure liefert DocumentNotesCount die Anzahl der Freitexte zur Rechnung; getDocumentNote füllt Text und Codes per Referenz. Die Freitexte der Positionen gibt Trade_ItemTradeNotes als Array von TradeItemNote zurück; Content ist dabei selbst ein Array von Textzeilen.

VB.NET

Dim alo As New Aloaha_ZUGFeRD.XML
If alo.FillZUGFeRD_Structure("C:\Rechnungen\eingang.xml", "IHR-LIZENZSCHLUESSEL") Then
    ' Freitexte zur Rechnung (BG-1)
    For i As Integer = 0 To alo.DocumentNotesCount - 1
        Dim Notiz As String = "", ContentCode As String = "", Betreff As String = ""
        alo.getDocumentNote(i, Notiz, ContentCode, Betreff)
        Console.WriteLine(Betreff & ": " & Notiz)
    Next

    ' Freitexte je Position (BT-127)
    For p As Integer = 0 To alo.TradeItemsCount - 1
        For Each n As Aloaha_ZUGFeRD.iXML.TradeItemNote In alo.Trade_ItemTradeNotes(p)
            Console.WriteLine("Position " & (p + 1) & ": " & String.Join(" ", n.Content))
        Next
    Next
End If

VBA / VB6 (COM) – hier greifen Sie statt auf das Array auf einzelne Zeilen zu:

Dim i As Long, p As Long, n As Long
Dim Notiz As String, ContentCode As String, Betreff As String

For i = 0 To alo.DocumentNotesCount - 1
    Notiz = "": ContentCode = "": Betreff = ""
    alo.getDocumentNote i, Notiz, ContentCode, Betreff
    Debug.Print Betreff, Notiz
Next i

For p = 0 To alo.TradeItemsCount - 1
    For n = 0 To alo.TradeItemNotesCount(p) - 1
        Debug.Print "Position " & p + 1, alo.TradeItemNoteLine(p, n, 0)
    Next n
Next p

Hinweise

• Variablen zurücksetzen: Bei einem ungültigen Index lässt getDocumentNote die übergebenen Variablen unverändert. Setzen Sie sie daher vor jedem Aufruf auf "", wie im Beispiel.
• Profile: Freitexte zur Rechnung sind ab BASIC WL erlaubt. Freitexte zur Position schreibt die SDK ab dem Profil BASIC (ZUGFeRD 2.x / Factur-X); in BASIC ohne SubjectCode. In älteren Versionen der SDK wurden sie erst ab EN 16931 (COMFORT) ausgegeben.
• Ein Positions-Freitext in BASIC, EN 16931 und XRechnung: BT-127 kommt je Position höchstens einmal vor. Haben Sie mehrere Freitexte angehängt, schreibt die SDK in diesen Profilen nur den ersten mit Text; in EXTENDED werden alle geschrieben.

Business Terms in diesem Artikel: BG-1 BT-21 BT-22 BT-127 BG-25