Mahnungen abrufen

Gibt eine paginierte Liste aller Mahnungen des Unternehmens zurück, sortiert nach interner ID aufsteigend.

Benötigte Lizenz

Dieser Endpoint erfordert das Add-on Mahnwesen.

Request

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

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`, `replaced`, `canceled`, `all`. Kommagetrennte Mehrfachwerte möglich, Standard `all`. Siehe Konventionen
`dunningStatus`	string	Nein	Filtert auf den fachlichen Mahnstatus. Erlaubte Werte: `active`, `replaced`, `canceled`, `done`
`paidStatus`	string	Nein	Filtert auf einen Zahlungsstatus. Erlaubte Werte: `open`, `paid`

Erforderlicher Scope: dunnings

Hinweis: Ein leerer Wert (?status= bzw. ?dunningStatus=) wirkt wie kein Filter – die API antwortet dann mit der ungefilterten Liste. Ein ungültiger Wert wird mit 400 validation_error abgelehnt. status und dunningStatus sind zwei unterschiedliche Filter und werden UND-verknüpft: status ist der technische Soft-Delete-Status aus den Konventionen, dunningStatus der fachliche fortlaufende Mahnstatus.

Response

Erfolg (200 OK)

json

{
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-234567890123",
      "invoice": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "customer": "f0e1d2c3-b4a5-6789-fedc-ba9876543210",
      "status": "active",
      "text": "Sehr geehrte Damen und Herren, wir erlauben uns, Sie an die folgende offene Rechnung zu erinnern.",
      "printedStatus": "unprinted",
      "paidStatus": "open",
      "dunningType": "7f8e9d0c-1b2a-3456-789a-bcdef0123456",
      "fee": "12.00",
      "latePaymentInterestRate": "4.00",
      "paymentDeadline": 14,
      "totalAmount": "122.35",
      "outstandingTotal": "122.35",
      "totalFee": "12.00",
      "outstandingFee": "12.00",
      "totalInterest": "0.35",
      "outstandingInterest": "0.35",
      "invoiceOutstandingBalance": "110.00",
      "interestCalculateStartDate": "2026-06-16",
      "interestCalculateEndDate": "2026-07-15",
      "createdAt": "2026-07-15T09:00:00+02:00",
      "updatedAt": "2026-07-15T09:00:00+02:00",
      "createdBy": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "updatedBy": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "tenancy": "9a8b7c6d-5e4f-3210-9876-543210fedcba"
    },
    {
      "id": "d4e5f6a7-b8c9-0123-defa-345678901234",
      "invoice": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "customer": null,
      "status": "replaced",
      "text": "Sehr geehrte Damen und Herren, trotz unserer ersten Mahnung ist die Rechnung weiterhin offen.",
      "printedStatus": "printed",
      "paidStatus": "open",
      "dunningType": "0f6b1c4a-8d21-4b7e-9a33-5c81e2f40a17",
      "fee": "5.00",
      "latePaymentInterestRate": "4.00",
      "paymentDeadline": 7,
      "totalAmount": "55.00",
      "outstandingTotal": "55.00",
      "totalFee": "5.00",
      "outstandingFee": "5.00",
      "totalInterest": "0.00",
      "outstandingInterest": "0.00",
      "invoiceOutstandingBalance": "50.00",
      "interestCalculateStartDate": null,
      "interestCalculateEndDate": null,
      "createdAt": "2026-06-30T08:15:00+02:00",
      "updatedAt": "2026-07-15T09:00:00+02:00",
      "createdBy": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "updatedBy": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "tenancy": null
    }
  ],
  "meta": {
    "total": 37,
    "offset": 0,
    "limit": 50
  }
}

Response-Felder

Feld	Typ	Beschreibung
`data`	Array	Liste der Mahnungen
`data[].id`	string (UUID) \| null	Eindeutige ID der Mahnung
`data[].invoice`	string (UUID) \| null	ID der gemahnten Rechnung, nachladbar über Rechnung anzeigen
`data[].customer`	string (UUID) \| null	ID des Kunden, nachladbar über Kunde anzeigen
`data[].status`	string	Technischer Status: `active`, `replaced`, `canceled`. Siehe Konventionen
`data[].text`	string \| null	Mahntext, wie er auf dem Schreiben an den Kunden steht
`data[].printedStatus`	string	Druckstatus: `printed` (gedruckt), `unprinted` (nicht gedruckt)
`data[].paidStatus`	string	Zahlungsstatus: `open` (offen), `paid` (bezahlt)
`data[].dunningType`	string (UUID) \| null	ID der Mahnstufe, nachladbar über Mahnstufe anzeigen
`data[].fee`	string	Mahngebühr dieser Mahnstufe
`data[].latePaymentInterestRate`	string	Verzugszinssatz in Prozent
`data[].paymentDeadline`	integer	Zahlungsziel in Tagen
`data[].totalAmount`	string	Gesamtbetrag der Mahnung
`data[].outstandingTotal`	string	Offener Gesamtbetrag
`data[].totalFee`	string	Mahngebühren gesamt
`data[].outstandingFee`	string	Offene Mahngebühren
`data[].totalInterest`	string	Verzugszinsen gesamt
`data[].outstandingInterest`	string	Offene Verzugszinsen
`data[].invoiceOutstandingBalance`	string	Offener Betrag der gemahnten Rechnung
`data[].interestCalculateStartDate`	string \| null	Beginn der Zinsberechnung (YYYY-MM-DD)
`data[].interestCalculateEndDate`	string \| null	Ende der Zinsberechnung (YYYY-MM-DD)
`data[].createdAt`	string (ISO 8601)	Erstellungszeitpunkt
`data[].updatedAt`	string (ISO 8601)	Letzter Änderungszeitpunkt
`data[].createdBy`	string (UUID) \| null	ID des Benutzers, der die Mahnung erstellt hat, nachladbar über Benutzer anzeigen
`data[].updatedBy`	string (UUID) \| null	ID des Benutzers, der die letzte Änderung vorgenommen hat
`data[].deleted`	boolean	Ob die Mahnung gelöscht ist
`data[].deletedAt`	string (ISO 8601) \| null	Löschzeitpunkt
`data[].deletedBy`	string (UUID) \| null	ID des Benutzers, der die Mahnung gelöscht hat
`data[].tenancy`	string (UUID) \| null	ID des zugeordneten Mandanten
`meta.total`	integer	Obergrenze der Gesamtanzahl – siehe Hinweis unten
`meta.offset`	integer	Aktuelle Startposition
`meta.limit`	integer	Anzahl der zurückgegebenen Einträge

Hinweis zu Geldbeträgen: Alle Geldbeträge und der Zinssatz kommen als JSON-String, nicht als Zahl ("fee": "12.00"). Das betrifft fee, latePaymentInterestRate, totalAmount, outstandingTotal, totalFee, outstandingFee, totalInterest, outstandingInterest und invoiceOutstandingBalance. Verarbeite die Werte mit einem Dezimaltyp. Parst du sie in eine Fließkommazahl, baust du Rundungsfehler ein. Gleiches Verhalten wie bei Rechnungen und Bareinnahmen.

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

Hinweis zu meta.total: total wird in der Datenbank gezählt, die Berechtigungsprüfung greift danach. Der Wert ist deshalb eine Obergrenze, keine exakte Zahl – die Seiten können weniger Mahnungen enthalten als total erwarten lässt. Eine Abbruchbedingung „paginieren, bis alle total Datensätze empfangen sind" terminiert nicht. Paginiere stattdessen, bis eine Seite leer ist.
Relevant ist das vor allem bei eingeschränkten Rechten: Ist der Besitzer-Benutzer deines API-Zugangs auf Standorte eingeschränkt, sind Mahnungen ohne Standortzuordnung für ihn unsichtbar.

Hinweis zu Mandanten: Arbeitet dein Unternehmen mit dem Add-on Mandanten, liefert der Endpoint nur Mahnungen aus Mandanten, auf die der Besitzer-Benutzer deines API-Zugangs Zugriff hat und in denen er das Recht Mahnwesen: Anzeigen hat. Mahnungen anderer Mandanten und Mahnungen ohne Mandant fehlen in der Liste, ohne dass das ein Fehler auslöst. meta.total zählt nur die Mahnungen dieser Mandanten. Details: Konventionen.

Hinweis zu Storno: Ein Storno setzt dunningStatus = canceled und die Soft-Delete-Markierung gleichzeitig. Ohne status-Filter (Standard all) bekommst du stornierte und gelöschte Mahnungen mitgeliefert, erkennbar an status = canceled bzw. deleted = true. Willst du sie ausschließen, filtere mit status=active,replaced.

Beispiele

bash

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

Server

Client-ID

Client-Secret

Parameter

offset integer

limit integer

status string

dunningStatus string

paidStatus string

Zuerst Token anfordern

Mögliche Fehler

Status	Code	Beschreibung
400	`validation_error`	Ungültiger Wert für `status`, `dunningStatus` oder `paidStatus`
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.

Mahnungen abrufen ​

Request ​

Header ​

Query-Parameter ​

Response ​

Erfolg (200 OK) ​

Response-Felder ​

Mögliche Fehler ​