Contacts Endpoint verstehen und effizient nutzen
Wenn du mit Geschäftskontakten in Lexware Office arbeitest, ist der Contacts Endpoint Lexware Office der zentrale Einstieg. Dieser stellt dir sämtliche Informationen zu Kontakten bereit – egal ob Kunde, Lieferant oder beides. Hier bekommst du nicht nur Namen und Nummern, sondern auch Adressen, Ansprechpartner, Telefonnummern und mehr. Damit hast du alles, was du für den Aufbau von digitalen Prozessen rund um Geschäftsbeziehungen brauchst.
-
Was steckt im Contact-Objekt?
Ein Kontakt besteht aus mehreren verschachtelten Objekten. Je nach Kontext kann das ein Unternehmen oder eine Privatperson sein. Entscheidend ist, dass jeder Kontakt mindestens eine Rolle (Kunde oder Lieferant) haben muss. Ohne Rolle kein Kontakt.
-
Firmenkontakte mit Struktur
Für Firmenkontakte sind vor allem folgende Felder interessant:
company,addresses,contactPersons,emailAddressesundphoneNumbers. Diese Datenstruktur erlaubt es dir, zentrale Unternehmensinformationen detailliert abzubilden. Besonders praktisch: Du kannst Ansprechpartner definieren, inklusive E-Mail und Telefonnummer. Dabei gilt: Nur ein Ansprechpartner kann per API gesetzt werden – mehr geht nur lesend. -
Adressen, E-Mails, Telefonnummern
Auch bei Adressen, Mail-Adressen und Telefonnummern ist das Prinzip gleich: Es lassen sich mehrere lesen, aber nur eine pro Typ schreiben oder aktualisieren. Bedeutet für dich: Beim Erstellen oder Aktualisieren solltest du dich auf jeweils eine Adresse pro Kategorie (z. B. eine Rechnungsadresse, eine Lieferadresse) beschränken.
-
Privatpersonen? Auch kein Problem
Neben Firmen kannst du auch Privatpersonen verwalten. Hier kommen die Felder
personsowiesalutation,firstNameundlastNameins Spiel. Auch hier ist eine Rolle notwendig – z. B. als Kunde. -
XRechnung-ready
Besonders spannend für alle, die mit öffentlichen Auftraggebern arbeiten: Mit den Feldern
buyerReferenceundvendorNumberAtCustomerlässt sich ein Kontakt für XRechnung kennzeichnen. Damit erzeugst du konforme Rechnungen direkt aus dem System heraus. -
Was du beim Schreiben beachten musst
Ein paar wichtige Punkte zur Nutzung des Endpunkts:
- Du kannst Kontakte mit mehreren Einträgen pro Kategorie lesen, aber nur mit einem Eintrag pro Kategorie schreiben.
- Jeder Kontakt braucht mindestens eine Rolle:
customerodervendor. - Versionierung ist eingebaut – jede Änderung erhöht die
versionautomatisch. - Felder wie
id,organizationIdoderversionsind Read-only.
-
Filter und Abfragen
Natürlich kannst du über diesen Endpoint auch gezielt Kontakte filtern – etwa nach Rolle, Name oder anderen Eigenschaften. Das macht ihn ideal für automatisierte Prozesse wie Angebotsversand, Rechnungsstellung oder Lieferantenkommunikation.
Der Contacts Endpoint ist mehr als nur eine einfache Datenschnittstelle – er ist ein zentrales Werkzeug für jede App, die mit Geschäftsbeziehungen arbeitet. Wenn du die Struktur verstanden hast, kannst du damit extrem schnell und sicher Kundendaten verarbeiten – egal ob für CRM-Zwecke, Rechnungsprozesse oder Kommunikation. Und mit ein bisschen Struktur im Code bist du auch bei Updates und Versionierung auf der sicheren Seite.
/contacts
GET
Wenn du Kontakte aus Lexware abrufen willst, nutzt du den GET-Endpunkt /v1/contacts. Du kannst dabei verschiedene Filterparameter setzen, zum Beispiel email, name, number, customer oder vendor. Jeder Filter darf nur einmal in der Anfrage vorkommen. Mehrere Filter werden logisch mit UND verknuepft. Filter, die nicht gesetzt sind, werden ignoriert. Damit eine Suche funktioniert, müssen mindestens drei Zeichen angegeben werden. Die Rückgabe erfolgt seitenweise. Mit dem Parameter page=0 startest du mit der ersten Seite. Die maximale Seitengrösse hängt vom System ab. Nach dem Abruf kannst du direkt per Deeplink zum jeweiligen Kontakt in der App springen. Die URL dafür lautet {appbaseurl}/permalink/contacts/view/{contactId}. Das ist nützlich, wenn du Daten manuell ergänzen oder anpassen willst.
Power Apps |
Lexoffice.RetrieveAllContacts()/contacts/{id}
GET
Mit dem Endpunkt /v1/contacts/{id} kannst du gezielt einen einzelnen Kontakt per ID abrufen oder aktualisieren. Beim Abruf per GET bekommst du alle gespeicherten Details des Kontakts.
Power Apps |
Lexoffice.RetrieveContact("076858cf-b8a0-4399-8dae-d09e486ed5ea")/contacts
POST
Um einen neuen Kontakt in Lexware anzulegen, nutzt du den POST-Endpunkt /v1/contacts. Der Request erwartet ein JSON-Objekt, das mindestens die Version, eine definierte Rolle sowie entweder eine Personen- oder Firmenangabe enthält. Die Version muss beim Anlegen immer auf 0 gesetzt sein. Damit der Kontakt als Kunde angelegt wird, reicht es aus, die Rolle customer als leeres Objekt zu übergeben. Entscheidend ist: Ein Kontakt kann entweder eine Firma oder eine Person sein – nie beides gleichzeitig. Bei einer Person musst du mindestens den Nachnamen angeben, Anrede und Vorname sind optional. Für Firmenkontakte ist der Firmenname Pflicht, außerdem muss ein Nachname für eine Ansprechperson mitgeliefert werden. Optional kannst du zusätzliche Felder wie eine Notiz oder später auch eine Adresse mitgeben – letztere verlangt dann zwingend einen gültigen Ländercode im ISO-3166-alpha2-Format, zum Beispiel DE für Deutschland. Nach dem erfolgreichen Erstellen liefert der Endpunkt eine eindeutige ID, den Ressourcentyp sowie Zeitstempel für Erstellungs- und Änderungsdatum zurück.
Power Apps |
Lexoffice.CreateContact(
ParseJSON(
JSON(
{
version: 0,
roles: {customer: {}},
person: {
salutation: "Frau",
firstName: "Inge",
lastName: "Musterfrau"
},
note: "Notizen"
}
)
)
)/contacts/{id}
PUT
Wenn du einen bestehenden Kontakt aktualisieren willst, nutzt du den PUT-Endpunkt /v1/contacts/{id}. Dabei ersetzt du {id} durch die eindeutige ID des Kontakts. Die neuen Daten übergibst du im JSON-Format im Body der Anfrage. Die benötigten Felder entsprechen dabei den gleichen Regeln wie beim Erstellen eines Kontakts. Wichtig ist, dass bestimmte Felder in der Datenstruktur nur jeweils einen Eintrag enthalten dürfen. Das betrifft zum Beispiel Rechnungs- und Lieferadressen oder die verschiedenen Kategorien von E-Mail-Adressen und Telefonnummern. Wenn du versuchst, einen Kontakt mit mehreren Einträgen in einem dieser Felder zu aktualisieren, wird die Anfrage mit einem Validierungsfehler abgelehnt. Auch bei den Kontaktpersonen einer Firma darf nur genau eine Person angegeben sein. Halte deine Daten also schlank und eindeutig, um Fehler zu vermeiden. Bei erfolgreichem Update bekommst du eine Bestätigung zurück, dass die Aktion abgeschlossen wurde.
Power Apps |
With(
{contactId: "076858cf-b8a0-4399-8dae-d09e486ed5ea"},
Lexoffice.UpdateContact(
contactId,
ParseJSON(
JSON(
{
version: Lexoffice.RetrieveContact(contactId).version,
roles: {customer: {number: 10021}},
person: {
salutation: "Frau",
firstName: "Inge",
lastName: "Musterfrau"
},
note: "Neue lala Notizen"
}
)
)
)
)
Entdecke deine Möglichkeiten
Beispiele für Lexware Office
Lexware Office /voucherlist
Mit dem voucherlist-Endpunkt Belege filtern Wenn du Belege per API effizient abrufen willst, ist der voucherlist-Endpunkt dein Einstiegspunkt. Hier bekommst du nicht nur eine paginierte Liste, sondern kannst auch gezielt nach Typ, Status, Zeitraum und mehr filtern. Egal ob Eingangsrechnung, Ausgangsrechnung oder Gutschrift – dieser Endpunkt liefert dir genau das,
Lexware Office – Einstieg in API
Lexware Office automatisieren mit Power Automate & Power Apps Die Standardfunktionen von Lexware Office reichen oft weit – aber eben nicht immer. Sobald Abläufe individueller werden oder du deine Daten weiterverarbeiten möchtest, kommt man mit Bordmitteln schnell an Grenzen. Und genau hier kommt der Lexware-Office-Connector ins Spiel. Mit der Verbindung
Lexware Office /articles
Artikelverwaltung per API: So nutzt du den Lexware-Endpunkt richtig Wenn du Artikel in Lexware programmatisch erstellen, lesen oder aktualisieren willst, dann ist der articles-Endpunkt dein Werkzeug der Wahl. Damit kannst du Produkte und Dienstleistungen in deinem System verwalten, die später in Belegen wie Angeboten oder Rechnungen verwendet werden. Klingt simpel?
Lexware Office /files
Dateien abrufen und hochladen – so einfach geht’s mit der API Du willst Belege nicht mehr manuell verwalten, sondern direkt per API in dein System holen oder hochladen? Genau dafür gibt es zwei praktische Endpunkte: Einen zum Herunterladen von Dokumenten wie Rechnungen, Quittungen oder E-Rechnungen – und einen zum Hochladen