Mit einem API-Key kann ein Agent wie GitHub Copilot in deiner WEG mitarbeiten: Dokumente hochladen, Rechnungen als PDF erstellen, Fristen, Begehungen, Beschlüsse und Aufgaben pflegen.
Dein WEG-Admin fragt unter API-Keys einen Key an. Nach persönlicher System-Admin-Freigabe wird er einmalig angezeigt. Eingeschränkte Mitglieder können keine Keys anfragen.
Nur System-Admins können Keys direkt per Login-Token erstellen:
VerwaloPOST /api/verwaltung/WEG-Beispiel/api-keys
{ "name": "GitHub Copilot", "scope": "write" } // scope: "read" oder "write"
→ 201 { "id": 1, "name": "GitHub Copilot", "key": "vwk_…" }Der Key wird nur einmal angezeigt und serverseitig nur als Hash gespeichert. WEG-Admins sehen und widerrufen ihre selbst beantragten Keys; System-Admins verwalten alle Keys der zugänglichen WEG.
Alle Agenten-Endpunkte liegen unter /api/agent/:weg/…. Der Key wird als Bearer-Token oder per X-API-Key-Header gesendet:
curl -H "Authorization: Bearer vwk_…" \
"https://app.grindler-ivs.de/api/agent/WEG-Beispiel/fristen"| Aufgabe | Endpunkt |
|---|---|
Dokument hochladen (multipart, Feld file, area, category, title) | POST /documents |
| Dokumente auflisten / herunterladen | GET /documents?area=eigentuemer, GET /documents/:id/download |
| Welche Dokumente fehlen? | GET /documents/missing?area=eigentuemer |
| Rechnung als PDF erstellen | POST /invoices/pdf |
| Fristen (z. B. Eigentümerversammlung) ansehen, anlegen, erledigen, wieder öffnen | GET /fristen, POST /fristen, POST /fristen/:id/done, POST /fristen/:id/reopen |
| Aufgaben anlegen und bearbeiten | /todos |
| Begehungen und Protokoll-PDF | /begehungen, GET /begehungen/:id/pdf |
| Beschluss-Sammlung | /beschluesse |
| Gesamtabrechnung lesen, PDF exportieren | GET /abrechnungen/:year, GET /abrechnungen/:year/pdf |
| Jahresunterlagen und gespeicherte Abrechnung prüfen | GET /abrechnungen/:year/checklist |
| Dokumentjahre und offene Synchronisierung lesen | GET /abrechnungen/document-sync |
| Belegte Text-Zuordnungen lesen / als Write-Agent einreichen | GET /abrechnungen/:year/agent-proposals, PUT /abrechnungen/:year/agent-proposals/:documentId |
| Mieterabrechnung vorbereiten (keine Freigabe) | GET /abrechnungen/:year/tenant-proposals/context, GET /abrechnungen/:year/tenant-proposals, PUT /abrechnungen/:year/tenant-proposals/:ownerId |
| Leitfaden-Checkliste | /checklist |
Alle Pfade beginnen mit /api/agent/:weg. Beispiel Rechnung und Upload:
curl -X POST -H "X-API-Key: vwk_…" -H "Content-Type: application/json" \
-d @rechnung.json -o rechnung.pdf \
https://app.grindler-ivs.de/api/agent/WEG-Beispiel/invoices/pdf
curl -X POST -H "X-API-Key: vwk_…" \
-F area=eigentuemer -F category=protokoll -F title="Protokoll 2026" -F file=@protokoll.pdf \
https://app.grindler-ivs.de/api/agent/WEG-Beispiel/documentsAuch mit Read-Key: GET /api/agent/:weg/documents/missing?area=eigentuemer. Die feste Basisliste umfasst Teilungserklärung/Gemeinschaftsordnung, Protokolle, Abrechnungen, Verträge und Versicherungen. Für area=miete umfasst sie Verträge, Abrechnungen und Versicherungen; der Mietbereich muss aktiviert sein.
{
"weg": "WEG-Beispiel",
"area": "eigentuemer",
"basis": "document_categories_v1",
"expected": [
{ "category": "teilungserklaerung", "label": "Teilungserklärung / Gemeinschaftsordnung" },
{ "category": "protokoll", "label": "Versammlungsprotokolle" },
{ "category": "abrechnung", "label": "Jahresabrechnungen" },
{ "category": "vertrag", "label": "Verträge" },
{ "category": "versicherung", "label": "Versicherungsunterlagen" }
],
"present": [
{ "category": "teilungserklaerung", "label": "Teilungserklärung / Gemeinschaftsordnung", "count": 1 },
{ "category": "protokoll", "label": "Versammlungsprotokolle", "count": 2 },
{ "category": "abrechnung", "label": "Jahresabrechnungen", "count": 1 },
{ "category": "vertrag", "label": "Verträge", "count": 1 }
],
"missing": [
{ "category": "versicherung", "label": "Versicherungsunterlagen" }
],
"note": "Orientierung anhand einer festen Basisliste: Eine Kategorie gilt ab einem abgelegten Dokument als vorhanden. Inhalte, Aktualität, einzelne Jahre und rechtliche Vollständigkeit werden nicht geprüft."
}Der Endpunkt prüft nur gespeicherte Kategorien, keine Dateiinhalte. Ein Dokument genügt pro Kategorie; das ist keine Aussage über vollständige oder aktuelle Unterlagen.
GET /api/agent/:weg/abrechnungen/2025/checklist liefert eine WEG-begründete Jahres-Checkliste, auch mit Read-Key. Sie trennt Grundlagen, geeignete Einnahmen-/Ausgabennachweise, gesetzlich vorgesehene Ergebnisse, fallbezogene Unterlagen und spätere Beschlussdokumentation.
Jeder Eintrag enthält category, label, group, scope, status, Anzahlen sowie purpose, review, amtliche sources und gegebenenfalls condition. Status: present (Nachweis abgelegt), needs_assignment (Jahr zuordnen), missing (kein zugeordneter Nachweis) oder check_applicability (nur falls relevant).
Zusätzlich: checks für gespeicherte Abrechnung, Positionen und Eigentümer; warnings für rechnerische Verteilung; invoices für Übernahmen ins Zahlungsjahr und noch unzugeordnete Rechnungen mit Rechnungsdatum im Jahr; manual_checks für erforderliche eigene Prüfungen. legal_checked_at bezeichnet den amtlichen Quellenabruf am 11.10.2026, keine laufende automatische Gesetzesprüfung.
Grundlagen: § 28 WEG (Jahresabrechnung und gesonderter Vermögensbericht), § 16 WEG (Verteilung), § 18 Abs. 4 WEG (Verwaltungsunterlagen), ergänzend §§ 10, 19, 21, 24, 29 WEG und bei Wärme-/Warmwasserversorgung HeizkostenV. Keine universelle gesetzliche Dateiliste, Inhaltsprüfung oder Rechtsberatung.
Unterlagen benötigen ein ausdrückliches accounting_year; dauerhafte Grundlagen können aus früheren Jahren stammen. Uploads dürfen dieses optionale Feld mitgeben. Bestehende Dokumente ordnen nur WEG-Admins per Benutzer-Login zu; Agenten können keine Zuordnungen ändern. Dokumentjahr und Kategorie lösen keine Buchung aus.
GET /abrechnungen/document-sync zeigt alle Dokumentjahre, noch nicht übernommene pending_document_ids, offene Prüfhinweise und Dokumente ohne Jahr. Der WEG-Admin startet die lokale Synchronisierung in der App. Optional speichert sie konfliktfreie Werte automatisch, nach Aktivierung mit Risikobestätigung unter „Bereiche und Funktionen“. Agenten-Uploads allein starten keine Auslese oder Buchung.
Dein Upload-/Bearbeitungsagent nutzt sein externes LLM, um im Original vorhandene Key-/Value-Paare zuzuordnen. Verwalo ruft selbst kein LLM auf. Zuerst mit area=eigentuemer, category=abrechnung und accounting_year hochladen. Danach die aktuelle Abrechnung und GET /abrechnungen/2025/agent-proposals lesen. Bei HTTP 404 ist die Revision null; andere Lesefehler müssen geklärt werden. Dann mit Write-Key einreichen:
PUT /api/agent/WEG-Beispiel/abrechnungen/2025/agent-proposals/123
{
"revision": null,
"proposal_updated_at": null,
"proposal": {
"positions": [
{"name": "Allgemeinstrom", "amount": 100, "key": "mea", "umlagefaehig": true}
],
"owners": [],
"meta": {},
"statedTotal": 100
},
"evidence": [
{"path": "year", "quote": "Gesamtabrechnung 2025"},
{"path": "positions.0.name", "quote": "Allgemeinstrom"},
{"path": "positions.0.amount", "quote": "Allgemeinstrom 100,00 EUR"},
{"path": "positions.0.key", "quote": "Verteilung nach MEA"},
{"path": "positions.0.umlagefaehig", "quote": "Umlagefähige Kosten"},
{"path": "statedTotal", "quote": "Gesamtkosten 100,00 EUR"}
]
}Jeder gelieferte Wert braucht einen passenden wörtlichen Textbeleg; Namen wie im Original verwenden. Zahlen als JSON-Zahlen, fehlende Beträge/Schlüssel als null – niemals geschätzte Nullwerte. Auch bestätigte 0 braucht einen Beleg. Schlüssel: mea oder direkt; Umlagefähigkeit muss ausdrücklich belegt sein. Zahlenbelege akzeptieren deutsche Gruppierung/Dezimalkomma und Dezimalpunkt mit ein bis zwei Nachkommastellen; 1.234 bedeutet 1234, nicht 1,234. Vorzeichen/Bedeutung, insbesondere Salden, nicht raten.
Eigentümer: name, unit, mea (Prozent, 0–100), vorauszahlung (monatlich), gezahlt, vorjahr, sonstige und direkt (Kostenname → Anteil). Belegpfade beispielsweise owners.0.mea und owners.0.direkt.Heizkosten. Direkte Kosten benötigen eine gleichnamige Position im Vorschlag. Metadaten: anlage, verwalter, iban, kontoEnde, ruecklage; Pfade etwa meta.anlage. Für eine belegte vollständige Kostenliste statedTotal übermitteln; Summenwidersprüche sperren Kosten für die Automatik.
Antwort: pending_review oder safe_additions_saved, dazu revision, updated_at, applied_revision und pending_review als Boolean. Auch nach Teilübernahme kann dieser Boolean true bleiben. Ohne WEG-Admin-Opt-in wird nichts in die Jahresabrechnung geschrieben. Mit Opt-in bleiben abweichende vorhandene Werte einschließlich Null geschützt; unbekannte neue Eigentümer bleiben unvollständig zur Prüfung offen. Fehlende Werte werden nur aus eindeutig passenden bestehenden Eigentümerdaten bewahrt, nicht erfunden. Ergänzende Dokumentvorschläge lassen sich in der App gemeinsam prüfen.
Bei Überarbeitung dieselbe Dokument-ID verwenden; aktuelle revision und bisheriges updated_at als proposal_updated_at mitsenden. Neue Quelle: proposal_updated_at: null. HTTP 409: neu lesen und abgleichen; HTTP 400: fehlenden/unpassenden Beleg korrigieren. Maximal 80 Positionen, 60 Eigentümer, 1000 eindeutige Belegpfade, 600 Zeichen pro Ausschnitt und 100 KB JSON. Kein serverseitiger Abgleich mit dem Originalvolltext und keine Rechtsgarantie. Datenschutz und Beauftragung des externen LLM verantwortet die WEG.
Bei aktivierter Mietverwaltung liest der Agent zuerst GET /abrechnungen/2025/tenant-proposals/context: aktuelle Quellrevision, Wohnungs-/Eigentümer-IDs, Kostenpositionen, bekannte Anteile, Objektanschrift und zulässige Kostenarten. GET /abrechnungen/2025/tenant-proposals liefert bisherige Entwürfe mit updated_at und stale. Diese GETs sind auch mit Read-Key verfügbar. Write-Keys reichen je Jahr und Wohnung einen prüfbaren Entwurf ein – keine fertige Forderung:
PUT /api/agent/WEG-Beispiel/abrechnungen/2025/tenant-proposals/owner-id
{
"source_revision": 3,
"proposal_updated_at": null,
"proposal": {
"tenant": "Muster Mieter",
"tenant_address": "Musterstrasse 1",
"advance_paid": 1200,
"lines": []
},
"evidence": [
{"path": "year", "source_document_id": 123, "quote": "Betriebskostenabrechnung 2025"},
{"path": "owner", "source_document_id": 123, "quote": "Eigentuemer: Muster Vermieter"},
{"path": "unit", "source_document_id": 123, "quote": "Wohnung: WE 1"},
{"path": "tenant", "source_document_id": 124, "quote": "Mieter: Muster Mieter"},
{"path": "tenant_address", "source_document_id": 124, "quote": "Musterstrasse 1"},
{"path": "advance_paid", "source_document_id": 125,
"quote": "Tatsaechlich gezahlte Betriebskostenvorauszahlungen 2025: 1200,00 EUR"}
]
}Alle Dokument-IDs müssen innerhalb derselben WEG vorhanden sein. owner und unit belegen die ausgewählte Zuordnung. Zulässige optionale Formularfelder: unit, property_address, tenant, tenant_address, landlord, landlord_address, contact, period_start, period_end, tenancy_start, tenancy_end, advance_paid, account_holder, iban, payment_note, notes. Fehlendes weglassen oder null; Zahlungen niemals aus Hausgeld, Nettokaltmiete, Monats-Soll oder Vorjahreszahlungen ableiten. Vorauszahlungen brauchen einen Textbeleg tatsächlicher Mietzahlungen im ausgewählten Jahr und ein Dokument mit diesem accounting_year. Mieterdaten aus Vorjahren nur übernehmen, wenn ihre Geltung für den aktuellen Mietzeitraum geklärt ist.
lines ergänzt bekannte position_ids um belegte category, tenant_amount, allocation, notes oder eine belegte included-Auswahl. Belegpfade: lines.0.name (Kostenname aus dem Kontext), lines.0.category (Text zur Kostenposition), lines.0.notes usw. Kostenarten müssen aus dem Kontext stammen und eine belegte Einordnungsnotiz haben; gemeinsame Wasser-/Abwasserkosten können wasser_abwasser verwenden. Umlagefähigkeit in der WEG ersetzt keine Mietvertragsprüfung. Mieterbeträge benötigen einen Jahresbeleg und korrekt zugeordnetes Dokumentjahr. allocation und notes werden wörtlich belegt; für fehlende Berechnungen verwendet die App vorhandene Jahres-/MEA-Anteile, ohne Teilzeiträume oder Verbrauch zu schätzen.
Zusätzliche Vermieterkosten: stabile position_id wie extra:grundsteuer:125 sowie belegte name, global_amount, category, tenant_amount, allocation und notes. Ausgeschlossene Verwaltung/Erhaltung darf nicht wieder eingeführt werden. Maximal 100 Positionen, 100 Dokumente, 1000 eindeutige Belegpfade und 2000 Zeichen pro Ausschnitt; 100 KB JSON insgesamt. Datumswerte sind ISO-Daten innerhalb des Abrechnungsjahres, Textbelege akzeptieren auch deutsche Datumsangaben.
Antwort draft_proposal_saved speichert ausschließlich den Vorschlag. Anders als Jahresergänzungen werden Mieterforderungen auch bei WEG-Automatik niemals automatisch freigegeben. Neue Formulare übernehmen aktuelle Vorschläge; bestehende Eingaben ergänzt die App nur in offenen Feldern. Veränderte Jahresrevisionen oder fehlende Zahlungs-/Kostenquellen markieren Entwürfe als stale. Bei Überarbeitung aktuellen Timestamp als proposal_updated_at mitsenden, nach HTTP 409 neu lesen. Erst der WEG-Admin prüft und speichert in der App; verwendete Agentenbelege werden dabei als Herkunftsnachweis mitgespeichert. Die App ruft weiterhin kein LLM auf.
Kontakt- und Rechnungsdaten geben ausschließlich WEG-Admins per Benutzer-Login frei, nicht Agenten. Der neue Dokumentcheck liest nur Kategorien und Anzahlen, keine Inhalte.
agent:<Key-Name> protokolliert. Widerrufene Keys sind sofort ungültig.