Nordlet

← Dokumentation / Leitfäden

Migration aus einem anderen System

Übernehmen Sie die Buchhaltung eines Unternehmens in einem einzigen Aufruf – Kontenrahmen, Geschäftspartner, Eröffnungsbilanz oder vollständige Historie, offene Rechnungen, Anlagevermögen und Lagerbestand.

Wenn ein Unternehmen von einem anderen Buchhaltungsprogramm zu Nordlet wechselt, startet die Buchhaltung nicht bei Null. Der Importer für historische Buchhaltungsdaten verarbeitet alle Daten aus dem Altsystem und schreibt sie in einem einzigen Aufruf, der als eine Datenbanktransaktion ausgeführt wird: Schlägt auch nur eine einzige Zeile bei der Prüfung fehl, wird nichts gespeichert. Dasselbe Paket kann vorab über einen reinen Prüfendpunkt ausgeführt werden, der alle Validierungen durchführt und ein Rollback ausführt.

POST /v1/migration/books/validate   # prüft alles, schreibt nichts
POST /v1/migration/books/import     # schreibt entweder alles oder nichts

Die Web-App bietet dieselben zwei Schaltflächen unter Einstellungen → Migration (JSON einfügen oder Datei hochladen). Der API-Schlüssel benötigt ledger:write sowie den Schreib-Scope für jeden enthaltenen Bereich (partners:write, catalog:write, sales:write, purchases:write, assets:write, inventory:write). Beide Endpunkte akzeptieren Anforderungskörper (Request Bodies) mit einer Größe von bis zu 32 MB.

Das Umstellungsdatum

Wählen Sie das Umstellungsdatum (Cut-over Date): den ersten Tag, an dem das Unternehmen in Nordlet geführt wird. Alles, was davor liegt, verbleibt im Altsystem (oder wird als Historie übernommen, siehe unten); alles ab diesem Tag wird in Nordlet über die regulären Endpunkte erfasst. Alle Beträge im Paket gelten "zum Stand des Tages vor der Umstellung": die Bilanz zum Jahres- oder Monatsabschluss, die noch unbezahlten Rechnungen, der Lagerbestand und das Anlagevermögen.

Führen Sie vor dem Import die folgenden Schritte in Nordlet aus:

  1. Legen Sie das Unternehmen an und wenden Sie die Kontenrahmenvorlage an (ledger/accounts/apply-template) - oder listen Sie die benötigten Konten im Abschnitt accounts des Pakets auf.
  2. Erstellen Sie mindestens ein Lager (inventory/warehouses/create), wenn Sie Lagerbestände importieren.
  3. Führen Sie das Paket über migration/books/validate aus, bis keine Fehler mehr gemeldet werden und Sie eventuelle Warnungen akzeptieren.

Das Paket

Jeder Abschnitt ist optional; fügen Sie nur die Bereiche hinzu, die Sie benötigen. Alle Verknüpfungen zwischen den Abschnitten erfolgen über Codes (Kontencode, Geschäftspartnercode, Artikelcode, Anlagengruppencode, Lagerortcode). Ein Code kann sich dabei entweder auf einen bereits in Nordlet vorhandenen Datensatz oder auf einen in einem früheren Abschnitt desselben Pakets erstellten Datensatz beziehen.

{
  "cutoverDate": "2026-01-01",
  "source": "Rivilė GAMA",
  "accounts": [
    { "code": "6210", "name": "Advertising expenses", "type": "expense", "parentCode": "6" }
  ],
  "partners": [
    { "code": "301111222", "name": "UAB Klientas", "vatCode": "LT100001112223", "isCustomer": true },
    { "code": "302222333", "name": "UAB Tiekėjas", "isCustomer": false, "isSupplier": true }
  ],
  "items": [
    { "code": "SKU-1", "name": "Widget", "type": "product", "unit": "vnt", "vatRatePercent": "21" }
  ],
  "assetGroups": [
    { "code": "TRANSP", "name": "Vehicles", "assetAccountCode": "1230", "depreciationAccountCode": "1239",
      "defaultUsefulLifeMonths": 60 }
  ],
  "openingBalances": {
    "balancingAccountCode": "3410",
    "entries": [
      { "accountCode": "2710", "debit": "5000.00" },
      { "accountCode": "2410", "debit": "1500.00" },
      { "accountCode": "2040", "debit": "300.00" },
      { "accountCode": "1230", "debit": "12000.00" },
      { "accountCode": "1239", "credit": "2400.00" },
      { "accountCode": "4430", "credit": "700.00" },
      { "accountCode": "3010", "credit": "10000.00" }
    ]
  },
  "openReceivables": [
    { "partnerCode": "301111222", "number": "SF-1050", "issueDate": "2025-12-10", "dueDate": "2026-01-09",
      "grossTotal": "1210.00", "vatTotal": "210.00" },
    { "partnerCode": "301111222", "number": "SF-1049", "issueDate": "2025-11-20",
      "grossTotal": "500.00", "outstanding": "290.00" }
  ],
  "openPayables": [
    { "partnerCode": "302222333", "documentNumber": "T-77", "documentDate": "2025-12-15", "grossTotal": "700.00" }
  ],
  "fixedAssets": [
    { "groupCode": "TRANSP", "code": "CAR-1", "name": "Delivery van", "acquisitionDate": "2025-01-01",
      "acquisitionCost": "12000.00", "accumulatedDepreciation": "2400.00", "depreciatedMonths": 12 }
  ],
  "stock": [
    { "itemCode": "SKU-1", "quantity": "30", "unitCost": "10" }
  ]
}

Beträge werden als Dezimalstrings übergeben, wie überall in der API. source ist ein freies Textfeld, das in der Beschreibung der Eröffnungsbilanzbuchung und in den Notizen migrierter Rechnungen erscheint.

accounts

Zeilen für den Kontenrahmen: code, name, type (asset, liability, equity, income, expense), optional parentCode und isPostable. Bereits vorhandene Codes werden unverändert übernommen und als existing gezählt. Verwenden Sie dies, wenn der Kontenrahmen des Altsystems von der Vorlage abweicht, oder überspringen Sie diesen Schritt und wenden Sie stattdessen die Vorlage an.

partners und items

Kunden, Lieferanten und Artikel, identifiziert über code. In Litauen entspricht der Geschäftspartnercode normalerweise dem Unternehmensregistercode; verwenden Sie für Privatpersonen einen Code, der innerhalb des Unternehmens eindeutig ist. Bereits vorhandene Codes werden übersprungen und nicht aktualisiert. Artikel akzeptieren type (product oder service), unit, barcode, vatRatePercent, salePriceExclVat, purchasePriceExclVat.

openingBalances

Die Saldenbilanz (Trial Balance) des Altsystems, eine Zeile pro Konto: accountCode mit entweder debit oder credit. Die Zeilen werden als eine einzige Buchungstapete (Journal Transaction) mit dem Datum openingBalances.date (standardmäßig das Umstellungsdatum) und dem Belegtyp migration_opening erfasst. Die Zeilen müssen sich auf bebuchbare Konten beziehen.

Die Transaktion muss ausgeglichen sein. Wenn die Saldenbilanz des Altsystems nicht ausgeglichen ist – etwa durch Rundungsdifferenzen, einen noch nicht ins Eigenkapital gebuchten Gewinn oder ein fehlendes Konto –, geben Sie balancingAccountCode an (typischerweise Gewinnrücklagen/Gewinnvortrag, 3410 in der litauischen Vorlage). Die Differenz wird dann dort verbucht; die Antwort weist diesen Betrag als balancingAmount aus.

Pro Unternehmen darf nur eine Eröffnungsbilanzbuchung existieren. Ein zweiter Import mit openingBalances wird abgelehnt (409). Nachträgliche Korrekturen erfolgen über normale manuelle Buchungen (ledger/journal/transactions/create); bereits gebuchte Transaktionen sind unveränderlich, sodass das Original als importiert erhalten bleibt.

journal – vollständige Historie anstelle oder zusätzlich zu Salden

Wenn Sie die Transaktionen des Altsystems in Nordlet übernehmen möchten (damit Berichte für frühere Zeiträume funktionieren), übergeben Sie diese hier: ein Objekt pro Transaktion mit date, optionaler description und reference sowie entries bestehend aus accountCode und debit/credit. Jede Transaktion muss in sich ausgeglichen sein. Sie werden mit dem Belegtyp migration gebucht.

Die Daten müssen vor dem Umstellungsdatum liegen. Wenn das Paket zusätzlich openingBalances enthält, muss die Historie auf oder nach openingBalances.date liegen – das übliche Muster sind Salden zu Beginn des vorherigen Geschäftsjahres zuzüglich der Transaktionen dieses Jahres, wobei die Umstellung auf den ersten Tag des aktuellen Jahres fällt. Übergeben Sie Salden und Historie nicht für denselben Zeitraum, da die Salden sonst doppelt gezählt würden.

Jeder Monat, der von den Eröffnungsbilanzen oder der Historie berührt wird, muss ein offener Buchungszeitraum sein (andernfalls erfolgt Fehler 409).

openReceivables und openPayables

Rechnungen, die zum Zeitpunkt der Umstellung noch ganz oder teilweise unbezahlt waren. Sie werden als ausgestellte Ausgangsrechnungen und erfasste Eingangsrechnungen mit paidAmount = grossTotal − outstanding angelegt, sodass der Bankabgleich (bank/transactions/match, bank/transactions/suggest-matches), der Fälligkeitsreport für Forderungen (Aging Report) und Zahlungs-Webhooks für diese Rechnungen genau wie für alle anderen Rechnungen funktionieren.

  • outstanding ist standardmäßig gleich grossTotal; vatTotal ist standardmäßig 0 (der Nettobetrag wird ermittelt).
  • dueDate entspricht standardmäßig dem Belegdatum.
  • currency entspricht standardmäßig der Rechnungswährung des Unternehmens. Für alle anderen Währungen als die Basiswährung des Unternehmens ist fxRate erforderlich – Einheiten dieser Währung pro 1 Einheit der Basiswährung, entsprechend der Konvention im Rest der API. Sie wird auf der Rechnung gespeichert, damit spätere Zahlungen die realisierte Währungskurzdifferenz korrekt berechnen.
  • Die Rechnungsnummer (number) einer Ausgangsrechnung ist die vollständige Nummer des Altsystems und muss im Unternehmen eindeutig sein. Eingangsrechnungen sind pro Geschäftspartner und documentNumber eindeutig.
  • Die Rechnungen werden nicht erneut gebucht: Ihr Forderungs- bzw. Verbindlichkeitssaldo ist bereits Teil der Eröffnungsbilanz. Sie werden mit der Eröffnungsbilanzbuchung verknüpft, weshalb openPayables den Bereich openingBalances im selben Paket voraussetzt.
  • Rechnungspositionen werden nicht importiert; die Rechnung enthält nur Summen. Das Altsystem bleibt die Quelle für Positionsdetails und Mehrwertsteuerregister (Umsatzsteuermeldungen) von Zeiträumen vor der Umstellung.

Wenn das Altsystem Kunden- und Lieferantensalden ohne offene Posten geführt hat, erstellen Sie pro Geschäftspartner eine Rechnung für den Saldo (zum Beispiel mit der Nummer OB-301111222), damit dieser ausgeglichen werden kann.

Die Nummerierung wird fortgesetzt. Wenn eine importierte Ausgangsrechnungsnummer das Format PREFIX-N hat und ihr Ausstellungsdatum in das Umstellungsjahr fällt, wird der Nummernkreis für dieses Präfix und Jahr auf N + 1 gesetzt (wird niemals herabgesetzt). Die Antwort listet den resultierenden numberSeries auf; für andere Fälle legen Sie den Nummernkreis selbst über reference/series/create an ({ documentType: "sale_invoice", prefix, year, startAt }).

assetGroups und fixedAssets

Anlagegüter werden mitsamt ihrer bisherigen Abschreibung übernommen: acquisitionCost, salvageValue, accumulatedDepreciation, depreciatedMonths und usefulLifeMonths (oder der Standardwert der Gruppe). Der Abschreinungslauf nach der linearen Methode (assets/depreciation/post) läuft auf Basis des Restwerts über die verbleibenden Monate weiter. Anlagegüter, deren kumulierte Abschreibung bereits dem abschreibungsfähigen Wert entspricht, werden als fully_depreciated (vollständig abgeschrieben) angelegt. Es wird nichts gebucht – Anschaffungskosten und kumulierte Abschreibung sind Teil der Eröffnungsbilanz.

Gruppen werden über code identifiziert und erfordern assetAccountCode sowie depreciationAccountCode (Standard-Aufwandskonto 6206).

stock

Lagerbestand pro Artikel: itemCode, quantity, unitCost (Einstandskosten pro Einheit in EUR) sowie optional warehouseCode (Standard: das Standardlager), lotNumber und expiryDate für chargen- oder seriennummerngeführte Artikel. Jede Zeile wird zu einer Lagerzugangsbewegung mit dem Datum der Umstellung und dem Belegtyp migration und startet eine FIFO-Schicht zu diesen Anschaffungskosten. Es wird nichts gebucht – der Lagerwert ist Teil der Eröffnungsbilanz.

Prüfungen und Warnungen

Der Validierungsendpunkt schlägt fehl (422) bei fehlenden Konten, nicht bebuchbaren Konten, nicht ausgeglichenen Transaktionen, unbekannten Partner-, Artikel-, Gruppen- oder Lagerhaltungs-Codes, doppelten Codes oder Nummern im Paket, offenen Beträgen, die den Bruttowert übersteigen, kumulierten Abschreibungen über dem abschreibungsfähigen Wert sowie fehlenden Wechselkursen. Bereits in Nordlet vorhandene Nummern oder Codes führen zu Fehler 409.

Darüber hinaus vergleichen beide Endpunkte die Nebenbücher (Subledgers) mit den Buchungssätzen im selben Paket und geben die Differenzen als warnings (Warnungen) statt als Fehler aus:

  • Summe der offenen Posten von openReceivables im Vergleich zum Saldo auf dem Forderungskonto (Buchungsregel sales.receivable, standardmäßig 2410);
  • Summe der offenen Posten von openPayables im Vergleich zum Verbindlichkeitskonto (purchases.payables, 4430);
  • Gesamtwert des Lagerbestands von stock im Vergleich zum Bestandskonto (inventory.stock, 2040);
  • pro Anlagengruppe die Anschaffungskosten der Anlagegüter im Vergleich zum Anlagenkonto der Gruppe und deren kumulierte Abschreibung im Vergleich zum Abschreibungskonto.

Eine Warnung bedeutet, dass Nebenbuch und Hauptbuch des Altsystems nicht übereinstimmen. Korrigieren Sie das Paket (oder akzeptieren Sie die Differenz wissentlich), bevor Sie den Import durchführen.

Die Antwort

{
  "dryRun": false,
  "cutoverDate": "2026-01-01",
  "accounts": { "created": 1, "existing": 0 },
  "partners": { "created": 2, "existing": 0 },
  "items": { "created": 1, "existing": 0 },
  "assetGroups": { "created": 1, "existing": 0 },
  "openingBalances": { "journalTransactionId": "…", "date": "2026-01-01", "entries": 8,
                        "debitTotal": "18800.00", "creditTotal": "18800.00", "balancingAmount": "5700.00" },
  "journal": { "transactions": 0, "entries": 0 },
  "openReceivables": { "created": 2, "outstandingTotal": "1500.00" },
  "openPayables": { "created": 1, "outstandingTotal": "700.00" },
  "fixedAssets": { "created": 1, "costTotal": "12000.00", "accumulatedDepreciationTotal": "2400.00" },
  "stock": { "movements": 1, "costTotal": "300.00" },
  "numberSeries": [],
  "warnings": []
}

dryRun: true kennzeichnet einen Testlauf (Validierung); in diesem Fall ist journalTransactionId gleich null. Ein echter Import wird im Prüfprotokoll (Audit Log) als migration.imported mit derselben Zusammenfassung protokolliert.

Nach dem Import

  • Sperren Sie die Zeiträume vor dem Umstellungsdatum (ledger/periods/lock), damit nicht versehentlich etwas in die migrierte Historie gebucht wird.
  • Überprüfen Sie die Saldenbilanz und die Bilanz zum Umstellungsdatum anhand der Abschlussberichte des Altsystems.
  • Fahren Sie mit dem regulären Ablauf fort: Rechnungen ausstellen, Kontoauszüge importieren, Zahlungen abgleichen – die migrierten offenen Rechnungen lassen sich wie jede andere Rechnung begleichen.

Was der Importer nicht abdeckt: Rechnungspositionen und Mehrwertsteuerregister vergangener Zeiträume (bewahren Sie diese im Altsystem oder dessen Archiv auf), Lohn- und Gehaltshistorie sowie andere Dokumente als Rechnungen (Bestellungen, Lieferscheine, Verträge).