{"openapi":"3.1.0","info":{"title":"AiZ-RVG — Öffentliche Schnittstelle (§ 28a RVG)","version":"v1","description":"Rechtsanwaltsabrechnung per Programmierschnittstelle. Authentifizierung über Bearer-Token (X-API-Key)."},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/abrechnung":{"post":{"summary":"Mandat abnehmen und abrechnen","description":"Nimmt ein Mandat mit Dokumenten entgegen, extrahiert die Angelegenheiten und liefert die Rechnung (synchron oder asynchron). Bei nicht finalisierten Bestimmungen werden die Sätze vorläufig berechnet (§ 28a.7).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AbrechnungRequest"}}}},"responses":{"200":{"description":"Abrechnung fertig (§ 28a.3).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AbrechnungResponse"}}}},"202":{"description":"Asynchrone Verarbeitung läuft noch (§ 28a.5).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Laeuft"}}}},"400":{"description":"Ungültige Anfrage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"401":{"description":"Token fehlt, ungültig, inaktiv, abgelaufen oder widerrufen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"402":{"description":"Kontingent erschöpft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"403":{"description":"Finalisierung nicht erlaubt (darf_finalisieren).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"404":{"description":"Schnittstelle nicht installiert oder Mandat unbekannt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"409":{"description":"Keine Angelegenheiten bestimmbar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"410":{"description":"Vorgang abgelaufen (Ergebnis nur 72 h abrufbar).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"413":{"description":"Zu viele oder zu große Dateien (max. 20, je 20 MB).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"415":{"description":"Ungültiges Dateiformat (kein PDF).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"422":{"description":"Eingaben fehlen — Fortsetzung mit vorgangId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EingabenOffen"}}}},"429":{"description":"Rate-Limit überschritten.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"503":{"description":"Dienst vorübergehend nicht verfügbar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}}},"/abrechnung/{vorgangId}":{"get":{"summary":"Status/Ergebnis eines Vorgangs abrufen","responses":{"200":{"description":"Vorgang abgeschlossen — identischer Körper wie die POST-Antwort.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AbrechnungResponse"}}}},"202":{"description":"Läuft noch — erneut abrufen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Laeuft"}}}},"401":{"description":"Nicht autorisiert.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"410":{"description":"Vorgang abgelaufen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"422":{"description":"Eingaben fehlen — mit vorgangId fortsetzen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EingabenOffen"}}}}}}},"/token":{"get":{"summary":"Eigenes Token prüfen","description":"Rechte, Vorabfreigabe und Kontingent des Tokens (§ 28a).","responses":{"200":{"description":"Token-Informationen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenOut"}}}},"401":{"description":"Nicht autorisiert.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}}}},"components":{"schemas":{"AbrechnungRequest":{"type":"object","properties":{"auftragsdatum":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"externeReferenz":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"aktenzeichenKanzlei":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"mandant":{"anyOf":[{"$ref":"#/components/schemas/Adresse"},{"type":"null"}]},"gegner":{"anyOf":[{"$ref":"#/components/schemas/Adresse"},{"type":"null"}]},"dateien":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/Datei"}},{"type":"null"}]},"angaben":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},{"type":"null"}]},"vorschuesseCents":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"optionen":{"default":{"warten":true,"pdf":true,"trace":true,"finalisieren":false},"$ref":"#/components/schemas/Optionen"},"vorgangId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["auftragsdatum"],"additionalProperties":false,"description":"Anfrage an die öffentliche Schnittstelle (§ 28a.2)."},"Adresse":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"strasse":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"plz":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"ort":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"required":["name"],"description":"Anschrift eines Beteiligten (Mandant/Gegner)."},"Datei":{"type":"object","properties":{"dateiname":{"type":"string","minLength":1,"maxLength":255},"mimeType":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"inhaltBase64":{"type":"string","minLength":1}},"required":["dateiname","inhaltBase64"],"description":"Ein Dokument als Base64 (bis 50 MB, max. 20 Dateien). Erlaubte Formate: PDF, Bilder (PNG/JPEG/GIF/TIFF) und Word (.docx)."},"Optionen":{"type":"object","properties":{"warten":{"default":true,"type":"boolean"},"pdf":{"default":true,"type":"boolean"},"trace":{"default":true,"type":"boolean"},"finalisieren":{"default":false,"type":"boolean"}},"description":"Steuerung des Abrechnungslaufs (§ 28a.5)."},"AbrechnungResponse":{"type":"object","properties":{"vorgangId":{"type":"string"},"status":{"type":"string","enum":["ABGESCHLOSSEN"]},"kanal":{"type":"string","const":"API"},"mandat":{"$ref":"#/components/schemas/Mandat"},"rechtsstand":{"$ref":"#/components/schemas/Rechtsstand"},"rechnung":{"$ref":"#/components/schemas/Rechnung"},"berechnung":{"type":"object","properties":{"trace":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["trace"],"additionalProperties":false},"dokumente":{"type":"array","items":{"$ref":"#/components/schemas/Dokument"}},"hinweise":{"type":"array","items":{"$ref":"#/components/schemas/Hinweis"}},"nutzung":{"$ref":"#/components/schemas/Nutzung"},"dauerMs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"requestId":{"type":"string"}},"required":["vorgangId","status","kanal","mandat","rechtsstand","rechnung","berechnung","dokumente","hinweise","nutzung","dauerMs","requestId"],"additionalProperties":false,"description":"Antwort auf eine Abrechnung (§ 28a.3)."},"Mandat":{"type":"object","properties":{"id":{"type":"string"},"mandatsnummer":{"type":"string"},"auftragsdatum":{"type":"string"},"externeReferenz":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","mandatsnummer","auftragsdatum","externeReferenz"],"additionalProperties":false},"Rechtsstand":{"type":"object","properties":{"versionId":{"type":"string"},"nameDe":{"type":"string"},"aufgeloestUeber":{"type":"string"}},"required":["versionId","nameDe","aufgeloestUeber"],"additionalProperties":false},"Rechnung":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ENTWURF","FINALISIERT"]},"rechnungsnummer":{"anyOf":[{"type":"string"},{"type":"null"}]},"rechnungsdatum":{"anyOf":[{"type":"string"},{"type":"null"}]},"nettoCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ustCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bruttoCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vorschuesseCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"restforderungCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"positionen":{"type":"array","items":{"$ref":"#/components/schemas/Position"}},"pdfBase64":{"type":"string"}},"required":["id","status","rechnungsnummer","rechnungsdatum","nettoCents","ustCents","bruttoCents","vorschuesseCents","restforderungCents","positionen"],"additionalProperties":false,"description":"Berechnete Rechnung inkl. Positionen und optionalem PDF (Base64)."},"Position":{"type":"object","properties":{"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vvNummer":{"type":"string"},"bezeichnungDe":{"type":"string"},"gegenstandswertCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"satz":{"anyOf":[{"type":"number"},{"type":"null"}]},"betragCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"istAnrechnung":{"type":"boolean"},"istAuslage":{"type":"boolean"},"istDurchlaufenderPosten":{"type":"boolean"}},"required":["position","vvNummer","bezeichnungDe","gegenstandswertCents","satz","betragCents","istAnrechnung","istAuslage","istDurchlaufenderPosten"],"additionalProperties":false,"description":"Eine Rechnungsposition (Gebühr, Anrechnung, Auslage)."},"Dokument":{"type":"object","properties":{"dateiname":{"type":"string"},"art":{"type":"string"},"seiten":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sha256":{"type":"string"},"dublette":{"type":"boolean"}},"required":["dateiname","art","seiten","sha256","dublette"],"additionalProperties":false},"Hinweis":{"type":"object","properties":{"code":{"type":"string"},"textDe":{"type":"string"}},"required":["code","textDe"],"additionalProperties":false},"Nutzung":{"type":"object","properties":{"gezaehlt":{"type":"boolean"},"verbrauch":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"kontingent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"zyklusEndeAm":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["gezaehlt","verbrauch","kontingent","zyklusEndeAm"],"additionalProperties":false},"Laeuft":{"type":"object","properties":{"vorgangId":{"type":"string"},"status":{"type":"string","const":"LAEUFT"},"pruefenAb":{"type":"string"},"hinweisUrl":{"type":"string"}},"required":["vorgangId","status","pruefenAb","hinweisUrl"],"additionalProperties":false,"description":"Asynchrone Verarbeitung läuft noch (§ 28a.5)."},"Fehler":{"type":"object","properties":{"fehler":{"type":"object","properties":{"code":{"type":"string"},"textDe":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","textDe"],"additionalProperties":false},"vorgangId":{"type":"string"},"requestId":{"type":"string"}},"required":["fehler"],"additionalProperties":false,"description":"Fehlerantwort (4xx/5xx)."},"EingabenOffen":{"type":"object","properties":{"fehler":{"type":"object","properties":{"code":{"type":"string","const":"eingabe_fehlt"},"textDe":{"type":"string"},"details":{"type":"object","properties":{"fehlendeSchluessel":{"type":"array","items":{"type":"object","properties":{"schluessel":{"type":"string"},"labelDe":{"type":"string"},"typ":{"type":"string"},"matterId":{"type":"string"},"rechtsgrundlage":{"type":"string"}},"required":["schluessel","labelDe","typ"],"additionalProperties":false}}},"required":["fehlendeSchluessel"],"additionalProperties":false}},"required":["code","textDe","details"],"additionalProperties":false},"vorgangId":{"type":"string"}},"required":["fehler","vorgangId"],"additionalProperties":false,"description":"Fortsetzung nötig: Eingaben fehlen (§ 28a.4)."},"TokenOut":{"type":"object","properties":{"token":{"type":"object","properties":{"id":{"type":"string"},"bezeichnung":{"type":"string"},"letzteVier":{"type":"string"},"darfFinalisieren":{"type":"boolean"},"saetzeVorabfreigabe":{"type":"boolean"},"vorabfreigabeMaxSatz":{"anyOf":[{"type":"number"},{"type":"null"}]},"vorabfreigabeErteiltAm":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","bezeichnung","letzteVier","darfFinalisieren","saetzeVorabfreigabe","vorabfreigabeMaxSatz","vorabfreigabeErteiltAm"],"additionalProperties":false},"benutzer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"}},"required":["id","email","role"],"additionalProperties":false},"plan":{"anyOf":[{"type":"object","properties":{"nameDe":{"anyOf":[{"type":"string"},{"type":"null"}]},"kontingentRechnungen":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["nameDe","kontingentRechnungen"],"additionalProperties":false},{"type":"null"}]}},"required":["token","benutzer","plan"],"additionalProperties":false,"description":"Informationen zum eigenen Token (§ 28a)."}},"headers":{"RateLimitLimit":{"description":"Limit im aktuellen Zeitfenster.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Verbleibende Anfragen im aktuellen Zeitfenster.","schema":{"type":"integer"}},"RateLimitReset":{"description":"UNIX-Zeitpunkt des Zurücksetzens.","schema":{"type":"integer"}},"RetryAfter":{"description":"Sekunden bis zum nächsten zulässigen Aufruf.","schema":{"type":"integer"}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API-Token aus der Portaleinstellung (X-API-Key)."}}}}