vereo-docuseal

DocuSeal-Anbindung für die Ausgaben-Freigabe in Vereo. Eigenständiges Plugin – nicht Teil des Vereo-Kerns. Vereo bleibt anbieter-neutral und spricht nur gegen die generische Schnittstelle App\Contracts\ExpenseApprovalProvider (ab Vereo v1.322.0).

Ablauf

1. In Vereo bei einer Ausgabe „Zur Abzeichnung" klicken.
2. Das Plugin legt in DocuSeal eine Submission aus eurer Vorlage „Kostenerstattung" an: Seite 1 = das Abzeichnungsblatt (Felder aus der Ausgabe vorbefüllt, 3 Signatur-Rollen), Seite 2+ = der angehängte Original-Beleg.
3. DocuSeal verschickt die Signatur-Einladungen nacheinander (order: preserved): Sachlich richtig → Rechnerisch richtig → Angewiesen. Niemand muss sich in Vereo einloggen.
4. Nach der letzten Unterschrift meldet der Webhook zurück → Vereo setzt die Ausgabe auf freigegeben und bezahlt. Es wird nichts angelegt, nur abgeschlossen (idempotent).

Installation (auf der Vereo-Instanz)

Da Vereo als fertiges Docker-Image läuft, das Paket über einen schlanken eigenen Image-Layer einbinden:

FROM ghcr.io/<euer>/vereo:latest
RUN composer config repositories.vereo-docuseal vcs https://forgejo.thiel.tools/thiel/vereo-docuseal.git \
 && composer require natec/vereo-docuseal:^0.1

Alternativ als lokales Pfad-Repository (Mount des Ordners) in composer.json.

Konfiguration

Provider in Vereo aktiv schalten (Env der Vereo-Instanz):

VEREO_EXPENSE_APPROVAL_PROVIDER="Natec\\VereoDocuseal\\DocusealApprovalProvider"

Außerdem in der Vereo-Oberfläche unter Konfiguration → Einstellungen → Finanzen die „Ausgaben-Freigabe" aktivieren.

DocuSeal-Einstellungen (Env):

DOCUSEAL_BASE_URL=https://docuseal.euer-verein.de
DOCUSEAL_API_TOKEN=xxxxxxxx            # DocuSeal: Einstellungen → API
DOCUSEAL_TEMPLATE_ID=123              # Vorlage „Kostenerstattung"

# Drei feste Unterzeichner (Rollen müssen exakt den Rollennamen in der Vorlage entsprechen):
DOCUSEAL_SIGNER_1=vorstand1@verein.de  # Rolle „Sachlich richtig"
DOCUSEAL_SIGNER_2=vorstand2@verein.de  # Rolle „Rechnerisch richtig"
DOCUSEAL_SIGNER_3=schatzmeister@verein.de # Rolle „Angewiesen"

# Webhook-Absicherung (gemeinsames Geheimnis als Header):
DOCUSEAL_WEBHOOK_SECRET=ein-langes-zufallsgeheimnis

Feld-Zuordnung (DocuSeal-Feldname → Wert aus der Ausgabe) steht in config/docuseal-approval.php und ist frei anpassbar. Standard:

DocuSeal-Feld	Wert aus der Ausgabe
BELEGDATUM	Datum (TT.MM.JJJJ)
BETRAG	Betrag „1.285,20 Euro"
VERWENDUNGSZWECK	Beschreibung
KOSTENSTELLE	Bereich
ZAHLUNGSVERMERK	Lieferant/Empfänger

Verfügbare Tokens: date, amount, description, area, category, payee. Neue Felder einfach in der fields-Zuordnung ergänzen.

DocuSeal-Vorlage einrichten

• Vorlage „Kostenerstattung" (Seite 1) mit den Feldern oben und drei Signatur-Rollen „Sachlich richtig", „Rechnerisch richtig", „Angewiesen".
• Die Datenfelder (BELEGDATUM, BETRAG, …) der Rolle aus prefill_role (Standard „Sachlich richtig") zuweisen, damit sie per API vorbefüllt (readonly) werden können.

Webhook in DocuSeal

DocuSeal Console → Webhooks → New Webhook:

• URL: https://<eure-vereo-domain>/webhooks/docuseal
• Event: submission.completed
• Eigenen Header setzen: X-Webhook-Secret: <DOCUSEAL_WEBHOOK_SECRET>

Beleg anhängen – Modus

DOCUSEAL_SUBMISSION_MODE (Standard template): Submission aus template_id, Beleg via documents[] angehängt. Falls eure DocuSeal-Version den Beleg in diesem Modus nicht übernimmt, auf pdf umstellen (template_ids[] + documents[]). Beim ersten Live-Lauf kurz prüfen, dass der Beleg als Seite 2+ erscheint.

Hinweis

Dies ist v0.1 und gegen euer konkretes DocuSeal-Setup beim ersten echten Vorgang zu verifizieren (Feldnamen, Rollennamen, Beleg-Anhang). Logik (Reihenfolge, Vorbefüllung, Webhook-Rücklauf) ist fertig.