Ressource: sepa (Plugin) #
Interaktiv: Alle Endpunkte dieser Ressource zum Ausprobieren in der interaktiven API-Referenz.
SEPA-Lastschriften und -Überweisungen als lizenzpflichtiges Plugin
(EulandaXsepa). Anders als die Kern-Ressourcen sind diese Routen
dynamisch: Sie existieren nur, wenn das Plugin in der Mandanten-Datenbank
installiert und aktiviert ist und der signierte Lizenzblock das Produkt
sepa enthält. Fehlt eines davon, mountet der Server die Routen gar nicht
erst - Aufrufe antworten dann mit 404, nicht mit 403. Die interaktive
Referenz zeigt deshalb den Stand einer Installation mit SEPA-Plugin;
gerechnet und gebucht wird wie immer in der Datenbank (SepaMandat,
SepaNachricht, konSEPA), das Plugin bringt keine zweite Fachlogik mit.
Endpunkte #
| Methode | Pfad | Scope | Zweck |
|---|---|---|---|
| GET | /api/v1/sepa/mandates | sepa:read | Mandate listen (addressId-Filter, activeOnly) |
| GET | /api/v1/sepa/mandates/{id}/document | sepa:read | Den kanonischen Mandats-Beleg (Scan) aus dem DMS laden |
| PUT | /api/v1/sepa/mandates/{id}/document | sepa:write | Beleg hochladen (base64-Hülle, PDF/JPG/PNG) |
| GET | /api/v1/sepa/mandates/{id}/files | sepa:read | DMS-Ordner des Mandats listen |
| GET | /api/v1/sepa/mandates/{id}/files/download?path=... | sepa:read | Datei aus dem Mandats-Ordner laden |
| POST | /api/v1/sepa/mandates/{id}/files?name=... | sepa:write | Datei in den Mandats-Ordner hochladen (Body = Roh-Inhalt) |
| DELETE | /api/v1/sepa/mandates/{id}/files?path=... | sepa:write | Datei aus dem Mandats-Ordner löschen |
| GET | /api/v1/sepa/direct-debits/candidates | sepa:read | Einzugsfähige offene Rechnungen (Lastschrift-Kandidaten) |
| GET | /api/v1/sepa/credit-transfers/candidates | sepa:read | Auszuzahlende Gutschriften (Überweisungs-Kandidaten) |
| POST | /api/v1/sepa/runs | sepa:submit | Lauf starten (Lastschrift oder Überweisung, Vorschau möglich) |
| GET | /api/v1/sepa/runs | sepa:read | Archiv der Läufe listen |
| GET | /api/v1/sepa/runs/{id} | sepa:read | Lauf mit Posten ansehen |
| GET | /api/v1/sepa/runs/{id}/file | sepa:read | Bankfähige XML-Datei erneut bereitstellen |
| POST | /api/v1/sepa/runs/{id}/actions/cancel | sepa:cancel | Lauf stornieren (Rechnungen werden wieder geöffnet) |
| GET | /api/v1/sepa/settings | sepa:read | Gläubiger-Identifikation, Bankverbindung, Ablagepfad |
Mandats-Belege (zwei Schichten) #
Der kanonische Beleg ist die Datei SEPAMandat\<Mandatsreferenz>.pdf
(bzw. .jpg) im DMS-Ordner der Adresse - eine Datei je Referenz, benannt
wird serverseitig, nie aus dem Request. GET .../document liefert sie als
base64-Hülle (fileName, mimeType, size, contentBase64); gibt es die
Datei nicht, fällt die Suche auf die neueste Datei im Klassik-Unterordner
je Mandat und auf Dubletten-Varianten " (n)" zurück. PUT .../document
prüft den Inhalt über Magic Bytes (PDF/JPG/PNG, max. 20 MB) und
überschreibt nie - eine neue Fassung bekommt die nächste freie
Dubletten-Nummer. Ein unterschriebenes Mandat ist ein Beweisdokument.
Die files-Routen darunter sind die generische DMS-Datei-Familie des
Kerns (gleiche Semantik wie bei /addresses/{id}/files), gemountet auf dem
Mandats-Ordner SEPAMandat\<Referenz>\ - für Korrespondenz und alles, was
über den einen Beleg hinausgeht.
Läufe #
POST /api/v1/sepa/runs nimmt type (directDebit/creditTransfer),
die Belegauswahl (invoiceIds), das Fälligkeits- bzw. Ausführungsdatum und
optional preview (nichts wird gebucht) entgegen. Die Antwort enthält die
bankfähige XML-Datei als base64-Hülle; optional legt der Server sie
zusätzlich im konfigurierten Serverordner ab. Wertverändernde Aktionen
tragen eigene Scopes (sepa:submit, sepa:cancel) - Muster wie
documents:book/cancel.
Capabilities #
Für Benutzer-Oberflächen gelten zusätzlich die Plugin-Capabilities
sepa.view, sepa.mandates.edit, sepa.run.submit, sepa.run.cancel
und sepa.settings.view - der Scope ist die Decke des API-Clients, die
Capability das Benutzer-Recht darunter.