> For the complete documentation index, see [llms.txt](https://one-loop.gitbook.io/help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://one-loop.gitbook.io/help/marketplace-apps/lexware-office/firmen-und-privatkunden-zuordnen.md). # Firmen- und Privatkunden zuordnen ## Teststatus Die beschriebene Kontaktlogik ist im ausgelieferten Implementierungsvertrag enthalten. Die allgemeine Verfügbarkeit der Integration ist noch nicht bestätigt. Teste die Zuordnung daher zunächst mit kontrollierten Kontakten und prüfe das Ergebnis in Lexware Office. ## Was löst diese Funktion? Beim Erstellen einer Rechnung oder eines Angebots muss Lexware Office wissen, ob der aktuelle Workflow-Kontakt eine **Firma** oder eine **Privatperson** ist. Die Integration wählt den passenden Kontakt aus, aktualisiert ihn nur unter sicheren Bedingungen oder legt ihn neu an. So vermeidest du, dass eine bestehende Privatperson ungewollt zu einer Firma geändert wird – oder dass eine Firma mit einem gleichnamigen Privatkontakt vermischt wird. > Der Kundentyp wird nur in **Rechnung erstellen** und **Angebot erstellen** gewählt. Eine Auftragsbestätigung verwendet das bereits angenommene Angebot weiter; sie führt keine neue Kundentyp-Auswahl aus. ## Das Feld: Lexware customer type | Auswahl in der Action | Technischer Wert | Wann verwenden? | Wie entscheidet die Integration? | | ----------------------------------------- | ---------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Detect automatically from CRM contact** | `auto` | Standard, wenn die Kontaktpflege zuverlässig ist. | Mit nativer Firmenbezeichnung oder Business ID wird der Kontakt als Firma behandelt; sonst als Privatperson. | | **Company / business customer** | `company` | Wenn das Dokument an eine Firma gehen soll. | Erzwingt eine Firmenstruktur, unabhängig davon, ob eine Person im Kontakt eingetragen ist. | | **Private person** | `person` | Wenn das Dokument an eine natürliche Person geht. | Erzwingt eine Personenstruktur, unabhängig von einer eventuell vorhandenen Firmenbezeichnung. | Das Feld ist in beiden Actions Pflicht. Bereits gespeicherte ältere Action-Konfigurationen ohne dieses Feld verhalten sich wie `auto`.\n\n**Wichtig:** Eine vorhandene Business ID löst bei `auto` zwar die Firmen-Erkennung aus. Die native Firmenbezeichnung bleibt trotzdem Pflicht; ohne sie wird kein Dokument erstellt. ## Welche Kontaktdaten werden benötigt? Die Integration liest den **aktuellen Workflow-Kontakt**. Er muss zum aktuellen Standort gehören. Ein Kontakt aus einem anderen Standort oder ein fehlender Kontakt wird nicht verwendet. | Kundentyp | Pflichtdaten | Optionale Daten | Nicht automatisch verwendet | | ------------ | ----------------------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------- | | Firma | Native Firmenbezeichnung, Straße, Postleitzahl, Ort, zweistelliger Ländercode | E-Mail, Telefon, Umsatzsteuer-ID | Eine Firmenbezeichnung, die nur in einem eigenen Zusatzfeld steht | | Privatperson | Nachname, Straße, Postleitzahl, Ort, zweistelliger Ländercode | Vorname, E-Mail, Telefon | Eine Firmenbezeichnung, wenn du ausdrücklich `person` wählst | Fehlt eine Pflichtangabe, wird kein Dokument erstellt. Der Workflow liefert dann `errorCode = LEX_CUSTOMER_001_REQUIRED_DATA_MISSING`. Der Fehler benennt das erste fehlende Feld, etwa `companyName` oder `lastName`. ## So sieht die Übergabe aus Du wählst den Kundentyp im sichtbaren Action-Feld. Die Kontaktdaten werden nicht als großer JSON-Block in das Feld kopiert: Sie stammen aus dem aktuellen Workflow-Kontakt. ```json { "data": { "customerEntityType": "company" }, "extras": { "locationId": "aktueller-standort", "contactId": "aktueller-workflow-kontakt" } } ``` Die Integration lädt daraufhin den Kontakt, prüft seinen Standort und verwendet für eine Firma zum Beispiel Firmenbezeichnung und Rechnungsadresse. Für eine Privatperson verwendet sie Vorname, Nachname und Rechnungsadresse. ## Die Zuordnungsreihenfolge Die Prüfung läuft immer in dieser Reihenfolge. Sobald ein sicherer Treffer gefunden wurde, werden spätere Stufen nicht mehr verwendet. ``` 1. Gespeicherte passende Zuordnung ↓ kein passender Treffer 2. Exakte E-Mail-Übereinstimmung ↓ kein passender Treffer 3. Exakte Stammdaten-Übereinstimmung ↓ kein passender Treffer 4. Neuen Lexware-Kontakt anlegen ``` ### 1. Gespeicherte passende Zuordnung: `mapping` Nach einer erfolgreichen Zuordnung speichert die Integration die Verbindung zwischen dem Workflow-Kontakt, dem Standort und dem Lexware-Kontakt. Sie prüft dabei die aktuelle rechtliche Identität: * Firma: Kundentyp, Firmenbezeichnung und – falls vorhanden – Umsatzsteuer-ID. * Privatperson: Kundentyp, Vor- und Nachname. Passt diese Identität weiterhin, wird der hinterlegte Lexware-Kontakt wiederverwendet. Eine geänderte Anschrift kann dabei sicher aktualisiert werden, sofern der Lexware-Kontakt einfach aufgebaut ist. ### 2. Exakte E-Mail-Übereinstimmung: `email` Gibt es keine passende gespeicherte Zuordnung, sucht die Integration nach exakt derselben E-Mail-Adresse. Groß-/Kleinschreibung und überflüssige Leerzeichen ändern den Vergleich nicht. Eine gleiche E-Mail-Adresse reicht allein nicht aus. Der gefundene Kontakt muss zusätzlich zum gewählten Kundentyp und zur rechtlichen Identität passen: * Eine Firma wird nicht mit einer Privatperson zusammengeführt. * Bei Firmen dürfen sich Firmenbezeichnung oder Land nicht widersprechen. * Bei Privatpersonen dürfen sich vorhandener Vor- oder Nachname oder das Land nicht widersprechen. * Eine abweichende Umsatzsteuer-ID wird bei Firmen nicht zusammengeführt. Teilen sich verschiedene Personen oder Firmen dieselbe E-Mail-Adresse, wird kein unpassender Kontakt verändert. Die Prüfung geht stattdessen zur Stammdatenprüfung weiter oder legt einen neuen Kontakt an. ### 3. Exakte Stammdaten-Übereinstimmung: `master_data` Ohne sicheren E-Mail-Treffer sucht die Integration nach einer vollständigen Übereinstimmung der Stammdaten: | Kundentyp | Vergleichte Daten | | ------------ | ------------------------------------------------------------------------------------------ | | Firma | Firmenbezeichnung, Land, Postleitzahl und Straße; zusätzlich passende rechtliche Identität | | Privatperson | Vorname, Nachname, Land, Postleitzahl und Straße | Nur ein Name allein genügt nicht. Mindestens drei Zeichen im Suchnamen sind erforderlich. Schreibweisen werden für den Vergleich vereinheitlicht, zum Beispiel bei Groß-/Kleinschreibung und mehrfachen Leerzeichen. ### 4. Neuanlage: `created` Findet die Integration keinen sicheren Treffer, legt sie einen neuen Lexware-Kontakt mit dem gewählten Kundentyp an: * Firma: Firmenbezeichnung, Rechnungsadresse, optionale E-Mail und optionales Telefon. * Privatperson: Vorname, Nachname, Rechnungsadresse, optionale E-Mail und optionales Telefon. Danach speichert sie die neue Zuordnung für spätere Dokumente. ## Was passiert bei einem Wechsel zwischen Firma und Privatperson? Ein bestehender Lexware-Kontakt wird **niemals** von Privatperson zu Firma oder von Firma zu Privatperson umgewandelt. Beispiel: 1. Dein Kontakt „Max Mustermann“ wird bisher als Privatperson abgerechnet. 2. Später ergänzt du die Firma „Muster GmbH“ und wählst `company`. 3. Die alte Privatperson bleibt für frühere Dokumente erhalten. 4. Die Integration verwendet einen passenden bestehenden Firmenkontakt oder legt einen neuen Firmenkontakt an. 5. Wechselt der Kontakt später wieder zurück, kann die frühere passende Privatpersonen-Zuordnung wiederverwendet werden. Damit bleiben historische Dokumente und ihre ursprüngliche Kontaktform nachvollziehbar. ## Wann wird ein vorhandener Kontakt aktualisiert? Ein wiederverwendeter Kontakt wird nur aktualisiert, wenn dies sicher ist. Als einfach gilt ein Kontakt, wenn in jeder gespeicherten Adress-, E-Mail- und Telefonart höchstens ein Wert liegt und – bei Firmen – höchstens eine Kontaktperson vorhanden ist. | Situation | Verhalten | Hinweis im Ergebnis | | ------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------- | | Einfacher Kontakt, E-Mail passt oder ist noch nicht vorhanden | Kontaktdaten können aktualisiert werden. | `customerUpdated = true`, wenn sich etwas geändert hat. | | Komplexer Kontakt mit mehreren Einträgen | Kontakt wird verwendet, aber nicht automatisch geändert. | `LEX_CONTACT_W001_UPDATE_SKIPPED_COMPLEX_CONTACT` in `warnings`. | | Bestehende E-Mail weicht von der Workflow-E-Mail ab | Kontakt wird verwendet, aber die E-Mail wird nicht überschrieben. | `LEX_CONTACT_W002_UPDATE_SKIPPED_EMAIL_CONFLICT` in `warnings`. | ## Was passiert bei mehrfachen gleichen Treffern? Gibt es mehrere vollständig identische Lexware-Kontakte, blockiert die Integration die Dokumenterstellung nicht. Sie wählt den Treffer nachvollziehbar aus: 1. zuerst die niedrigere Kundennummer, 2. bei gleicher oder fehlender Kundennummer die niedrigere technische Kontakt-ID. Der Workflow erhält zusätzlich die Warnung `LEX_CONTACT_W003_DUPLICATE_IDENTITY_MATCH_SELECTED` in `warnings`. Prüfe diesen Fall später in Lexware Office und bereinige die doppelten Kontakte bewusst. ## Beziehung zu Steuerfeldern Kundentyp und Steuerart sind zwei getrennte Einstellungen. Das Wählen von `company` aktiviert keine besondere Steuerart automatisch. Die Steuerarten `intraCommunitySupply`, `constructionService13b`, `externalService13b`, `thirdPartyCountryService` und `thirdPartyCountryDelivery` sind nur für Firmen zulässig. Bei Privatpersonen stoppt der Workflow vor der Kontaktanlage mit `LEX_CONTACT_006_COMPANY_REQUIRED_FOR_TAX_TYPE`. Für `intraCommunitySupply` muss außerdem eine Umsatzsteuer-ID am Firmenkontakt vorhanden sein. Fehlt sie, lautet der Fehler `LEX_CONTACT_005_VAT_ID_REQUIRED`. ## Die Ergebnisvariablen verstehen und verwenden Nach **Rechnung erstellen** oder **Angebot erstellen** prüfst du diese Variablen im nächsten Schritt: | Variable | Mögliche Werte / Bedeutung | So setzt du sie ein | | ---------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `lexwareContactId` | Technische ID des tatsächlich verwendeten Lexware-Kontakts. | Für Protokolle oder technische Folgeaktionen verwenden. | | `customerMatchMethod` | `mapping`, `email`, `master_data` oder `created`. | In einer Notiz protokollieren oder bei `created` eine interne Prüfung anlegen. | | `customerCreated` | `true`, wenn ein neuer Lexware-Kontakt angelegt wurde. | If/Else: bei `true` den neuen Kontakt intern prüfen. | | `customerUpdated` | `true`, wenn ein bestehender Kontakt sicher aktualisiert wurde. | In einem Änderungsprotokoll verwenden. | | `warnings` | Zusätzliche Hinweise ohne zwingenden Fehler. | Vor einer automatischen Folgeaktion auf Warnungen prüfen. | | `success` | `true`, wenn die gesamte Action erfolgreich beendet wurde. | Erst dann mit Dokumentnummer oder Datei-Link weiterarbeiten. | | `errorCode` / `errorMessage` | Fehlerkennung und verständliche Fehlerbeschreibung. | Im Fehlerzweig des Workflows speichern oder an die zuständige Person geben. | ## Realistisches Beispiel: Neuer Firmenkunde trotz gleicher E-Mail Ein Kontakt „Anna Beispiel“ ist als Privatperson in Lexware Office vorhanden. Später bestellt die „Beispiel GmbH“ über dieselbe E-Mail-Adresse. 1. In **Rechnung erstellen** wählst du **Company / business customer**. 2. Der Workflow-Kontakt enthält die native Firmenbezeichnung „Beispiel GmbH“ sowie vollständige Rechnungsadresse. 3. Die E-Mail-Suche findet den bestehenden Privatkontakt, erkennt aber den anderen Kundentyp. 4. Der Privatkontakt wird nicht geändert. 5. Die Integration sucht nach einem passenden Firmenkontakt und legt ihn an, falls keiner vorhanden ist. 6. Der Workflow liefert `customerMatchMethod = created`, `customerCreated = true` und die neue `lexwareContactId`. 7. Im nächsten Schritt erstellst du mit diesen Werten eine interne Prüfnachricht. ## Ergebnis prüfen Nach einem Testlauf: 1. Prüfe im Workflow-Verlauf `customerMatchMethod`, `customerCreated`, `customerUpdated`, `warnings` und `lexwareContactId`. 2. Öffne den zurückgegebenen `lexwareViewUrl` und kontrolliere den verwendeten Kontakt in Lexware Office. 3. Teste mindestens diese Fälle getrennt: Privatperson, Firma, gleicher E-Mail-Wert bei unterschiedlichen Kundentypen und Wechsel von Privatperson zu Firma. 4. Prüfe bei Firmen mit besonderer Steuerart zusätzlich die Umsatzsteuer-ID. ## Typische Fehler vermeiden * Verwende für eine Firma die native Firmenbezeichnung des Workflow-Kontakts, nicht nur ein eigenes Zusatzfeld. * Wähle `company` bewusst, wenn ein Kontakt sowohl persönliche als auch Firmenangaben enthält. * Überschreibe Warnungen nicht: Sie bedeuten, dass die Dokumenterstellung zwar fortgesetzt wurde, eine automatische Kontaktänderung aber ausgelassen wurde. * Nutze `customerMatchMethod` und `customerCreated` für einen transparenten internen Prüfpfad. * Ändere einen bestehenden Kontakt nicht manuell zwischen Firma und Privatperson, um eine alte Zuordnung „passend zu machen“. Lege oder verwende die korrekte rechtliche Identität. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://one-loop.gitbook.io/help/marketplace-apps/lexware-office/firmen-und-privatkunden-zuordnen.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.