APIReferenz

API-Referenz

Integrieren Sie Kontakte, Produkte, Rechnungen und Zahlungen direkt in Ihre eigenen Systeme. Hier finden Sie alle Endpunkte, Datenmodelle und ausführbare Beispiele.

REST APIVersion 1JSONBearer Token

Auf dieser Seite+

Schnellstart

Die Sysbalance REST-API stellt Rechnungen, Produkte, Kontakte und Auswertungen als JSON bereit. Jede Anfrage ist strikt auf das Unternehmen des verwendeten API-Schlüssels begrenzt.

Basis-URL

https://beta.sysbalance.de/api/v1

Authentifizierung

Bearer Token

Erstellen Sie Ihren API-Schlüssel im Dashboard unter Schlüssel. Übergeben Sie ihn anschließend bei jeder Anfrage im Header Authorization: Bearer <dein-schlüssel>.

Terminal

curl https://beta.sysbalance.de/api/v1/invoices \
  -H "Authorization: Bearer sb_live_dein-schluessel"

API-Schlüssel beginnen mit sb_live_ und werden nur einmal vollständig angezeigt. Bewahren Sie sie ausschließlich serverseitig auf.

Authentifizierte Anfragen erscheinen unter API-Aktivität. Ungültige, widerrufene oder abgelaufene Schlüssel liefern 401 unauthorized.

Antwortformat

Erfolgreiche Antworten liefern Nutzdaten im Feld data. Listen enthalten zusätzlich ein meta-Objekt mit den Paginierungsangaben.

JSON

{
  "data": [
    { "id": "clx…", "type": "COMPANY", "companyName": "Muster GmbH", "email": "buchhaltung@muster.de" }
  ],
  "meta": { "page": 1, "pageSize": 25, "pageCount": 4, "total": 92 }
}

Der Content-Type ist application/json. Geldbeträge werden als Ganzzahl in Cent übertragen, Datumswerte im ISO-Format.

Paginierung & Filter

Listenendpunkte akzeptieren die Query-Parameter page (ab 1) und pageSize (Standard 25, maximal 100). Die Angaben zur Gesamtzahl und Seitenanzahl stehen im meta-Objekt der Antwort.

Beispiel

https://beta.sysbalance.de/api/v1/contacts?page=2&pageSize=50&search=muster

Je nach Ressource stehen weitere Filter zur Verfügung, etwa search, status, type oder role. Die genauen Parameter finden Sie beim jeweiligen Endpunkt.

Fehler

Fehler verwenden ein einheitliches Format mit maschinenlesbarem code, einer message und - bei Validierungsfehlern - feldweisen details.

JSON

{
  "error": {
    "code": "validation_error",
    "message": "Bitte korrigiere die markierten Felder.",
    "details": {
      "fields": { "companyName": ["Bitte gib einen Firmennamen ein."] },
      "form": []
    }
  }
}

Code	HTTP	Bedeutung
`unauthorized`	401	Schlüssel fehlt, ist ungültig, widerrufen oder abgelaufen.
`forbidden`	403	Zugriff auf die angeforderte Ressource nicht erlaubt.
`not_found`	404	Die Ressource existiert nicht.
`validation_error`	400	Übergebene Felder sind ungültig (Details unter details.fields).
`invalid_body`	400	Der Anfragekörper ist kein gültiges JSON.
`method_not_allowed`	405	Die HTTP-Methode wird für diesen Pfad nicht unterstützt.
`conflict`	409	Konflikt mit dem aktuellen Zustand der Ressource.
`unprocessable`	422	Anfrage verstanden, im aktuellen Zustand aber nicht ausführbar.
`rate_limited`	429	Zu viele Anfragen in kurzer Zeit.
`internal_error`	500	Unerwarteter Fehler auf dem Server.

Datenmodelle

Diese Modelle beschreiben die Felder, die die API zurückgibt. Anfragekörper erwarten je Endpunkt nur die dort genannten Felder.

Rechnung (Invoice)

Vollständige Rechnung mit Positionen, Beträgen (netto/Steuer/brutto in Cent) und Zahlungsstand. Festgeschriebene Rechnungen sind unveränderlich.

Feld	Typ	Beschreibung
`id`	string	Eindeutige ID der Rechnung.
`status`	enum	DRAFT, ISSUED, PAID oder CANCELLED.
`type`	enum	INVOICE (regulär) oder STORNO (Stornorechnung).
`number`	string \| null	Rechnungsnummer (erst nach dem Festschreiben vergeben).
`sequence`	number \| null	Lückenlose laufende Nummer innerhalb des Nummernkreises.
`issueDate`	string (ISO)	Rechnungsdatum.
`serviceDate`	string \| null	Leistungs-/Lieferdatum.
`dueDate`	string \| null	Fälligkeitsdatum.
`currency`	string	ISO-4217-Währungscode, z. B. EUR.
`smallBusiness`	boolean	Kleinunternehmerregelung (§19 UStG) angewandt.
`taxScheme`	enum	STANDARD, REVERSE_CHARGE oder NOT_TAXABLE.
`netTotalCents`	number	Nettosumme in Cent.
`taxTotalCents`	number	Umsatzsteuersumme in Cent.
`grossTotalCents`	number	Bruttosumme in Cent.
`paymentTerms`	string \| null	Zahlungsziel als Freitext.
`buyerReference`	string \| null	Käuferreferenz (Leitweg-ID / B2G).
`footer`	string \| null	Fußzeilentext des Dokuments.
`sellerBankHolder`	string \| null	Kontoinhaber der Absender-Momentaufnahme.
`sellerBankName`	string \| null	Bank der Absender-Momentaufnahme.
`sellerIban`	string \| null	IBAN der Absender-Momentaufnahme.
`sellerBic`	string \| null	BIC der Absender-Momentaufnahme.
`templateKey`	string	Verwendeter Vorlagen-Schlüssel.
`contactId`	string \| null	ID des Empfänger-Kontakts.
`buyerName`	string \| null	Name des Empfängers (Momentaufnahme).
`buyerVatId`	string \| null	USt-IdNr. des Empfängers (Momentaufnahme).
`hasEInvoice`	boolean	Eine XRechnung ist gespeichert.
`cancelledAt`	string \| null	Zeitpunkt der Stornierung.
`cancelledReason`	string \| null	Grund der Stornierung.
`stornoOfId`	string \| null	Auf Stornorechnungen: ID der aufgehobenen Rechnung.
`stornoInvoiceId`	string \| null	Auf stornierten Rechnungen: ID der Stornorechnung.
`paidAmountCents`	number	Summe aller erfassten Zahlungen in Cent.
`openAmountCents`	number	Noch offener Betrag in Cent (Brutto − Zahlungen).
`payments`	Payment[]	Erfasste Zahlungen, neueste zuerst.
`items`	InvoiceItem[]	Rechnungspositionen.
`createdAt`	string (ISO)	Zeitpunkt der Erstellung.
`updatedAt`	string (ISO)	Zeitpunkt der letzten Änderung.
`issuedAt`	string \| null	Zeitpunkt des Festschreibens.
`paidAt`	string \| null	Zeitpunkt der vollständigen Bezahlung.

Rechnungsposition (InvoiceItem)

Eine einzelne Position einer Rechnung.

Feld	Typ	Beschreibung
`id`	string	ID der Position.
`position`	number	Reihenfolge (1-basiert).
`title`	string	Titel/Bezeichnung der Position.
`icon`	string	Optionaler Icon-Schlüssel ("" = keins).
`description`	string	Beschreibungstext (kann leer sein).
`quantity`	number	Menge.
`unit`	string	Einheit, z. B. Stk, Std, Pauschal.
`unitPriceCents`	number	Einzelpreis netto in Cent.
`vatRate`	number	Umsatzsteuersatz in Prozent.
`netAmountCents`	number	Berechneter Nettobetrag der Position in Cent.

Zahlung (Payment)

Eine erfasste Zahlung zu einer Rechnung.

Feld	Typ	Beschreibung
`id`	string	ID der Zahlung.
`amountCents`	number	Betrag in Cent (positiv = Eingang, negativ = Rückzahlung).
`method`	enum	BANK_TRANSFER, CASH, CARD, DIRECT_DEBIT, PAYPAL oder OTHER.
`paidAt`	string (ISO)	Datum des Geldflusses.
`note`	string \| null	Freie Notiz.
`reversal`	boolean	Automatische Storno-Rückbuchung (nicht manuell entfernbar).
`createdAt`	string (ISO)	Zeitpunkt der Erfassung.

Kontakt (Contact)

Ein Kunde oder Lieferant – Person oder Unternehmen.

Feld	Typ	Beschreibung
`id`	string	ID des Kontakts.
`type`	enum	PERSON oder COMPANY.
`role`	enum	CUSTOMER, SUPPLIER oder BOTH.
`firstName`	string \| null	Vorname (bei Personen).
`lastName`	string \| null	Nachname (bei Personen).
`companyName`	string \| null	Firmenname (bei Unternehmen).
`email`	string \| null	E-Mail-Adresse.
`phone`	string \| null	Telefonnummer.
`street`	string \| null	Straße und Hausnummer.
`zip`	string \| null	Postleitzahl.
`city`	string \| null	Ort.
`country`	string \| null	Land.
`vatId`	string \| null	Umsatzsteuer-Identifikationsnummer.
`notes`	string \| null	Interne Notizen.
`status`	enum	ACTIVE oder INACTIVE.
`createdAt`	string (ISO)	Zeitpunkt der Erstellung.
`updatedAt`	string (ISO)	Zeitpunkt der letzten Änderung.

Produkt (Product)

Ein Produkt oder eine Dienstleistung aus dem Katalog.

Feld	Typ	Beschreibung
`id`	string	ID des Produkts.
`type`	enum	PRODUCT oder SERVICE.
`name`	string	Bezeichnung.
`description`	string \| null	Beschreibung.
`articleNumber`	string \| null	Artikelnummer.
`unit`	string \| null	Einheit, z. B. Stk, Std.
`unitPriceCents`	number	Einzelpreis netto in Cent.
`vatRate`	number	Umsatzsteuersatz in Prozent.
`status`	enum	ACTIVE oder INACTIVE.
`createdAt`	string (ISO)	Zeitpunkt der Erstellung.
`updatedAt`	string (ISO)	Zeitpunkt der letzten Änderung.

Rechnungen

Rechnungen anlegen, bearbeiten, festschreiben, bezahlen und stornieren. Bearbeiten und Löschen sind nur für Entwürfe möglich; festgeschriebene Rechnungen werden storniert.

GET/invoices

Rechnungen auflisten

Gibt eine paginierte, filterbare Liste der Rechnungen zurück.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`page`	integer	1	Seitennummer (ab 1).
`pageSize`	integer	25	Einträge pro Seite (1–100).
`search`	string	–	Volltextsuche über Nummer und Empfänger.
`status`	enum	ALL	Filter: DRAFT, ISSUED, PAID oder CANCELLED.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/invoices \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": [
    {
      "id": "clx8f3a1b0000qz01k4p2h9dz",
      "status": "ISSUED",
      "type": "INVOICE",
      "number": "RE-2026-0042",
      "buyerName": "Muster GmbH",
      "issueDate": "2026-08-01",
      "dueDate": "2026-08-15",
      "grossTotalCents": 119000,
      "currency": "EUR",
      "paidAmountCents": 0,
      "openAmountCents": 119000,
      "createdAt": "2026-08-01T08:30:00.000Z"
    }
  ],
  "meta": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 }
}

POST/invoices

Rechnung anlegen

Legt einen Rechnungsentwurf an. Mit ?finalize=1 (oder "finalize": true im Körper) wird sie direkt festgeschrieben.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`finalize`	boolean	false	Bei 1/true wird die Rechnung sofort festgeschrieben.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`bankAccountHolder`	string	ja	Kontoinhaber (max. 120 Zeichen).
`bankName`	string	ja	Name der Bank (max. 120 Zeichen).
`iban`	string	ja	Gültig formatierte IBAN.
`bic`	string	ja	BIC/SWIFT mit 8 oder 11 Stellen.
`contactId`	string	ja	ID des Empfänger-Kontakts.
`templateKey`	string	nein	Vorlagen-Schlüssel. Ausgelassen greift die Standardvorlage.
`taxScheme`	enum	nein	STANDARD (Standard), REVERSE_CHARGE oder NOT_TAXABLE.
`issueDate`	string (yyyy-mm-dd)	ja	Rechnungsdatum.
`serviceDate`	string (yyyy-mm-dd)	nein	Leistungsdatum.
`dueDate`	string (yyyy-mm-dd)	nein	Fälligkeitsdatum.
`paymentTerms`	string	nein	Zahlungsziel (max. 200 Zeichen).
`buyerReference`	string	nein	Käuferreferenz (max. 100 Zeichen).
`footer`	string	nein	Fußzeile (max. 2000 Zeichen).
`items`	InvoiceItem[]	ja	1–50 Positionen mit title, quantity, unitPriceCents und vatRate.

Positionsfelder: title (max. 200), description (max. 1000), quantity (> 0), unit (max. 20), unitPriceCents (Ganzzahl), vatRate (0–100).
Beträge werden immer in Cent als Ganzzahl übergeben.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/invoices \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "bankAccountHolder": "Beispiel GmbH",
    "bankName": "Musterbank",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "contactId": "clx7a9c2d0000qz01m3n8k1ab",
    "issueDate": "2026-08-25",
    "dueDate": "2026-09-08",
    "items": [
      {
        "title": "Beratung",
        "description": "Konzeption und Umsetzung",
        "quantity": 8,
        "unit": "Std",
        "unitPriceCents": 12500,
        "vatRate": 19
      }
    ]
  }'

Antwort · 201 Created

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "DRAFT",
    "type": "INVOICE",
    "number": null,
    "issueDate": "2026-08-25",
    "dueDate": "2026-09-08",
    "netTotalCents": 100000,
    "taxTotalCents": 19000,
    "grossTotalCents": 119000,
    "paidAmountCents": 0,
    "openAmountCents": 119000,
    "items": [
      {
        "id": "clx0p1…",
        "position": 1,
        "title": "Beratung",
        "quantity": 8,
        "unit": "Std",
        "unitPriceCents": 12500,
        "vatRate": 19,
        "netAmountCents": 100000
      }
    ],
    "createdAt": "2026-08-25T09:00:00.000Z",
    "updatedAt": "2026-08-25T09:00:00.000Z"
  }
}

GET/invoices/:id

Rechnung abrufen

Ruft eine einzelne Rechnung mit allen Positionen und Zahlungen ab.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "ISSUED",
    "type": "INVOICE",
    "number": "RE-2026-0042",
    "buyerName": "Muster GmbH",
    "issueDate": "2026-08-01",
    "dueDate": "2026-08-15",
    "netTotalCents": 100000,
    "taxTotalCents": 19000,
    "grossTotalCents": 119000,
    "paidAmountCents": 0,
    "openAmountCents": 119000,
    "payments": [],
    "items": [ /* … */ ]
  }
}

PATCH/invoices/:id

Entwurf aktualisieren

Aktualisiert einen Rechnungsentwurf. Nur übergebene Felder werden geändert; fehlende Felder behalten ihren Wert. Nur für Entwürfe möglich.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`dueDate`	string (yyyy-mm-dd)	nein	Beispielhaft geändertes Feld.
`…`	-	nein	Alle Felder aus „Rechnung anlegen“ sind zulässig.

Beispielanfrage

Terminal

curl -X PATCH https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "dueDate": "2026-09-15",
    "paymentTerms": "Zahlbar innerhalb von 21 Tagen"
  }'

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "DRAFT",
    "dueDate": "2026-09-15",
    "paymentTerms": "Zahlbar innerhalb von 21 Tagen"
  }
}

DELETE/invoices/:id

Entwurf löschen

Löscht einen Rechnungsentwurf. Festgeschriebene Rechnungen können nicht gelöscht, sondern nur storniert werden.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Beispielanfrage

Terminal

curl -X DELETE https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{ "data": { "id": "clx8f3a1b0000qz01k4p2h9dz", "deleted": true } }

POST/invoices/:id/finalize

Rechnung festschreiben

Schreibt einen Entwurf GoBD-konform fest: vergibt lückenlos die Rechnungsnummer, friert die Absenderdaten ein und erzeugt HTML sowie XRechnung.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/finalize \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "ISSUED",
    "number": "RE-2026-0042",
    "issuedAt": "2026-08-25T09:05:00.000Z",
    "hasEInvoice": true
  }
}

POST/invoices/:id/pay

Als bezahlt markieren

Markiert eine festgeschriebene Rechnung als vollständig bezahlt.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/pay \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "PAID",
    "paidAmountCents": 119000,
    "openAmountCents": 0,
    "paidAt": "2026-08-25T09:10:00.000Z"
  }
}

POST/invoices/:id/cancel

Rechnung stornieren

Storniert eine festgeschriebene oder bezahlte Rechnung GoBD-konform. Es entsteht eine eigene Stornorechnung mit negierten Beträgen; erfasste Zahlungen werden automatisch zurückgebucht.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`reason`	string	nein	Optionaler Stornogrund.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/cancel \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Falscher Empfänger" }'

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "CANCELLED",
    "cancelledAt": "2026-08-25T09:15:00.000Z",
    "cancelledReason": "Falscher Empfänger",
    "stornoInvoiceId": "clxstorno…",
    "stornoInvoiceNumber": "RE-2026-0043"
  }
}

GET/invoices/:id/xrechnung

E-Rechnung abrufen

Liefert die strukturierte E-Rechnung (XRechnung/UBL nach EN 16931) als XML. Für festgeschriebene Rechnungen wird die gespeicherte Momentaufnahme ausgeliefert.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`download`	boolean	false	Bei 1 wird die Datei als Download (Content-Disposition) angeboten.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/xrechnung \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

XML

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ID>RE-2026-0042</cbc:ID>
  <cbc:IssueDate>2026-08-01</cbc:IssueDate>
  <!-- … EN 16931 / XRechnung … -->
</Invoice>

GET/invoices/:id/payments

Zahlungen auflisten

Listet die erfassten Zahlungen einer Rechnung samt Zahlungsstand auf.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/payments \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": [
    {
      "id": "clx9d4g6h0000qz01s2u8w0ef",
      "amountCents": 59500,
      "method": "BANK_TRANSFER",
      "paidAt": "2026-08-20",
      "note": "Teilzahlung",
      "reversal": false,
      "createdAt": "2026-08-20T10:00:00.000Z"
    }
  ],
  "meta": { "paidAmountCents": 59500, "openAmountCents": 59500, "grossTotalCents": 119000 }
}

POST/invoices/:id/payments

Zahlung erfassen

Erfasst eine (Teil-)Zahlung zu einer festgeschriebenen Rechnung.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`amountCents`	integer	ja	Betrag in Cent (> 0).
`method`	enum	nein	BANK_TRANSFER (Standard), CASH, CARD, DIRECT_DEBIT, PAYPAL, OTHER.
`paidAt`	string (yyyy-mm-dd)	ja	Datum des Geldflusses.
`note`	string	nein	Freie Notiz (max. 500 Zeichen).

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/payments \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 59500,
    "method": "BANK_TRANSFER",
    "paidAt": "2026-08-20",
    "note": "Teilzahlung"
  }'

Antwort · 201 Created

JSON

{
  "data": {
    "id": "clx9d4g6h0000qz01s2u8w0ef",
    "amountCents": 59500,
    "method": "BANK_TRANSFER",
    "paidAt": "2026-08-20",
    "note": "Teilzahlung",
    "reversal": false,
    "createdAt": "2026-08-20T10:00:00.000Z"
  }
}

DELETE/invoices/:id/payments/:paymentId

Zahlung löschen

Entfernt eine manuell erfasste Zahlung. Automatische Storno-Rückbuchungen sind geschützt und können nicht entfernt werden.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.
`paymentId`erforderlich	string	–	ID der Zahlung.

Beispielanfrage

Terminal

curl -X DELETE https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/payments/clx9d4g6h0000qz01s2u8w0ef \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{ "data": { "id": "clx9d4g6h0000qz01s2u8w0ef", "deleted": true } }

Produkte

Produkte und Dienstleistungen aus dem Katalog verwalten.

GET/products

Produkte auflisten

Gibt eine paginierte, filterbare Liste von Produkten und Dienstleistungen zurück.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`page`	integer	1	Seitennummer (ab 1).
`pageSize`	integer	25	Einträge pro Seite (1–100).
`search`	string	–	Volltextsuche über Name und Artikelnummer.
`type`	enum	ALL	Filter: PRODUCT oder SERVICE.
`status`	enum	ALL	Filter: ACTIVE oder INACTIVE.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/products \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": [
    {
      "id": "clx6b2e4f0000qz01p7r5t3cd",
      "type": "SERVICE",
      "name": "Beratung",
      "unit": "Std",
      "unitPriceCents": 12500,
      "vatRate": 19,
      "status": "ACTIVE"
    }
  ],
  "meta": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 }
}

POST/products

Produkt anlegen

Legt ein Produkt oder eine Dienstleistung an.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`type`	enum	ja	PRODUCT oder SERVICE.
`name`	string	ja	Bezeichnung (max. 160 Zeichen).
`description`	string	nein	Beschreibung (max. 1000 Zeichen).
`articleNumber`	string	nein	Artikelnummer (max. 60 Zeichen).
`unit`	string	nein	Einheit (max. 20 Zeichen).
`unitPriceCents`	integer	ja	Einzelpreis netto in Cent (≥ 0).
`vatRate`	integer	ja	Umsatzsteuersatz in Prozent (0–100).
`status`	enum	nein	ACTIVE (Standard) oder INACTIVE.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/products \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SERVICE",
    "name": "Beratung",
    "unit": "Std",
    "unitPriceCents": 12500,
    "vatRate": 19
  }'

Antwort · 201 Created

JSON

{
  "data": {
    "id": "clx6b2e4f0000qz01p7r5t3cd",
    "type": "SERVICE",
    "name": "Beratung",
    "description": null,
    "articleNumber": null,
    "unit": "Std",
    "unitPriceCents": 12500,
    "vatRate": 19,
    "status": "ACTIVE",
    "createdAt": "2026-08-25T09:00:00.000Z",
    "updatedAt": "2026-08-25T09:00:00.000Z"
  }
}

GET/products/:id

Produkt abrufen

Ruft ein einzelnes Produkt ab.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Produkts.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/products/clx6b2e4f0000qz01p7r5t3cd \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx6b2e4f0000qz01p7r5t3cd",
    "type": "SERVICE",
    "name": "Beratung",
    "unit": "Std",
    "unitPriceCents": 12500,
    "vatRate": 19,
    "status": "ACTIVE"
  }
}

PATCH/products/:id

Produkt aktualisieren

Aktualisiert ein Produkt. Nur übergebene Felder werden geändert.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Produkts.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`unitPriceCents`	integer	nein	Beispielhaft geändertes Feld.
`…`	-	nein	Alle Felder aus „Produkt anlegen“ sind zulässig.

Beispielanfrage

Terminal

curl -X PATCH https://beta.sysbalance.de/api/v1/products/clx6b2e4f0000qz01p7r5t3cd \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{ "unitPriceCents": 13500 }'

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx6b2e4f0000qz01p7r5t3cd",
    "type": "SERVICE",
    "name": "Beratung",
    "unitPriceCents": 13500,
    "vatRate": 19,
    "status": "ACTIVE"
  }
}

DELETE/products/:id

Produkt löschen

Löscht ein Produkt aus dem Katalog.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Produkts.

Beispielanfrage

Terminal

curl -X DELETE https://beta.sysbalance.de/api/v1/products/clx6b2e4f0000qz01p7r5t3cd \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{ "data": { "id": "clx6b2e4f0000qz01p7r5t3cd", "deleted": true } }

Kontakte

Kunden und Lieferanten verwalten – Personen wie Unternehmen.

GET/contacts

Kontakte auflisten

Gibt eine paginierte, filterbare Liste der Kontakte zurück.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`page`	integer	1	Seitennummer (ab 1).
`pageSize`	integer	25	Einträge pro Seite (1–100).
`search`	string	–	Volltextsuche über Name, Firma und E-Mail.
`type`	enum	ALL	Filter: PERSON oder COMPANY.
`role`	enum	ALL	Filter: CUSTOMER, SUPPLIER oder BOTH.
`status`	enum	ALL	Filter: ACTIVE oder INACTIVE.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/contacts \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": [
    {
      "id": "clx7a9c2d0000qz01m3n8k1ab",
      "type": "COMPANY",
      "role": "CUSTOMER",
      "companyName": "Muster GmbH",
      "email": "buchhaltung@muster.de",
      "city": "Berlin",
      "status": "ACTIVE"
    }
  ],
  "meta": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 }
}

POST/contacts

Kontakt anlegen

Legt einen Kontakt an. Personen benötigen einen Vor- oder Nachnamen, Unternehmen einen Firmennamen.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`type`	enum	ja	PERSON oder COMPANY.
`role`	enum	nein	CUSTOMER (Standard), SUPPLIER oder BOTH.
`firstName`	string	nein	Vorname (Person, max. 100).
`lastName`	string	nein	Nachname (Person, max. 100).
`companyName`	string	nein	Firmenname (Unternehmen, max. 160).
`email`	string	nein	Gültige E-Mail-Adresse (max. 254).
`phone`	string	nein	Telefonnummer (max. 40).
`street`	string	nein	Straße (max. 160).
`zip`	string	nein	Postleitzahl (max. 20).
`city`	string	nein	Ort (max. 100).
`country`	string	nein	Land (max. 100).
`vatId`	string	nein	USt-IdNr. (max. 30).
`notes`	string	nein	Notizen (max. 1000).
`status`	enum	nein	ACTIVE (Standard) oder INACTIVE.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/contacts \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "COMPANY",
    "role": "CUSTOMER",
    "companyName": "Muster GmbH",
    "email": "buchhaltung@muster.de",
    "city": "Berlin"
  }'

Antwort · 201 Created

JSON

{
  "data": {
    "id": "clx7a9c2d0000qz01m3n8k1ab",
    "type": "COMPANY",
    "role": "CUSTOMER",
    "companyName": "Muster GmbH",
    "email": "buchhaltung@muster.de",
    "city": "Berlin",
    "status": "ACTIVE",
    "createdAt": "2026-08-25T09:00:00.000Z",
    "updatedAt": "2026-08-25T09:00:00.000Z"
  }
}

GET/contacts/:id

Kontakt abrufen

Ruft einen einzelnen Kontakt ab.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Kontakts.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/contacts/clx7a9c2d0000qz01m3n8k1ab \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx7a9c2d0000qz01m3n8k1ab",
    "type": "COMPANY",
    "role": "CUSTOMER",
    "companyName": "Muster GmbH",
    "email": "buchhaltung@muster.de",
    "city": "Berlin",
    "status": "ACTIVE"
  }
}

PATCH/contacts/:id

Kontakt aktualisieren

Aktualisiert einen Kontakt. Nur übergebene Felder werden geändert.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Kontakts.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`city`	string	nein	Beispielhaft geändertes Feld.
`…`	-	nein	Alle Felder aus „Kontakt anlegen“ sind zulässig.

Beispielanfrage

Terminal

curl -X PATCH https://beta.sysbalance.de/api/v1/contacts/clx7a9c2d0000qz01m3n8k1ab \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{ "city": "Hamburg" }'

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx7a9c2d0000qz01m3n8k1ab",
    "type": "COMPANY",
    "companyName": "Muster GmbH",
    "city": "Hamburg",
    "status": "ACTIVE"
  }
}

DELETE/contacts/:id

Kontakt löschen

Löscht einen Kontakt.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Kontakts.

Beispielanfrage

Terminal

curl -X DELETE https://beta.sysbalance.de/api/v1/contacts/clx7a9c2d0000qz01m3n8k1ab \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{ "data": { "id": "clx7a9c2d0000qz01m3n8k1ab", "deleted": true } }

Statistiken

Aggregierte Auswertungen zu Liquidität, Prognose und Jahresergebnis (Beträge in Cent).

GET/statistics/liquiditaet

Liquiditätsübersicht

Einnahmen und Ausgaben je Monat, Summen, Gesamtsaldo und Durchschnitt.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`months`	integer	12	Betrachtetes Zeitfenster (1–36).

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/statistics/liquiditaet \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "points": [
      { "month": "2026-08", "label": "Aug 26", "incomeCents": 250000, "expenseCents": 90000, "netCents": 160000 }
    ],
    "totals": { "incomeCents": 250000, "expenseCents": 90000, "netCents": 160000 },
    "currentBalanceCents": 1200000,
    "avgMonthlyNetCents": 160000,
    "monthCount": 12
  }
}

GET/statistics/prognose

Umsatzprognose

Fortschreibung auf Basis der Vergangenheitswerte inklusive der offenen Forderungen (festgeschriebene, unbezahlte Rechnungen).

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`historyMonths`	integer	6	Zugrunde gelegte Ist-Monate (1–24).
`projectionMonths`	integer	6	Prognostizierte Monate (1–24).

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/statistics/prognose \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "history": [ { "month": "2026-08", "label": "Aug 26", "incomeCents": 250000, "expenseCents": 90000, "netCents": 160000 } ],
    "projection": [ { "month": "2026-09", "label": "Sep 26", "incomeCents": 240000, "expenseCents": 88000, "netCents": 152000, "cumulativeCents": 1352000 } ],
    "avgIncomeCents": 240000,
    "avgExpenseCents": 88000,
    "avgNetCents": 152000,
    "openReceivables": { "items": [], "totalCents": 0, "overdueCents": 0, "count": 0 },
    "startBalanceCents": 1200000
  }
}

GET/statistics/jahresbericht

Jahresbericht

Gewinn/Verlust, Monatsverlauf, Aufschlüsselung nach Kategorien und Umsatzsteuer.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`year`	integer	laufendes Jahr	Berichtsjahr (2000 bis aktuelles Jahr + 1).

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/statistics/jahresbericht \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "year": 2026,
    "availableYears": [2026, 2025],
    "incomeCents": 2500000,
    "expenseCents": 900000,
    "resultCents": 1600000,
    "monthly": [ { "month": "2026-01", "label": "Jan 26", "incomeCents": 200000, "expenseCents": 70000, "netCents": 130000 } ],
    "expenseByCategory": [ { "category": "OFFICE", "grossCents": 300000 } ],
    "incomeByCategory": [ { "category": "SALES", "grossCents": 2500000 } ],
    "vat": { "outputCents": 475000, "inputCents": 171000, "payloadCents": 304000 },
    "belegCount": 128
  }
}

Beispiel-Workflow

Ein typischer Ablauf von der Anlage bis zum Zahlungseingang - Kontakt anlegen, Rechnung als Entwurf erstellen, festschreiben und die Zahlung erfassen:

Terminal

# 1) Kontakt anlegen
curl -X POST https://beta.sysbalance.de/api/v1/contacts \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{ "type": "COMPANY", "companyName": "Muster GmbH", "email": "buchhaltung@muster.de" }'

# 2) Rechnung als Entwurf anlegen (contactId aus Schritt 1)
curl -X POST https://beta.sysbalance.de/api/v1/invoices \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "bankAccountHolder": "Beispiel GmbH",
    "bankName": "Musterbank",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "contactId": "clx7a9c2d0000qz01m3n8k1ab",
    "issueDate": "2026-08-25",
    "items": [{ "title": "Beratung", "quantity": 8, "unit": "Std", "unitPriceCents": 12500, "vatRate": 19 }]
  }'

# 3) Rechnung festschreiben (vergibt die endgültige Nummer)
curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/finalize \
  -H "Authorization: Bearer sb_live_dein-schluessel"

# 4) Zahlungseingang erfassen
curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/payments \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{ "amountCents": 119000, "method": "BANK_TRANSFER", "paidAt": "2026-09-01" }'

Verwendete Endpunkte:POST /invoicesPOST /invoices/:id/finalize

APIReferenz

API-Referenz

Integrieren Sie Kontakte, Produkte, Rechnungen und Zahlungen direkt in Ihre eigenen Systeme. Hier finden Sie alle Endpunkte, Datenmodelle und ausführbare Beispiele.

REST APIVersion 1JSONBearer Token

Auf dieser Seite+

Schnellstart

Die Sysbalance REST-API stellt Rechnungen, Produkte, Kontakte und Auswertungen als JSON bereit. Jede Anfrage ist strikt auf das Unternehmen des verwendeten API-Schlüssels begrenzt.

Basis-URL

https://beta.sysbalance.de/api/v1

Authentifizierung

Bearer Token

Erstellen Sie Ihren API-Schlüssel im Dashboard unter Schlüssel. Übergeben Sie ihn anschließend bei jeder Anfrage im Header Authorization: Bearer <dein-schlüssel>.

Terminal

curl https://beta.sysbalance.de/api/v1/invoices \
  -H "Authorization: Bearer sb_live_dein-schluessel"

API-Schlüssel beginnen mit sb_live_ und werden nur einmal vollständig angezeigt. Bewahren Sie sie ausschließlich serverseitig auf.

Authentifizierte Anfragen erscheinen unter API-Aktivität. Ungültige, widerrufene oder abgelaufene Schlüssel liefern 401 unauthorized.

Antwortformat

Erfolgreiche Antworten liefern Nutzdaten im Feld data. Listen enthalten zusätzlich ein meta-Objekt mit den Paginierungsangaben.

JSON

{
  "data": [
    { "id": "clx…", "type": "COMPANY", "companyName": "Muster GmbH", "email": "buchhaltung@muster.de" }
  ],
  "meta": { "page": 1, "pageSize": 25, "pageCount": 4, "total": 92 }
}

Der Content-Type ist application/json. Geldbeträge werden als Ganzzahl in Cent übertragen, Datumswerte im ISO-Format.

Paginierung & Filter

Listenendpunkte akzeptieren die Query-Parameter page (ab 1) und pageSize (Standard 25, maximal 100). Die Angaben zur Gesamtzahl und Seitenanzahl stehen im meta-Objekt der Antwort.

Beispiel

https://beta.sysbalance.de/api/v1/contacts?page=2&pageSize=50&search=muster

Je nach Ressource stehen weitere Filter zur Verfügung, etwa search, status, type oder role. Die genauen Parameter finden Sie beim jeweiligen Endpunkt.

Fehler

Fehler verwenden ein einheitliches Format mit maschinenlesbarem code, einer message und - bei Validierungsfehlern - feldweisen details.

JSON

{
  "error": {
    "code": "validation_error",
    "message": "Bitte korrigiere die markierten Felder.",
    "details": {
      "fields": { "companyName": ["Bitte gib einen Firmennamen ein."] },
      "form": []
    }
  }
}

Code	HTTP	Bedeutung
`unauthorized`	401	Schlüssel fehlt, ist ungültig, widerrufen oder abgelaufen.
`forbidden`	403	Zugriff auf die angeforderte Ressource nicht erlaubt.
`not_found`	404	Die Ressource existiert nicht.
`validation_error`	400	Übergebene Felder sind ungültig (Details unter details.fields).
`invalid_body`	400	Der Anfragekörper ist kein gültiges JSON.
`method_not_allowed`	405	Die HTTP-Methode wird für diesen Pfad nicht unterstützt.
`conflict`	409	Konflikt mit dem aktuellen Zustand der Ressource.
`unprocessable`	422	Anfrage verstanden, im aktuellen Zustand aber nicht ausführbar.
`rate_limited`	429	Zu viele Anfragen in kurzer Zeit.
`internal_error`	500	Unerwarteter Fehler auf dem Server.

Datenmodelle

Diese Modelle beschreiben die Felder, die die API zurückgibt. Anfragekörper erwarten je Endpunkt nur die dort genannten Felder.

Rechnung (Invoice)

Vollständige Rechnung mit Positionen, Beträgen (netto/Steuer/brutto in Cent) und Zahlungsstand. Festgeschriebene Rechnungen sind unveränderlich.

Feld	Typ	Beschreibung
`id`	string	Eindeutige ID der Rechnung.
`status`	enum	DRAFT, ISSUED, PAID oder CANCELLED.
`type`	enum	INVOICE (regulär) oder STORNO (Stornorechnung).
`number`	string \| null	Rechnungsnummer (erst nach dem Festschreiben vergeben).
`sequence`	number \| null	Lückenlose laufende Nummer innerhalb des Nummernkreises.
`issueDate`	string (ISO)	Rechnungsdatum.
`serviceDate`	string \| null	Leistungs-/Lieferdatum.
`dueDate`	string \| null	Fälligkeitsdatum.
`currency`	string	ISO-4217-Währungscode, z. B. EUR.
`smallBusiness`	boolean	Kleinunternehmerregelung (§19 UStG) angewandt.
`taxScheme`	enum	STANDARD, REVERSE_CHARGE oder NOT_TAXABLE.
`netTotalCents`	number	Nettosumme in Cent.
`taxTotalCents`	number	Umsatzsteuersumme in Cent.
`grossTotalCents`	number	Bruttosumme in Cent.
`paymentTerms`	string \| null	Zahlungsziel als Freitext.
`buyerReference`	string \| null	Käuferreferenz (Leitweg-ID / B2G).
`footer`	string \| null	Fußzeilentext des Dokuments.
`sellerBankHolder`	string \| null	Kontoinhaber der Absender-Momentaufnahme.
`sellerBankName`	string \| null	Bank der Absender-Momentaufnahme.
`sellerIban`	string \| null	IBAN der Absender-Momentaufnahme.
`sellerBic`	string \| null	BIC der Absender-Momentaufnahme.
`templateKey`	string	Verwendeter Vorlagen-Schlüssel.
`contactId`	string \| null	ID des Empfänger-Kontakts.
`buyerName`	string \| null	Name des Empfängers (Momentaufnahme).
`buyerVatId`	string \| null	USt-IdNr. des Empfängers (Momentaufnahme).
`hasEInvoice`	boolean	Eine XRechnung ist gespeichert.
`cancelledAt`	string \| null	Zeitpunkt der Stornierung.
`cancelledReason`	string \| null	Grund der Stornierung.
`stornoOfId`	string \| null	Auf Stornorechnungen: ID der aufgehobenen Rechnung.
`stornoInvoiceId`	string \| null	Auf stornierten Rechnungen: ID der Stornorechnung.
`paidAmountCents`	number	Summe aller erfassten Zahlungen in Cent.
`openAmountCents`	number	Noch offener Betrag in Cent (Brutto − Zahlungen).
`payments`	Payment[]	Erfasste Zahlungen, neueste zuerst.
`items`	InvoiceItem[]	Rechnungspositionen.
`createdAt`	string (ISO)	Zeitpunkt der Erstellung.
`updatedAt`	string (ISO)	Zeitpunkt der letzten Änderung.
`issuedAt`	string \| null	Zeitpunkt des Festschreibens.
`paidAt`	string \| null	Zeitpunkt der vollständigen Bezahlung.

Rechnungsposition (InvoiceItem)

Eine einzelne Position einer Rechnung.

Feld	Typ	Beschreibung
`id`	string	ID der Position.
`position`	number	Reihenfolge (1-basiert).
`title`	string	Titel/Bezeichnung der Position.
`icon`	string	Optionaler Icon-Schlüssel ("" = keins).
`description`	string	Beschreibungstext (kann leer sein).
`quantity`	number	Menge.
`unit`	string	Einheit, z. B. Stk, Std, Pauschal.
`unitPriceCents`	number	Einzelpreis netto in Cent.
`vatRate`	number	Umsatzsteuersatz in Prozent.
`netAmountCents`	number	Berechneter Nettobetrag der Position in Cent.

Zahlung (Payment)

Eine erfasste Zahlung zu einer Rechnung.

Feld	Typ	Beschreibung
`id`	string	ID der Zahlung.
`amountCents`	number	Betrag in Cent (positiv = Eingang, negativ = Rückzahlung).
`method`	enum	BANK_TRANSFER, CASH, CARD, DIRECT_DEBIT, PAYPAL oder OTHER.
`paidAt`	string (ISO)	Datum des Geldflusses.
`note`	string \| null	Freie Notiz.
`reversal`	boolean	Automatische Storno-Rückbuchung (nicht manuell entfernbar).
`createdAt`	string (ISO)	Zeitpunkt der Erfassung.

Kontakt (Contact)

Ein Kunde oder Lieferant – Person oder Unternehmen.

Feld	Typ	Beschreibung
`id`	string	ID des Kontakts.
`type`	enum	PERSON oder COMPANY.
`role`	enum	CUSTOMER, SUPPLIER oder BOTH.
`firstName`	string \| null	Vorname (bei Personen).
`lastName`	string \| null	Nachname (bei Personen).
`companyName`	string \| null	Firmenname (bei Unternehmen).
`email`	string \| null	E-Mail-Adresse.
`phone`	string \| null	Telefonnummer.
`street`	string \| null	Straße und Hausnummer.
`zip`	string \| null	Postleitzahl.
`city`	string \| null	Ort.
`country`	string \| null	Land.
`vatId`	string \| null	Umsatzsteuer-Identifikationsnummer.
`notes`	string \| null	Interne Notizen.
`status`	enum	ACTIVE oder INACTIVE.
`createdAt`	string (ISO)	Zeitpunkt der Erstellung.
`updatedAt`	string (ISO)	Zeitpunkt der letzten Änderung.

Produkt (Product)

Ein Produkt oder eine Dienstleistung aus dem Katalog.

Feld	Typ	Beschreibung
`id`	string	ID des Produkts.
`type`	enum	PRODUCT oder SERVICE.
`name`	string	Bezeichnung.
`description`	string \| null	Beschreibung.
`articleNumber`	string \| null	Artikelnummer.
`unit`	string \| null	Einheit, z. B. Stk, Std.
`unitPriceCents`	number	Einzelpreis netto in Cent.
`vatRate`	number	Umsatzsteuersatz in Prozent.
`status`	enum	ACTIVE oder INACTIVE.
`createdAt`	string (ISO)	Zeitpunkt der Erstellung.
`updatedAt`	string (ISO)	Zeitpunkt der letzten Änderung.

Rechnungen

Rechnungen anlegen, bearbeiten, festschreiben, bezahlen und stornieren. Bearbeiten und Löschen sind nur für Entwürfe möglich; festgeschriebene Rechnungen werden storniert.

GET/invoices

Rechnungen auflisten

Gibt eine paginierte, filterbare Liste der Rechnungen zurück.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`page`	integer	1	Seitennummer (ab 1).
`pageSize`	integer	25	Einträge pro Seite (1–100).
`search`	string	–	Volltextsuche über Nummer und Empfänger.
`status`	enum	ALL	Filter: DRAFT, ISSUED, PAID oder CANCELLED.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/invoices \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": [
    {
      "id": "clx8f3a1b0000qz01k4p2h9dz",
      "status": "ISSUED",
      "type": "INVOICE",
      "number": "RE-2026-0042",
      "buyerName": "Muster GmbH",
      "issueDate": "2026-08-01",
      "dueDate": "2026-08-15",
      "grossTotalCents": 119000,
      "currency": "EUR",
      "paidAmountCents": 0,
      "openAmountCents": 119000,
      "createdAt": "2026-08-01T08:30:00.000Z"
    }
  ],
  "meta": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 }
}

POST/invoices

Rechnung anlegen

Legt einen Rechnungsentwurf an. Mit ?finalize=1 (oder "finalize": true im Körper) wird sie direkt festgeschrieben.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`finalize`	boolean	false	Bei 1/true wird die Rechnung sofort festgeschrieben.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`bankAccountHolder`	string	ja	Kontoinhaber (max. 120 Zeichen).
`bankName`	string	ja	Name der Bank (max. 120 Zeichen).
`iban`	string	ja	Gültig formatierte IBAN.
`bic`	string	ja	BIC/SWIFT mit 8 oder 11 Stellen.
`contactId`	string	ja	ID des Empfänger-Kontakts.
`templateKey`	string	nein	Vorlagen-Schlüssel. Ausgelassen greift die Standardvorlage.
`taxScheme`	enum	nein	STANDARD (Standard), REVERSE_CHARGE oder NOT_TAXABLE.
`issueDate`	string (yyyy-mm-dd)	ja	Rechnungsdatum.
`serviceDate`	string (yyyy-mm-dd)	nein	Leistungsdatum.
`dueDate`	string (yyyy-mm-dd)	nein	Fälligkeitsdatum.
`paymentTerms`	string	nein	Zahlungsziel (max. 200 Zeichen).
`buyerReference`	string	nein	Käuferreferenz (max. 100 Zeichen).
`footer`	string	nein	Fußzeile (max. 2000 Zeichen).
`items`	InvoiceItem[]	ja	1–50 Positionen mit title, quantity, unitPriceCents und vatRate.

Positionsfelder: title (max. 200), description (max. 1000), quantity (> 0), unit (max. 20), unitPriceCents (Ganzzahl), vatRate (0–100).
Beträge werden immer in Cent als Ganzzahl übergeben.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/invoices \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "bankAccountHolder": "Beispiel GmbH",
    "bankName": "Musterbank",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "contactId": "clx7a9c2d0000qz01m3n8k1ab",
    "issueDate": "2026-08-25",
    "dueDate": "2026-09-08",
    "items": [
      {
        "title": "Beratung",
        "description": "Konzeption und Umsetzung",
        "quantity": 8,
        "unit": "Std",
        "unitPriceCents": 12500,
        "vatRate": 19
      }
    ]
  }'

Antwort · 201 Created

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "DRAFT",
    "type": "INVOICE",
    "number": null,
    "issueDate": "2026-08-25",
    "dueDate": "2026-09-08",
    "netTotalCents": 100000,
    "taxTotalCents": 19000,
    "grossTotalCents": 119000,
    "paidAmountCents": 0,
    "openAmountCents": 119000,
    "items": [
      {
        "id": "clx0p1…",
        "position": 1,
        "title": "Beratung",
        "quantity": 8,
        "unit": "Std",
        "unitPriceCents": 12500,
        "vatRate": 19,
        "netAmountCents": 100000
      }
    ],
    "createdAt": "2026-08-25T09:00:00.000Z",
    "updatedAt": "2026-08-25T09:00:00.000Z"
  }
}

GET/invoices/:id

Rechnung abrufen

Ruft eine einzelne Rechnung mit allen Positionen und Zahlungen ab.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "ISSUED",
    "type": "INVOICE",
    "number": "RE-2026-0042",
    "buyerName": "Muster GmbH",
    "issueDate": "2026-08-01",
    "dueDate": "2026-08-15",
    "netTotalCents": 100000,
    "taxTotalCents": 19000,
    "grossTotalCents": 119000,
    "paidAmountCents": 0,
    "openAmountCents": 119000,
    "payments": [],
    "items": [ /* … */ ]
  }
}

PATCH/invoices/:id

Entwurf aktualisieren

Aktualisiert einen Rechnungsentwurf. Nur übergebene Felder werden geändert; fehlende Felder behalten ihren Wert. Nur für Entwürfe möglich.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`dueDate`	string (yyyy-mm-dd)	nein	Beispielhaft geändertes Feld.
`…`	-	nein	Alle Felder aus „Rechnung anlegen“ sind zulässig.

Beispielanfrage

Terminal

curl -X PATCH https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "dueDate": "2026-09-15",
    "paymentTerms": "Zahlbar innerhalb von 21 Tagen"
  }'

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "DRAFT",
    "dueDate": "2026-09-15",
    "paymentTerms": "Zahlbar innerhalb von 21 Tagen"
  }
}

DELETE/invoices/:id

Entwurf löschen

Löscht einen Rechnungsentwurf. Festgeschriebene Rechnungen können nicht gelöscht, sondern nur storniert werden.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Beispielanfrage

Terminal

curl -X DELETE https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{ "data": { "id": "clx8f3a1b0000qz01k4p2h9dz", "deleted": true } }

POST/invoices/:id/finalize

Rechnung festschreiben

Schreibt einen Entwurf GoBD-konform fest: vergibt lückenlos die Rechnungsnummer, friert die Absenderdaten ein und erzeugt HTML sowie XRechnung.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/finalize \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "ISSUED",
    "number": "RE-2026-0042",
    "issuedAt": "2026-08-25T09:05:00.000Z",
    "hasEInvoice": true
  }
}

POST/invoices/:id/pay

Als bezahlt markieren

Markiert eine festgeschriebene Rechnung als vollständig bezahlt.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/pay \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "PAID",
    "paidAmountCents": 119000,
    "openAmountCents": 0,
    "paidAt": "2026-08-25T09:10:00.000Z"
  }
}

POST/invoices/:id/cancel

Rechnung stornieren

Storniert eine festgeschriebene oder bezahlte Rechnung GoBD-konform. Es entsteht eine eigene Stornorechnung mit negierten Beträgen; erfasste Zahlungen werden automatisch zurückgebucht.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`reason`	string	nein	Optionaler Stornogrund.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/cancel \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Falscher Empfänger" }'

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx8f3a1b0000qz01k4p2h9dz",
    "status": "CANCELLED",
    "cancelledAt": "2026-08-25T09:15:00.000Z",
    "cancelledReason": "Falscher Empfänger",
    "stornoInvoiceId": "clxstorno…",
    "stornoInvoiceNumber": "RE-2026-0043"
  }
}

GET/invoices/:id/xrechnung

E-Rechnung abrufen

Liefert die strukturierte E-Rechnung (XRechnung/UBL nach EN 16931) als XML. Für festgeschriebene Rechnungen wird die gespeicherte Momentaufnahme ausgeliefert.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`download`	boolean	false	Bei 1 wird die Datei als Download (Content-Disposition) angeboten.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/xrechnung \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

XML

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ID>RE-2026-0042</cbc:ID>
  <cbc:IssueDate>2026-08-01</cbc:IssueDate>
  <!-- … EN 16931 / XRechnung … -->
</Invoice>

GET/invoices/:id/payments

Zahlungen auflisten

Listet die erfassten Zahlungen einer Rechnung samt Zahlungsstand auf.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/payments \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": [
    {
      "id": "clx9d4g6h0000qz01s2u8w0ef",
      "amountCents": 59500,
      "method": "BANK_TRANSFER",
      "paidAt": "2026-08-20",
      "note": "Teilzahlung",
      "reversal": false,
      "createdAt": "2026-08-20T10:00:00.000Z"
    }
  ],
  "meta": { "paidAmountCents": 59500, "openAmountCents": 59500, "grossTotalCents": 119000 }
}

POST/invoices/:id/payments

Zahlung erfassen

Erfasst eine (Teil-)Zahlung zu einer festgeschriebenen Rechnung.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`amountCents`	integer	ja	Betrag in Cent (> 0).
`method`	enum	nein	BANK_TRANSFER (Standard), CASH, CARD, DIRECT_DEBIT, PAYPAL, OTHER.
`paidAt`	string (yyyy-mm-dd)	ja	Datum des Geldflusses.
`note`	string	nein	Freie Notiz (max. 500 Zeichen).

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/payments \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 59500,
    "method": "BANK_TRANSFER",
    "paidAt": "2026-08-20",
    "note": "Teilzahlung"
  }'

Antwort · 201 Created

JSON

{
  "data": {
    "id": "clx9d4g6h0000qz01s2u8w0ef",
    "amountCents": 59500,
    "method": "BANK_TRANSFER",
    "paidAt": "2026-08-20",
    "note": "Teilzahlung",
    "reversal": false,
    "createdAt": "2026-08-20T10:00:00.000Z"
  }
}

DELETE/invoices/:id/payments/:paymentId

Zahlung löschen

Entfernt eine manuell erfasste Zahlung. Automatische Storno-Rückbuchungen sind geschützt und können nicht entfernt werden.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID der Rechnung.
`paymentId`erforderlich	string	–	ID der Zahlung.

Beispielanfrage

Terminal

curl -X DELETE https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/payments/clx9d4g6h0000qz01s2u8w0ef \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{ "data": { "id": "clx9d4g6h0000qz01s2u8w0ef", "deleted": true } }

Produkte

Produkte und Dienstleistungen aus dem Katalog verwalten.

GET/products

Produkte auflisten

Gibt eine paginierte, filterbare Liste von Produkten und Dienstleistungen zurück.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`page`	integer	1	Seitennummer (ab 1).
`pageSize`	integer	25	Einträge pro Seite (1–100).
`search`	string	–	Volltextsuche über Name und Artikelnummer.
`type`	enum	ALL	Filter: PRODUCT oder SERVICE.
`status`	enum	ALL	Filter: ACTIVE oder INACTIVE.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/products \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": [
    {
      "id": "clx6b2e4f0000qz01p7r5t3cd",
      "type": "SERVICE",
      "name": "Beratung",
      "unit": "Std",
      "unitPriceCents": 12500,
      "vatRate": 19,
      "status": "ACTIVE"
    }
  ],
  "meta": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 }
}

POST/products

Produkt anlegen

Legt ein Produkt oder eine Dienstleistung an.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`type`	enum	ja	PRODUCT oder SERVICE.
`name`	string	ja	Bezeichnung (max. 160 Zeichen).
`description`	string	nein	Beschreibung (max. 1000 Zeichen).
`articleNumber`	string	nein	Artikelnummer (max. 60 Zeichen).
`unit`	string	nein	Einheit (max. 20 Zeichen).
`unitPriceCents`	integer	ja	Einzelpreis netto in Cent (≥ 0).
`vatRate`	integer	ja	Umsatzsteuersatz in Prozent (0–100).
`status`	enum	nein	ACTIVE (Standard) oder INACTIVE.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/products \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SERVICE",
    "name": "Beratung",
    "unit": "Std",
    "unitPriceCents": 12500,
    "vatRate": 19
  }'

Antwort · 201 Created

JSON

{
  "data": {
    "id": "clx6b2e4f0000qz01p7r5t3cd",
    "type": "SERVICE",
    "name": "Beratung",
    "description": null,
    "articleNumber": null,
    "unit": "Std",
    "unitPriceCents": 12500,
    "vatRate": 19,
    "status": "ACTIVE",
    "createdAt": "2026-08-25T09:00:00.000Z",
    "updatedAt": "2026-08-25T09:00:00.000Z"
  }
}

GET/products/:id

Produkt abrufen

Ruft ein einzelnes Produkt ab.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Produkts.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/products/clx6b2e4f0000qz01p7r5t3cd \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx6b2e4f0000qz01p7r5t3cd",
    "type": "SERVICE",
    "name": "Beratung",
    "unit": "Std",
    "unitPriceCents": 12500,
    "vatRate": 19,
    "status": "ACTIVE"
  }
}

PATCH/products/:id

Produkt aktualisieren

Aktualisiert ein Produkt. Nur übergebene Felder werden geändert.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Produkts.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`unitPriceCents`	integer	nein	Beispielhaft geändertes Feld.
`…`	-	nein	Alle Felder aus „Produkt anlegen“ sind zulässig.

Beispielanfrage

Terminal

curl -X PATCH https://beta.sysbalance.de/api/v1/products/clx6b2e4f0000qz01p7r5t3cd \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{ "unitPriceCents": 13500 }'

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx6b2e4f0000qz01p7r5t3cd",
    "type": "SERVICE",
    "name": "Beratung",
    "unitPriceCents": 13500,
    "vatRate": 19,
    "status": "ACTIVE"
  }
}

DELETE/products/:id

Produkt löschen

Löscht ein Produkt aus dem Katalog.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Produkts.

Beispielanfrage

Terminal

curl -X DELETE https://beta.sysbalance.de/api/v1/products/clx6b2e4f0000qz01p7r5t3cd \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{ "data": { "id": "clx6b2e4f0000qz01p7r5t3cd", "deleted": true } }

Kontakte

Kunden und Lieferanten verwalten – Personen wie Unternehmen.

GET/contacts

Kontakte auflisten

Gibt eine paginierte, filterbare Liste der Kontakte zurück.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`page`	integer	1	Seitennummer (ab 1).
`pageSize`	integer	25	Einträge pro Seite (1–100).
`search`	string	–	Volltextsuche über Name, Firma und E-Mail.
`type`	enum	ALL	Filter: PERSON oder COMPANY.
`role`	enum	ALL	Filter: CUSTOMER, SUPPLIER oder BOTH.
`status`	enum	ALL	Filter: ACTIVE oder INACTIVE.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/contacts \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": [
    {
      "id": "clx7a9c2d0000qz01m3n8k1ab",
      "type": "COMPANY",
      "role": "CUSTOMER",
      "companyName": "Muster GmbH",
      "email": "buchhaltung@muster.de",
      "city": "Berlin",
      "status": "ACTIVE"
    }
  ],
  "meta": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 }
}

POST/contacts

Kontakt anlegen

Legt einen Kontakt an. Personen benötigen einen Vor- oder Nachnamen, Unternehmen einen Firmennamen.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`type`	enum	ja	PERSON oder COMPANY.
`role`	enum	nein	CUSTOMER (Standard), SUPPLIER oder BOTH.
`firstName`	string	nein	Vorname (Person, max. 100).
`lastName`	string	nein	Nachname (Person, max. 100).
`companyName`	string	nein	Firmenname (Unternehmen, max. 160).
`email`	string	nein	Gültige E-Mail-Adresse (max. 254).
`phone`	string	nein	Telefonnummer (max. 40).
`street`	string	nein	Straße (max. 160).
`zip`	string	nein	Postleitzahl (max. 20).
`city`	string	nein	Ort (max. 100).
`country`	string	nein	Land (max. 100).
`vatId`	string	nein	USt-IdNr. (max. 30).
`notes`	string	nein	Notizen (max. 1000).
`status`	enum	nein	ACTIVE (Standard) oder INACTIVE.

Beispielanfrage

Terminal

curl -X POST https://beta.sysbalance.de/api/v1/contacts \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "COMPANY",
    "role": "CUSTOMER",
    "companyName": "Muster GmbH",
    "email": "buchhaltung@muster.de",
    "city": "Berlin"
  }'

Antwort · 201 Created

JSON

{
  "data": {
    "id": "clx7a9c2d0000qz01m3n8k1ab",
    "type": "COMPANY",
    "role": "CUSTOMER",
    "companyName": "Muster GmbH",
    "email": "buchhaltung@muster.de",
    "city": "Berlin",
    "status": "ACTIVE",
    "createdAt": "2026-08-25T09:00:00.000Z",
    "updatedAt": "2026-08-25T09:00:00.000Z"
  }
}

GET/contacts/:id

Kontakt abrufen

Ruft einen einzelnen Kontakt ab.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Kontakts.

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/contacts/clx7a9c2d0000qz01m3n8k1ab \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx7a9c2d0000qz01m3n8k1ab",
    "type": "COMPANY",
    "role": "CUSTOMER",
    "companyName": "Muster GmbH",
    "email": "buchhaltung@muster.de",
    "city": "Berlin",
    "status": "ACTIVE"
  }
}

PATCH/contacts/:id

Kontakt aktualisieren

Aktualisiert einen Kontakt. Nur übergebene Felder werden geändert.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Kontakts.

Anfragekörper

Feld	Typ	Pflicht	Beschreibung
`city`	string	nein	Beispielhaft geändertes Feld.
`…`	-	nein	Alle Felder aus „Kontakt anlegen“ sind zulässig.

Beispielanfrage

Terminal

curl -X PATCH https://beta.sysbalance.de/api/v1/contacts/clx7a9c2d0000qz01m3n8k1ab \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{ "city": "Hamburg" }'

Antwort · 200 OK

JSON

{
  "data": {
    "id": "clx7a9c2d0000qz01m3n8k1ab",
    "type": "COMPANY",
    "companyName": "Muster GmbH",
    "city": "Hamburg",
    "status": "ACTIVE"
  }
}

DELETE/contacts/:id

Kontakt löschen

Löscht einen Kontakt.

Pfadparameter

Parameter	Typ	Standard	Beschreibung
`id`erforderlich	string	–	ID des Kontakts.

Beispielanfrage

Terminal

curl -X DELETE https://beta.sysbalance.de/api/v1/contacts/clx7a9c2d0000qz01m3n8k1ab \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{ "data": { "id": "clx7a9c2d0000qz01m3n8k1ab", "deleted": true } }

Statistiken

Aggregierte Auswertungen zu Liquidität, Prognose und Jahresergebnis (Beträge in Cent).

GET/statistics/liquiditaet

Liquiditätsübersicht

Einnahmen und Ausgaben je Monat, Summen, Gesamtsaldo und Durchschnitt.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`months`	integer	12	Betrachtetes Zeitfenster (1–36).

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/statistics/liquiditaet \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "points": [
      { "month": "2026-08", "label": "Aug 26", "incomeCents": 250000, "expenseCents": 90000, "netCents": 160000 }
    ],
    "totals": { "incomeCents": 250000, "expenseCents": 90000, "netCents": 160000 },
    "currentBalanceCents": 1200000,
    "avgMonthlyNetCents": 160000,
    "monthCount": 12
  }
}

GET/statistics/prognose

Umsatzprognose

Fortschreibung auf Basis der Vergangenheitswerte inklusive der offenen Forderungen (festgeschriebene, unbezahlte Rechnungen).

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`historyMonths`	integer	6	Zugrunde gelegte Ist-Monate (1–24).
`projectionMonths`	integer	6	Prognostizierte Monate (1–24).

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/statistics/prognose \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "history": [ { "month": "2026-08", "label": "Aug 26", "incomeCents": 250000, "expenseCents": 90000, "netCents": 160000 } ],
    "projection": [ { "month": "2026-09", "label": "Sep 26", "incomeCents": 240000, "expenseCents": 88000, "netCents": 152000, "cumulativeCents": 1352000 } ],
    "avgIncomeCents": 240000,
    "avgExpenseCents": 88000,
    "avgNetCents": 152000,
    "openReceivables": { "items": [], "totalCents": 0, "overdueCents": 0, "count": 0 },
    "startBalanceCents": 1200000
  }
}

GET/statistics/jahresbericht

Jahresbericht

Gewinn/Verlust, Monatsverlauf, Aufschlüsselung nach Kategorien und Umsatzsteuer.

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`year`	integer	laufendes Jahr	Berichtsjahr (2000 bis aktuelles Jahr + 1).

Beispielanfrage

Terminal

curl https://beta.sysbalance.de/api/v1/statistics/jahresbericht \
  -H "Authorization: Bearer sb_live_dein-schluessel"

Antwort · 200 OK

JSON

{
  "data": {
    "year": 2026,
    "availableYears": [2026, 2025],
    "incomeCents": 2500000,
    "expenseCents": 900000,
    "resultCents": 1600000,
    "monthly": [ { "month": "2026-01", "label": "Jan 26", "incomeCents": 200000, "expenseCents": 70000, "netCents": 130000 } ],
    "expenseByCategory": [ { "category": "OFFICE", "grossCents": 300000 } ],
    "incomeByCategory": [ { "category": "SALES", "grossCents": 2500000 } ],
    "vat": { "outputCents": 475000, "inputCents": 171000, "payloadCents": 304000 },
    "belegCount": 128
  }
}

Beispiel-Workflow

Ein typischer Ablauf von der Anlage bis zum Zahlungseingang - Kontakt anlegen, Rechnung als Entwurf erstellen, festschreiben und die Zahlung erfassen:

Terminal

# 1) Kontakt anlegen
curl -X POST https://beta.sysbalance.de/api/v1/contacts \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{ "type": "COMPANY", "companyName": "Muster GmbH", "email": "buchhaltung@muster.de" }'

# 2) Rechnung als Entwurf anlegen (contactId aus Schritt 1)
curl -X POST https://beta.sysbalance.de/api/v1/invoices \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "bankAccountHolder": "Beispiel GmbH",
    "bankName": "Musterbank",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "contactId": "clx7a9c2d0000qz01m3n8k1ab",
    "issueDate": "2026-08-25",
    "items": [{ "title": "Beratung", "quantity": 8, "unit": "Std", "unitPriceCents": 12500, "vatRate": 19 }]
  }'

# 3) Rechnung festschreiben (vergibt die endgültige Nummer)
curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/finalize \
  -H "Authorization: Bearer sb_live_dein-schluessel"

# 4) Zahlungseingang erfassen
curl -X POST https://beta.sysbalance.de/api/v1/invoices/clx8f3a1b0000qz01k4p2h9dz/payments \
  -H "Authorization: Bearer sb_live_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{ "amountCents": 119000, "method": "BANK_TRANSFER", "paidAt": "2026-09-01" }'

Verwendete Endpunkte:POST /invoicesPOST /invoices/:id/finalize