Migrálás másik rendszerből

Amikor egy vállalat másik könyvelőprogramból tér át a Nordlet rendszerére, a könyvelése nem tiszta lappal indul. A történeti adatok importőre mindent átvesz, amit a régi rendszer hátrahagyott, és egyetlen hívásban, egyetlen adatbázis-tranzakció keretében rögzíti: ha egyetlen sor ellenőrzése is sikertelen, semmi sem kerül mentésre. Ugyanez a csomag először futtatható egy kizárólag ellenőrzést végző végponton is, amely minden validációt elvégez, majd visszagörget.

POST /v1/migration/books/validate   # mindent ellenőriz, semmit sem ír
POST /v1/migration/books/import     # mindent rögzít vagy semmit sem

A webes alkalmazásban ugyanez a két gomb a Könyvelés -> Migráció (Account -> Migration) menüpont alatt érhető el (ide illeszthető be a JSON, vagy tölthető fel a fájl). Az API-kulcsnak rendelkeznie kell a ledger:write jogosultsággal, valamint a csomagban szereplő összes szekció írási hatáskörével (partners:write, catalog:write, sales:write, purchases:write, assets:write, inventory:write). Mindkét végpont legfeljebb 32 MB méretű kéréstesteket fogad el.

Az átállási nap

Válassza ki az átállási napot (cut-over date): ez a Nordletben történő könyvelés első napja. Az ezt megelőző időszak minden adata a régi rendszerben marad (vagy történeti adatként kerül átemelésre, lásd lentebb); az ettől a naptól kezdődő események a szokásos végpontokon keresztül kerülnek rögzítésre a Nordletben. A csomagban szereplő összes összeg az „átállási nap előtti nap végén fennálló állapotot” jelenti: a záró főkönyvi kivonatot, a még ki nem egyenlített számlákat, a polcon lévő készletet és a nyilvántartásban szereplő eszközöket.

Az importálás előtt hajtsa végre a következő lépéseket a Nordletben:

1. Hozza létre a céget, és alkalmazza a számlatükör-sablont (ledger/accounts/apply-template), vagy sorolja fel a szükséges számlákat a csomag accounts szekciójában.
2. Hozzon létre legalább egy raktárat (inventory/warehouses/create), ha készletet is importál.
3. Futtassa át a csomagot a migration/books/validate végponton addig, amíg az nem jelez hibát, és Ön el nem fogadja a figyelmeztetéseit.

A csomag

Minden szekció opcionális; csak azokat adja meg, amelyekkel rendelkezik. A szekciók közötti hivatkozások kódok alapján történnek (számlakód, partnerkód, cikkszám, eszközcsoport kódja, raktárkód), és egy kód hivatkozhat egy már létező rekordra a Nordletben, vagy egy olyan rekordra, amelyet a csomag egy korábbi szekciója hozott létre.

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

Az összegek decimális karakterláncokként (string) adandók meg, ahogy az API-ban mindenhol. A source egy szabadon megadható címke, amely bekerül a nyitómérleg-tranzakció leírásába és a migrált számlák megjegyzéseibe.

accounts

Számlatükör sorai: code, name, type (asset, liability, equity, income, expense), opcionális parentCode és isPostable. A már létező kódok változatlanok maradnak, és existing (létező) státusszal kerülnek elszámolásra. Akkor használja ezt, ha a régi rendszer számlatükre eltér a sablontól, vagy hagyja ki, és alkalmazza előbb a sablont.

partners és items

Vevők, szállítók és katalóguselemek, code kulccsal azonosítva. Litvániában a partnerkód általában a cégjegyzékszám; magánszemélyek esetén használjon bármilyen, a cégen belül egyedi kódot. A létező kódok átugrásra kerülnek, nem frissülnek. A tételek (items) a következő mezőket fogadják el: type (product vagy service), unit, barcode, vatRatePercent, salePriceExclVat, purchasePriceExclVat.

openingBalances

A régi rendszer záró főkönyvi kivonata, számlánként egy sorral: accountCode, valamint vagy debit, vagy credit. A sorok egyetlen könyvelési tételként kerülnek rögzítésre a openingBalances.date dátummal (alapértelmezés szerint az átállási nap), migration_opening bizonylattípussal. A soroknak könyvelhető (postable) számlákra kell hivatkozniuk.

A tranzakciónak egyensúlyban kell lennie. Ha a régi rendszer főkönyvi kivonata nem egyensúlyos - kerekítési különbség, le nem zárt eredmény, hiányzó számla miatt -, adja meg a balancingAccountCode értéket (jellemzően az eredménytartalékot, a litván sablonban a 3410-es számlát), és a különbség arra a számlára könyvelődik; a válasz a különbözetet balancingAmount néven jelenti.

Cégenként csak egy nyitómérleg-tranzakció létezhet. Egy második, openingBalances szekciót tartalmazó importálás elutasításra kerül (409-es hiba). Az utólagos helyesbítések hagyományos kézi könyvelési tételekkel (ledger/journal/transactions/create) végezhetők el; a már könyvelt tételek nem módosíthatók, így az eredeti tétel a importált formájában marad.

journal - teljes előzmény az egyenlegek helyett vagy mellett

Ha a régi rendszer tételeit is át szeretné hozni a Nordletbe (hogy a korábbi időszakok jelentései is működjenek), küldje el őket itt: tranzakciónként egy objektum a date (dátum), az opcionális description (leírás) és reference (hivatkozás) mezővel, valamint az accountCode + debit/credit párosokból álló entries többel. Minden tranzakciónak önmagában is egyensúlyban kell lennie. Ezek migration bizonylattípussal kerülnek rögzítésre.

A dátumoknak az átállási nap előttieknek kell lenniük. Ha a csomag openingBalances adatokat is tartalmaz, az előzmények dátumának az openingBalances.date napján vagy azt követően kell lennie. A szokásos minta az előző üzleti év eleji egyenlegek plusz az adott év tételei, az átállási nap pedig a aktuális év első napja. Ugyanarra az időszakra ne küldjön egyenlegeket és előzményeket is: az egyenlegek duplán lennének beszámítva.

Minden olyan hónapnak, amelyet a nyitóegyenlegek vagy az előzmények érintenek, nyitott számviteli időszaknak kell lennie (ellenkező esetben 409-es hiba történik).

openReceivables és openPayables

Azok a számlák, amelyek az átálláskor még (teljesen vagy részben) kifizetetlenek voltak. Ezek kiállított eladási számlaként és rögzített beszerzési számlaként jönnek létre a paidAmount = grossTotal − outstanding értékkel, így a banki egyeztetés (bank/transactions/match, bank/transactions/suggest-matches), a lejárt követelések jelentése és a fizetési webhookok ugyanúgy működnek rajtuk, mint bármely más számlán.

• Az outstanding alapértelmezett értéke a grossTotal; a vatTotal alapértelmezett értéke 0 (a nettó összeg ebből származtatódik).
• A dueDate alapértelmezett értéke a bizonylat kelte.
• A currency alapértelmezett értéke a cég számlázási pénzneme. A cég alappénznemétől eltérő minden más pénznem esetén a fxRate megadása kötelező - az adott pénznem egységei 1 alappénznemre vetítve, az API többi részénél megszokott konvenció szerint -, és ez eltárolásra kerül a számlán, hogy a későbbi kifizetések helyesen számítsák ki a realizált árfolyam-különbözetet.
• Az eladási számla number (számlaszáma) a régi rendszer teljes számlaszáma, amelynek egyedinek kell lennie a cégen belül. A beszerzési számlák partnerenként és documentNumber alapján egyediek.
• A számlák nem kerülnek újra könyvelésre: a vevő/szállító egyenlegük már része a nyitóegyenlegeknek. Ezek hozzá vannak rendelve a nyitómérleg-tranzakcióhoz, ezért követeli meg az openPayables a openingBalances meglétét ugyanebben a csomagban.
• A számlatételek (sorok) nem kerülnek importálásra; a számla csak a végösszegeket tartalmazza. A sorok részleteiért és az átállás előtti időszakok ÁFA-nyilvántartásaiért továbbra is a régi rendszer a mérvadó.

Ha a régi rendszer a vevői egyenlegeket nyitott tételek nélkül tartotta nyilván, hozzon létre partnerenként egy számlát az egyenleghez (például OB-301111222 számlaszámmal), hogy azt le lehessen zárni.

A sorszámozás folytatódik. Ha egy importált eladási számla száma a PREFIX-N formátumú, és a kiállítási dátuma az átállási évre esik, az adott előtaghoz és évhez tartozó sorszámtartomány N + 1 értékre áll be (soha nem lesz alacsonyabb). A válasz felsorolja az eredményül kapott numberSeries listát; egyéb esetekben állítsa be a sorszámtartományt saját maga a reference/series/create végponttal ({ documentType: "sale_invoice", prefix, year, startAt }).

assetGroups és fixedAssets

A tárgyi eszközök az eddigi értékcsökkenésükkel együtt kerülnek át: acquisitionCost, salvageValue, accumulatedDepreciation, depreciatedMonths és usefulLifeMonths (vagy a csoport alapértelmezett értéke). A lineáris leírás (assets/depreciation/post) a hátralévő értéken, a hátralévő hónapok alatt folytatódik. Azok az eszközök, amelyek akkumulált értékcsökkenése már eléri az értékcsökkenési alapot, fully_depreciated (teljesen leírt) státusszal jönnek létre. Semmi sem kerül könyvelésre - a bekerülési érték és az akkumulált értékcsökkenés a nyitóegyenlegek része.

A csoportok kulcsa a code, és szükségük van az assetAccountCode (eszköz számlakód) valamint a depreciationAccountCode (értékcsökkenési számlakód, alapértelmezés szerint a 6206 számú ráfordításszámla) értékekre.

stock

Készlet tételenként: itemCode, quantity, unitCost (egységár EUR-ban), opcionálisan pedig warehouseCode (alapértelmezés szerint az alapértelmezett raktár), valamint lotNumber és expiryDate a tételszámmal vagy sorozatszámmal nyomon követett cikkekhez. Minden egyes sor az átállási napra datált bejövő készletmozgássá alakul migration bizonylattípussal, és FIFO-réteget indít az adott áron. Semmi sem kerül könyvelésre - a készlet értéke a nyitóegyenlegek része.

Ellenőrzések és figyelmeztetések

Az ellenőrző végpont hibával (422) leáll hiányzó számlák, nem könyvelhető számlák, egyensúlyban lévő nem lévő tranzakciók, ismeretlen partner-, cikk-, csoport- vagy raktárkódok, a csomagon belüli duplikált kódok vagy számok, a bruttó összeget meghaladó nyitott összegek, az értékcsökkenési alapot meghaladó akkumulált értékcsökkenés, valamint hiányzó árfolyamok esetén. A Nordletben már létező számok vagy kódok 409-es hibát eredményeznek.

Ezen felül mindkét végpont összehasonlítja az analitikákat (sub-ledgers) a csomagban szereplő főkönyvi tételekkel, és az eltéréseket hiba helyett figyelmeztetésként (warnings) adja vissza:

• az openReceivables teljes nyitott összege a vevőszámla-számla egyenlegével szemben (sales.receivable könyvelési szabály, alapértelmezés szerint 2410);
• az openPayables teljes nyitott összege a szállítószámla-számlával szemben (purchases.payables, 4430);
• a stock teljes bekerülési értéke a készletszámlával szemben (inventory.stock, 2040);
• eszközcsoportonként az eszközök bekerülési értéke a csoport eszközszámlájával, valamint az akkumulált értékcsökkenésük az értékcsökkenési számlával szemben.

A figyelmeztetés azt jelenti, hogy a régi rendszer analitikája és főkönyve nem egyezik. Az importálás előtt javítsa ki a csomagot (vagy tudatosan fogadja el az eltérést).

A válasz

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

A dryRun: true jelöli a tesztfuttatást; ebben az esetben a journalTransactionId értéke null. Az importálás az auditnaplóban migration.imported néven, ugyanezzel a összesítéssel kerül rögzítésre.

Az importálás után

• Zárja le az átállási nap előtti időszakokat (ledger/periods/lock), hogy véletlenül se kerüljön semmi a migrált előzmények közé.
• Ellenőrizze az átállási nap szerinti főkönyvi kivonatot és mérleget a régi rendszer záró jelentéseivel összehasonlítva.
• Folytassa a szokásos ügymenetet: számlák kiállítása, bankkivonatok importálása, kifizetések egyeztetése - a migrált nyitott számlák ugyanúgy egyenlíthetők ki, mint bármely más számla.

Amit az importőr nem fed le: a korábbi időszakok számlatételei és ÁFA-nyilvántartásai (ezeket őrizze meg a régi rendszerben vagy annak archívumában), a bérszámfejtési előzmények, valamint a számláktól eltérő dokumentumok (megrendelések, szállítólevelek, szerződések).