Faktura — API und MCP
Überblick
Dieser Bereich stellt 52 Operationen bereit. Jede davon ist zugleich ein MCP-Werkzeug.
Der Bereich hängt am Modul-Schalter module.invoicing. Ist das Modul aus, antworten diese Operationen mit 404.
Operationen
| Methode | Pfad | Zweck | Recht | Parameter |
|---|---|---|---|---|
GET | /api/v1/dunning-levels | Liste der DunningLevel | invoicing.dunning.manage · invoicing.config.manage | page, brandId |
POST | /api/v1/dunning-levels | Eine DunningLevel anlegen | invoicing.config.manage | + Rumpf |
DELETE | /api/v1/dunning-levels/{ulid} | Eine DunningLevel löschen | invoicing.config.manage | ulid |
GET | /api/v1/dunning-levels/{ulid} | Eine DunningLevel lesen | invoicing.dunning.manage · invoicing.config.manage | ulid |
PATCH | /api/v1/dunning-levels/{ulid} | Eine DunningLevel ändern | invoicing.config.manage | ulid, + Rumpf |
GET | /api/v1/invoice-correction-summary | Liste der InvoiceCorrectionSummary | invoicing.invoice.view | — |
GET | /api/v1/invoice-payments | Liste der InvoicePayment | invoicing.payment.record · invoicing.invoice.view | page, customerId, source, invoiceUlid |
POST | /api/v1/invoice-payments | Eine InvoicePayment anlegen | invoicing.payment.record | + Rumpf |
POST | /api/v1/invoice-payments/lexoffice-sync | Zahlungseingänge mit lexoffice abgleichen — Fragt für offene, an lexoffice übergebene Rechnungen den Zahlungsstand in lexoffice ab und bucht die noch fehlenden Zahlungseingänge (Quelle lexoffice, maschinell zugeordnet). Gebucht wird nur die Differenz zu den bereits verbuchten Zahlungen — ein zweiter Lauf bucht nichts doppelt. Derselbe Lauf läuft stündlich im Zeitplan; ohne lexoffice-Zugang oder bei abgeschaltetem Schalter invoicing.lexoffice.payment_sync bucht er nichts. Antwortet mit dem Bericht des Laufs; läuft gerade ein Zeitplan-Lauf, 409. | finance.lexoffice.sync | + Rumpf |
GET | /api/v1/invoices | Liste der Invoice | invoicing.invoice.view | page, status, type, creditKind, recurringInvoiceId, sourceOrderId, customerId, brandId, ownerId, q, receivable, exportStatus, order[number], order[status], order[issueDate], order[dueDate], order[totalAmount], order[createdAt] |
POST | /api/v1/invoices | Eine Invoice anlegen | invoicing.invoice.create | + Rumpf |
POST | /api/v1/invoices/bulk-send | Rechnungen gesammelt versenden — Payload {invoiceUlids: [...]} (höchstens 100). Antwort {results: [{ulid, number, ok, reason}]} — reason ist der Fehlerschlüssel, wenn eine Rechnung nicht hinausging (Entwurf, storniert, kein Empfänger, fremde Marke). | invoicing.invoice.send | + Rumpf |
GET | /api/v1/invoices/dunning-board | Mahnwesen-Board und Mahnlauf-Vorschau — Überfällige offene Rechnungen mit aktueller Mahnstufe und der Wirkung des nächsten Mahnlaufs (nextLevel, nextFeeAmount, nextInterestAmount; null = keine neue Stufe fällig oder pausiert). Höchstens 500 Zeilen. | invoicing.dunning.manage | brandId |
POST | /api/v1/invoices/dunning-run | Eine InvoiceDunning anlegen | invoicing.dunning.manage | + Rumpf |
POST | /api/v1/invoices/from-order | Create invoice from an order — Create invoice from an order. Dedicated action endpoint — not a standard CRUD create. | invoicing.invoice.create | + Rumpf |
GET | /api/v1/invoices/legacy-documents | Altbelege (Lese-Archiv) — Kopfdaten übernommener Altbelege, neueste zuerst. Ohne Buchungswirkung. | invoicing.invoice.view | page, q, customerId, documentType, brandId, sourceSystem, dateFrom, dateTo, order[number], order[documentDate], order[customerName], order[grossAmount] |
POST | /api/v1/invoices/legacy-documents | Altbeleg einspielen — Legt einen Altbeleg im Lese-Archiv an — Kopfdaten, optional das PDF als pdfBase64. Gleiche Herkunft (sourceSystem + externalId) ein zweites Mal liefert den vorhandenen Beleg (created: false). Netto + Steuer muss Brutto ergeben. | invoicing.config.manage | + Rumpf |
DELETE | /api/v1/invoices/legacy-documents/{ulid} | Fehlimport entfernen — Entfernt einen falsch eingespielten Altbeleg samt PDF; danach ist dieselbe Herkunft neu einspielbar. | invoicing.config.manage | ulid |
GET | /api/v1/invoices/legacy-documents/{ulid} | Eine LegacyDocument lesen | invoicing.invoice.view | ulid |
GET | /api/v1/invoices/legacy-documents/{ulid}/pdf | PDF eines Altbelegs — Liefert das archivierte PDF; 404, solange keines angehängt ist. | invoicing.invoice.view | ulid |
POST | /api/v1/invoices/legacy-documents/{ulid}/pdf | PDF an Altbeleg hängen — Hängt das PDF (pdfBase64, max. 10 MB) an einen Altbeleg ohne PDF. Ein vorhandenes PDF wird nie ersetzt (409). | invoicing.config.manage | ulid, + Rumpf |
POST | /api/v1/invoices/owner-reassignment | Inhaber von Rechnungen ändern — Setzt den Inhaber (ownerId, User-Id) an einem oder vielen Belegen (ulids, max. 500) — auch festgeschrieben, z. B. beim Ausscheiden eines Mitarbeiters. Der Beleginhalt bleibt unverändert; jede Änderung steht im Änderungsprotokoll (Herkunft owner_reassignment). Entwürfe genügen mit invoicing.invoice.create, alle anderen Belege brauchen invoicing.invoice.reassign_owner. Belege ohne dieses Recht in ihrer Marke oder außerhalb der Sichtbarkeit: not_found; Ziel-Nutzer ohne invoicing.invoice.view in der Beleg-Marke: target_not_allowed; schon Inhaber: unchanged. Ausgeschiedener/unbekannter Ziel-Nutzer: 422. | invoicing.invoice.reassign_owner · invoicing.invoice.create | + Rumpf |
DELETE | /api/v1/invoices/{ulid} | Eine Invoice löschen | invoicing.invoice.create | ulid |
GET | /api/v1/invoices/{ulid} | Eine Invoice lesen | invoicing.invoice.view | ulid |
PATCH | /api/v1/invoices/{ulid} | Eine Invoice ändern | invoicing.invoice.create | ulid, + Rumpf |
POST | /api/v1/invoices/{ulid}/cancel | Cancel invoice — Cancel invoice. Dedicated action endpoint — not a standard CRUD create. | invoicing.invoice.cancel | ulid, + Rumpf |
POST | /api/v1/invoices/{ulid}/correct | Correct invoice — Correct invoice. Dedicated action endpoint — not a standard CRUD create. | invoicing.invoice.cancel | ulid, + Rumpf |
POST | /api/v1/invoices/{ulid}/dunning-pause | Rechnung aus dem Mahnlauf nehmen — Payload {until: Y-m-d, reason}. Bis einschließlich until entsteht keine neue Mahnstufe (Zahlungsvereinbarung, Kulanz); die Überfälligkeit wird weiter festgestellt. reason ist Pflicht (Prüfpfad). Nur an festgeschriebenen, offenen Rechnungen (409 sonst). | invoicing.dunning.manage | ulid, + Rumpf |
POST | /api/v1/invoices/{ulid}/dunning-resume | Mahnpause aufheben — Die Rechnung nimmt wieder am Mahnlauf teil. | invoicing.dunning.manage | ulid, + Rumpf |
GET | /api/v1/invoices/{ulid}/dunnings | Liste der InvoiceDunning | invoicing.invoice.view · invoicing.dunning.manage | ulid |
POST | /api/v1/invoices/{ulid}/dunnings/{dunningUlid}/mark-sent | Mahnung als postalisch versendet vermerken — Vermerkt die Mahnung als auf dem Postweg versendet (setzt sentAt). Es wird keine Mail verschickt. | invoicing.dunning.manage | ulid, dunningUlid, + Rumpf |
GET | /api/v1/invoices/{ulid}/dunnings/{dunningUlid}/pdf | Eine InvoiceDunning lesen | invoicing.invoice.view · invoicing.dunning.manage | ulid, dunningUlid |
POST | /api/v1/invoices/{ulid}/dunnings/{dunningUlid}/resolve | Mahnvorgang abschließen — Schließt den Mahnvorgang als erledigt ab; die Mahnstufe läuft nicht weiter. | invoicing.dunning.manage | ulid, dunningUlid, + Rumpf |
POST | /api/v1/invoices/{ulid}/dunnings/{dunningUlid}/send | Send dunning — Send dunning. Dedicated action endpoint — not a standard CRUD create. | invoicing.dunning.manage | ulid, dunningUlid, + Rumpf |
GET | /api/v1/invoices/{ulid}/e-invoice | Eine Invoice lesen | invoicing.invoice.view | ulid |
POST | /api/v1/invoices/{ulid}/e-invoice | E-Rechnung erzeugen — Erzeugt idempotent die E-Rechnung zur FESTGESCHRIEBENEN Rechnung. Format aus eInvoiceFormat, sonst vom Beleg, dann vom Kunden, sonst XRechnung. | invoicing.invoice.einvoice | ulid, + Rumpf |
POST | /api/v1/invoices/{ulid}/export-retry | Übergabe an lexoffice wiederholen — Legt die Übergabe der festgeschriebenen Rechnung an (falls sie fehlt) und fährt sie sofort; ein Fehler oder Konflikt wird dabei zurückgesetzt. Ohne eingerichtete lexoffice-Anbindung bleibt der Stand pending und der nächste Lauf holt ihn nach. Antwort trägt exportStatus/exportError. | finance.lexoffice.sync | ulid, + Rumpf |
POST | /api/v1/invoices/{ulid}/issue | Issue invoice — Issue invoice. Dedicated action endpoint — not a standard CRUD create. | invoicing.invoice.issue | ulid, + Rumpf |
GET | /api/v1/invoices/{ulid}/pdf | Eine Invoice lesen | invoicing.invoice.view | ulid |
POST | /api/v1/invoices/{ulid}/redeem-voucher | Gutschein auf der Rechnung einlösen — Löst einen Rabattgutschein auf der Rechnung ein und schreibt ihn als Position — bei mehreren Steuersätzen je Satz eine Zeile. Nur im Entwurf; nicht auf Gutschrift oder Kostenbeleg. Derselbe Code ein zweites Mal: 422. | invoicing.invoice.create | ulid, + Rumpf |
POST | /api/v1/invoices/{ulid}/revoke-voucher | Gutschein-Einlösung der Rechnung zurücknehmen — Entfernt die Gutschein-Positionen und gibt den Wert an den Gutschein zurück. | invoicing.invoice.create | ulid, + Rumpf |
POST | /api/v1/invoices/{ulid}/send | Send invoice — Send invoice. Dedicated action endpoint — not a standard CRUD create. | invoicing.invoice.send | ulid, + Rumpf |
GET | /api/v1/invoices/{ulid}/vouchers | Eingelöste Gutscheine der Rechnung — Welche Gutscheine liegen offen auf der Rechnung? Auskunft aus dem Gutschein-Hauptbuch. Ohne Gutschein-Plugin eine leere Liste. | invoicing.invoice.view | ulid |
GET | /api/v1/recurring-invoices | Liste der RecurringInvoice | invoicing.recurring.view | page, status, cycle, customerId, brandId, q, order[title], order[status], order[nextRunAt], order[totalAmount], order[createdAt] |
POST | /api/v1/recurring-invoices | Eine RecurringInvoice anlegen | invoicing.recurring.manage | + Rumpf |
DELETE | /api/v1/recurring-invoices/{ulid} | Eine RecurringInvoice löschen | invoicing.recurring.manage | ulid |
GET | /api/v1/recurring-invoices/{ulid} | Eine RecurringInvoice lesen | invoicing.recurring.view | ulid |
PATCH | /api/v1/recurring-invoices/{ulid} | Eine RecurringInvoice ändern | invoicing.recurring.manage | ulid, + Rumpf |
POST | /api/v1/recurring-invoices/{ulid}/end | End recurring invoice — End recurring invoice. Dedicated action endpoint — not a standard CRUD create. | invoicing.recurring.manage | ulid, + Rumpf |
POST | /api/v1/recurring-invoices/{ulid}/pause | Pause recurring invoice — Pause recurring invoice. Dedicated action endpoint — not a standard CRUD create. | invoicing.recurring.manage | ulid, + Rumpf |
POST | /api/v1/recurring-invoices/{ulid}/resume | Resume recurring invoice — Resume recurring invoice. Dedicated action endpoint — not a standard CRUD create. | invoicing.recurring.manage | ulid, + Rumpf |
POST | /api/v1/recurring-invoices/{ulid}/run-now | Fällige Rechnung sofort erzeugen — Erzeugt sofort die fällige Rechnung aus der Serienrechnung (respektiert runMode), idempotent je Leistungszeitraum. Die Antwort trägt generatedInvoiceUlid. | invoicing.recurring.manage | ulid, + Rumpf |
Zweckangaben, die nicht dem Standardmuster folgen, stammen unverändert aus der Schnittstellen-Beschreibung im Code.