Automatische Aufteilung der Adressen-Felder für Bexio

Änderung seitens Bexio

Bexio hat angekündigt, dass ab dem 8.12.25 alle Kontakte und Zusatzadressen mit strukturierten Adressen-Felder erstellt und bearbeitet werden müssen (Link zum Helpcenter). Dies bedeutet, dass Strasse und Hausnummer getrennt geschickt werden müssen. Diese Anpassung ist auf regulatorische Änderungen seitens des Swiss Payment Standards zurückzuführen, welcher eine getrennte Erfassung für diese Daten bei der Überweisung von Zahlungen oder Abrechnungen mit QR-Codes vorschreibt.

Aufteilung der Adresse im Bexio Automator

Standardmässig erfasst WooCommerce im Bestellprozess diese Daten nicht getrennt, die Adresse wird in einem Feld eingegeben (als Strasse + Hausnummer). Da Bexio dies zukünftig nicht mehr unterstützt, wurde der Bexio Automator entsprechend angepasst, um dem Rechnung zu tragen. Adressen werden zukünftig, bei der Übermittlung an Bexio, automatisch aufgeteilt in Strasse und Hausnummer.

Die automatische Aufteilung geschieht dabei wie folgt:

• Die vom Shop geschickte Adresse wird ab der ersten Zahl, die auf eine Zeichenkette und ein Leerzeichen folgt, aufgetrennt.
• Alles was vorangehend ist, wird als "Strasse" an Bexio übermittelt.
• Alles was ab dieser Zahl nachfolgend ist, wird als "Hausnummer" an Bexio übermittelt.

Ein Beispiel einer gültigen Adresse:

• Der Shop schickt die Adresse "Muster Strasse 13a".
• "Muster Strasse" wird als "Strasse" an Bexio geschickt.
• "13a" wird als "Hausnummer" an Bexio geschickt.

Ein Beispiel einer ungültigen Adresse:

• Der Shop schickt die Adresse "Irgend eine Strasse 10a, lorem ipsum".
• "Irgend eine Strasse" wird als "Strasse" an Bexio geschickt.
• "10a, lorem ipsum" wird als "Hausnummer" an Bexio geschickt.

Diese Hausnummer ist länger, als Bexio erlaubt und führt zu einem Synchronisierungsfehler. Du müsstest diese Adresse korrigieren, um die Bestellung synchronisieren zu können.

Wenn du selbständig eine Aufteilung der Adresse in deinem Shop vornehmen willst, um diese bereits strukturiert zu schicken, siehe hier.

Übermittelte Felder

Da Bexio eine Übermittlung der Adresse in strukturierten Feldern erwartet, muss die Adresse aus WooCommerce entsprechend aufgeteilt werden. Diese wird dann jeweils an die passenden Felder in Bexio übermittelt:

• Die Adresszeile 1 wird in Strassenname und Hausnummer aufgeteilt (siehe oben)
• Die Adresszeile 2 wird als Adresszusatz übermittelt.

Werden Daten im Shop nicht in den vorgesehenen Feldern erfasst, kann dies dazu führen, dass die Adresse in Bexio unvollständig ist / anders als erwartet hinterlegt wird.

Individuelle Aufteilung der Adresse

Ab Version 2.12.0 des WooCommerce Bexio Automator API's (siehe Changelog), unterstützt unser Dienst auch die Entgegennahme von strukturierten Feldern und leitet diese entsprechend unverändert an Bexio weiter. Dies kann verwendet werden, wenn du mit der automatischen Aufteilung der Adresse nicht zufrieden bist und die Adresse selbständig aufteilen willst.

Zu beachten: WooCommerce hat standardmässig nur 1 Feld für die Adresse. Während unser Dienst eine strukturierte Weitergabe an Bexio ab der genannten Version des API's unterstützt, obliegt es dem Shop, die Adresse entsprechend zu schicken. Hierzu gibt es grundsätzlich 2 Möglichkeiten:

• Du passt den Checkout in deinem Shop so an, dass direkt eine strukturierte Erfassung der  Adresse vom Kunden erwartet wird. Die Daten, die während der Synchronisierung geschickt werden, werden anschliessend überschrieben, um diese strukturiert erfassten Felder zu verwenden.
• Du erstellst ein Code-Snippet, nimmst eine eigenständige Aufteilung der Adressen anhand von dir definierten Kriterien vor und überschreibst die Daten, die während der Synchronisierung geschickt werden. So kannst du die Adresse selbständig aufteilen und strukturiert an Bexio schicken.

In beiden Fällen müssen die an unseren Dienst geschickten Daten überschrieben werden, da das Plugin weiterhin primär für eine standard WooCommerce Installation ausgelegt ist, wo keine strukturierte Erfassung der Adresse seitens WooCommerce vorgesehen ist. Wende dich für derartige Anpassungen an deinem Shop an deine Website-Betreuer:innen.

Um die Daten während der Synchronisierung zu überschreiben, kann der Filter 'raptus_wc_bexio_connector_order_data' verwendet und in ['customer']['billing'] (Rechnungsadresse) und ['customer']['shipping'] (Lieferadresse) die Strukturierte Adresse mit folgenden Feldern (gleich wie bei Bexio) angegeben werden:

• street_name: für den Strassenname
• house_number: für die Hausnummer

Das Standard-Adressen-Feld address_1 sollte dabei jeweils aus der Rechnungs- & Lieferadresse entfernt werden.

Ein Beispiel, wie eine individuelle Aufteilung der Adresse vorgenommen werden könnte:

add_filter('raptus_wc_bexio_connector_order_data', function($order_data, $order) {
    foreach (['billing', 'shipping'] as $type) {
        if (empty($order_data['customer'][$type]['address_1'])) {
            continue;
        }
        $address = $order_data['customer'][$type]['address_1'];
        if (preg_match('/^(\d+[a-zA-Z]?)\s+(.+)$/', $address, $matches)) { // Split address in the french format, starting with a leading house-number
            $order_data['customer'][$type]['house_number'] = $matches[1];
            $order_data['customer'][$type]['street_name']  = $matches[2];
            unset($order_data['customer'][$type]['address_1']);
        }
    }
    return $order_data;
}, 10, 2);

Beachte: dies ist ein Beispiel. Es obliegt dir selbst, die Kriterien zu definieren, wie die Adresse aufgeteilt wird und für welche Bestellungen dies vorgenommen wird. Obiges Beispiel dient nur als Ausgangspunkt.

Spezialfall Suche nach Zusatzadresse

Wenn die vom Shop erhaltene Adresse von jener des gefundenen Bexio Kontaktes abweicht, wird eine Zusatzadresse benötigt. Bisher hat das Plugin in diesem Fall direkt nach einer existierenden Zusatzadresse gesucht, bevor eine neue erstellt wird. Der entsprechende Such-Endpunkt der Bexio-Schnittstelle unterstützt jedoch (Stand 09.02.2026) gemäss Schnittstellen-Dokumentation von Bexio die neuen Adressen Felder nach wie vor nicht.

Gemäss Auskunft vom Schnittstellen-Support von Bexio, seien die neuen Felder bei diesem Endpunkt in der Tat nicht unterstützt. Ob / wann diese unterstützt werden, ist unklar. Bis auf weiteres könne das alte Feld verwendet werden, jedoch ist ebenso unklar, wie lange und ob das alte Feld dann direkt entfernt wird, sobald die neuen Felder nachgerüstet wurden, oder ob dies auch wieder angekündigt wird.

Aufgrund der Unklarheiten wird der Bexio Automator bei vom Kontakt abweichenden Adressen daher vorübergehend auf einen Workaround setzen und jeweils alle Zusatzadressen eines Kontaktes abfragen und diese einzeln vergleichen, um sicherzustellen, dass bestehende Zusatzadressen auch zukünftig noch gefunden werden können, unabhängig ob Bexio das alte Adressen-Feld bei diesem Endpunkt mit/ohne Vorankündigung entfernen wird. Dies kann je nach Anzahl Zusatzadressen auf einem Kontakt zu einer leicht erhöhten Bearbeitungsdauer von Synchronisierungen führen. Üblicherweise haben Kontakte jedoch nur wenige Zusatzadressen, wodurch dies nicht allzu stark ins Gewicht fallen sollte. Sobald erkennbar ist, dass die Such-Endpunkte die neuen Felder unterstützten, werden auch diese im Bexio Automator umgestellt.

Mit der Umstellung auf die strukturierten Adressen-Felder wurde zudem das alte Format für Zusatzadressen entfernt - nach diesem wird neu nicht mehr gesucht, wenn bei der ersten Suche keine passende Zusatzadresse gefunden werden konnte. Dies ist darauf zurückzuführen, dass neben der Aufteilung der Adresse in Strasse & Hausnummer auch zusätzliche Informationen neu in die auf den Zusatzadressen verfügbaren Felder aufgeteilt werden können. Für weitere Informationen, siehe hier.

Troubleshooting

Die Adresse wurde nicht so aufgeteilt, wie ich möchte

WooCommerce unterscheidet in der Adresszeile 1 nicht zwischen Strassenname und Hausnummer, Bexio erwartet diese jedoch separat übermittelt. Das bedeutet: damit eine Bestellung synchronisiert werden kann, muss die Adresse aus WooCommerce automatisch aufgeteilt werden - wie dies stattfindet, ist oben beschrieben. Falls du Kontakte hast, die aufgrund dieses Schemas nicht wie von dir erwartet erstellt wurden, müsstest du diese allenfalls in Bexio nachträglich bearbeiten.

Beachte dabei jedoch: bei Zusatzadressen wird für bestehende Adressen mit obigem Schema auch nach der Adresse gesucht (siehe auch hier). Wird keine gefunden (z.B. weil du diese nachträglich bearbeitet/geändert hast), wird eine neue Zusatzadresse nach obigem Schema erstellt. Firmen und Privatkontakte werden hingegen weiterhin nach der regulären Vorgehensweise gesucht (mehr dazu hier).

Dies bedeutet: wenn du die Adresse in Bexio nachträglich bearbeitest, im Shop aber nicht sicherstellst, dass diese dort wie von dir erwartet eingegeben wird, wird sie bei zukünftigen Synchronisierungen weiterhin gemäss oben beschriebenem Schema automatisch aufgeteilt - es wird dann mitunter eine redundante Zusatzadresse im unerwünschten Format erstellt.

Teile der Adresse wurden in anderen Feldern gespeichert als erwartet

Um eine korrekte Übermittlung der Adresse zu garantieren, stelle sicher, dass in der Adresszeile 1 Strassenname und Hausnummer (und ausschliesslich nur diese beiden Daten) erfasst werden und alles andere in der Adresszeile 2, welche im Adresszusatz an Bexio übermittelt wird. Dies gilt auch für PLZ / Ort, welche in den dafür vorgesehenen Feldern im Shop zu erfassen sind. Ein paar Beispiele: