Migreren vanuit een ander systeem

Wanneer een bedrijf vanuit een ander boekhoudprogramma overstapt naar Nordlet, begint de administratie niet bij nul. De importfunctie voor historische administraties verwerkt alles wat het oude systeem achterlaat in één aanroep en één databanktransactie: als één enkele regel een validatie niet doorloopt, wordt er niets opgeslagen. Hetzelfde pakket kan eerst via een controle-endpoint worden uitgevoerd, dat alle validaties uitvoert en bij fouten een rollback doet.

POST /v1/migration/books/validate   # controleert alles, slaat niets op
POST /v1/migration/books/import     # slaat alles op of niets

De webapplicatie heeft dezelfde twee knoppen onder Account → Migratie (plak de JSON of upload een bestand). De API-sleutel vereist ledger:write plus de schrijfrechten voor elk onderdeel dat u opneemt (partners:write, catalog:write, sales:write, purchases:write, assets:write, inventory:write). Beide endpoints accepteren berichten tot 32 MB.

De overstapdatum

Kies de overstapdatum: de eerste dag waarop het bedrijf in Nordlet draait. Alles van vóór die datum blijft in het oude systeem (of wordt als historie overgedragen, zie hieronder); alles vanaf die dag wordt in Nordlet ingevoerd via de normale endpoints. Alle bedragen in het pakket zijn "per de dag vóór de overstapdatum": de kolommenbalans bij het sluiten, de facturen die nog openstaan, de voorraad die nog in het magazijn ligt en de activa die nog op de vaste-activastaat staan.

Voer voorafgaand aan de import de volgende stappen uit in Nordlet:

1. Maak het bedrijf aan en pas het grootboekrekeningschema toe (ledger/accounts/apply-template), of vermeld de rekeningen die u nodig hebt in het gedeelte accounts van het pakket.
2. Maak ten minste één magazijn aan (inventory/warehouses/create) als u voorraad importeert.
3. Voer het pakket uit via migration/books/validate totdat dit geen fouten meer meldt en u eventuele waarschuwingen accepteert.

Het pakket

Elk onderdeel is optioneel; neem op wat van toepassing is. Alle verwijzingen tussen onderdelen gaan op code (rekeningcode, relatiecode, artikelcode, activagroepcode, magazijncode), en een code kan verwijzen naar een record dat al bestaat in Nordlet of naar een record dat is aangemaakt in een vorig gedeelte van hetzelfde pakket.

{
  "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" }
  ]
}

Bedragen zijn decimale strings, zoals overal in de API. source is een vrij veld dat terechtkomt in de omschrijving van de beginbalansboeking en in de notities van gemigreerde facturen.

accounts

Regels voor het grootboekrekeningschema: code, name, type (asset, liability, equity, income, expense), optioneel parentCode en isPostable. Bestaande codes worden ongewijzigd gelaten en geteld als existing. Gebruik dit wanneer het rekeningschema van het oude systeem afwijkt van het sjabloon, of sla dit over en pas eerst het sjabloon toe.

partners en items

Klanten, leveranciers en artikelcatalogus, geïndexeerd op code. In Litouwen is de partnercode doorgaans het kvk-nummer; gebruik voor natuurlijke personen een willekeurige code die uniek is binnen het bedrijf. Bestaande codes worden overgeslagen en niet bijgewerkt. Artikelen accepteren type (product of service), unit, barcode, vatRatePercent, salePriceExclVat, purchasePriceExclVat.

openingBalances

De eindbalans van het oude systeem, één regel per rekening: accountCode met òf debit òf credit. De regels worden geboekt als één journaalpost met datum openingBalances.date (standaard de overstapdatum) en documenttype migration_opening. Regels moeten verwijzen naar boekbare rekeningen.

De transactie moet in evenwicht zijn. Als de balans van het oude systeem niet in evenwicht is door afronding, een winst die nooit naar het eigen vermogen is geboekt of een ontbrekende rekening, geef dan balancingAccountCode op (doorgaans ingehouden winst, 3410 in het Litouwse sjabloon) en het verschil wordt daarop geboekt; het antwoord rapporteert het bedrag als balancingAmount.

Er mag slechts één beginbalansboeking per bedrijf bestaan. Een tweede import met openingBalances wordt geweigerd (409). Correcties achteraf zijn gewone handmatige journaalposten (ledger/journal/transactions/create); geboekte transacties zijn onwijzigbaar, dus de oorspronkelijke boeking blijft behouden zoals deze is geïmporteerd.

journal - volledige historie in plaats van, of als aanvulling op, saldi

Als u de transacties uit het oude systeem in Nordlet wilt opnemen (zodat rapportages voor eerdere perioden werken), stuur deze dan hierheen: één object per transactie met date, optioneel description en reference, en entries bestaande uit accountCode + debit/credit. Elke transactie moet op zichzelf in evenwicht zijn. Ze worden geboekt met documenttype migration.

Data moeten vóór de overstapdatum liggen. Wanneer het pakket ook openingBalances bevat, moet de historie de datum van of na openingBalances.date hebben. Het gebruikelijke patroon is saldi aan het begin van het vorige boekjaar plus de transacties van dat jaar, met de overstap op de eerste dag van het lopende jaar. Stuur geen saldi en historie mee voor dezelfde periode, aangezien de saldi dan dubbel zouden meetellen.

Elke maand waarin de beginbalans of de historie mutaties kent, moet een open periode zijn (anders volgt een 409).

openReceivables en openPayables

Facturen die op de overstapdatum (geheel of gedeeltelijk) nog openstonden. Deze worden aangemaakt als uitgereikte verkoopfacturen en geregistreerde inkoopfacturen met paidAmount = grossTotal − outstanding, zodat bankkoppeling (bank/transactions/match, bank/transactions/suggest-matches), de ouderdomsanalyse van debiteuren/crediteuren en betalingswebhooks hierop werken zoals op elke andere factuur.

• outstanding is standaard gelijk aan grossTotal; vatTotal is standaard 0 (het ex-bTW-bedrag wordt afgeleid).
• dueDate is standaard de factuurdatum.
• currency is standaard de factuurvaluta van het bedrijf. Voor elke andere valuta dan de basisvaluta van het bedrijf is fxRate vereist - het aantal eenheden van die valuta per 1 eenheid van de basisvaluta, volgens dezelfde conpventie als de rest van de API. Dit wordt op de factuur opgeslagen zodat latere betalingen het gerealiseerde koersverschil juist kunnen berekenen.
• Het verkoopfactuurnummer number is het volledige nummer uit het oude systeem en moet uniek zijn binnen het bedrijf.
• Inkoopfacturen zijn uniek per relatie en documentNumber.
• De facturen worden niet opnieuw geboekt: hun debiteuren-/crediteurensaldo maakt reeds deel uit van de beginbalans. Ze zijn gekoppeld aan de beginbalansboeking, wat de reden is waarom openPayables vereist dat openingBalances in hetzelfde pakket is opgenomen.
• Factuurregels worden niet geïmporteerd; de factuur bevat alleen totalen. Het oude systeem blijft de bron voor regeldetails en voor de btw-aangiften van perioden van vóór de overstap.

Als het oude systeem klantsaldi bijhield zonder openstaande posten, maak dan één factuur per relatie aan voor het saldo (bijvoorbeeld nummer OB-301111222) zodat dit kan worden vereffend.

Nummering loopt door. Wanneer een geïmporteerd verkoopfactuurnummer de vorm PREFIX-N heeft en de factuurdatum in het overstapjaar valt, wordt de notatiereeks voor dat voorvoegsel en jaar ingesteld op N + 1 (nooit verlaagd). Het antwoord somt de resulterende numberSeries op; stel in andere gevallen de reeks zelf in via reference/series/create ({ documentType: "sale_invoice", prefix, year, startAt }).

assetGroups en fixedAssets

Vaste activa worden overgebracht inclusief hun tot dan toe opgebouwde afschrijving: acquisitionCost, salvageValue, accumulatedDepreciation, depreciatedMonths en usefulLifeMonths (of de standaardwaarde van de groep). De lineaire afschrijvingsrun (assets/depreciation/post) loopt door over de resterende boekwaarde en de resterende maanden. Activa waarvan de cumulatieve afschrijving al gelijk is aan de afschrijfbare waarde, worden aangemaakt als fully_depreciated. Er wordt niets geboekt; de aanschafwaarde en de cumulatieve afschrijving maken deel uit van de beginbalans.

Groepen worden geïndexeerd op code en vereisen assetAccountCode en depreciationAccountCode (standaard kostenrekening 6206).

stock

Voorraad op voorraad per artikel: itemCode, quantity, unitCost (kostprijs per eenheid in EUR) en optioneel warehouseCode (standaard: het standaardmagazijn), lotNumber en expiryDate voor artikelen die per batch of serienummer worden gevolgd. Elke regel wordt een inkomende voorraadmutatie met datum gelijk aan de overstapdatum, documenttype migration, en start een FIFO-laag tegen die kostprijs. Er wordt niets geboekt; de voorraadwaarde maakt deel uit van de beginbalans.

Controles en waarschuwingen

Het validatie-endpoint mislukt (422) bij ontbrekende grootboekrekeningen, niet-boekbare rekeningen, niet in evenwicht zijnde transacties, onbekende codes van relaties, artikelen, groepen of magazijnen, dubbele codes of nummers binnen het pakket, openstaande bedragen die hoger zijn dan het brutototaal, cumulatieve afschrijvingen die hoger zijn dan de afschrijfbare waarde, en ontbrekende wisselkoersen. Nummers of codes die al bestaan in Nordlet resulteren in een 409.

Daarnaast vergelijken beide endpoints de subadministraties met de grootboekrekeningen in hetzelfde pakket en retourneren de verschillen als warnings (waarschuwingen) in plaats van fouten:

• totaal openstaand van openReceivables versus het saldo op de debiteurenrekening (boekingsregel sales.receivable, standaard 2410);
• totaal openstaand van openPayables versus de crediteurenrekening (purchases.payables, 4430);
• totale kostprijs van stock versus de voorraadrekening (inventory.stock, 2040);
• per activagroep de aanschafwaarde van de activa versus de activarekening van de groep en hun cumulatieve afschrijving versus de afschrijvingsrekening.

Een waarschuwing betekent dat de subadministratie en het grootboek van het oude systeem niet met elkaar overeenkomen. Corrigeer het pakket (of accepteer het verschil bewust) voordat u importeert.

Het antwoord

{
  "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 markeert een validatie-uitvoering; hierin is journalTransactionId gelijk aan null. Een import wordt vastgelegd in het auditlogboek als migration.imported met dezelfde samenvatting.

Na de import

• Blokkeer de perioden van vóór de overstap (ledger/periods/lock) zodat er per ongeluk niets meer wordt geboekt in de gemigreerde historie.
• Controleer de kolommenbalans en de balans per de overstapdatum aan de hand van de eindbalansrapportages van het oude systeem.
• Ga door met de normale workflow: facturen uitreiken, bankafschriften importeren, betalingen matchen - de gemigreerde openstaande facturen worden vereffend zoals elke andere factuur.

Wat de importfunctie niet dekt: factuurregels en btw-aangiften van voorgaande perioden (bewaar deze in het oude systeem of het archief daarvan), loonhistorie en andere documenten dan facturen (orders, vrachtbrieven, contracten).