Nordlet

← Dokumenti / Gwidi

Migrazzjoni minn sistema oħra

Tella' l-kotba ta' kumpanija f'sejħa waħda - pjan tal-kontijiet, imsieħba, saldi tal-ftuħ jew storja sħiħa, fatturi miftuħa, assi fissi u stokk.

Meta kumpanija tgħaddi għal Nordlet minn programm tal-kontabilità ieħor, il-kotba tagħha ma jibdewx minn żero. L-importatur tal-kotba storiċi jieħu dak kollu li tħallik is-sistema l-qadima u jikteb kollox f'sejħa waħda, tranżazzjoni waħda tad-database: jekk ringiela waħda tfalli verifika, xejn ma jiġi maħżun. L-istess pakkett jista' jitmexxa l-ewwel minn endpoint li jagħmel verifika biss (check-only), li jwettaq kull validazzjoni u jreġġa' kollox lura f'każ ta' żball.

POST /v1/migration/books/validate   # jivverifika kollox, ma jikteb xejn
POST /v1/migration/books/import     # jikteb kollox jew xejn

L-applikazzjoni tal-web għandha l-istess żewġ buttuni taħt Account → Migration (pejstja l-JSON jew tella' fajl). Iċ-ċavetta tal-API (API key) teħtieġ ledger:write flimkien mal-ambitu (scope) tal-kitba ta' kull taqsima li inkludejt (partners:write, catalog:write, sales:write, purchases:write, assets:write, inventory:write). Iż-żewġ endpoints jaċċettaw korpi sa 32 MB.

Id-data tat-tranżizzjoni (Cut-over date)

Agħżel id-data tat-tranżizzjoni: l-ewwel jum li fih il-kumpanija titħaddem f'Nordlet. Kulma jiġi qabel din id-data jibqa' fis-sistema l-qadima (jew jidħol b'mod storiku, ara hawn taħt); kulma jiġi minn dakinhar 'il quddiem jiddaħħal f'Nordlet permezz tal-endpoints normali. L-ammonti kollha fil-pakkett huma "sal-ġurnata ta' qabel it-tranżizzjoni": il-bilanċ ta' prova tal-għeluq, il-fatturi li għadhom mhux imħallsa, l-istokk li għadu fuq l-ixkaffa, l-assi li għadhom fir-reġistru.

Qabel ma timporta, agħmel dan li ġej f'Nordlet:

  1. Oħloq il-kumpanija u applika t-template tal-pjan tal-kontijiet (ledger/accounts/apply-template) - jew elenka l-kontijiet li għandek bżonn fit-taqsima accounts tal-pakkett.
  2. Oħloq mill-inqas maħżen wieħed (inventory/warehouses/create) jekk qed timporta stokk.
  3. Mexxi l-pakkett permezz ta' migration/books/validate sakemm ma jirrapporta l-ebda żball u taċċetta t-twissijiet tiegħu.

Il-pakkett

Kull taqsima hija fakultattiva; inkludi dawk li għandek. Ir-referenzi kollha bejn it-taqsima u oħra jsiru permezz tal-kodiċi (kodiċi tal-kont, kodiċi tal-imsieħeb, kodiċi tal-oġġett, kodiċi tal-grupp tal-assi, kodiċi tal-maħżen), u kodiċi jista' jirreferi jew għal rekord li diġà jeżisti f'Nordlet jew għal wieħed maħluq minn taqsima preċedenti tal-istess pakkett.

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

L-ammonti huma kodiċi deċimali bħala string, bħal kullimkien fl-API. source hija tikketta libera li tispiċċa fid-deskrizzjoni tat-tranżazzjoni tas-saldi tal-ftuħ u fin-noti tal-fatturi migrati.

accounts

Ringieli tal-pjan tal-kontijiet: code, name, type (asset, liability, equity, income, expense), u b'mod fakultattiv parentCode u isPostable. Kodiċijiet li diġà eżistew jitħallew kif inhuma u jiġu magħduda bħala existing. Uża dan meta l-pjan tas-sistema l-qadima jkun differenti mit-template, jew aqbeż dan il-pass u applika t-template l-ewwel.

partners u items

Klijenti, fornituri u oġġetti tal-katalgu, imqassmin bil-code. Fil-Litwanja l-kodiċi tal-imsieħeb normalment ikun il-kodiċi tar-reġistru tal-kumpanija; għal persuni privati uża kwalunkwe kodiċi li jkun uniku fi ħdan il-kumpanija. Kodiċijiet eżistenti jinqabżu u ma jiġux aġġornati. L-oġġetti jaċċettaw type (product jew service), unit, barcode, vatRatePercent, salePriceExclVat, purchasePriceExclVat.

openingBalances

Il-bilanċ ta' prova tal-għeluq tas-sistema l-qadima, ringiela waħda għal kull kont: accountCode flimkien jew ma' debit jew ma' credit. Ir-ringieli jiġu posted bħala tranżazzjoni waħda tal-ġurnal bid-data openingBalances.date (default hija d-data tat-tranżizzjoni) bit-tip ta' dokument migration_opening. Ir-ringieli jridu jirreferu għal kontijiet li jistgħu jiġu posted.

It-tranżazzjoni trid tibbilanċja. Jekk il-bilanċ ta' prova tas-sistema l-qadima ma jibbilanċjax - minħabba rounding, profitt li qatt ma ngħalaq fl-ekwità, jew kont nieqes - ipprovdi balancingAccountCode (tipikament qligħ miżmum jew retained earnings, 3410 fit-template Litwana) u d-differenza titpoġġa hemmhekk; ir-rispons jirrapporta l-ammont bħala balancingAmount.

Tista' eżisti biss tranżazzjoni waħda tas-saldi tal-ftuħ għal kull kumpanija. It-tieni importazzjoni b'openingBalances tiġi rrifjutata (409). Il-korrezzzjonijiet wara l-fatti huma tranżazzjonijiet manwali ordinarji tal-ġurnal (ledger/journal/transactions/create); it-tranżazzjonijiet posted ma jistgħux jinbidlu, għalhekk l-oriġinal jibqa' kif ġie importat.

journal - storja sħiħa minflok, jew flimkien ma', is-saldi

Jekk trid it-tranżazzjonijiet tas-sistema l-qadima f'Nordlet (sabiex ir-rapporti għal perjodi preċedenti jaħdmu), ibgħathom hawn: oġġett wieħed għal kull tranżazzjoni b'date, u b'mod fakultattiv description u reference, flimkien mal-entrati (entries) ta' accountCode + debit/credit. Kull tranżazzjoni trid tibbilanċja waħedha. Dawn jiġu posted bit-tip ta' dokument migration.

Id-dati iridu jkunu qabel id-data tat-tranżizzjoni. Meta l-pakkett ikollu wkoll openingBalances, l-istorja trid tkun datata f'jew wara openingBalances.date - ix-xejra tas-soltu hija saldi fil-bidu tas-sena finanzjarja preċedenti flimkien mat-tranżazzjonijiet ta' dik is-sena, bid-data tat-tranżizzjoni fl-ewwel jum tas-sena kurrenti. Tibgħatx saldi u storja għall-istess perjodu: is-saldi jiġu magħduda darbtejn.

Kull xahar immiss mis-saldi tal-ftuħ jew mill-istorja jrid ikun perjodu ta' kontabilità miftuħ (inkella tirċievi 409).

openReceivables u openPayables

Fatturi li kienu għadhom mhux imħallsa (parzjalment jew kompletament) fid-data tat-tranżizzjoni. Dawn jinħolqu bħala fatturi tal-bejgħ maħruġa (issued) u fatturi tax-xiri reġistrati b'paidAmount = grossTotal − outstanding, sabiex it-tqabbil mal-bank (bank/transactions/match, bank/transactions/suggest-matches), ir-rapport tal-aging tad-debiti u l-webhooks tal-pagamenti jaħdmu fuqhom eżatt bħal fuq kwalunkwe fattura oħra.

  • outstanding awtomatikament teħuda l-valur ta' grossTotal; vatTotal awtomatikament ikun 0 (in-net jiġi kkalkulat).
  • dueDate awtomatikament teħuda d-data tad-dokument.
  • currency awtomatikament teħuda l-munita tal-fatturi tal-kumpanija. Għal kwalunkwe munita minbarra l-munita bażi tal-kumpanija, fxRate hija meħtieġa - unitajiet ta' dik il-munita għal kull unità waħda tal-munita bażi, bl-istess konvenzjoni bħall-bqija tal-API - u tinħażen fuq il-fattura sabiex pagamenti sussegwenti jikkalkulaw id-differenza realizzata tal-FX b'mod korrett.
  • In-numru (number) tal-fattura tal-bejgħ huwa n-numru sħiħ tas-sistema l-qadima u jrid ikun uniku fil-kumpanija. Il-fatturi tax-xiri huma uniċi għal kull imsieħeb u documentNumber.
  • Il-fatturi ma jerġgħux jiġu posted: il-bilanċ tagħhom ta' assi/passiv diġà huwa parti mis-saldi tal-ftuħ. Dawn huma marbuta mat-tranżazzjoni tas-saldi tal-ftuħ, u hu għalhekk li openPayables teħtieġ openingBalances fl-istess pakkett.
  • Il-linji tal-fatturi ma jiġux importati; il-fattura ġġorr it-totals biss. Is-sistema l-qadima tibqa' s-sors għad-dettalji tal-linji u għar-reġistri tal-VAT ta' perjodi ta' qabel it-tranżizzjoni.

Jekk is-sistema l-qadima kienet issegwi s-saldi tal-klijenti mingħajr oġġetti miftuħa, oħloq fattura waħda għal kull imsieħeb għall-bilanċ (pereżempju n-numru OB-301111222) sabiex ikun jista' jiġi saldat.

In-numerazzjoni tkompli. Meta numru ta' fattura tal-bejgħ importata jkollu l-forma PREFIX-N u d-data tal-ħruġ tiegħ2 taqa' fis-sena tat-tranżizzjoni, is-serje tan-numri għal dak il-prefix u dik is-sena tiġi stabbilita għal N + 1 (qatt ma titbaxxa). Ir-rispons elenka s-numberSeries li tirriżulta; f'każijiet oħra ssettja s-serje int stess b'reference/series/create ({ documentType: "sale_invoice", prefix, year, startAt }).

assetGroups u fixedAssets

L-assi fissi jidħlu bid-deprezzament tagħhom sal-data: acquisitionCost, salvageValue, accumulatedDepreciation, depreciatedMonths u usefulLifeMonths (jew id-default tal-grupp). Il-proċess tal-linja dritta (assets/depreciation/post) ikompli mill-valur li fadal fuq ix-xhur li fadal. Assi li d-deprezzament akkumulat tagħnjom diġà jlaħħaq mal-valur deprezzabbli jinħolqu bħala fully_depreciated. Xejn ma jiġi posted - l-ispiża u d-deprezzament akkumulat huma parti mis-saldi tal-ftuħ.

Il-gruppi huma mqassmin bil-code u jeħtieġu assetAccountCode u depreciationAccountCode (kont tal-ispejjeż default 6206).

stock

Stokk fil-idejn għal kull oġġett: itemCode, quantity, unitCost (l-ispiża għal kull unità f'EUR) u b'mod fakultattiv warehouseCode (default: il-maħżen default), lotNumber u expiryDate għal oġġetti segwiti b'lott jew b'numru tas-serje. Kull ringiela ssir moviment tal-istokk li jidħol iddatat fid-data tat-tranżizzjoni bit-tip ta' dokument migration u tibda saff FIFO f'dik l-ispiża. Xejn ma jiġi posted - il-valur tal-istokk huwa parti mis-saldi tal-ftuħ.

Verifiki u twissijiet (Checks and warnings)

L-endpoint ta' validazzjoni jfalli (422) f'każ ta' kontijiet neqsin, kontijiet li ma jistgħux jiġu posted, tranżazzjonijiet mhux ibbilanċjati, kodiċijiet mhux magħrufa ta' msieħba/oġġetti/gruppi/mħażen, kodiċijiet jew numri duplikati fi ħdan il-pakkett, ammonti pendenti ogħla mill-gross, deprezzament akkumulat ogħla mill-valur deprezzabbli, u rati tal-FX neqsin. Numri jew kodiċijiet li diġà jeżistu f'Nordlet jagħtu 422 jew 409.

Apparti dan, iż-żewġ endpoints jqabblu s-sub-ledgers mal-entrati tal-ledger fl-istess pakkett u jirritornaw id-differenzi bħala warnings minflok bħala żbalji:

  • l-ammont pendenti totali ta' openReceivables vs il-bilanċ fuq il-kont tal-kontijiet a ricevuti (regola ta' postjar sales.receivable, 2410 b'default);
  • l-ammont pendenti totali ta' openPayables vs il-kont tal-kontijiet a pagatu (purchases.payables, 4430);
  • l-ispiża totali ta' stock vs il-kont tal-istokk (inventory.stock, 2040);
  • għal kull grupp ta' assi, l-ispiża tal-assi vs il-kont tal-assi tal-grupp u d-deprezzament akkumulat tagħhom vs il-kont tad-deprezzament.

Twissija tfisser li s-sub-ledger tas-sistema l-qadima u l-general ledger ma jaqblux. Irranġa l-pakkett (jew aċċetta d-differenza b'kuxjenza) qabel timporta.

Ir-rispons

{
  "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 jimmarka ġirja ta' validazzjoni; f'dan il-każ journalTransactionId ikun null. Importazzjoni tiġi rreġistrata fil-log tal-awditjar (audit log) bħala migration.imported bl-istess sommarju.

Wara l-importazzjoni

  • Sakkar il-perjodi ta' qabel id-data tat-tranżizzjoni (ledger/periods/lock) sabiex xejn ma jitpoġġa bi żball fl-istorja migrata.
  • Iċċekkja l-bilanċ ta' prova u l-karta tal-bilanċ mid-data tat-tranżizzjoni 'l quddiem kontra r-rapporti tal-għeluq tas-sistema l-qadima.
  • Kompli bil-fluss normali: oħroġ fatturi, importa dikjarazzjonijiet bankarji, tqabbel il-pagamenti - il-fatturi miftuħa migrati jiġu saldati bħal kull oħra.

Dak li l-importatur ma jkoprix: il-linji tal-fatturi u r-reġistri tal-VAT ta' perjodi passati (żommhom fis-sistema l-qadima jew fl-arkivju tagħha), l-istorja tal-pagi, u dokumenti minbarra fatturi (ordnijiet, noti tal-kunsinna jew waybills, kuntratti).