API - Mandant / Organisation Admin

📕 Für Administratoren und Entwickler.

Die Mandanten-Endpunkte ermöglichen den Zugriff auf Stammdaten, Rechnungs-Einstellungen und Bankverbindung des eigenen Mandanten. Alle Aenderungen sind auf den Mandanten des verwendeten API-Keys beschränkt.

Mandanten-Daten abrufen

GET /api/v1/tenant

Scope: tenant:read

Antwort:

{
  "data": {
    "id": 1,
    "name": "Muster GmbH",
    "phone": "+49 211 123456",
    "website": "https://www.muster-gmbh.de",
    "industry": "IT-Dienstleistungen",
    "teamSize": 25,
    "defaultWeeklyWorkingHours": 40.0,
    "annualVacationDays": 30,
    "workingDays": "[\"MO\", \"TU\", \"WE\", \"TH\", \"FR\"]",
    "createdAt": "2025-01-15T08:00:00Z"
  }
}

Felder

Feld	Typ	Beschreibung
`id`	`number`	Interne ID des Mandanten
`name`	`string`	Name der Organisation
`phone`	`string?`	Telefonnummer
`website`	`string?`	Website
`industry`	`string?`	Branche
`teamSize`	`number?`	Teamgröße (Anzahl Mitarbeiter)
`defaultWeeklyWorkingHours`	`number`	Standard-Wochenarbeitsstunden
`annualVacationDays`	`number`	Jaehrliche Urlaubstage
`workingDays`	`string?`	Arbeitstage als JSON-Array (z.B. `["MO","TU","WE","TH","FR"]`)
`createdAt`	`string?`	Erstellungszeitpunkt (ISO 8601 UTC)

Mandanten-Daten aktualisieren

PUT /api/v1/tenant

Scope: tenant:write

Partial Update — nur angegebene Felder werden geändert. Sicherheitsrelevante Felder (Status, Speicherkontingent etc.) können nicht veraendert werden.

Request-Body:

{
  "name": "Neue Firma GmbH",
  "phone": "+49 211 654321",
  "website": "https://www.neue-firma.de",
  "industry": "Handwerk",
  "teamSize": 10,
  "defaultWeeklyWorkingHours": 38.5,
  "annualVacationDays": 28,
  "workingDays": "[\"MO\", \"TU\", \"WE\", \"TH\", \"FR\"]"
}

Antwort (200 OK): Aktualisiertes Mandanten-Objekt im data-Feld.

Rechnungs-Einstellungen abrufen

GET /api/v1/tenant/billing-settings

Scope: tenant:read

Antwort:

{
  "data": {
    "companyName": "Muster GmbH",
    "street": "Musterstrasse",
    "houseNumber": "42",
    "postalCode": "40210",
    "city": "Düsseldorf",
    "country": "Deutschland",
    "phone": "+49 211 123456",
    "email": "buchhaltung@muster-gmbh.de",
    "website": "https://www.muster-gmbh.de",
    "taxId": "123/456/78900",
    "vatId": "DE123456789",
    "hasLogo": true,
    "logoOriginalFilename": "logo.png",
    "defaultPaymentDays": 14,
    "defaultTaxRate": 19.00,
    "invoiceNumberFormat": "INV-{YEAR}-{COUNTER}",
    "nextInvoiceCounter": 42,
    "counterMinLength": 5,
    "cancellationNumberFormat": "ST-{YEAR}-{COUNTER}",
    "nextCancellationCounter": 1,
    "templateStyle": "CLASSIC",
    "logoPosition": "TOP_LEFT",
    "logoScale": 100,
    "primaryColor": "#333333",
    "accentColor": "#7B1FA2",
    "footerText": "Vielen Dank für Ihr Vertrauen.",
    "closingText": null,
    "attachReportDefault": false,
    "includePaymentQrCode": true,
    "defaultEInvoiceProfile": "EN16931",
    "defaultLeitwegId": null,
    "updatedAt": "2025-03-01T10:00:00"
  }
}

Rechnungs-Einstellungen aktualisieren

PUT /api/v1/tenant/billing-settings

Scope: tenant:write

Partial Update — nur angegebene Felder werden geändert.

Request-Body (Beispiel):

{
  "companyName": "Neue Firma GmbH",
  "defaultPaymentDays": 30,
  "defaultTaxRate": 19.00,
  "footerText": "Wir freuen uns auf die weitere Zusammenarbeit."
}

Verfuegbare Felder

Feld	Typ	Beschreibung
`companyName`	`string?`	Firmenname für Rechnungen
`street`	`string?`	Strasse
`houseNumber`	`string?`	Hausnummer
`postalCode`	`string?`	Postleitzahl
`city`	`string?`	Stadt
`country`	`string?`	Land
`phone`	`string?`	Telefonnummer
`email`	`string?`	E-Mail-Adresse für Rechnungen
`website`	`string?`	Website
`taxId`	`string?`	Steuernummer
`vatId`	`string?`	USt-IdNr.
`defaultPaymentDays`	`number?`	Standard-Zahlungsziel in Tagen
`defaultTaxRate`	`number?`	Standard-Mehrwertsteuersatz in Prozent
`invoiceNumberFormat`	`string?`	Rechnungsnummern-Format (z.B. `INV-{YEAR}-{COUNTER}`)
`counterMinLength`	`number?`	Mindestlänge des Zaehlers mit fuehrenden Nullen
`footerText`	`string?`	Fusszeilen-Text der Rechnung
`closingText`	`string?`	Abschlusstext unterhalb des Gesamtbetrags
`defaultEInvoiceProfile`	`string?`	Standard E-Rechnungs-Profil (z.B. `EN16931`)
`defaultLeitwegId`	`string?`	Standard Leitweg-ID

Antwort (200 OK): Aktualisiertes BillingSettings-Objekt im data-Feld.

Bankverbindung abrufen

GET /api/v1/tenant/bank-account

Scope: tenant:read

Antwort:

{
  "data": {
    "id": 1,
    "accountName": "Hauptkonto",
    "accountHolder": "Muster GmbH",
    "iban": "DE02120300000000202051",
    "ibanFormatted": "DE02 1203 0000 0000 2020 51",
    "bic": "BYLADEM1001",
    "bankName": "Deutsche Bank",
    "updatedAt": "2025-03-01T10:00:00"
  }
}

Bankverbindung erstellen / aktualisieren

PUT /api/v1/tenant/bank-account

Scope: tenant:write

Partial Update. Bei Neuanlage (noch keine Bankverbindung vorhanden) sind accountHolder und iban Pflichtfelder.

Request-Body:

{
  "accountName": "Hauptkonto",
  "accountHolder": "Muster GmbH",
  "iban": "DE02120300000000202051",
  "bic": "BYLADEM1001",
  "bankName": "Deutsche Bank"
}

Felder

Feld	Typ	Pflicht (Neuanlage)	Beschreibung
`accountName`	`string?`	Nein	Bezeichnung des Kontos
`accountHolder`	`string?`	Ja	Kontoinhaber
`iban`	`string?`	Ja	IBAN
`bic`	`string?`	Nein	BIC/SWIFT-Code
`bankName`	`string?`	Nein	Name der Bank

Antwort (200 OK): Aktualisiertes Bankverbindungs-Objekt im data-Feld.