API und Webhooks

Mit der API lesen eigene Programme, n8n, Make oder Ihr Buchhaltungssystem die Daten Ihrer Verwaltung aus. Webhooks melden sich von selbst, sobald sich etwas ändert – etwa wenn ein Kontakt angelegt oder eine Abrechnung generiert wird. Beides gehört zum Zusatzmodul API; ist es für Ihre Verwaltung nicht freigeschaltet, sprechen Sie uns an.

Was die API kann

Die API ist lesend. Alle Aufrufe sehen nur die Daten Ihrer eigenen Verwaltung.

Bereich	Was Sie abrufen
Objekte	Aktive Objekte, ein einzelnes Objekt
Einheiten	Einheiten mit aktuellem Eigentum und Saldo, offene Posten je Sollstellung mit Fälligkeit
Eigentums- und Mietverhältnisse	Je Einheit, je Kontakt oder für ein ganzes Objekt
Kontakte	Kontakte mit ihren Eigentums- und Mietverhältnissen
Mahnwesen	Einheiten mit Zahlungsrückstand, Mahnläufe, Mahnschreiben mit Download-Link

Jeden Aufruf mit Parametern und Antwort beschreibt die API-Referenz:

https://portal.abrechnung360.de/api/accounting/api-docs/

Sie ist öffentlich und lässt sich direkt im Browser ausprobieren. Programme wie Postman oder n8n lesen die Beschreibung unter …/api-docs/openapi ein.

Zugang einrichten

1. API-Schlüssel anlegen

   Unter Konto & Einstellungen › API-Schnittstelle auf API-Schlüssel anlegen, einen Namen vergeben (etwa „n8n”) und den Schlüssel kopieren. Er wird nur dieses eine Mal angezeigt.

2. Zugriffstoken holen

   Der Schlüssel selbst öffnet keine Daten. Tauschen Sie ihn gegen ein Zugriffstoken, das bis zu einer Stunde gilt:

   curl -X POST https://portal.abrechnung360.de/api/directory/access-tokens \
     -H "Authorization: Bearer <API-Schlüssel>"

   Die Antwort enthält access_token und in expires_in die Sekunden bis zum Ablauf. Holen Sie rechtzeitig ein neues.

3. Daten abrufen

   Das Zugriffstoken geht bei jedem Aufruf mit:

   curl https://portal.abrechnung360.de/api/accounting/objects \
     -H "Authorization: Bearer <Zugriffstoken>"

Schlüssel wie ein Kennwort behandeln

Wer den API-Schlüssel kennt, liest die Daten Ihrer Verwaltung. Ist er an anderer Stelle bekannt geworden, löschen Sie ihn unter API-Schnittstelle – Programme, die ihn verwenden, verlieren den Zugriff spätestens nach einer Stunde.

Webhooks

Ein Webhook ist eine https-Adresse Ihres Systems, die Abrechnung360 aufruft, sobald eines der gewählten Ereignisse eintritt. Sie fragen also nicht ständig nach, sondern werden benachrichtigt.

Webhook anlegen

Unter Konto & Einstellungen › Webhooks auf Webhook anlegen: Name, die Adresse (sie muss mit https:// beginnen) und die Ereignisse wählen.

Ereignis	Schlüssel	Inhalt von data
Objekt angelegt, geändert, gelöscht	property.created, property.updated, property.deleted	das Objekt
WEG-Abrechnung generiert	weg-statement.generated	eine Einzelabrechnung je Eigentumsverhältnis
Nebenkostenabrechnung generiert	mv-statement.generated	eine Abrechnung je Mietverhältnis
Kontakt angelegt, geändert, gelöscht	contact.created, contact.updated, contact.deleted	der Kontakt mit seinen Verhältnissen

Bei einem gelöschten Datensatz enthält data seinen letzten Stand. Die Felder je Ereignis beschreibt die API-Referenz im Abschnitt Webhooks.

So sieht ein Ereignis aus

Abrechnung360 sendet einen POST mit JSON:

{
  "id": "6d8f4c56-44ab-4837-801a-a7698eaf8dfe",
  "event": "contact.created",
  "occurredAt": "2026-10-12T05:59:44.431Z",
  "data": { "id": "cbcae340-…", "firstName": "Max", "lastName": "Mustermann", "organisationId": 123456789 }
}

Dazu kommen diese Header:

Header	Bedeutung
webhook-id	Die ID des Ereignisses, gleich id im Inhalt
webhook-timestamp	Sekunden seit 1970 (UTC), zu denen dieser Versuch gesendet wurde
webhook-signature	Die Signatur, siehe unten
X-Organisation-Id, X-Webhook-Id	Ihre Verwaltung und der aufgerufene Webhook

Antworten und Wiederholungen

Antworten Sie binnen zehn Sekunden mit einem Status von 200 bis 299. Jede andere Antwort, auch keine, gilt als fehlgeschlagen; Abrechnung360 versucht es dann erneut – nach 5 Sekunden, 5 Minuten, 30 Minuten, 2, 5, 10 und 10 Stunden. Ihr System darf also gut einen Tag ausfallen, ohne ein Ereignis zu verlieren.

Jede Wiederholung trägt dieselbe webhook-id. Verarbeiten Sie jede ID nur einmal – kommt eine bekannte ID erneut, antworten Sie mit 200 und tun nichts. Die Reihenfolge ist nicht garantiert; welche von zwei Änderungen die neuere ist, sagt occurredAt.

Signatur prüfen

Jede Zustellung ist nach dem offenen Standard Standard Webhooks signiert. Mit der Signatur stellen Sie sicher, dass ein Aufruf wirklich von Abrechnung360 kommt und unterwegs nicht verändert wurde. Das Signatur-Secret (beginnt mit whsec_) finden Sie, wenn Sie den Webhook in der Liste aufklappen.

Am einfachsten prüfen Sie mit der Bibliothek des Standards, die es für viele Sprachen gibt:

from standardwebhooks.webhooks import Webhook

payload = Webhook("whsec_…").verify(request_body, request_headers)

import { Webhook } from "standardwebhooks";

const payload = new Webhook("whsec_…").verify(requestBody, requestHeaders);

verify wirft einen Fehler, wenn die Signatur nicht passt oder der Zeitstempel mehr als fünf Minuten abweicht. Wichtig: Übergeben Sie den unveränderten Text der Anfrage, nicht ein neu erzeugtes JSON – schon ein anderes Leerzeichen ändert die Signatur.

Ohne Bibliothek: webhook-signature enthält v1, gefolgt vom Base64-Wert von HMAC-SHA256 über <webhook-id>.<webhook-timestamp>.<Rohtext>. Schlüssel ist der Teil des Secrets nach whsec_, Base64-dekodiert.

Secret erneuern

Ist das Secret an anderer Stelle bekannt geworden, klappen Sie den Webhook auf und wählen Secret erneuern. Das bisherige Secret signiert noch 24 Stunden mit: In dieser Zeit stehen zwei Signaturen im Header, durch ein Leerzeichen getrennt, und Ihr System akzeptiert die Zustellung mit dem alten wie mit dem neuen Secret. Tauschen Sie es in Ruhe aus.

Zustellungen nachverfolgen

Aufgeklappt zeigt jeder Webhook seine Zustellungen der letzten 30 Tage: Ereignis, Status, HTTP-Antwort und Zahl der Versuche, aufgeklappt den gesendeten Inhalt und den letzten Fehler. Erneut senden stellt eine Zustellung noch einmal zu, unter derselben webhook-id – etwa nachdem Sie einen Fehler in Ihrem System behoben haben.

Status	Bedeutung
Zugestellt	Ihr System hat mit 2xx geantwortet
Ausstehend	Der erste Versuch läuft gleich
Wird wiederholt	Ein Versuch ist fehlgeschlagen, der nächste ist geplant
Fehlgeschlagen	Auch der letzte Versuch nach gut einem Tag ist fehlgeschlagen

In der Liste der Webhooks steht unter Letzte Zustellung, wie der jüngste Versuch ausging.