Abrechnung — API und MCP
Überblick
Dieser Bereich stellt 35 Operationen bereit. Jede davon ist zugleich ein MCP-Werkzeug.
Der Bereich hängt am Modul-Schalter module.finance. Ist das Modul aus, antworten diese Operationen mit 404.
Operationen
| Methode | Pfad | Zweck | Recht | Parameter | |
|---|---|---|---|---|---|
GET | /api/v1/billing-handoff-targets | Liste der BillingHandoffTarget | finance.billing.view | page, customerId, target | |
POST | /api/v1/billing-handoff-targets | Übergabeziel je Kunde setzen — Legt fest, wohin die Abrechnungs-Vorschauen dieses Kunden übergeben werden (Faktura in-house oder lexoffice). Ohne Eintrag gilt die Instanz-Vorgabe. | finance.recurring.manage | + Rumpf | |
DELETE | /api/v1/billing-handoff-targets/{ulid} | Übergabeziel je Kunde zurücknehmen — Entfernt die kundenbezogene Ausnahme; danach gilt wieder die Instanz-Vorgabe. | finance.recurring.manage | ulid | |
GET | /api/v1/billing-handoffs | Liste der BillingHandoff | finance.billing.view | page, status, target, customerId, brandId, previewUlid, order[status], order[handedOverAt], order[createdAt] | |
GET | /api/v1/billing-handoffs/{ulid} | Eine BillingHandoff lesen | finance.billing.view | ulid | |
POST | /api/v1/billing-handoffs/{ulid}/retry | Übergabe wiederholen — Wiederholt eine gescheiterte oder aufgegebene Übergabe (error, gave_up); mit target an ein anderes Ziel. Eine bereits erfolgreiche Übergabe wird nicht erneut versucht (409) — das wäre ein zweiter Beleg. Unabhängig davon wiederholt das System gescheiterte Übergaben selbst mit wachsendem Abstand und gibt nach sechs Versuchen auf. | finance.lexoffice.sync · finance.recurring.manage | ulid, + Rumpf | |
GET | /api/v1/billing-previews | Liste der BillingPreview | finance.billing.view | page, status, customerId, brandId, q, order[status], order[totalAmount], order[handedOverAt], order[createdAt] | |
POST | /api/v1/billing-previews | Eine BillingPreview anlegen | finance.recurring.manage | + Rumpf | |
POST | /api/v1/billing-previews/lexoffice-sync-run | Eine LexofficeSyncRun anlegen | finance.lexoffice.sync | + Rumpf | |
GET | /api/v1/billing-previews/{ulid} | Eine BillingPreview lesen | finance.billing.view | ulid | |
POST | /api/v1/billing-previews/{ulid}/add-item | Position zur Vorschau hinzufügen — Payload `{description, qty, unitPriceAmount, unit?, taxRate?\ | taxRateId?} (Preis in Cent, negativ = Nachlass; Steuersatz als Wert oder Katalog-Id, sonst Regelsatz; die Steuer-Behandlung des Kunden gilt). Fügt einer Vorschau im Entwurf eine freie Position hinzu (Herkunft manual`, 409 sonst) und rechnet die Summen neu. | finance.recurring.manage | ulid, + Rumpf |
POST | /api/v1/billing-previews/{ulid}/create-invoice | Aus der Abrechnungs-Vorschau eine Rechnung erzeugen — Erzeugt aus einer freigegebenen Vorschau einen Rechnungs-ENTWURF (Alternative zur lexoffice-Übergabe). Eine zweite Übergabe derselben Vorschau scheitert (409). | finance.lexoffice.sync · finance.recurring.manage | ulid, + Rumpf | |
POST | /api/v1/billing-previews/{ulid}/handoff | Vorschau an lexoffice übergeben — Übergibt die freigegebene Vorschau an lexoffice und setzt die enthaltenen Zeiten auf invoiced. Nur aus dem Zustand ready (sonst 409); idempotent über die lexoffice-Verknüpfung — ein zweiter Aufruf schiebt nichts nach. | finance.lexoffice.sync · finance.recurring.manage | ulid, + Rumpf | |
POST | /api/v1/billing-previews/{ulid}/ready | Abrechnungs-Vorschau freigeben — Markiert die Vorschau als geprüft und gibt sie zur Übergabe frei (Zustand ready) — erst dann nimmt der Übergabeweg sie an. | finance.recurring.manage | ulid, + Rumpf | |
POST | /api/v1/billing-previews/{ulid}/remove-items | Quellen aus der Vorschau abwählen — Payload {itemUlids: [...]}. Entfernt die genannten Zeilen aus einer Vorschau im Entwurf (409 sonst) und rechnet die Summen neu — die zugrunde liegenden Zeiten/Posten bleiben offen und erscheinen in der nächsten Vorschau. Der Abrechnen-Assistent aus dem Projekt nutzt das, um nur dessen Leistungen abzurechnen. | finance.recurring.manage | ulid, + Rumpf | |
POST | /api/v1/billing-previews/{ulid}/reopen | Geprüfte Vorschau wieder öffnen — Öffnet eine geprüfte Vorschau wieder zur Bearbeitung. Nach der Übergabe ist das nicht mehr möglich. | finance.recurring.manage | ulid, + Rumpf | |
POST | /api/v1/billing-previews/{ulid}/update-item | Position der Vorschau anpassen — Payload {itemUlid, description?, qty?, unitPriceAmount?} (Preis in Cent, Menge als Dezimaltext). Ändert Text, Menge und/oder Einzelpreis einer Zeile einer Vorschau im Entwurf (409 sonst) und rechnet Zeile und Summen neu. Angepasste Zeilen bleiben beim Neuaufbau der Vorschau erhalten. Abschlags- und Schlusszeilen gehören dem Abschlagsplan (409). | finance.recurring.manage | ulid, + Rumpf | |
GET | /api/v1/deposit-schedules | Liste der DepositSchedule | finance.billing.view | page, status, customerId, brandId, sourceType, sourceRef, order[status], order[baseAmount], order[createdAt] | |
POST | /api/v1/deposit-schedules | Abschlagsplan anlegen — Legt einen Anzahlungs-/Abschlagsplan mit seinen Fälligkeiten an. Je Fälligkeit ist entweder percent oder amountAmount gesetzt; die Summe darf die Netto-Basis nicht übersteigen. | finance.recurring.manage | + Rumpf | |
GET | /api/v1/deposit-schedules/{ulid} | Eine DepositSchedule lesen | finance.billing.view | ulid | |
POST | /api/v1/deposit-schedules/{ulid}/activate | Abschlagsplan aktivieren — Schaltet den Plan für den Fälligkeits-Lauf frei — ab dann entsteht zu jedem erreichten Termin eine Abschlagsvorgabe. | finance.recurring.manage | ulid, + Rumpf | |
POST | /api/v1/deposit-schedules/{ulid}/cancel | Abschlagsplan abbrechen — Bricht den Plan und alle offenen Fälligkeiten ab. Bereits abgerechnete Abschläge bleiben bestehen. | finance.recurring.manage | ulid, + Rumpf | |
POST | /api/v1/deposit-schedules/{ulid}/settle | Schlussrechnung vorbereiten — Erzeugt die Schlussrechnungs-Vorgabe: volle Netto-Basis, danach je bereits abgerechnetem Abschlag eine negative Position (§14 UStG). Offene Fälligkeiten werden abgebrochen. | finance.recurring.manage | ulid, + Rumpf | |
GET | /api/v1/recurring-billing-plans | Liste der RecurringBillingPlan | finance.recurring.manage | page, status, customerId, licenseId, runMode, q, order[amountAmount], order[status], order[nextRunAt] | |
POST | /api/v1/recurring-billing-plans | Eine RecurringBillingPlan anlegen | finance.recurring.manage | + Rumpf | |
POST | /api/v1/recurring-billing-plans/run | Eine RecurringBillingRun anlegen | finance.recurring.manage | + Rumpf | |
GET | /api/v1/recurring-billing-plans/{ulid} | Eine RecurringBillingPlan lesen | finance.recurring.manage | ulid | |
PATCH | /api/v1/recurring-billing-plans/{ulid} | Eine RecurringBillingPlan ändern | finance.recurring.manage | ulid, + Rumpf | |
POST | /api/v1/recurring-billing-plans/{ulid}/end | End recurring billing plan — End recurring billing plan. Dedicated action endpoint — not a standard CRUD create. | finance.recurring.manage | ulid, + Rumpf | |
POST | /api/v1/recurring-billing-plans/{ulid}/pause | Pause recurring billing plan — Pause recurring billing plan. Dedicated action endpoint — not a standard CRUD create. | finance.recurring.manage | ulid, + Rumpf | |
POST | /api/v1/recurring-billing-plans/{ulid}/resume | Resume recurring billing plan — Resume recurring billing plan. Dedicated action endpoint — not a standard CRUD create. | finance.recurring.manage | ulid, + Rumpf | |
GET | /api/v1/recurring-plan-summary | Liste der RecurringPlanSummary | finance.recurring.manage | — | |
GET | /api/v1/usage-records | Liste der UsageRecord | finance.billing.view | page, customerId, brandId, metric, billed, subjectType, subjectRef, from, to, order[occurredAt], order[metric] | |
POST | /api/v1/usage-records | Verbrauch einliefern — Bucht eine Verbrauchszeile (Seats/Transaktionen/Verbrauch). Mit externalRef idempotent: dieselbe Fremd-Kennung liefert die bestehende Zeile zurück, statt doppelt abzurechnen. | finance.recurring.manage | + Rumpf | |
GET | /api/v1/usage-records/{ulid} | Eine UsageRecord lesen | finance.billing.view | ulid |
Zweckangaben, die nicht dem Standardmuster folgen, stammen unverändert aus der Schnittstellen-Beschreibung im Code.