NAV

lexoffice API Kochbuch - Public API

Entwicklungsumgebung

Die lexoffice Public API steht als REST API in unserer Produktivumgebung zur Verfügung.

Wir empfehlen für die Entwicklung von Integrationen und Anbindungen, welche die Public API verwenden, die Verwendung von lexoffice Test-Accounts. Diese können jederzeit angelegt werden, sind kostenfrei und 30 Tage gültig. Bis auf wenige Einschränkungen (z.B. Elster) bieten lexoffice Test-Accounts alle Funktionen der Version lexoffice XL.

Sie entscheiden selbst, wann die Integration oder Anbindung den Stand erreicht hat um damit produktiv zu arbeiten. Es ist keine Abnahme oder Qualitätskontrolle seitens lexoffice vorgesehen oder erforderlich.

Bitte beachten Sie die folgenden Hinweise zur Nutzung der lexoffice Public API:

First Steps

Allgemeine Nutzungsbedingungen zur Public API

Für die Nutzung der Public API gelten unsere Allgemeinen Nutzungsbedingungen zur Public API: https://www.lexoffice.de/public-api-lizenz-nutzungsbedingungen/

API Key

API Keys können in gängigen Tools sofort eingesetzt werden. lexoffice bietet für Postman (https://www.getpostman.com/) eine Beispielsammlung an. Sie finden diese in den Samples der Technischen Dokumentation: https://developers.lexoffice.io/docs/

Pro Benutzer können mehrere API Keys mit einem bezeichnenden Namen erstellt werden. Optional können die Berechtigungen des Keys für den Zugriff auf lexoffice eingeschränkt werden. Für eine erhöhte Sicherheit, können Sie weiterhin mehrere Benutzer anlegen, falls Sie den Zugang kontrollieren und die Überwachung von Aktivitäten erleichtern wollen (siehe Benutzer und Berechtigungen und Protokollierung in lexoffice).

Die Lebensdauer des API Keys beträgt 24 Monate. Diese können Sie bei Bedarf in der API Keys Verwaltung (https://app.lexoffice.de/addons/public-api) erneuern.

Events und Webhooks

Zur Synchronisierung von Daten der API Client-Anwendung und lexoffice bietet die Public API Webhooks an. Details zur Verwendung von Webhooks finden Sie im Kapitel “Event Subscriptions Endpoint” der Technischen API Dokumentation.

Wie Webhooks funktionieren wird anhand des Events “invoice.status.changed” erklärt.

Änderungen am Status einer Rechnung können Webhooks auslösen. Dazu muss die API Client-Anwendung eine Subscription auf den event “invoice.status.changed” anlegen. Bei der Anlage des Events muss eine callback-URL angegeben werden. Diese callback-URL wird seitens lexoffice aufgerufen, wenn der event eintritt.

Hier ein POST request mit Beispiel Payload im JSON Format der beim Eintreten des Events an die callback-URL gesendet wird:

{
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "eventType": "invoice.status.changed",
  "resourceId": "4d43ad14-671d-4e0c-fd4b-2fd8cc117eff",
  "eventDate": "2023-05-23T12:30:00.000+02:00"
}

Der Beispiel JSON Payload ist wie folgt zu interpretieren:

Best Practice für die Verarbeitung von Webhooks den Einsatz einer Eingangs-Queue. Die Einträge in der Queue können dann z.B. asynchron abgearbeitet werden.

Falls die Zustellung eines Webhooks temporär aufgrund von z.B. Netzwerkproblemen fehlschlägt, finden innerhalb von 48 Stunden mehrere Wiederholungen statt.

lexoffice unterstützt neben Events für Rechnungen auch Events für Kontakte (Kontakt angelegt, geändert, …).

API Dokumentation

Die vollständige Dokumentation aller REST-Endpunkte und der verfügbaren Methoden finden Sie hier.