Siirtyminen toisesta järjestelmästä

Kun yritys siirtyy Nordletiin toisesta taloushallinnon ohjelmistosta, sen kirjanpito ei ala nollasta. Historiasietäjä ottaa kaiken vanhasta järjestelmästä jäävän ja tallentaa sen yhdellä kutsulla ja yhdellä tietokantatapahtumalla (database transaction): jos yksikin rivi epäonnistuu tarkistuksessa, mitään ei tallenneta. Sama paketti voidaan ajaa ensin pelkän tarkistuksen rajapinnan (endpoint) kautta, joka suorittaa kaikki validoinnit ja palauttaa muutokset (rollback).

POST /v1/migration/books/validate   # tarkistaa kaiken, ei kirjoita mitään
POST /v1/migration/books/import     # kirjoittaa kaiken tai ei mitään

Verkkosovelluksesta löytyvät samat kaksi painiketta kohdasta Tili (Account) → Siirri tiedot (Migration) (liitä JSON tai lataa tiedosto). API-avaimella on oltava oikeus ledger:write sekä kaikkien sisällyttämiesi osioiden kirjoitusoikeus (partners:write, catalog:write, sales:write, purchases:write, assets:write, inventory:write). Molemmat rajapinnat hyväksyvät enintään 32 Mt:n kokoiset pyynnön rungot (bodies).

Siirtymäpäivä (cut-over date)

Valitse siirtymäpäivä: ensimmäinen päivä, jolloin yrityksen kirjanpitoa pyöritetään Nordletissa. Kaikki tätä edeltävä jää vanhaan järjestelmään (tai tuodaan historiana, katso alta); kaikki tästä päivästä eteenpäin kirjataan Nordletiin normaalien rajapintojen kautta. Kaikki paketin summat ovat "siirtymäpäivää edeltävän päivän tilanteen mukaisia": pääkirjan loppusaldo, vielä maksamattomat laskut, hyllyssä oleva varasto ja rekisterissä olevat käyttöomaisuushyödykkeet.

Tee ennen tuontia seuraavat toimenpiteet Nordletissa:

1. Luo yritys ja ota käyttöön tilikarttamalli (ledger/accounts/apply-template) tai luettele tarvittamasi tilit paketin accounts-osiossa.
2. Luo vähintään yksi varasto (inventory/warehouses/create), jos tuot varastoa.
3. Aja paketti rajapinnan migration/books/validate kautta, kunnes se ei ilmoita virheistä ja olet hyväksynyt sen varoitukset.

Paketti

Jokainen osio on valinnainen; sisällytä ne, jotka sinulla on. Kaikki osioiden väliset viittaukset tehdään koodilla (tilikoodi, kumppanikoodi, nimikekoodi, käyttöomaisuusryhmän koodi, varastokoodi). Koodi voi viitata joko Nordletissa jo olevaan tietueeseen tai saman paketin aiemmassa osiossa luotuun tietueeseen.

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

Summat ovat desimaalimerkkijonoja, kuten kaikkialla API:ssa. source on vapaamuotoinen tunniste, joka tallentuu alkusaldotapahtuman kuvaukseen ja siirrettyjen laskujen huomautuksiin.

accounts

Tilikartan rivit: code, name, type (asset, liability, equity, income, expense), valinnaiset parentCode ja isPostable. Olemassa olevia koodeja ei muuteta, ja ne lasketaan tilastoon existing. Käytä tätä, kun vanhan järjestelmän tilikartta poikkeaa mallista, tai ohita tämä ja ota malli käyttöön ensin.

partners ja items

Asiakkaat, toimittajat ja tuoterekisterin nimikkeet, joita haetaan code-tunnisteella. Liettuassa kumppanikoodi on tavallisesti yritystunnus (company registry code); luonnollisille henkilöille voi käyttää mitä tahansa koodia, joka on yksilöllinen yrityksen sisällä. Olemassa olevat koodit ohitetaan, niitä ei päivitetä. Nimikkeet hyväksyvät kentät type (product tai service), unit, barcode, vatRatePercent, salePriceExclVat, purchasePriceExclVat.

openingBalances

Vanhan järjestelmän pääkirjan loppusaldo, yksi rivi per tili: accountCode ja joko debit tai credit. Rivit kirjanpidollistetaan yhtenä pääkirjatapahtumana (journal transaction), jonka päivämäärä on openingBalances.date (oletuksena siirtymäpäivä) ja asiakirjatyyppi migration_opening. Rivien on viitattava tileille, joille voidaan kirjata.

Tapahtuman on oltava tasapainossa. Jos vanhan järjestelmän saldoissa on epätasapainoa pyöristysten, pääomaan sulkemattoman tuloksen tai puuttuvan tilin vuoksi, määritä balancingAccountCode (yleensä edellisten tilikausien voitto/tappio, Liettuan mallissa 3410), jolloin erotus kirjataan sinne. Vastaus ilmoittaa summan kentässä balancingAmount.

Yritystä kohden voi olla vain yksi alkusaldotapahtuma. Toinen tuonti openingBalances-tiedoilla hylätään (409). Jälkikäteen tehtävät korjaukset ovat tavallisia manuaalisia pääkirjan kirjauksia (ledger/journal/transactions/create); kirjatut tapahtumat ovat muuttumattomia, joten alkuperäinen pysyy sellaisenaan kuin se tuotiin.

journal - koko historia saldojen sijasta tai niiden lisäksi

Jos haluat vanhan järjestelmän tapahtumat Nordletiin (jotta aiempien kausien raportit toimivat), lähetä ne täällä: yksi objekti per tapahtuma, joka sisältää kentät date, valinnaiset description ja reference, sekä entries-taulukon, jossa on accountCode sekä debit/credit. Jokaisen tapahtuman on oltava erikseen tasapainossa. Ne kirjataan asiakirjatyypillä migration.

Päivämäärien on oltava ennen siirtymäpäivää. Kun paketissa on myös openingBalances, historiallisten tapahtumien on oltava päivätty vähintään openingBalances.date-päivälle. Tavallinen toimintatapa on tuoda edellisen tilikauden alun saldot sekä kyseisen tilikauden tapahtumat siten, että siirtymäpäivä on kuluvan tilikauden ensimmäinen päivä. Älä lähetä saldoja ja historiaa samalle ajanjaksolle, sillä saldot laskettaisiin muussa tapauksessa kahdesti.

Jokaisen alkusaldojen tai historian koskettaman kuukauden on oltava avoin tilikausi (muussa tapauksessa palautetaan 409).

openReceivables ja openPayables

Laskut, jotka olivat siirtymäpäivänä edelleen maksamattomia (kokonaan tai osittain). Ne luodaan lähetettyinä myyntilaskuina ja kirjattuina ostolaskuina, joille on määritetty paidAmount = grossTotal − outstanding. Tämän ansiosta pankkitäsmäytys (bank/transactions/match, bank/transactions/suggest-matches), saatavien ikääntymisraportti ja maksuihin liittyvät verkkohaukat (webhooks) toimivat näillä laskuilla samalla tavalla kuin millä tahansa muulla laskulla.

• outstanding:n oletusarvo on grossTotal; vatTotal:n oletusarvo on 0 (veroton summa lasketaan johdannaisesti).
• dueDate:n oletusarvo on asiakirjan päivämäärä.
• currency:n oletusarvo on yrityksen laskutusvaluutta. Muille kuin yrityksen perusvaluutalle vaaditaan fxRate (kyseisen valuutan yksikkömäärä per 1 perusvaluutan yksikkö, sama käytäntö kuin muualla API:ssa). Kurssi tallennetaan laskuun, jotta myöhemmät maksut osaavat laskea toteutuneen kurssieron oikein.
• Myyntilaskun number on vanhan järjestelmän koko numero, ja sen on oltava yrityksessä yksilöllinen. Ostolaskut ovat yksilöllisiä kumppanikohtaisesti kentän documentNumber kanssa.
• Laskuja ei kirjata uudelleen: niiden saamis- tai velkasaldo on jo osa alk saldoja. Ne linkitetään alkusaldotapahtumaan, minkä vuoksi openPayables edellyttää openingBalances-tietoja samassa paketissa.
• Laskun rivejä ei tuoda; laskulla on vain kokonaissummat. Vanha järjestelmä säilyy rivitietojen ja siirtymäpäivää edeltävien kausien arvonlisäverorekisterien lähteenä.

Jos vanha järjestelmä seurasi asiakassaldoja ilman avoimia laskuja, luo saldoa kohden yksi lasku kumppania kohti (esimerkiksi numerolla OB-301111222), jotta sen voi kuitata.

Numerointi jatkuu. Kun tuodulla myyntilaskun numerolla on muoto PREFIX-N ja sen laskutuspäivä osuu siirtymäpäivän vuodelle, kyseisen etuliitteen ja vuoden numerosarja asetetaan arvoon N + 1 (sitä ei koskaan pienennetä). Vastaus luettelee tuloksena syntyvät kentät numberSeries; muissa tapauksissa aseta sarja itse rajapinnalla reference/series/create ({ documentType: "sale_invoice", prefix, year, startAt }).

assetGroups ja fixedAssets

Käyttöomaisuus tuodaan sen senkertaisten poistojen kanssa: acquisitionCost, salvageValue, accumulatedDepreciation, depreciatedMonths ja usefulLifeMonths (tai ryhmän oletusarvo). Tasapoistojen ajo (assets/depreciation/post) jatkuu jäljellä olevasta arvosta jäljellä olevien kuukausien ajan. Hyödykkeet, joiden kertyneet poistot vastaavat jo poistettavaa arvoa, luodaan tilassa fully_depreciated. Mitään ei kirjata - hankintameno ja kertyneet poistot ovat osa alkusaldoja.

Ryhmiä haetaan code-tunnisteella, ja ne vaativat kentät assetAccountCode ja depreciationAccountCode (oletuskulutilinä toimii 6206).

stock

Varastosaldo nimikkeittäin: itemCode, quantity, unitCost (yksikkökustannus euroina) ja valinnaisesti warehouseCode (oletus: oletusvarasto), lotNumber ja expiryDate erä- tai sarjanumeroseuratuille nimikkeille. Jokaisesta rivistä tulee siirtymäpäivälle päivätty saapuva varastotapahtuma asiakirjatyypillä migration, ja se aloittaa FIFO-kerroksen kyseisellä hankintahinnalla. Mitään ei kirjata - varaston arvo on osa alkusaldoja.

Tarkistukset ja varoitukset

Tarkistusrajapenteri (validate) epäonnistuu (422), jos tilejä puuttuu, tileille ei voi kirjata, tapahtumat eivät ole tasapainossa, tunnistamattomia kumppanin, nimikkeen, ryhmän tai varaston koodeja esiintyy, paketissa on kaksoiskappaleita koodeista tai numeroista, avoimet summat ylittävät kokonaissumman, kertyneet poistot ylittävät poistettavan arvon tai valuuttakurssit puuttuvat. Numerot tai koodit, jotka ovat jo olemassa Nordletissa, palauttavat virheen 409.

Sen lisäksi molemmat rajapinnat vertaavat osakirjanpitoja saman paketin pääkirjan kirjauksiin ja palauttavat erotukset warnings-taulukossa virheiden sijaan:

• openReceivables-tietojen yhteenlaskettu avoin saldo suhteessa saamistilin saldoon (sales.receivable-kirjaussääntö, oletuksena 2410);
• openPayables-tietojen yhteenlaskettu avoin saldo suhteessa velkatilin saldoon (purchases.payables, 4430);
• stock-tietojen yhteenlaskettu hankintameno suhteessa varastotiliin (inventory.stock, 2040);
• käyttöomaisuusryhmittäin hyödykkeiden hankintamenot suhteessa ryhmän käyttöomaisuustiliin ja niiden kertyneet poistot suhteessa poistotiliin.

Varoitus tarkoittaa, että vanhan järjestelmän osakirjanpito ja pääkirja ovat erimielisiä. Korjaa paketti (tai hyväksy erotus tietoisesti) ennen tuontia.

Vastaus

{
  "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 merkitsee testiajoa (validate); tällöin journalTransactionId on null. Varsinainen tuonti tallennetaan auditointilokiin (audit log) nimellä migration.imported samojen yhteenvetotietojen kera.

Tuonnin jälkeen

• Lukitse siirtymäpäivää edeltävät kaudet (ledger/periods/lock), jotta siirrettyyn historiaan ei kirjata mitään vahingossa.
• Tarkista pääkirjan loppusaldo ja tase siirtymäpäivän tilanteen osalta vanhan järjestelmän loppuraportteja vasten.
• Jatka normaalilla prosessilla: lähetä laskuja, tuo tiliotteita, täsmäytä maksuja - siirretyt avoimet laskut kuitataan kuten mitkä tahansa muutkin laskut.

Mitä siirtäjä ei kata: menneiden kauksien laskurivit ja arvonlisäverorekisterit (pidä ne vanhassa järjestelmässä tai sen arkistossa), palkkahistoria sekä muut asiakirjat kuin laskut (tilaukset, rahtikirjat, sopimukset).