PPartnerDesk

36 — lexoffice-Integration

Aktualisiert am 1. Juni 2026

36 — lexoffice-Integration

lexoffice ist eine Online-Buchhaltung von Lexware. Wie easybill nimmt es eine Doppel-Rolle ein (Sales-In + Payout-Status), aber mit einem anderen Notification-Mechanismus.

Webhook-URL

https://<tenant-slug>.partnerdesk.io/api/webhooks/<tenant-slug>/lexoffice

Event-Matrix

Event Aktion
invoice.status.paid Transaktion + MLM-Provisionen
invoice.status.voided / invoice.status.cancelled TX auf refunded
credit-note.status.paid Payout.markAsPaid($paymentReference)
credit-note.status.voided Payout.cancel()

Resource-ID-Only-Modus

Wichtig: lexoffice sendet im Standard-Modus nur die resourceId des Dokuments. Die Details (Beträge, Adresse, LineItems) müssen via API nachgefragt werden.

PartnerDesk macht das automatisch — aber nur wenn ein API-Key in den Provider-Settings hinterlegt ist. Ohne API-Key wird der Webhook als skipped quittiert.

Setup

1. lexoffice-Webhook konfigurieren

lexoffice-Backend → Einstellungen → Öffentliche API → Webhook anlegen mit Ihrer URL.

2. Auth-Token

lexoffice akzeptiert drei Auth-Methoden:

  1. Authorization: Bearer <token> (Empfehlung).
  2. X-Lexoffice-Token-Header.
  3. ?token=... Query-Parameter.

Token-Wert kann ein selbst gewählter geheimer String sein.

3. PartnerDesk-Settings

Admin → „Zahlungsanbieter" → lexoffice:

  • Webhook-Token (= Bearer-Token aus Schritt 2) → für eingehende Webhooks.
  • API-Key → der separate „API-Key" aus den lexoffice-Settings, für Payload-Enrichment + Credit-Note-Anlage.

4. OAuth (optional, neuer Pfad)

lexoffice unterstützt seit einer neueren Version OAuth statt API-Key. PartnerDesk-OAuth-Flow:

  1. Admin → „Zahlungsanbieter" → lexoffice → „Mit OAuth verbinden".
  2. Redirect zu lexoffice → Login + Zustimmung.
  3. PartnerDesk speichert das Refresh-Token automatisch.

Voraussetzung: Plattform-Owner hat LEXOFFICE_OAUTH_CLIENT_ID und _SECRET als Env-Variablen gesetzt. Wenn nicht: Fehlerhinweis + Fallback auf API-Key.

Affiliate-Identifikation

Analog easybill: Document-customFields → Customer-customFields → Customer.assignedPartner. lexoffice nennt Custom Fields additionalProperties im JSON — PartnerDesk normalisiert das transparent.

Bidirektionaler Lifecycle

Wenn beide Richtungen aktiv sind, entsteht ein lückenloser Loop:

1. Sale tritt ein (Stripe-Webhook bei PartnerDesk)
2. Tenant erstellt manuell oder per API eine Rechnung in lexoffice
3. Endkunde bezahlt
4. lexoffice → Webhook „invoice.status.paid" → PartnerDesk markiert Provision als approved
5. Admin approve den Payout → PartnerDesk → API → Credit-Note in lexoffice
6. Tenant überweist Partner (manuell oder via SEPA)
7. Tenant markiert Credit-Note in lexoffice als bezahlt
8. lexoffice → Webhook „credit-note.status.paid" → PartnerDesk markiert Payout als paid

Externe Belegnummern

Nach jedem erfolgreichen Credit-Note-API-Call merkt sich PartnerDesk:

  • lexoffice-Resource-ID (UUID).
  • lexoffice-Voucher-Nummer (z. B. GS-2026-0042).

Beim Webhook-Eingang nutzt PartnerDesk diese persistierten Referenzen für deterministisches Matching statt heuristischer Suche über payoutNumber.

Verwandte Kapitel

Technische Tiefen-Doku: ../012-lexoffice-webhook.md, ../013-lexoffice-api-client.md, ../148-lead-campaigns-bundle.md (OAuth-Anbindung)