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 Buchhalter und Berichte.

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:

• Zur Synchronisierung von Daten (z.B. Kontakten) zwischen ihrer API Client-Anwendung und lexoffice steht unsere Webhook Funktionalität (siehe unten) zur Verfügung. Polling von Ressourcen ist unbedingt zu vermeiden.
• Es ist nicht erlaubt die lexoffice Public API für Performance- und Lasttests zu verwenden. Wenn die Notwendigkeit hierfür besteht, kommen Sie bitte auf uns zu.

First Steps

• Legen Sie sich unter https://app.lexoffice.de/signup einen lexoffice Account an oder verwenden Sie einen existierenden lexoffice Account.
• Sofern noch nicht vorhanden komplettieren Sie bitte die Daten zur Firmierung (https://app.lexoffice.de/settings/#/company)
• Optional: Konfigurieren Sie das Rechnungs-Layout unter https://app.lexoffice.de/voucher/settings/#/Step1
• Generieren Sie einen API Key; über diesen in der Pilotphase noch versteckten Link erreichen Sie die Public API Key Verwaltung: https://app.lexoffice.de/addons/public-api
  Weitere Informationen zu den API Keys finden Sie weiter unten.

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

• Keine Übertragung des API Keys über potentiell unsichere Kanäle wie z.B. E-Mail.
• Installation des API Keys ausnahmslos in Webapplikationen die HTTPS unterstützen.

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/

Wenn Sie mehrere API Keys benötigen, legen Sie bitte pro API Key einen eigenen Benutzer an: https://app.lexoffice.de/user-administration/#/userList

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

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:

• organizationId: Der Webhook bezieht sich auf die ID des lexoffice Accounts 612f56c7-4e92-4124-9e1f-4ed2b48e3e50.
  
• eventType: Es handelt sich um die Änderung am Status einer Rechnung.
• resourceId: Der Event bezieht sich auf die Rechnung mit ID 4d43ad14-671d-4e0c-fd4b-2fd8cc117eff
• eventDate: Die Änderung am Status der Rechnung fand am 2023-05-23 um 12:30:00.000+02:00 Uhr statt.

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.