kaffeekasse-saas/docs/billing.md

Preis- und Abrechnungslogik

Stand: 2026-07-16

Geplante Architektur (mit dem Kunden abgestimmt): Stripe Billing für den Zahlungseinzug, bestehendes Dolibarr für Rechnungsstellung/Buchhaltung. Kein eigenes Rechnungssystem, kein zusätzliches ERP nur für Kaffeeliste – siehe Begründung unten.

Warum diese Aufteilung

Drei getrennte Probleme:

1. Rechnung erzeugen – löst Dolibarr (bereits im Einsatz für ein anderes Business des Kunden), fortlaufend nummeriert, GoBD-konform.
2. Geld tatsächlich einziehen – der eigentlich schwierige Teil (wiederkehrende Belastung, Fehlschlag-Wiederholung, Zahlungsmittel- Verwaltung). Weder ein selbstgebautes System noch Dolibarr allein lösen das; ein Zahlungsanbieter mit Abo-Logik schon.
3. Tarif-/Nutzungsstand verwalten – das übernimmt Kaffeeliste selbst, da die Teilnehmerzahl je Mandant ohnehin schon vorhanden ist.

Empfehlung: Stripe Billing statt Mollie, weil eine echte Abo-Logik mit automatischem Stufenwechsel gebraucht wird (Stripes Billing-Produkt ist dafür ausgereifter als Mollies Subscriptions-API); Mollie ist bei SEPA-Lastschrift günstiger, aber weniger auf SaaS-Abos zugeschnitten.

Phase 1: Datenmodell und Tariflogik (umgesetzt, keine externen Zugänge nötig)

Umgesetzte Dateien:

database/migrations/0014_saas_tenant_billing.sql
app/billing.php
app/saas-auth.php (Init bei Registrierung)
mandant-einstellungen.php (Anzeige "Abo & Tarif")
app/platform-admin.php, backoffice.php (Tarif-Spalte im Back-Office)

• Neue Tabelle tenant_billing: plan_code, subscription_status, stripe_customer_id, stripe_subscription_id, current_period_end, dolibarr_thirdparty_id (letztere beide vorbereitet für Phase 2/3, noch ungenutzt).
• billing_plans() ist die einzige Quelle für die Tarifstufen (free/basic/plus/pro/enterprise), synchron mit den Preisen auf preise.php.
• billing_required_plan_code() errechnet anhand der aktiven Teilnehmerzahl die günstigste ausreichende Stufe.
• billing_check_tenant() vergleicht gebuchten mit benötigtem Tarif; rein informativ – kein Enforcement, kein Sperren bei Überschreitung. Solange Stripe nicht angebunden ist, wird bei Bedarf manuell umgestellt (Hinweistext verweist auf Kontakt per E-Mail).
• Neue Mandanten starten automatisch mit plan_code = 'free'.
• Owner/Admin sehen ihren aktuellen Tarif und die aktive Teilnehmerzahl unter „Abo & Tarif" auf mandant-einstellungen.php; bei Bedarf einer höheren Stufe erscheint ein Hinweis.
• Das Back-Office (backoffice.php) zeigt zusätzlich zur Mandantenliste den gebuchten Tarif und, falls abweichend, den tatsächlich benötigten Tarif – der Betreiber sieht auf einen Blick, wer manuell hochgestuft werden müsste.

Live getestet: Tarifgrenzen-Berechnung (10/25/50/150) mit einem Mandanten knapp unter und einem mit 12 Teilnehmern (über dem Freikontingent, korrekt als „basic" erkannt) geprüft; UI-Anzeige in Mandant-Einstellungen und Back-Office live verifiziert. Alle bestehenden M8-Isolationstests und der Rollen-Matrix-Test bleiben unverändert grün.

Phase 2: Stripe-Anbindung (umgesetzt)

Umgesetzte Dateien:

app/stripe.php
app/billing.php (Stripe-Preis-Auflösung ergänzt)
abo-upgrade.php
abo-portal.php
stripe-webhook.php
mandant-einstellungen.php (Upgrade-/Portal-Buttons)

• app/stripe.php: minimaler REST-Client für die Stripe-API auf Basis von PHP-Streams (file_get_contents + stream_context_create), kein vendortes SDK und kein composer.json nötig – diese PHP-Installation hat ohnehin keine curl-Extension, Streams sind portabler.
• Für jeden bezahlten Tarif (basic/plus/pro) wurde per API ein Stripe-Produkt mit monatlichem Preis angelegt, referenziert über einen stabilen lookup_key (kaffeeliste_basic/_plus/_pro) statt einer hartcodierten Price-ID – stripe_find_or_create_price() ist idempotent, ein erneuter Aufruf legt nichts doppelt an.
• abo-upgrade.php: erstellt eine Stripe-Checkout-Session (Modus subscription) für den vom Kunden gewählten Tarif und leitet dorthin weiter. tenant_id/plan_code werden sowohl auf der Checkout-Session als auch auf der Subscription selbst als Metadaten gesetzt, damit spätere Subscription-Events (die kein Checkout-Session-Objekt mehr enthalten) trotzdem einem Mandanten zugeordnet werden können.
• abo-portal.php: öffnet das Stripe Customer Portal für den bestehenden Stripe-Kunden (Zahlungsmittel ändern, Abo kündigen) – Self-Service ohne eigene UI dafür.
• stripe-webhook.php: verifiziert die Stripe-Signature nach dem von Stripe dokumentierten HMAC-SHA256-Schema (inklusive Zeitstempel-Toleranz gegen Replay), verarbeitet checkout.session.completed, customer.subscription.updated/.deleted, invoice.paid/.payment_failed und hält tenant_billing aktuell. Bewusst kein app_require_csrf()/saas_require_login() (Stripe ruft unauthentifiziert von außen auf), stattdessen ausschließlich die Signaturprüfung als Echtheitsnachweis.
• mandant-einstellungen.php: zeigt bei Bedarf einen echten „Jetzt upgraden"-Button (führt zu Stripe Checkout) sowie, sobald ein Stripe-Kunde existiert, „Zahlungsmethode verwalten / Abo kündigen" (führt zum Customer Portal).

Noch nicht umgesetzt: automatischer Stufenwechsel bei wachsender Teilnehmerzahl (aktuell muss der Kunde selbst erneut auf „Upgraden" klicken, wenn billing_check_tenant() einen höheren Bedarf anzeigt).

Live getestet (Testmodus, kein echtes Geld)

• Checkout-Session-Erstellung direkt über die API sowie über den vollen Seiten-Flow (Login → Mandant-Einstellungen zeigt Upgrade-Button bei 13 Teilnehmern → Klick → echter 302-Redirect zu einer checkout.stripe.com-URL).
• Webhook-Verarbeitung durch selbst erzeugte, korrekt signierte Test-Ereignisse (da diese Dev-Umgebung keine öffentlich erreichbare URL für echte Stripe-Zustellung hat): checkout.session.completed setzt tenant_billing korrekt (Tarif, Status, Stripe-IDs) und wird im Mandanten-Audit-Log protokolliert; customer.subscription.deleted setzt den Mandanten korrekt auf free/canceled zurück.
• Signaturprüfung: eine Anfrage mit falscher Signatur wird korrekt mit 400 abgelehnt.
• Customer Portal: mit einem echten, per API angelegten Stripe-Test-Kunden liefert abo-portal.php einen echten 302-Redirect zu billing.stripe.com.
• Alle bestehenden Regressionstests (Golden Master, M8-Isolation, M8-Rollenmatrix, HTTP-Smoke mit 36 Seiten) weiterhin grün.
• Alle Testdaten (Stripe-Testobjekte kosten nichts und wurden im Stripe-Testmodus belassen; lokale DB-Testdaten wurden entfernt) aufgeräumt.

Für den Produktivbetrieb noch zu tun

• Echten Webhook-Endpunkt im Stripe-Dashboard (oder per API) auf die produktive Domain (https://app.kaffeeliste.de/stripe-webhook.php) eintragen und das dortige Signing-Secret als STRIPE_WEBHOOK_SECRET hinterlegen – das aktuelle Secret ist nur ein lokal erzeugter Platzhalter für die Simulation in dieser Dev-Umgebung.
• Von Test- auf Live-API-Keys wechseln, sobald ein echter Stripe-Account mit Bankverbindung eingerichtet ist.

Phase 3: Dolibarr-Anbindung (umgesetzt)

Ausgangslage: Der Kunde betreibt nur eine einzige Dolibarr-Instanz, und das ist die produktive für sein anderes Business – keine separate Sandbox verfügbar (Dolibarr 23.0.3, https://verwaltung.ctb-it.de). Der ursprüngliche Plan „erst gegen Sandbox testen" wurde daher ersetzt durch sicheres Testen innerhalb der einen produktiven Instanz.

Umgesetzte Dateien:

app/dolibarr.php
stripe-webhook.php (invoice.paid ruft dolibarr_sync_invoice_paid())

• app/dolibarr.php: minimaler REST-Client nach demselben Muster wie app/stripe.php (PHP-Streams, kein SDK). dolibarr_find_or_create_thirdparty() legt bei Erstkontakt einen Dolibarr-Kunden für den Mandanten an (Kaffeeliste - <Mandantenname>, E-Mail des Owners) und cached die Dolibarr-Kunden-ID in tenant_billing.dolibarr_thirdparty_id. dolibarr_create_and_validate_invoice() legt eine Rechnung mit einer Freitext-Position an (kein eigenes Dolibarr-Produkt pro Tarif nötig), fügt die Position hinzu und validiert die Rechnung sofort (vergibt die permanente, fortlaufende Nummer). tva_tx = 0 durchgängig, da Kleinunternehmer nach § 19 UStG.
• stripe-webhook.php: invoice.paid löst jetzt zusätzlich zum Audit-Log-Eintrag dolibarr_sync_invoice_paid() aus. Ein Fehlschlag dort (Netzwerk, Dolibarr down, ungültige Daten) wird nicht an Stripe als Fehler zurückgemeldet – Stripe hat das Geld bereits erfolgreich eingezogen, das ist unabhängig vom Dolibarr-Spiegel. Der Fehler landet stattdessen als billing.dolibarr_invoice_failed im Mandanten-Audit-Log (sichtbar sowohl unter „Protokoll" in Mandant-Einstellungen als auch im Back-Office) zur manuellen Nachbearbeitung.
• Rechnungen werden automatisch validiert (nicht als Entwurf für manuelle Prüfung liegen gelassen) – bewusste Entscheidung des Kunden, um den Prozess vollautomatisch zu halten.
• Das automatische Erfassen der Zahlung in Dolibarr (Rechnung als bezahlt markieren) ist bewusst nicht umgesetzt – erfordert Kenntnis der Bankkonto-/Zahlungsart-IDs der Dolibarr-Instanz. Rechnungen erscheinen offen und werden vom Kunden manuell abgeglichen.
• Stripe bleibt alleiniger Zahlungsweg; Dolibarr wird nur als Buchhaltungs- Spiegel befüllt, nicht selbst zum Auslösen von Zahlungen verwendet.

Live getestet

• Verbindung/Lesezugriff: GET /status, /thirdparties, /invoices gegen die echte Instanz erfolgreich geprüft (Version, Erreichbarkeit, Rechte des API-Keys).
• Schreibzugriff (mit expliziter Freigabe des Kunden): ein eindeutig benannter Test-Kunde („TEST – Kaffeeliste Integration") sowie eine Entwurfs-Rechnung mit Position wurden über die API angelegt und die Struktur verifiziert (status: 0 = Entwurf, ref: (PROVx) = noch keine permanente Nummer, korrekter Betrag, korrekte Verknüpfung). Nicht validiert – der Kunde hat die beiden Testdatensätze danach manuell in der Dolibarr-Oberfläche gelöscht (der beschränkte API-Key hat kein Lösch-Recht, DELETE liefert 403).
• Bewusst nicht live getestet: der eigentliche validate()-Aufruf, der die permanente Rechnungsnummer vergibt – das hätte einen unlöschbaren Testeintrag in der produktiven Buchhaltung hinterlassen. Auf Wunsch des Kunden ist die erste echte Stripe-Zahlung nach dem Go-Live der erste echte Test dieses Schritts. Das Risiko ist durch die fehlertolerante Webhook-Verarbeitung begrenzt (siehe oben).
• Alle bestehenden Regressionstests (Golden Master, M8-Isolation, M8-Rollenmatrix, HTTP-Smoke mit 36 Seiten) weiterhin grün.

Für den Produktivbetrieb noch zu tun

• Nach dem ersten echten invoice.paid-Ereignis in Produktion das Mandanten-Audit-Log prüfen (billing.dolibarr_invoice_created bzw. billing.dolibarr_invoice_failed), um den validate()-Aufruf einmal scharf zu bestätigen.
• Zahlungserfassung in Dolibarr (Rechnung als bezahlt markieren) als möglicher Ausbau, sobald Bankkonto-/Zahlungsart-IDs bekannt sind.