PPartnerDesk

44 — Externe Buchhaltung-Sync (easybill / lexoffice)

Aktualisiert am 1. Juni 2026

44 — Externe Buchhaltung-Sync (easybill / lexoffice)

Sobald Sie als Tenant easybill oder lexoffice nutzen, kann PartnerDesk Ihre Provisionsgutschriften automatisch dort anlegen. Doppelte Erfassung (lokal + extern) wird damit überflüssig.

Wie funktioniert es?

Bei jedem Approval eines Payouts (siehe 40):

  1. PartnerDesk legt das lokale PDF an (für Ihr Archiv + Partner-Download).
  2. Asynchron im Hintergrund wird die Gutschrift in easybill oder lexoffice angelegt.
  3. PartnerDesk speichert die externe Belegnummer auf dem lokalen PayoutDocument.
  4. UI zeigt grünes Badge „Synct" mit Provider-Logo + externer Belegnummer.

Provider-Reihenfolge

PartnerDesk prüft die konfigurierten Provider in dieser Priorität:

  1. lexoffice (wenn API-Key oder OAuth-Token vorhanden).
  2. easybill (wenn API-Key vorhanden).

Beim ersten erfolgreichen Provider wird gestoppt. Schlägt der erste fehl: automatischer Fallback auf den zweiten. Schlagen beide fehl: Sync wird übersprungen, Approval-Prozess bricht nicht ab — Sie haben weiterhin die lokale PDF.

Setup

easybill aktivieren

Admin → „Zahlungsanbieter" → easybill:

  • Webhook-Token + API-Key eintragen.
  • Standardmäßig deaktiviert — Sie aktivieren via Toggle.

lexoffice aktivieren

Admin → „Zahlungsanbieter" → lexoffice:

  • OAuth (empfohlen) oder API-Key.
  • Toggle aktivieren.

Wenn Sie nur lokal arbeiten wollen

Beide deaktiviert lassen. PartnerDesk arbeitet rein lokal mit DomPDF-Gutschriften.

Was wird in der externen Software angelegt?

Empfänger (Partner)

  • Adresse aus den Partner-Stammdaten.
  • Bei Partner.companyName gesetzt → als Firma in der Buchhaltung, sonst aus Vor-/Nachname.

Position

Eine Position mit Beschreibung:

„Provisionsgutschrift {payoutNumber} für Zeitraum {periodStart} – {periodEnd}"

Einheitspreis = Brutto-Provision des Payouts.

Steuer

  • Standard: 19 % (oder Tenant-Default).
  • Kleinunternehmer (Partner.vat_rate=0): 0 % + Vermerk nach §19 UStG.

In lexoffice wird das als taxType: 'smallbusiness' markiert, in easybill als is_small_business: true.

Reference

Payout.payoutNumber wird als reference (lexoffice) bzw. external_id (easybill) am externen Dokument gespeichert. Das ist die Brücke für das spätere Webhook-Matching.

Retry-Strategie

Falls der API-Call zur externen Software fehlschlägt (Netzwerk, Server-Error):

  • Message landet in der accounting-Queue.
  • 6 Retries, exponentielles Backoff 10 s → 1 h.
  • Bei Erschöpfen: Message im failed-Transport (Admin kann via Re-Sync-Button erneut auslösen).

Manueller Re-Sync

Falls Sync fehlgeschlagen ist (gelbes „Ausstehend"-Badge in der Payouts-Liste):

Admin → Payout-Liste → „Sync" → triggert die SyncAccountingCreditNoteMessage erneut. Polling-Update der UI bis Status grün wird.

Sync-Status sehen

Admin → „Auszahlungen" → Spalte „Buchhaltung":

Badge Bedeutung
(leer, grau) Payout ist draft — noch nicht approved
🟡 „Ausstehend" Approved, aber externer Sync noch nicht erfolgt
🟢 „lexoffice GS-2026-0042" Erfolgreich gesynct, mit externer Belegnummer

Webhook-Rückfluss

Wenn der externe Beleg in der Buchhaltungs-Software später als bezahlt markiert wird (z. B. nach Banküberweisung):

  • easybill/lexoffice senden einen document.paid/credit-note.status.paid Webhook.
  • PartnerDesk matcht den Beleg via der gespeicherten externen Belegnummer.
  • Lokaler Payout wechselt automatisch auf paid.

Damit ist der Loop vollständig automatisiert: Approval → externe Gutschrift → Banküberweisung → Status-Update zurück.

Kleinunternehmer-Hinweis

Wenn ein Partner Kleinunternehmer ist (vat_rate=0), wird das durchgängig korrekt behandelt:

  • Lokale PDF mit §19 UStG-Vermerk.
  • Externe Gutschrift mit Smallbusiness-Flag.
  • Keine MwSt im Betrag.

Voraussetzung: Partner.vat_rate=0 ist gepflegt.

Verwandte Kapitel

Technische Tiefen-Doku: ../015-outgoing-credit-notes.md, ../016-auto-external-credit-on-approval.md, ../017-external-document-references.md, ../018-async-accounting-sync.md