PPartnerDesk

35 — easybill-Integration

Aktualisiert am 1. Juni 2026

35 — easybill-Integration

easybill ist ein deutsches Online-Buchhaltungs-/Rechnungstool. Anders als Stripe/Digistore/CopeCart/Ablefy ist easybill kein Payment-Provider, sondern eine Buchhaltungs-Software — easybill weiß nur, wann eine Rechnung als „bezahlt" markiert wurde. PartnerDesk nutzt easybill in zwei Richtungen.

Webhook-URL

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

Doppel-Rolle

Richtung Was passiert
Eingehend (Sales) Sobald in easybill eine Invoice als bezahlt markiert wird, erzeugt PartnerDesk eine Transaktion
Ausgehend (Auszahlungen) Bei Payout-Approval legt PartnerDesk automatisch eine Credit-Note in easybill an (siehe 44)

Event-Matrix

Event Document-Typ Aktion
document.paid invoice Neue Transaktion + MLM-Provisionen (falls Affiliate identifizierbar)
document.paid credit_note Bestehenden Payout auf paid setzen (Bank-Referenz aus dem payment_reference-Feld)
document.canceled invoice Transaktion auf refunded
document.canceled credit_note Payout auf cancelled

Setup

1. easybill-Webhook konfigurieren

easybill-Backend → Einstellungen → API & Webhooks → URL eintragen.

2. Token-basierte Authentifizierung

easybill nutzt keinen HMAC, sondern einen Token. Wird mitgesendet via:

  • X-Easybill-Token-Header, ODER
  • ?token=...-Query-Parameter (für Test-Tools).

hash_equals() prüft den Token timing-safe gegen den hinterlegten Wert.

3. Token + API-Key in PartnerDesk eintragen

Admin → „Zahlungsanbieter" → easybill:

  • Webhook-Token → für eingehende Webhooks.
  • API-Key (separat in easybill-Settings) → für ausgehende API-Calls (Enrichment + Credit-Note-Anlage).

Affiliate-Identifikation

easybill kennt keinen nativen Affiliate-Begriff. PartnerDesk versucht drei Wege:

  1. Custom Fields auf dem Document: custom_fields[].name == 'affiliate_id' oder 'partner_id'.
  2. Custom Fields auf dem Customer: Lookup auf Customer-Ebene.
  3. Customer.assignedPartner: bestehender Match aus früherer Lifetime-Zuweisung.

Wenn keine Quelle einen Partner liefert: TX wird als skipped quittiert (nicht jede easybill-Rechnung ist affiliate-getrieben — das ist OK).

Payload-Enrichment

Webhook von easybill enthält oft nur event + document_id. PartnerDesk holt sich Document- und Customer-Details automatisch per API-Call (deshalb die separate API-Key-Eingabe). Details: …/014-easybill-api-client.md.

Payment-Reference

Bei credit_note.paid wird payment_reference aus dem easybill-Document ausgelesen — Bank-Transaktions-ID o. ä. — und in Payout.payoutReference persistiert. Damit ist nachvollziehbar, welche Bank-Überweisung welche Auszahlung erledigt hat.

Auszahlungs-Sync (Ausgehend)

Bei jedem Payout-Approval erzeugt PartnerDesk automatisch eine Credit-Note in easybill (sofern API-Key konfiguriert). Inhalt:

  • Empfänger: Partner-Adresse aus den Stammdaten.
  • Position: „Provisionsgutschrift {Nummer} für Zeitraum {Start} – {Ende}".
  • Steuer: 19 % oder 0 % (Kleinunternehmer).
  • external_id: PartnerDesk-Payout-Nummer (für späteren Match beim Webhook).

Details: 44.

Verwandte Kapitel

Technische Tiefen-Doku: ../011-easybill-webhook.md, ../014-easybill-api-client.md, ../015-outgoing-credit-notes.md