Skip to content
ONE LOOP / Documentation / Apps & connections

The source documentation is currently available in German. No English translation is implied.

Apps & connections

Payloads parsen und Variablen verwenden

ONE LOOP: Datenübergaben und Variablen in Lexware-Office-Workflows prüfen. Die allgemeine Verfügbarkeit ist noch nicht bestätigt.

Teststatus

Stand 7. November 2026: Lexware Office Connector 9.2.0 ist privat live; vier Dokument-Actions und beide Trigger wurden im freigegebenen ONE LOOP Teststand geprüft. Der Zahlungstrigger 1.5 ist veröffentlicht. Version 9.3.0 befindet sich in öffentlicher Prüfung; eine allgemeine öffentliche Freigabe oder ein kostenpflichtiger Neukundenabschluss ist noch nicht bestätigt.

Schnellwahl: Welche Variable verwende ich wofür?

Nutze diese Tabelle, bevor du in die Detailseiten gehst. Sie beantwortet direkt: Welchen Wert nehme ich? Wohin setze ich ihn? Was passiert dann?

Dein Ziel

Nimm diese Variable

Setze sie hier ein

Ergebnis

Nur nach vollständiger Zahlung fortfahren

isFullyPaid oder der Triggerfilter final

In eine If/Else-Bedingung nach Rechnungszahlung empfangen

Der Abschlussweg läuft nur bei true.

Die aktuelle Zahlung in einer Nachricht nennen

paymentAmountFormatted

In den Nachrichtentext

Der Betrag erscheint lesbar mit Währung.

Mit einem Betrag rechnen

paymentAmount, totalAmount, grossAmount oder refundAmount

In ein Zahlenfeld oder eine Berechnung

Der Workflow verarbeitet eine Zahl ohne Währungssymbol.

Einen Vorgang in Lexware Office prüfen

invoiceUrl oder lexwareViewUrl

In eine interne Aufgabe oder Notiz

Der Empfänger öffnet den passenden Vorgang direkt.

Den PDF-Link weitergeben

invoiceFileUrl, quotationFileUrl, orderConfirmationFileUrl oder creditNoteFileUrl

In einen Link- oder Dokumentenschritt

Der offizielle Beleg kann geöffnet werden, sofern die Variable gefüllt ist.

Aus einem angenommenen Angebot eine Auftragsbestätigung erstellen

quotationId

In das Feld Quotation der Action Auftragsbestätigung erstellen

Die Bestätigung wird aus genau diesem Angebot weitergeführt.

Eine Nummer in einem Text zeigen

invoiceNumber, quotationNumber, orderConfirmationNumber oder creditNoteNumber

In Text, E-Mail oder interne Notiz

Menschen sehen die richtige Belegnummer.

Einen technischen Folgeprozess verknüpfen

invoiceId, quotationId, orderConfirmationId oder creditNoteId

In ein ID-Feld einer passenden Folgeaction

Der Workflow referenziert den eindeutigen Vorgang statt nur dessen sichtbarer Nummer.

Nach einem Fehler sauber reagieren

success, errorCode, errorMessage, retryable

In eine If/Else-Bedingung und eine interne Fehlermeldung

Erfolgs- und Fehlerweg bleiben getrennt und nachvollziehbar.

Eine doppelte Folgeaktion vermeiden

eventId

In einer eigenen Duplikat-Prüfung speichern und vergleichen

Dasselbe Trigger-Ereignis löst nicht zweimal denselben Folgeprozess aus.

Merkregel: Für Texte nimmst du eine sichtbare Nummer oder einen ...Formatted-Wert. Für Übergaben zwischen Actions nimmst du die passende ...Id. Für Berechnungen nimmst du einen reinen Zahlenwert.

Worum geht es auf dieser Seite?

Diese Seite erklärt die Datenübergabe der Lexware-Office-Integration von Anfang bis Ende:

  • welche Daten ein Auslöser in einen Workflow gibt,

  • welche Felder du bei einer Action befüllst,

  • welche Werte nach einer Action zurückkommen,

  • wann du einen Payload wirklich parsen musst – und wann nicht,

  • wie du Daten sicher in Bedingungen, Texten und Folgeaktionen verwendest.

Die Detailseiten enthalten anschließend jede einzelne Action und jeden Trigger mit allen Feldern und allen Rückgabevariablen.

Die Begriffe einfach erklärt

Begriff

Einfache Bedeutung

Beispiel

Payload

Das gesamte Datenpaket eines Auslösers oder einer Action.

Alle Daten zu einer Rechnungszahlung zusammen.

Variable

Ein einzelner Wert aus diesem Paket.

invoiceNumber oder paymentAmount.

Mapping

Du setzt eine Variable in ein Eingabefeld des nächsten Schritts ein.

quotationId wird in das Feld Quotation gemappt.

Parsen

Ein umfangreicher Rohtext wird in einzelne verwendbare Werte zerlegt.

Aus einem JSON-Text wird ein eigener Wert für Rechnungsnummer, Betrag und Datum.

Bedingung

Der Workflow entscheidet anhand eines Werts, welchen Weg er geht.

Nur fortfahren, wenn isFullyPaid = true.

Der Datenfluss im Workflow

Lexware-Ereignis oder vorheriger Workflow-Schritt ↓ Payload mit einzelnen Variablen ↓ Mapping in eine Lexware-Action ↓ Aktion erstellt oder liest einen Vorgang ↓ Ergebnis-Payload der Action ↓ Bedingungen, Nachrichten, Aufgaben oder Folgeaktion

Die Lexware-Trigger und -Actions liefern die Werte bereits als einzelne Workflow-Variablen. In diesen Fällen musst du keinen JSON-Text selbst parsen: Du wählst im Variablen-Auswahlfeld einfach den benötigten Wert.

Technischer Aufbau: Was du sehen musst – und was nicht

Bei einer Lexware-Action füllst du in der Oberfläche nur die sichtbaren Felder aus. Die Integration baut daraus intern ein technisches Paket auf:

{ "data": { "sourceMode": "manual", "title": "Beratung August", "item1Name": "Beratung", "item1Quantity": 2, "item1UnitPrice": 120, "item1TaxRate": 19 }, "extras": { "locationId": "…", "contactId": "…", "executionId": "…", "workflowId": "…" }, "meta": { "key": "one_loop_lexware_create_invoice" } }

Bereich

Bedeutung

Was du damit machst

data

Deine fachlichen Eingaben aus den sichtbaren Action-Feldern.

Hierhin mappt die Oberfläche deine Eingaben automatisch.

extras

Technische Zuordnung zum Standort, Kontakt und Workflow-Lauf.

Nicht selbst eintragen oder verändern.

meta.key

Kennung der auszuführenden Lexware-Action.

Nicht selbst eintragen oder verändern.

Du musst diesen Umschlag nicht als JSON in ein Feld kopieren. Nutze für die sichtbaren Eingaben immer das normale manuelle Mapping der Action. Das gezeigte Objekt dient nur zum Verständnis, wenn du einen Workflow-Lauf technisch prüfst.

Welche Feldtypen sicher mappen?

Feldart

So mapst du sie

Worauf achten?

Text

Textvariable direkt in ein Textfeld setzen.

Leere Werte vorher abfangen, wenn der Text fachlich notwendig ist.

Zahl

Zahlvariable in ein Zahlenfeld setzen.

Keine Währungssymbole in Betragsfelder mappen.

Datum

Ein Datum im erwarteten Format setzen.

Für Angebote ist das Ablaufdatum exakt YYYY-MM-DD.

Auswahl

Einen der angebotenen Werte wählen oder dynamisch liefern.

Schreibweise muss zum erlaubten Wert passen.

Wahr/Falsch

Boolean-Wert in einer Bedingung prüfen.

Nicht auf den Text true oder false prüfen, wenn die Bedingung einen Boolean erwartet.

ID

Die Kennung eines vorherigen Vorgangs mappen.

IDs nicht mit sichtbaren Nummern verwechseln.

Link oder Datei

Die zurückgegebene URL verwenden.

Der Wert kann fehlen; vorher prüfen.

Sichtbare Nummer und technische ID sind nicht dasselbe

Die sichtbare Nummer ist für Menschen. Die ID wird für eine eindeutige Weiterverarbeitung benötigt.

Fachlicher Vorgang

Sichtbarer Wert

Technischer Wert

Typische Verwendung

Rechnung

invoiceNumber

invoiceId

Nummer in Nachricht, ID für Verknüpfungen.

Angebot

quotationNumber

quotationId

Für eine Auftragsbestätigung immer quotationId mappen.

Auftragsbestätigung

orderConfirmationNumber

orderConfirmationId

Nummer in einer Notiz, ID für technische Folgeprozesse.

Gutschrift

creditNoteNumber

creditNoteId

Nummer für Kommunikation, ID für Abgleiche.

Kontakt

contactName

lexwareContactId

Name für Texte, ID für Verknüpfungen.

Auslöser richtig verwenden

Rechnungszahlung empfangen

Der Trigger liefert Rechnung, Kontakt, Beträge und Zahlungsstand. Für die Steuerung eines Prozesses sind diese Werte besonders wichtig:

Variable

Bedeutung

Sichere Verwendung

paymentStage

partial oder final. any ist die Filterauswahl für beide Ereignisstufen.

Den Trigger auf final filtern, wenn der Ablauf erst nach vollständigem Ausgleich starten soll.

isFullyPaid

true bei vollständig ausgeglichener Rechnung.

Als If/Else-Bedingung vor Abschlussaktionen verwenden.

remainingAmount

Noch offener Betrag.

Für Teilzahlungs- oder Follow-up-Logik.

paymentAmount

Betrag genau dieses Zahlungseingangs.

Für Berechnungen.

paymentAmountFormatted

Derselbe Betrag als lesbarer Text.

Für eine Nachricht oder interne Notiz.

eventId

Eindeutige Kennung des Zahlungsereignisses.

Gegen doppelte Folgeaktionen absichern.

Beispiel: Ein Workflow startet nur bei final. Danach prüft eine Bedingung isFullyPaid. Nur im Ja-Zweig wird eine interne Bestätigung angelegt. In diese Bestätigung werden invoiceNumber, totalAmountFormatted und invoiceUrl gemappt.

Zur vollständigen Feldliste: Rechnungszahlung empfangen.

Angebotsstatus geändert

Dieser Trigger startet bei accepted oder rejected.

Variable

Bedeutung

Sichere Verwendung

quotationStatus

Neuer Angebotsstatus.

Den Workflow nach Annahme und Ablehnung getrennt behandeln.

quotationId

Eindeutige Lexware-ID des Angebots.

An Auftragsbestätigung erstellen weitergeben.

quotationNumber

Sichtbare Angebotsnummer.

In interne Nachrichten einsetzen.

quotationFileUrl

Datei-Link, sofern verfügbar.

Vor Nutzung auf einen leeren Wert prüfen.

eventId

Eindeutige Kennung der Statusänderung.

Gegen doppelte Folgeaktionen absichern.

Beispiel: Ein Workflow mit Filter accepted mappt quotationId in die folgende Action Auftragsbestätigung erstellen. Die Angebotsnummer und der Link werden in einer internen Aufgabe dokumentiert.

Zur vollständigen Feldliste: Angebotsstatus geändert.

Ergebnisse einer Action weiterverwenden

Jede Action liefert einen Ergebnis-Payload zurück. Diese Variablen sind der sichere Übergabepunkt für deinen nächsten Workflow-Schritt.

Gemeinsame Ergebniswerte

Variable

Bedeutung

So verwenden

success

true, wenn der Schritt erfolgreich abgeschlossen wurde.

Erst nach success = true mit der Folgeaktion fortfahren.

status

Ergebnisstatus des Schritts.

Für Protokolle und ergänzende Prüfungen.

errorCode

Technische oder fachliche Fehlerkennung bei einem fehlgeschlagenen Lauf.

In einer internen Fehlermeldung speichern.

errorMessage

Verständliche Fehlerbeschreibung, sofern geliefert.

Zur Analyse in eine interne Aufgabe oder Notiz übernehmen.

retryable

Zeigt, ob eine Wiederholung fachlich möglich sein kann.

Ursache prüfen und nur dann bewusst wiederholen.

warnings

Zusätzliche Hinweise ohne zwingenden Fehler.

Im Workflow-Verlauf kontrollieren.

lexwareContactId

Zugeordnete Kontakt-ID in Lexware Office.

Für Abgleiche oder Folgeprozesse.

customerMatchMethod

Wie ein bestehender Kontakt zugeordnet wurde, sofern angegeben.

Zur Prüfung einer unerwarteten Zuordnung.

customerCreated / customerUpdated

Ob ein Kontakt angelegt oder aktualisiert wurde.

Für interne Protokolle.

lexwareViewUrl

Direkter Link zum Vorgang in Lexware Office.

In eine interne Prüfung oder Aufgabe einfügen.

officialDocumentFileName / officialDocumentMimeType

Dateiname und Dateityp des offiziellen Dokuments.

Für Dokumentationsschritte.

contactDocumentStatus

Status der Dokumentablage am Kontakt.

Bei einem fehlenden Dokument prüfen.

Nicht jede Action liefert exakt jede gemeinsame Variable in derselben fachlichen Ausprägung. Die vollständige Liste pro Action findest du auf den verlinkten Detailseiten.

Rechnung erstellen

Nach einem erfolgreichen Lauf stehen unter anderem invoiceId, invoiceNumber, invoiceStatus, invoiceDocumentId, invoiceFileUrl, invoiceFileName und invoiceMimeType bereit.

Robuster Ablauf:

  1. Prüfe success.

  2. Bei Erfolg: verwende invoiceNumber in Texten und invoiceFileUrl für einen Dokumentlink.

  3. Bei Fehler: protokolliere errorCode, errorMessage und retryable.

  4. Prüfe bei Bedarf lexwareViewUrl direkt in Lexware Office.

Vollständige Action-Dokumentation: Rechnung erstellen.

Angebot erstellen

Nach Erfolg stehen unter anderem quotationId, quotationNumber, quotationStatus, expirationDate, quotationDocumentId, quotationFileUrl, quotationFileName und quotationMimeType bereit.

Wichtig: quotationId ist der passende Wert für die spätere Auftragsbestätigung. quotationNumber dient dagegen für Menschen lesbare Texte.

Vollständige Action-Dokumentation: Angebot erstellen.

Auftragsbestätigung erstellen

Die Action erwartet ein bereits angenommenes Angebot und nutzt dessen quotationId. Nach Erfolg liefert sie unter anderem orderConfirmationId, orderConfirmationNumber, orderConfirmationStatus, orderConfirmationDocumentId, orderConfirmationFileUrl, orderConfirmationFileName und orderConfirmationMimeType.

Der Vorgang ist an die Angebots-ID gebunden. Starte denselben Übergabeschritt nicht blind mehrfach.

Vollständige Action-Dokumentation: Auftragsbestätigung erstellen.

Gutschrift erstellen

Die Action verwendet Daten einer erfolgreichen Rückerstattung. Nach Erfolg liefert sie unter anderem creditNoteId, creditNoteNumber, creditNoteStatus, creditNoteDocumentId, creditNoteFileUrl, creditNoteFileName und creditNoteMimeType.

Für die Eingabe sind die Rückerstattungswerte entscheidend: transactionId, refundId, refundAmount, currencyCode, refundStatus und refundType. Bei einer teilweise erstatteten Rechnung mit gemischten Steuersätzen wird keine Gutschrift erstellt.

Vollständige Action-Dokumentation: Gutschrift erstellen.

Wann musst du wirklich parsen?

Bei den nativen Lexware-Auslösern und -Actions nicht: Die einzelnen Werte sind bereits als Variablen verfügbar.

Parsen ist erst nötig, wenn ein vorheriger Workflow-Schritt einen kompletten JSON-Text oder einen unstrukturierten Text liefert. Prüfe dann diese Reihenfolge:

  1. Enthält der Schritt bereits einzelne Variablen? Dann direkt mappen.

  2. Enthält er nur einen JSON-Text? Zerlege ihn zuerst mit der im Workflow verfügbaren Parsing- oder Formatierungsfunktion in einzelne Werte.

  3. Prüfe Datentyp und Format jedes Werts: Zahl, Datum, Text, Boolean oder ID.

  4. Mappe erst danach den einzelnen Wert in das Lexware-Feld.

  5. Führe einen Testlauf durch und vergleiche den Workflow-Verlauf mit Lexware Office.

Ein JSON-Text darf nicht ungeprüft in ein Zahlen-, Datums- oder ID-Feld gemappt werden. Zum Beispiel ist "refundAmount": "119,00 €" kein passender Zahlenwert für eine Rückerstattung; benötigt wird der Betrag als Zahl, etwa 119 oder 119.00.

Die vier wichtigsten Schutzregeln

  1. Vor Folgeaktionen immer Erfolg prüfen. Verwende success, bevor du eine Dokumentnummer weitergibst oder einen Abschlussprozess startest.

  2. IDs und Nummern nicht verwechseln. Für Übergaben zwischen Actions benötigst du die ID, etwa quotationId; für Texte meist die Nummer, etwa quotationNumber.

  3. Doppelte Ereignisse einplanen. Trigger werden mindestens einmal zugestellt. Sichere wichtige Folgeaktionen mit eventId oder einer eigenen Prüfung.

  4. Leere optionale Werte abfangen. Datei-Links, Kontakt-E-Mail, Kundennummer und einzelne Datumswerte können fehlen. Baue vor einer Nutzung eine Bedingung ein.

Kompakte Prüfliste vor der Veröffentlichung eines Workflows

  • ☐ Auslöser und Filter passen zum gewünschten fachlichen Zeitpunkt.

  • ☐ Jede Pflichtangabe der Action ist gemappt.

  • ☐ Zahlenfelder erhalten Zahlen ohne Währungssymbol.

  • ☐ Datumsfelder haben das erwartete Format.

  • ☐ Für eine Folge-Action wird die technische ID statt der sichtbaren Nummer verwendet.

  • ☐ Der Erfolgsweg prüft success; der Fehlerweg dokumentiert mindestens errorMessage.

  • ☐ Datei-Links und optionale Werte werden auf Leerwerte geprüft.

  • ☐ Ein Testlauf wurde im Workflow-Verlauf und in Lexware Office verglichen.

Weiterführende Details

Zahlungs- und Angebotskontext unterscheiden

Vor der Zustellung ordnet der aktuelle Zahlungstrigger die Rechnung einem ONE-LOOP-Kontakt im richtigen Standort zu: über die bestehende sichere Zuordnung oder genau einen Treffer mit derselben E-Mail-Adresse. Er legt dabei keinen Kontakt an. Fehlt eine eindeutige Zuordnung, stoppt die Verarbeitung mit invoice_payment_contact_unresolved; wähle keinen beliebigen Kontakt als Ersatz.

Prüfe nach Neuinstallation jede Triggerinstanz, Bedingung und Variable erneut. Eine erfolgreiche Zahlungsnachricht darf keine Variablen aus einem Angebots-Action-Schritt verwenden. Bei unklarer Teilwirkung denselben Vorgang abgleichen und keine neue Geschäftsreferenz zum Umgehen der Wiederholungssperre setzen.

Filterauswahl ist kein Zahlungsstatus

Ab Zahlungstrigger 1.5 bezeichnet paymentStageFilter die gewählte Auswahl any, partial oder final. paymentStage enthält dagegen ausschließlich die tatsächliche Teil- oder Schlusszahlung. Prüfe für einen abgeschlossenen Vorgang paymentStage=final und isFullyPaid=true. Der Trigger bindet vor Zustellung den passenden ONE-LOOP-Kontakt; eine fehlende oder mehrdeutige Zuordnung wird nicht durch einen beliebigen Kontakt ersetzt.

← Back to articles