Migracija iz drugog sustava

Kada tvrtka prelazi na Nordlet iz drugog knjigovodstvenog programa, njezine poslovne knjige ne kreću od nule. Uvoznik povijesnih knjiga preuzima sve što vam stari sustav ostavlja i zapisuje to u jednom pozivu, u jednoj bazi podataka (database transaction): ako samo jedan redak ne prođe provjeru, ništa se ne sprema. Isti se paket najprije može pokrenuti kroz krajnju točku (endpoint) samo za provjeru, koja obavlja svaku validaciju i poništava promjene (rollback).

POST /v1/migration/books/validate   # provjerava sve, ništa ne zapisuje
POST /v1/migration/books/import     # zapisuje sve ili ništa

Web-aplikacija ima isto usklađena dva gumba pod stavkom Račun → Migracija (zalijepite JSON ili učitajte datoteku). API ključ treba imati pravo ledger:write plus pravo pisanja za svaku uključenu sekciju (partners:write, catalog:write, sales:write, purchases:write, assets:write, inventory:write). Obje krajnje točke prihvaćaju tijela zahtjeva veličine do 32 MB.

Datum prelaska

Odaberite datum prelaska (cut-over date): prvi dan poslovanja tvrtke u Nordletu. Sve prije toga ostaje u starom sustavu (ili se prenosi kao povijest, vidi niže); sve od tog dana nadalje unosi se u Nordlet kroz uobičajene krajnje točke. Svi iznosi u paketu iskazani su "na dan prije prelaska": zaključna bruto bilanca, računi koji su još uvijek neplaćeni, zalihe koje su još na polici, imovina koja je još u registru.

Prije uvoza učinite sljedeće u Nordletu:

1. Kreirajte tvrtku i primijenite predložak kontnog plana (ledger/accounts/apply-template) ili navedite konta koja su vam potrebna u sekciji accounts unutar paketa.
2. Kreirajte barem jedno skladište (inventory/warehouses/create) ako uvozite zalihe.
3. Pokrenite paket kroz migration/books/validate sve dok ne javi da nema pogrešaka i dok ne prihvatite njegova upozorenja.

Paket

Svaka je sekcija neobavezna; uključite one koje imate. Sve veze između sekcija ostvaruju se putem šifre (šifra konta, šifra partnera, šifra artikla, šifra grupe imovine, šifra skladišta), pri čemu šifra može upućivati na zapis koji već postoji u Nordletu ili na zapis kreiran u prethodnoj sekciji istog paketa.

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

Iznosi su decimalni nizovi znakova (decimal strings), kao i svugdje u API-ju. source je slobodna oznaka koja završava u opisu transakcije početnog salda i u napomenama uvezenih računa.

accounts

Redci kontnog plana: code, name, type (asset, liability, equity, income, expense), uz opcionalne parentCode i isPostable. Konta koja već postoje ostaju netaknuta i bilježe se kao existing. Upotrijebite ovo kada se kontni plan starog sustava razlikuje od predloška ili preskočite ovaj dio i najprije primijenite predložak.

partners i items

Kupci, dobavljači i artikli iz kataloga, indeksirani prema code. U Litvi je šifra partnera obično matični broj tvrtke; za fizičke osobe upotrijebite bilo koju šifru koja je jedinstvena unutar tvrtke. Postojeće šifre se preskaču, a ne ažuriraju. Artikli prihvaćaju atribute type (product ili service), unit, barcode, vatRatePercent, salePriceExclVat, purchasePriceExclVat.

openingBalances

Zaključna bruto bilanca starog sustava, jedan redak po kontu: accountCode s dugovnim (debit) ili potražnim (credit) iznosom. Redci se knjiže kao jedna temeljnica (journal transaction) s datumom openingBalances.date (zadano je datum prelaska) i tipom dokumenta migration_opening. Redci moraju upućivati na konta na koja se može knjižiti.

Transakcija mora biti uravnotežena. Ako bruto bilanca starog sustava nije uravnotežena zbog zaokruživanja, dobiti koja nikada nije raspoređena u kapital ili zbog nedostajućeg konta, navedite balancingAccountCode (obično zadržana dobit, 3410 u litavskom predlošku) i razlika će se proknjižiti na taj konto; odgovor vraća taj iznos pod nazivom balancingAmount.

Za svaku tvrtku može postojati samo jedna transakcija početnog salda. Drugi uvoz s poljem openingBalances bit će odbijen (kod 409). Naknadni ispravci predstavljaju uobičajene ručne temeljnice (ledger/journal/transactions/create); proknjižene temeljnice su nepromjenjive, tako da izvorna temeljnica ostaje zabilježena kako je uvezena.

journal - puna povijest umjesto ili uz stanja

Ako želite transakcije iz starog sustava unijeti u Nordlet (kako bi izvještaji za ranija razdoblja radili), pošaljite ih ovdje: jedan objekt po transakciji s poljima date, opcionalnim description i reference, te entries koje se sastoje od accountCode + debit/credit. Svaka transakcija mora biti samostalno uravnotežena. One se knjiže s tipom dokumenata migration.

Datumi moraju biti prije datuma prelaska. Kada paket sadrži i openingBalances, povijest mora imati datum na ili nakon datuma openingBalances.date - uobičajeni obrazac jest početni saldo na početku prethodne financijske godine plus transakcije te godine, s prelaskom na prvi dan tekuće godine. Nemojte slati početna stanja i povijest za isto razdoblje jer bi se stanja brojila dvaput.

Svaki mjesec obuhvaćen početnim stanjima ili povijesti mora biti otvoreno obračunsko razdoblje (u suprotnom se vraća kod 409).

openReceivables i openPayables

Računi koji su na dan prelaska još uvijek bili neplaćeni (u cijelosti ili djelomično). Kreiraju se kao izdani izlazni računi i evidentirani ulazni računi s postavkom paidAmount = grossTotal − outstanding, tako da usklađivanje s bankom (bank/transactions/match, bank/transactions/suggest-matches), izvještaj o starosti duga (debt-aging report) i webhook obavijesti o plaćanju rade s njima kao i sa svakim drugim računom.

• Za outstanding zadana je vrijednost grossTotal; za vatTotal zadana je vrijednost 0 (iznos bez PDV-a se izračunava).
• Za dueDate zadani je datum dokumenta.
• Za currency je zadana valuta računa tvrtke. Za svaku valutu koja nije osnovna valuta tvrtke obavezan je parametar fxRate - broj jedinica te valute za 1 jedinicu osnovne valute, prema istoj konvenciji kao i u ostatku API-ja - te se on pohranjuje na računu kako bi kasnija plaćanja mogla ispravno izračunati realizirane tečajne razlike.
• Broj izlaznog računa (number) puni je broj iz starog sustava i mora biti jedinstven unutar tvrtke. Ulazni računi jedinstveni su po partneru i polju documentNumber.
• Računi se ne knjiže ponovno: njihov saldo potraživanja/obveza već je dio početnih stanja. Povezani su s transakcijom početnog salda, zbog čega openPayables zahtijeva openingBalances u istom paketu.
• Stavke računa se ne uvoze; račun nosi samo ukupne iznose. Stari sustav ostaje izvor podataka za detalje stavki i za evidencije PDV-a za razdoblja prije prelaska.

Ako je stari sustav pratio saldo kupaca bez otvorenih stavki, kreirajte jedan račun po partneru za iznos salda (na primjer, s brojem OB-301111222) kako bi se mogao podmiriti.

Numeriranje se nastavlja. Kada uvezeni broj izlaznog računa ima oblik PREFIX-N i njegov datum izdavanja pada u godinu prelaska, numerčkoj seriji za taj prefiks i godinu postavlja se vrijednost N + 1 (nikada se ne smanjuje). Odgovor navodi rezultirajuću seriju numberSeries; za ostale slučajeve postavite seriju sami pomoću reference/series/create ({ documentType: "sale_invoice", prefix, year, startAt }).

assetGroups i fixedAssets

Dugotrajna imovina prenosi se zajedno s dosadašnjom amortizacijom: acquisitionCost, salvageValue, accumulatedDepreciation, depreciatedMonths i usefulLifeMonths (ili zadana vrijednost grupe). Obračun linearne amortizacije (assets/depreciation/post) nastavlja se od preostale vrijednosti kroz preostale mjesece. Imovina čija akumulirana amortizacija već doseže amortizivu vrijednost kreira se s statusom fully_depreciated (u cijelosti amortizirano). Ništa se dodatno ne knjiži - nabavna vrijednost i akumulirana amortizacija već su dio početnih stanja.

Grupe su indeksirane prema code i zahtijevaju konta assetAccountCode i depreciationAccountCode (zadani konto troška je 6206).

stock

Zalihe na skladištu po artiklu: itemCode, quantity, unitCost (trošak po jedinici u EUR) i opcionalno warehouseCode (zadano: glavno skladište), lotNumber i expiryDate za artikle koji se prate po serijama ili lotovima. Svaki redak postaje ulazno kretanje zaliha s datumom na dan prelaska, tipom dokumenta migration, te pokreće FIFO sloj po tom trošku. Ništa se dodatno ne knjiži - vrijednost zaliha dio je početnih stanja.

Provjere i upozorenja

Krajnja točka za provjeru vraća pogrešku (kod 422) u slučaju nedostajućih konta, konta na koja se ne može knjižiti, neuravnoteženih transakcija, nepoznatih šifra partnera, artikala, grupa ili skladišta, dvostrukih šifra ili brojeva unutar paketa, iznosa otvorenih stavki većih od bruto iznosa, akumulirane amortizacije veće od amortizive vrijednosti te nedostajućih tečajeva. Šifre ili brojevi koji već postoje u Nordletu vraćaju kod 409.

Povrh toga, obje krajnje točke uspoređuju analitičke evidencije (subledgere) s temeljnim kontima u istom paketu i vraćaju razlike kao warnings (upozorenja) umjesto pogrešaka:

• ukupni otvoren iznos openReceivables u odnosu na saldo na kontu potraživanja od kupaca (pravilo knjiženja sales.receivable, standardno 2410);
• ukupni otvoren iznos openPayables u odnosu na konto obveza prema dobavljačima (purchases.payables, 4430);
• ukupni trošak stock u odnosu na konto zaliha (inventory.stock, 2040);
• po grupi imovine, nabavna vrijednost imovine u odnosu na konto imovine te grupe i njihova akumulirana amortizacija u odnosu na konto amortizacije.

Upozorenje znači da se analitička evidencija starog sustava i glavna knjiga ne podudaraju. Ispravite paket (ili svjesno prihvatite razliku) prije uvoza.

Odgovor

{
  "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 označava probno pokretanje (validate); u tom je slučaju journalTransactionId jednak null. Uvoz se bilježi u revizijskom tragom (audit log) kao migration.imported s istim sažetkom.

Nakon uvoza

• Zaključite razdoblja prije datuma prelaska (ledger/periods/lock) kako se slučajno ništa ne bi proknjižilo u uvezenu povijest.
• Provjerite bruto bilancu i bilanco stanja na dan prelaska u usporedbi sa zaključnim izvještajima starog sustava.
• Nastavite s uobičajenim tijekom rada: izdajite račune, uvozite bankovne izvode, usklađujte plaćanja - uvezeni otvoreni računi podmiruju se kao i svi drugi.

Što uvoznik ne obuhvaća: stavke računa i evidencije PDV-a za protekla razdoblja (zadržite ih u starom sustavu ili njegovoj arhivi), povijest obračuna plaća te dokumente koji nisu računi (narudžbe, otpremnice, ugovori).