Zum Inhalt springen
Dokumentation
Handbuch API Demo
Deutsch
App öffnen

Das Hauptbuch lesen

Anwendungsfall Schritt für Schritt, um über die NovaFisko-API die Saldenliste und anschließend das Hauptbuch eines Kontos mit laufendem Saldo zu lesen.

Aktualisiert am 05.10.2026 Diese Seite bearbeiten

Dieser Leitfaden ruft die Saldenliste eines Geschäftsjahres ab, anschließend die einzelnen Bewegungen eines Kontos mit dessen laufendem Saldo. Er richtet sich an Werkzeuge für Reporting, Konsolidierung und Dashboards.

Voraussetzungen: ein Token mit der Berechtigung read und das public_token des Mandats.

Schritt 1: das Geschäftsjahr finden

Auswertungen werden immer für ein Geschäftsjahr berechnet, das über seine id bezeichnet wird.

curl https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/fiscal-years \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

[
  {
    "id": 6,
    "code": "2025",
    "starts_on": "2025-01-01T00:00:00.000000Z",
    "ends_on": "2025-12-31T00:00:00.000000Z",
    "is_closed": true,
    "closed_at": "2026-03-14T10:22:05.000000Z",
    "periods": []
  },
  {
    "id": 7,
    "code": "2026",
    "starts_on": "2026-01-01T00:00:00.000000Z",
    "ends_on": "2026-12-31T00:00:00.000000Z",
    "is_closed": false,
    "closed_at": null,
    "periods": [
      {"id": 85, "number": 1, "label": "01/2026", "starts_on": "2026-01-01T00:00:00.000000Z", "ends_on": "2026-01-31T00:00:00.000000Z", "is_locked": true}
    ]
  }
]

Schritt 2: die Saldenliste lesen

Die Saldenliste liefert für jedes bebuchte Konto die Soll- und Habensummen sowie den Saldo. Sie ist der natürliche Einstiegspunkt: Sie zeigt, welche Konten eine Detailbetrachtung verdienen.

curl "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/fiscal-years/7/trial-balance?from=2026-01-01&to=2026-09-30" \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"
Parameter Standard Beschreibung
from Beginn des Geschäftsjahres Anfangsdatum, einschließlich
to Ende des Geschäftsjahres Enddatum, einschließlich
include_empty false true, um Konten einzubeziehen, deren Summen null sind 
{
  "fiscal_year": "2026",
  "from": "2026-01-01",
  "to": "2026-09-30",
  "lines": [
    {
      "account_id": 90,
      "number": "440000",
      "label": "Fournisseurs",
      "type": "liability",
      "debit": "48210.35",
      "credit": "55120.80",
      "debit_balance": "0.00",
      "credit_balance": "6910.45",
      "balance": "-6910.45"
    },
    {
      "account_id": 118,
      "number": "604000",
      "label": "Achats de marchandises",
      "type": "expense",
      "debit": "31874.20",
      "credit": "412.00",
      "debit_balance": "31462.20",
      "credit_balance": "0.00",
      "balance": "31462.20"
    }
  ],
  "totals": {
    "debit": "412587.14",
    "credit": "412587.14",
    "is_balanced": true,
    "result": "18240.66"
  }
}

Das Feld balance ist vorzeichenbehaftet: positiv für einen Sollsaldo, negativ für einen Habensaldo. totals.result ist das Ergebnis des Zeitraums, positiv für einen Gewinn und negativ für einen Verlust. totals.is_balanced muss immer den Wert true haben.

Schritt 3: das Hauptbuch eines Kontos lesen

Das Hauptbuch wird Konto für Konto gelesen, mit der account_id aus der Saldenliste oder aus GET accounts.

curl "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/fiscal-years/7/general-ledger/118?from=2026-07-01&to=2026-09-30" \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

{
  "account_id": 118,
  "from": "2026-07-01",
  "to": "2026-09-30",
  "opening_balance": "20918.75",
  "movements": [
    {
      "line_id": 5388,
      "entry_id": 1790,
      "entry_date": "2026-07-03",
      "journal": "ACH",
      "document": "2026/000171",
      "label": "Fûts 20 L blonde",
      "reference": "F-2026-0611",
      "third_party": "Brasserie des Collines SA",
      "debit": "980.00",
      "credit": "0.00",
      "balance": "21898.75",
      "reconciliation_code": null
    },
    {
      "line_id": 5521,
      "entry_id": 1842,
      "entry_date": "2026-09-30",
      "journal": "ACH",
      "document": "2026/000212",
      "label": "Fûts 20 L blonde",
      "reference": "F-2026-0918",
      "third_party": "Brasserie des Collines SA",
      "debit": "1250.00",
      "credit": "0.00",
      "balance": "31462.20",
      "reconciliation_code": null
    }
  ],
  "totals": {
    "debit": "10955.45",
    "credit": "412.00",
    "balance": "31462.20"
  }
}
Feld Beschreibung
opening_balance Saldovortrag: Bewegungen des Geschäftsjahres vor from
movements[].balance Laufender Saldo nach der Bewegung
movements[].document Belegnummer im Format Geschäftsjahr/Nummer mit sechs Stellen
movements[].reconciliation_code Auszifferungscode, null, wenn die Zeile nicht ausgeziffert ist
totals.balance Endsaldo: opening_balance plus Sollbeträge minus Habenbeträge

Die Bewegungen sind nach Datum, dann nach Buchung, dann nach Zeilenposition sortiert. Diese Route ist nicht paginiert: Begrenzen Sie bei stark bebuchten Konten den Zeitraum mit from und to.

Schritt 4: zur Buchung zurückgehen

Jede Bewegung trägt eine entry_id. Die vollständige Buchung mit allen ihren Zeilen lesen Sie so:

curl https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/entries/1842 \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

Vollständiges Beispiel: das gesamte Hauptbuch in Python

import os
import requests

BASE = "https://api.novafisko.com/v1"
COMPANY = "k3Jd9fPq2LmX"
FISCAL_YEAR = 7

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {os.environ['NOVAFISKO_TOKEN']}",
    "Accept": "application/json",
})

balance = session.get(
    f"{BASE}/companies/{COMPANY}/fiscal-years/{FISCAL_YEAR}/trial-balance", timeout=60
).json()
assert balance["totals"]["is_balanced"]

ledger = {}
for line in balance["lines"]:
    # One call per account that actually moved during the year
    ledger[line["number"]] = session.get(
        f"{BASE}/companies/{COMPANY}/fiscal-years/{FISCAL_YEAR}/general-ledger/{line['account_id']}",
        timeout=60,
    ).json()

for number, account in sorted(ledger.items()):
    print(number, account["totals"]["balance"], len(account["movements"]), "movements")
Tipp

Wenn Sie das vollständige Hauptbuch in einer einzigen Datei benötigen, verwenden Sie den Export: GET exports/general-ledger?format=csv&fiscal_year_id=7. Er akzeptiert account_from und account_to, um einen Kontenbereich einzugrenzen. Siehe Die vollständige Akte exportieren.

Weitere verfügbare Auswertungen

Route Inhalt
fiscal-years/{id}/balance-by-period Saldenliste nach Perioden
fiscal-years/{id}/financial-statements Bilanz und GuV
journals/{id}/entries Buch eines Journals, mit from und to
third-party-balance/{type} Saldenliste der Kunden (customer) oder der Lieferanten (supplier)
aged-balance/{type} Altersstruktur der offenen Posten
fiscal-years/{id}/consistency Konsistenzprüfungen des Geschäftsjahres
integrity Integritätsprüfung des Mandats
Hinweis

Ein unbekanntes oder zu einem anderen Mandat gehörendes Geschäftsjahr antwortet mit 404. Dasselbe gilt für ein Konto eines anderen Mandats.

Siehe auch