Mahnung erstellen

Erstellt eine neue Mahnung zu einer offenen Rechnung.

Benötigte Lizenz

Dieser Endpoint erfordert das Add-on Mahnwesen.

Request

POST /api/oauth/v2/resource/invoices/dunnings

Header

Header	Wert
Authorization	Bearer {access_token}
Content-Type	application/json

Body-Parameter

Feld	Typ	Pflicht	Beschreibung
invoiceId	string (UUID)	Ja	Rechnung, zu der gemahnt wird
dunningTypeId	string (UUID)	Ja	Mahnstufe, aus der die Werte übernommen werden
interestCalculateStartDate	string	Nein	Beginn der Zinsberechnung (YYYY-MM-DD)
interestCalculateEndDate	string	Nein	Ende der Zinsberechnung (YYYY-MM-DD)

Hinweis: Mahngebühr, Verzugszinssatz, Zahlungsziel und Mahntext nimmt der Endpoint nicht an – diese Werte stammen ausschließlich aus der gewählten Mahnstufe. Das ist Absicht: So bestimmt kein Fremdsystem, welche Beträge einem Kunden in Rechnung gestellt werden oder wie der Wortlaut eines Schreibens an ihn lautet. Willst du andere Werte, ändere die Mahnstufe in Offisy oder wähle eine andere. totalFee weist den kumulierten Betrag aus: Die Mahngebühren aller Vormahnungen derselben Rechnung sind mitsummiert.

Hinweis: interestCalculateStartDate und interestCalculateEndDate gelten nur gemeinsam – setzt du nur eines von beiden, antwortet der Endpoint mit 400 validation_error. Schick beide Daten im Format YYYY-MM-DD mit zweistelligem Monat und Tag, als echtes Kalenderdatum; der Zinsbeginn darf nicht nach dem Zinsende liegen. Lässt du beide weg, schlägt Offisy denselben Zeitraum vor wie die Oberfläche: vom Tag nach der Fälligkeit der Rechnung über 14 Tage – das ist eine Vorbelegung, die sich ändern kann.

Hinweis: Die UUID der Mahnstufe liefert Mahnstufen abrufen – das Feld id einer Mahnstufe ist der Wert, den du hier als dunningTypeId sendest. Der Endpoint funktioniert auch für ein Unternehmen, das noch nie gemahnt hat.

Erforderlicher Scope: dunnings

Zusätzlich braucht der Besitzer-Benutzer deines API-Zugangs die Berechtigung Mahnwesen: Erstellen sowie Zugriff auf die Rechnung und die Mahnstufe.

Beispiel (cURL)

curl -X POST "https://app.offisy.at/api/oauth/v2/resource/invoices/dunnings" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "dunningTypeId": "7f8e9d0c-1b2a-3456-789a-bcdef0123456",
    "interestCalculateStartDate": "2026-06-16",
    "interestCalculateEndDate": "2026-07-15"
  }'

Response

Erfolg (201 Created)

{
  "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"
  }
}

Response-Felder

Der Endpoint liefert dasselbe Objekt wie die beiden lesenden Endpoints. Siehe Mahnung anzeigen für die vollständige Feldbeschreibung.

Beispiele

bash

curl -X POST "https://my.offisy.at/api/oauth/v2/resource/invoices/dunnings" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
    "dunningTypeId": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
    "interestCalculateStartDate": "2026-04-15T10:00:00",
    "interestCalculateEndDate": "2026-04-15T10:00:00"
  }'

Server

Client-ID

Client-Secret

Parameter

invoiceId *string

dunningTypeId *string

interestCalculateStartDate string

interestCalculateEndDate string

Zuerst Token anfordern

Mögliche Fehler

Status	Code	Beschreibung
400	validation_error	invoiceId oder dunningTypeId fehlt, ist kein gültiges UUID-Format, nur eines der beiden Zinsdaten ist gesetzt, ein Zinsdatum ist kein echtes Kalenderdatum im Format YYYY-MM-DD, oder der Zinsbeginn liegt nach dem Zinsende
400	validation_error	Mahnstufe gehört zu einem anderen Unternehmen als die Rechnung – eine Mahnung darf nur Mahnstufen des eigenen Unternehmens verwenden (error_description: dunningTypeId must belong to the same company as the invoice.)
400	validation_error	Mahnstufe ist für den Mandanten der Rechnung nicht freigegeben – welche Mandanten eine Mahnstufe zulässt, zeigt das Feld tenancies unter Mahnstufen abrufen (error_description: dunningTypeId must be available for the tenancy of the invoice.)
400	invalid_request	Der API-Zugang ist keinem Benutzer zugeordnet – ordne ihm in den Offisy-Einstellungen einen Benutzer zu
401	invalid_client	Access Token ungültig oder abgelaufen
403	insufficient_scope	Scope dunnings nicht vorhanden
403	access_denied	Der Besitzer-Benutzer deines API-Zugangs hat keine Berechtigung für die Rechnung oder die Mahnstufe (Standard-error_description: Insufficient permission for this resource.)
404	not_found	Rechnung oder Mahnstufe nicht gefunden, oder die Rechnung gehört mit dem Add-on Mandanten einem Mandanten, auf den der Besitzer-Benutzer deines API-Zugangs keinen Zugriff hat oder in dem ihm das Recht Mahnwesen: Erstellen fehlt. Bei der Rechnung ist die Antwort dieselbe wie bei einer unbekannten Rechnung (error_description: Invoice not found.)
422	unprocessable_entity	Rechnung kann nicht gemahnt werden: Entwurf, storniert, Storno-Rechnung oder bereits stornierte Rechnung, Bareinnahme, Trainingsrechnung oder kein offener Betrag
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.