Mahnstufen abrufen

Gibt eine paginierte Liste aller Mahnstufen des Unternehmens zurück, sortiert nach interner ID aufsteigend. Die id einer Mahnstufe ist der Wert, den Mahnung erstellen als dunningTypeId erwartet – dieser Endpoint liefert sie auch für ein Unternehmen, das noch nie gemahnt hat: Der erste Aufruf legt dann die Standard-Mahnstufen an, eine leere Liste bekommst du nie.

Benötigte Lizenz

Dieser Endpoint erfordert das Add-on Mahnwesen.

Request

GET /api/oauth/v2/resource/invoices/dunnings/types

Header

Header	Wert
Authorization	Bearer {access_token}

Query-Parameter

Parameter	Typ	Pflicht	Beschreibung
offset	integer	Nein	Startposition (Standard: 0)
limit	integer	Nein	Anzahl Ergebnisse (Standard: 50, Max: 200)
status	string	Nein	Filtert nach Status. Erlaubte Werte: active, deleted, all. Kommagetrennte Mehrfachwerte möglich, Standard all. Siehe Konventionen

Hinweis: Die Liste ist nach interner ID aufsteigend sortiert (siehe Konventionen) – das ist nicht dasselbe wie die Eskalationsreihenfolge. Die Eskalationsreihenfolge einer Mahnstufe steht im Feld sort; willst du die Mahnstufen in dieser Reihenfolge anzeigen, sortiere clientseitig danach. Ohne status-Filter (Standard all) sind auch gelöschte Mahnstufen enthalten, erkennbar an deleted = true.

Erforderlicher Scope: dunnings

Zusätzlich braucht der Besitzer-Benutzer deines API-Zugangs die Berechtigung Mahnwesen: Anzeigen.

Response

Erfolg (200 OK)

{
  "data": [
    {
      "id": "0f6b1c4a-8d21-4b7e-9a33-5c81e2f40a17",
      "name": "1. Mahnung",
      "text": "Sehr geehrte Damen und Herren, wir erlauben uns, Sie an die folgende offene Rechnung zu erinnern.",
      "emailSubject": null,
      "emailBody": null,
      "color": "#f5a623",
      "sort": 1,
      "dunningFee": "5.00",
      "latePaymentInterestRate": "4.00",
      "paymentDeadline": 14,
      "tenancies": ["7c2f5b81-40de-4a19-b6c3-8ea1d0742f95"],
      "deleted": false
    },
    {
      "id": "7f8e9d0c-1b2a-3456-789a-bcdef0123456",
      "name": "2. Mahnung",
      "text": "Sehr geehrte Damen und Herren, trotz unserer ersten Mahnung ist die Rechnung weiterhin offen.",
      "emailSubject": "Zahlungserinnerung",
      "emailBody": "Sehr geehrte Damen und Herren, ...",
      "color": "#d0021b",
      "sort": 2,
      "dunningFee": "12.00",
      "latePaymentInterestRate": "4.00",
      "paymentDeadline": 7,
      "tenancies": ["7c2f5b81-40de-4a19-b6c3-8ea1d0742f95", "b3d4e5f6-7890-4a1b-8c2d-3e4f5a6b7c8d"],
      "deleted": false
    }
  ],
  "meta": {
    "total": 3,
    "offset": 0,
    "limit": 50
  }
}

Response-Felder

Feld	Typ	Beschreibung
data	Array	Liste der Mahnstufen
data[].id	string (UUID) | null	Eindeutige ID der Mahnstufe – dieser Wert gehört als dunningTypeId in den Create-Request
data[].name	string | null	Name der Mahnstufe (z.B. 1. Mahnung)
data[].text	string | null	Mahntext, wie er auf dem Schreiben an den Kunden steht
data[].emailSubject	string | null	Betreff der Erinnerungs-E-Mail, null = Standardvorlage
data[].emailBody	string | null	Text der Erinnerungs-E-Mail, null = Standardvorlage
data[].color	string | null	Farbe der Mahnstufe als Hex-Code
data[].sort	integer	Position in der Eskalationsreihenfolge – keine Ergebnis-Sortierung dieses Endpoints, siehe oben
data[].dunningFee	string | null	Mahngebühr dieser Mahnstufe
data[].latePaymentInterestRate	string | null	Verzugszinssatz in Prozent
data[].paymentDeadline	integer | null	Zahlungsziel in Tagen
data[].tenancies	Array<string (UUID)>	IDs der Mandanten, für die diese Mahnstufe verwendbar ist – leer ohne das Add-on Mandanten
data[].deleted	boolean	Ob die Mahnstufe gelöscht ist
meta.total	integer	Anzahl der Mahnstufen insgesamt
meta.offset	integer	Aktuelle Startposition
meta.limit	integer	Angeforderte Seitengröße

Hinweis zu Geldbeträgen: dunningFee und latePaymentInterestRate kommen als JSON-String, nicht als Zahl ("dunningFee": "5.00"). Verarbeite die Werte mit einem Dezimaltyp. Parst du sie in eine Fließkommazahl, baust du Rundungsfehler ein. Gleiches Verhalten wie bei Mahnungen, Rechnungen und Bareinnahmen.

Hinweis: paymentDeadline ist eine Anzahl von Tagen, kein Datum.

Hinweis zu meta.total: Anders als bei Mahnungen abrufen ist total hier eine exakte Zahl. Die Berechtigungsprüfung greift vor dem Zählen, nicht danach.

Hinweis zu tenancies: Das Feld sagt, für welche Mandanten eine Mahnstufe verwendbar ist – nicht, welchen Mandanten sie ausdrücklich zugeordnet wurde. Eine Mahnstufe ohne Mandanten-Einschränkung ist überall verwendbar und listet deshalb die IDs aller Mandanten deines Unternehmens, nicht ein leeres Array. Arbeitet dein Unternehmen ohne das Add-on Mandanten, steht bei jeder Mahnstufe "tenancies": []. Der Nutzen liegt beim Anlegen einer Mahnung: Mahnung erstellen lehnt mit 400 validation_error ab, wenn die Mahnstufe für den Mandanten der Rechnung nicht freigegeben ist. Mit tenancies wählst du vorher die passende Mahnstufe aus, statt es auszuprobieren.

Beispiele

bash

curl -X GET "https://my.offisy.at/api/oauth/v2/resource/invoices/dunnings/types?offset=0&limit=50&status=beispiel" \
  -H "Authorization: Bearer {access_token}"

Server

Client-ID

Client-Secret

Parameter

offset integer

limit integer

status string

Zuerst Token anfordern

Mögliche Fehler

Status	Code	Beschreibung
400	validation_error	Ungültiger Wert für status
401	invalid_client	Access Token ungültig oder abgelaufen
403	insufficient_scope	Scope dunnings nicht vorhanden
403	access_denied	Keine Berechtigung zum Lesen von Mahnungen
429	rate_limit_exceeded	Zu viele Anfragen – siehe Fehlerbehandlung

Hinweis: Fehlt der Authorization-Header oder ist der Token ungültig, antwortet die API mit 401 und dem JSON-Envelope invalid_client. Das gilt für die OAuth-API allgemein, nicht nur für diesen Endpoint.