Mahnwesen

Der Bereich Mahnwesen ermöglicht den Zugriff auf die Mahnungen deines Unternehmens.

Erforderlicher Scope: dunnings

Benötigte Lizenz

Dieser Bereich ist nur verfügbar, wenn das Add-on Mahnwesen in deiner Lizenz enthalten ist.

Die Einrichtung eines API-Zugangs ist im Help Center beschrieben.

Endpoints

Method	Endpoint	Beschreibung
GET	/api/oauth/v2/resource/invoices/dunnings	Paginierte Liste aller Mahnungen
GET	/api/oauth/v2/resource/invoices/dunnings/{uuid}	Details einer einzelnen Mahnung
POST	/api/oauth/v2/resource/invoices/dunnings	Neue Mahnung zu einer Rechnung erstellen
GET	/api/oauth/v2/resource/invoices/dunnings/types	Paginierte Liste aller Mahnstufen
GET	/api/oauth/v2/resource/invoices/dunnings/types/{uuid}	Details einer einzelnen Mahnstufe

Hinweis: Der Versand einer Mahnung läuft nicht über die API. Eine per API erstellte Mahnung wird weder per E-Mail verschickt noch gedruckt – das machst du in Offisy.

Mahnstufen und Eskalation

Eine Mahnung trägt keine Mahnstufen-Nummer. Das Feld dunningType enthält die UUID der Mahnstufe, nicht ihre Ordnungszahl. Name und Eskalationsposition (sort) der Stufe bekommst du über Mahnstufen abrufen oder Mahnstufe anzeigen.

Die Eskalation bildet sich über die Kette der Mahnungen ab: Sobald eine neue Mahnung zur selben Rechnung entsteht, wechselt die vorherige auf status = replaced. Die aktuelle Mahnung einer Rechnung ist damit die mit status = active.

Status und Storno

Jede Mahnung führt zwei Statuswerte:

• status ist der technische Status aus den Konventionen: active, replaced oder canceled. Ohne status-Filter (Standard all) liefern beide Endpoints alle drei Zustände mit.
• dunningStatus ist der fachliche Filter mit den Werten active, replaced, canceled und done.

Storno und Löschung sind in Offisy derselbe Vorgang: Wer eine Mahnung storniert, setzt dunningStatus = canceled und markiert sie gleichzeitig als soft-gelöscht (deleted = true). Genau das bildet status = canceled ab – der Wert deckt sowohl explizit stornierte als auch anderweitig gelöschte Mahnungen ab.

Zahlungsstatus

paidStatus kennt nur open und paid – es gibt keinen Wert für „teilbezahlt". Eine teilbezahlte Mahnung bleibt open und hat ein reduziertes outstandingTotal.

paid wird erst gesetzt, wenn outstandingTotal auf 0 oder darunter fällt. Das passiert immer gemeinsam mit dunningStatus = done – beide Werte treten stets zusammen auf.