Accounting and dimensions use cases

Accounting and cost objects – use case guide

This guide explains how to import and maintain accounting vouchers (tositteet) through the Netvisor API, how to read accounting data back into your own system, and how to manage cost objects (laskentakohteet), which the API calls dimensions. For element-level details, see the API reference.

The Finnish UI term is shown in italics after the English description, for example voucher type (Tositelaji).

Resources

Area	Resource	Method	Purpose
Vouchers	accounting.nv	POST	Import a new voucher
	accountingedit.nv	POST	Edit an existing voucher
	invalidatevouchers.nv	POST	Invalidate (mitätöidä) vouchers
	accountingledger.nv	GET	Get vouchers with their lines
	getvoucherattachments.nv	GET	Get voucher attachments
	deletedvouchers.nv	GET	List deleted vouchers
Reference data	accountlist.nv	GET	Chart of accounts (tililuettelo)
	vouchertypelist.nv	GET	Voucher types (tositelajit)
	accountingperiodlist.nv	GET	Accounting periods (tilikaudet) and period locks
	getbankaccounts.nv	GET	The company's bank accounts (pankkitilit)
	getaccountdimensionlist.nv	GET	Account follow-up objects (seurantakohteet)
	accountbalance.nv	GET	Account balances on given dates
Financial obligations	financialobligationstatus.nv	GET	Status of VAT returns, ledger reconciliations, income tax return and accounting periods
Account follow-up	settransactionallocation.nv	POST	Attach or detach allocations between voucher lines
	settransactionfollowupstatus.nv	POST	Open or close follow-up on voucher lines
Corporation groups	vouchercorporationevent.nv	POST	Mark voucher lines as corporation group events (konsernitapahtumat)
Cost objects (dimensions)	dimensionlist.nv	GET	List cost object headers (laskentakohdeotsikot) and cost objects (laskentakohteet)
	dimensionitem.nv	POST	Create or edit a cost object
	dimensiondelete.nv	POST	Hide a cost object

Use case: import a voucher

accounting.nv imports one voucher per request, with its lines, line cost objects and attachments. The response returns the new voucher's Netvisor key. Store it if you need to edit or invalidate the voucher later.

Transaction fee: importing a voucher with attachments through the API is charged per voucher. On the service invoice, the charge is shown as an e-scan charge.

Before you start

Accounts: every account used on the voucher must exist in Netvisor; otherwise INVALID_DATA is returned with an explanation. Get the chart of accounts with accountlist.nv.
Voucher type: give the voucher type with its full name, not its abbreviation. List the company's voucher types with vouchertypelist.nv. Users can also add their own voucher types in Netvisor.
Period locks: check the accounting period lock dates with accountingperiodlist.nv before posting to past periods.

Netvisor's built-in voucher types:

Voucher type (`voucherclass`)	Abbreviation	English
Myyntilasku	ML	Sales invoice
Myyntisuoritus	MS	Sales payment
Pankki	PT	Bank
Kassa	KT	Cash
Tuodut tapahtumat	PUMP	Imported transactions
Automaattiset tilinpäätöskirjaukset	T	Automatic year-end entries
Järjestelmän muodostamat	AT	System-generated
Muut	MU	Other
Ostolasku	OL	Purchase invoice
Ostosuoritus	OS	Purchase payment
Jaksotukset	JK	Accruals
Palkka	PA	Payroll

Calculation mode: gross or net

The calculation mode (laskentatapa) is chosen per voucher with calculationmode:

`calculationmode`	Behaviour
`gross` (brutto)	Netvisor always calculates the VAT lines and rounding difference lines (pyöristyserot) automatically. If debits and credits do not balance, the difference is posted to rounding differences.
`net` (netto)	Netvisor does not calculate VAT or rounding difference lines. The voucher is saved exactly as given, so debits and credits do not necessarily balance.

Vouchers are always double-entry: a positive line sum is posted to debit and a negative line sum to credit. Especially with the net calculation mode, your integration is responsible for making sure the voucher complies with bookkeeping rules.

Voucher header

Element	Netvisor UI name	Notes
`calculationmode`	Laskentatapa	`gross` or `net`. Required.
`voucherdate`	Tositteen päiväys	Voucher date, `format="ansi"`. Required.
`voucherclass`	Tositelaji	Voucher type by full name. Required.
`number`	Tositenumero	Voucher number, max 9 digits. If not given, Netvisor uses the next number of the voucher type.
`description`	Kuvaus	Description, max 255 characters.
`checked`	–	`true` or `false` (default). Determines whether the voucher appears among unchecked postings (tarkastamattomat tiliöinnit).
`comment`	Kommentti	Comment shown in the voucher's processing history (käsittelyhistoria), max 255 characters.

Voucher lines

At least one voucher line (voucherline) is required.

Element	Netvisor UI name	Notes
`linesum`	Rivisumma	Line sum with two decimals. Positive = debit, negative = credit. `type` is `net` (excluding VAT) or `gross` (including VAT).
`accountnumber`	Tilinumero	Account number. Must exist in Netvisor. Required.
`vatpercent`	ALV-prosentti	VAT percentage. Required. Must not conflict with the VAT code.
`vatcode` attribute	ALV-koodi	If not given, the VAT code is taken from the account. If given, it is always used. A VAT code that conflicts with the VAT percentage returns an error.
`description`	Kuvaus	Line description, max 255 characters.
`accountdimension`	Seurantakohde	Account follow-up object. `type="name"` (by name; the object must already exist in Netvisor) or `type="netvisorkey"`. Follow-up objects are listed by getaccountdimensionlist.nv.
`dimension`	Cost object (Laskentakohde)	One line can have several cost objects. If the cost object header (Laskentakohdeotsikko) or cost object does not exist, it is created. See "How to refer to a cost object in a message" below. When `dimensionitemcode` or `dimensionitemname` is given, `dimensionitem` is ignored.

Attachments

Several attachments can be added in voucherattachments, each with a MIME type, description, file name and the file as Base64 in documentdata. The API does not check attachment size, but the maximum total size of attachments is 2 GB.

Example

The account numbers and VAT codes in this example are illustrative; use the accounts and VAT codes of the company.

<root>

<description>Office rent November</description>

<description>Office rent</description>

</voucherline>

<description>Office rent</description>

</voucherline>

</voucher>

</root>

Use case: edit a voucher

accountingedit.nv edits one existing voucher, identified by its Netvisor key (netvisorkey). Find the key with accountingledger.nv.

Header: you can change the calculation mode, date, number, description, voucher type and comment. Header elements are optional; send only those you want to change. Changes to header data are not currently recorded in the voucher's history.
Lines: if the message contains voucher lines, the voucher's existing lines are invalidated and the lines in the message are added to the voucher as new lines. If the message contains no lines, the existing lines are left unchanged.
When lines are given, each line requires linesum with its type, description, accountnumber, and vatpercent with the vatcode attribute.
Attachments can also be added to the voucher.

Use case: invalidate vouchers

invalidatevouchers.nv invalidates (mitätöi) one or more vouchers. Invalidated vouchers remain in the ledger but are marked as void.

Element	Notes
`identifier` attribute	How the vouchers are identified: `netvisorkey` or `guid`.
`invalidatevoucher`	The Netvisor key (or GUID) of a voucher to invalidate. Up to 100 vouchers per request.
`comment`	Optional comment, max 255 characters. Shown in the processing history of the invalidated vouchers before the invalidation entry. An invalidation entry is always added to the history, even without a comment.

Use case: read accounting data

Vouchers

accountingledger.nv returns vouchers with their lines and cost objects. At least one of the following is required: netvisorkey, netvisorkeylist (up to 500), startdate + enddate, changedsince, lastmodifiedstart or lastmodifiedend.

Parameter	Use
`startdate` / `enddate`	Voucher date range.
`changedsince`, `lastmodifiedstart` / `lastmodifiedend`	Vouchers modified within a time window. Extend the search range backwards to catch vouchers edited before the desired range. A voucher missing from a range query can be fetched by its Netvisor key.
`accountnumberstart` / `accountnumberend`	Account number range.
`voucherstatus`	1 = all, 2 = valid (default), 3 = invalidated and deleted.
`vouchertype`	Voucher type by Netvisor key (from `vouchertypelist.nv`). Requires a date range or `lastmodified` parameters.
`showgenerator`	1 = include the user who created the voucher.
`includetransactionhistory`	1 = include the voucher's processing history (max 500 vouchers per request).
`includeattachmentsmetadata`	1 = include attachment metadata (max 500 vouchers per request). Fetch the files with getvoucherattachments.nv.
`includetransactionallocations`	1 = include account follow-up allocations of the voucher lines.

Use deletedvouchers.nv with deletedsince to keep your system in sync with vouchers deleted in Netvisor.

Reference data and balances

Resource	Returns
accountlist.nv	The full chart of accounts and the company's default accounts used in default postings.
accountingperiodlist.nv	The company's accounting periods and the current lock dates for accounting, VAT and purchases. It does not tell which period is active.
vouchertypelist.nv	All voucher types and the default voucher types for built-in document categories.
getbankaccounts.nv	The company's bank accounts with IBAN, BIC, currency and linked accounting account.
getaccountdimensionlist.nv	Account follow-up objects and the accounts linked to each.
accountbalance.nv	Account balances on given dates (`balancedates`), optionally as a daily, weekly, monthly or yearly series (`intervaltype`). Without account keys, all accounts are returned.

Use case: account follow-up and corporation groups

settransactionallocation.nv attaches (attach) or detaches (detach) allocations between voucher lines in account follow-up, identified by the voucher lines' Netvisor keys. Within a request, detach actions are processed before attach actions. Up to 100 entries per request.
settransactionfollowupstatus.nv sets the follow-up status of voucher lines to open or close. Up to 1,000 voucher line keys per request.
vouchercorporationevent.nv marks voucher lines as corporation group events (konsernitapahtumat) targeting another company in the group, identified by its business ID (Y-tunnus). The voucher and lines are identified by Netvisor key or GUID. Both companies must belong to the same corporation group.

Use case: monitor financial obligations

financialobligationstatus.nv returns the status of the company's financial obligations (taloushallinnon velvoitteet) for a period: VAT returns, the VAT summary report, ledger reconciliations, the income tax return and the status of accounting periods.

Parameter	Notes
`StartMonth`	First month of the range, `YYYY-MM`. If both parameters are omitted, the previous month is returned.
`EndMonth`	Last month of the range (inclusive), `YYYY-MM`. Requires `StartMonth`. The range can be at most 24 months.

The response contains a Months block with one Month per month in the range and a Years block with one Year per calendar year the range touches.

Monthly data (`Month`)

VAT return (VATReport, ALV-ilmoitus). The element is empty for months with no filing yet.

Element	Notes
`FilingDate`	Date the VAT return was filed.
`Status`	Status of the VAT return, see below.
`TaxPeriod`	VAT reporting period: `Month`, `Quarter` or `Year`.
`PayableAmount`	Amount of VAT payable.
`GeneratedBankTransfers`	Bank transfers generated for the VAT payment, each with due date, amount and status (`Unprocessed`, `Processing`, `Processed`, `Paid`, `Error` or `Unknown`).

VAT return `Status`	Meaning
`Sent`	The VAT return has been sent electronically.
`MonthsFirst`	The first return generated for the month.
`Replacing`	A replacing return that replaces a previously sent return.
`MarkAsSent`	Manually marked as sent: the return has been handled outside Netvisor, for example filed directly in OmaVero.
`Errorneous`	An error occurred when sending the return. Requires corrective action.
`Invalidated`	The return has been invalidated.
`Unknown`	Unknown status.

Ledger reconciliations (Reconciliations, täsmäytykset). Always included, with a SalesLedger block for the sales ledger (myyntireskontra) and a PurchaseLedger block for the purchase ledger (ostoreskontra):

Element	Meaning
`DeviatingVouchers`	Number of deviating vouchers.
`DeviatingPayments`	Number of deviating payments.
`SourceEndBalance`	The ledger's end balance at the end of the month.
`BookkeepingEndBalance`	The end balance in bookkeeping. If it differs from `SourceEndBalance`, the ledger and bookkeeping do not match.

Yearly data (`Year`)

Block	Content
`VATSummaryReport` (yhteenvetoilmoitus)	The latest sent summary report period, its status (`UnProcessed`, `NotReady`, `Ready`, `Sent`, `MarkedAsSent` or `Unknown`) and the total of its lines (0.00 if there are no lines).
`IncomeTaxReport` (tuloveroilmoitus)	`Sent` if an approved income tax return exists for the year, otherwise `Unsent`.
`FiscalYearStatus` (tilikauden tila)	Status of the accounting period, see below.

Accounting period `Status`	Meaning
`Open`	The period is open for postings.
`Locked`	The period is locked; changes are not allowed without unlocking it.
`SealedUnderGeneration`	Intermediate state: the period is being closed (financial statements are being generated).
`Sealed`	The period has been closed. A stronger state than locked.
`Validated`	An accountant has checked and confirmed the period.
`Audited`	The period has been audited. Final state.
`Unknown`	Unknown status.

Payroll obligations are monitored with a separate resource, payrollobligationstatus.nv.

Use case: manage cost objects (dimensions)

Cost objects (laskentakohteet) consist of a cost object header (laskentakohdeotsikko, for example "Kustannuspaikka", cost centre) and the cost objects (laskentakohde) under it, for example "KP1". Cost objects can be arranged in a hierarchy. In the API, cost objects are called dimensions: the elements are named dimension, dimensionname, dimensionitem and so on.

Many import resources (vouchers, sales and purchase invoices, products, customers) create missing cost object headers and cost objects automatically when they are referenced.

How to refer to a cost object in a message

This section explains, step by step, how a cost object is given in an import message and how it is returned in responses. The same dimension structure is used in every import message that contains cost objects: vouchers, sales and purchase invoices, purchase invoice posting data, sales payments, products, customers, employees, payroll, travel expenses and working hours.

The fields in the Netvisor UI

In Netvisor, a cost object is edited in the Edit cost object view (Muokkaa laskentakohdetta), which has the following fields:

Netvisor UI field	Meaning	Example
Cost object header (Laskentakohdeotsikko)	The header the cost object belongs to.	Kustannuspaikka
Cost object's name (Laskentakohteen nimi)	The name of the cost object.	KP1
Cost object's identifier (Laskentakohteen tunniste)	An optional identifier (code) of the cost object. Can be empty.	1234
Cost object's parent (Laskentakohteen ylätaso)	Where the cost object is in the hierarchy: directly under the header, shown as "Kustannuspaikka (Header)" (Kustannuspaikka (Otsikko)), or under another cost object.	Kustannuspaikka (Header)
Validity period (Voimassaoloaika)	Active for now (Voimassa toistaiseksi) or Inactive (Ei voimassa): the cost object is hidden from the menu (Laskentakohde piilotetaan valikosta).	Active for now

If a cost object has a cost object's identifier (Laskentakohteen tunniste), Netvisor forms its full name from the identifier and the name separated by a space, for example 1234 KP1. If the cost object has no identifier, the full name is just the name, for example KP1.

How the UI fields map to the API

Netvisor UI field	In import messages (`dimension`)	In `dimensionitem.nv`	In responses
Cost object header (Laskentakohdeotsikko)	`dimensionname`	`name`	`DimensionName`
Cost object's name (Laskentakohteen nimi)	`dimensionitemname`	`label`	`DimensionItemName` (`Label` in `dimensionlist.nv`)
Cost object's identifier (Laskentakohteen tunniste)	`dimensionitemcode`	`code`	`DimensionItemCode` (`Code` in `dimensionlist.nv`)
Full name (identifier + name)	`dimensionitem`	`item`	`DimensionItem` (`Name` in `dimensionlist.nv`)
Cost object's parent (Laskentakohteen ylätaso)	–	`fatherid` / `fatheritem`, or `fathercode` / `fatherlabel`	`FatherID` and `Level` in `dimensionlist.nv`
Validity period (Voimassaoloaika)	–	`ishidden`	`IsHidden` in `dimensionlist.nv`

The cost object's parent (Laskentakohteen ylätaso) and validity period (Voimassaoloaika) are managed with dimensionitem.nv and dimensiondelete.nv, not in the dimension element of other messages.

There are therefore two ways to give a cost object in a message:

Option	Elements	Use when
A – Legacy: header + cost object	`dimensionname` + `dimensionitem`	The cost object has no cost object's identifier (Laskentakohteen tunniste).
B – Current: header + identifier + name	`dimensionname` + `dimensionitemcode` + `dimensionitemname`	The cost object has a cost object's identifier (Laskentakohteen tunniste), or you want to give the identifier and name as separate fields.

dimensionname, the cost object header (Laskentakohdeotsikko), is always required. When dimensionitemcode or dimensionitemname is given, dimensionitem is ignored, so do not mix the two options in the same dimension element.

Option A – legacy: cost object header + cost object

Use this for a cost object that has no identifier. In this example, the cost object header (Laskentakohdeotsikko) is "Kustannuspaikka", the cost object's name (Laskentakohteen nimi) is "KP1" and the cost object's identifier (Laskentakohteen tunniste) is empty:

<dimensionname>Kustannuspaikka</dimensionname>

</dimension>

If the cost object header or cost object does not exist, it is created (unless the resource's useonlyexistingdimensions parameter prevents this). A cost object created this way has a name but no identifier.

Option B – current: cost object header + cost object's identifier + cost object's name

Use this for a cost object that has an identifier. Give the identifier and the name in separate elements, exactly as they appear in the UI fields. In this example, the cost object's identifier (Laskentakohteen tunniste) is "1234":

<dimensionname>Kustannuspaikka</dimensionname>

</dimension>

Here dimensionitemcode corresponds to the cost object's identifier (Laskentakohteen tunniste) and dimensionitemname to the cost object's name (Laskentakohteen nimi). Do not give the full name 1234 KP1 in dimensionitemname.

Creating the cost object with `dimensionitem.nv`

The same distinction applies when you create cost objects in advance with dimensionitem.nv. A cost object without an identifier:

<root>

<name>Kustannuspaikka</name>

</dimensionitem>

</root>

A cost object with an identifier (code and label override item). This creates the cost object shown in the UI example: directly under the header, so the cost object's parent (Laskentakohteen ylätaso) is "Kustannuspaikka (Header)", and active, so the validity period (Voimassaoloaika) is "Active for now" (Voimassa toistaiseksi):

<root>

<name>Kustannuspaikka</name>

<ishidden>false</ishidden>

</dimensionitem>

</root>

To create a cost object one level lower, under KP1, give the parent cost object's identifier and name in fathercode and fatherlabel. The new cost object's parent (Laskentakohteen ylätaso) is then KP1:

<root>

<name>Kustannuspaikka</name>

</dimensionitem>

</root>

What the API returns for a cost object that has an identifier

dimensionlist.nv returns the full name in Name and the identifier and name separately in Code and Label:

<Name>Kustannuspaikka</Name>

<IsHidden>False</IsHidden>

<IsHidden>False</IsHidden>

</DimensionDetail>

</DimensionDetails>

</DimensionName>

</DimensionNameList>

In dimensionlist.nv, IsHidden shows the validity period (Voimassaoloaika): False = Active for now (Voimassa toistaiseksi), True = Inactive (Ei voimassa). Level and FatherID show the cost object's parent (Laskentakohteen ylätaso); in this example the cost object is directly under the header ("Kustannuspaikka (Header)"), so both are 0.

When the same cost object is used on a voucher line, invoice line or customer, responses such as accountingledger.nv and getcustomer.nv return it like this:

<DimensionName>Kustannuspaikka</DimensionName>

</Dimension>

DimensionName contains the cost object header (Laskentakohdeotsikko).
DimensionItem contains the full name (identifier + space + name).
DimensionItemName contains only the cost object's name (Laskentakohteen nimi).
DimensionItemCode contains only the cost object's identifier (Laskentakohteen tunniste). It is omitted when the cost object has no identifier; DimensionItem then contains just the name.

Tip: to send a cost object back to Netvisor that you have read from a response, use DimensionItemCode → dimensionitemcode and DimensionItemName → dimensionitemname. Do not copy DimensionItem into dimensionitemname, because for cost objects with an identifier it contains the full name, not the cost object's name (Laskentakohteen nimi).

List cost objects

dimensionlist.nv returns cost object headers (laskentakohdeotsikot) and their cost objects (laskentakohteet). By default only active rows are returned; showhidden=1 also includes hidden headers and cost objects, that is, cost objects whose validity period (Voimassaoloaika) is Inactive (Ei voimassa).

Create or edit a cost object

dimensionitem.nv creates (method=add) or edits (method=edit) one cost object per request. The cost object header (Laskentakohdeotsikko) must already exist in Netvisor. Service and sector classification headers are read-only and cannot be edited.

Element	Netvisor UI name	Notes
`name`	Cost object header (Laskentakohdeotsikko)	The header under which the cost object is created. Required.
`item`	Cost object (Laskentakohde)	The cost object's full name, max 200 characters.
`code` / `label`	Cost object's identifier (Laskentakohteen tunniste) / cost object's name (Laskentakohteen nimi)	Identifier (max 50 characters) and name (max 200 characters). When given, they override `item`.
`olditem`		Edit: the current name of the cost object to edit, wherever it is in the hierarchy.
`oldcode` / `oldlabel`		Edit: the current identifier and name of the cost object to edit. When given, they override `olditem`.
`integrationdimensiondetailguid`		Edit: the cost object can also be identified by the GUID registered for it earlier.
`fatherid` / `fatheritem`	Cost object's parent (Laskentakohteen ylätaso)	The Netvisor key and name of the parent cost object when adding a cost object under an existing one. Without parent elements, the cost object is created directly under the header ("Kustannuspaikka (Header)" / Kustannuspaikka (Otsikko)).
`fathercode` / `fatherlabel`	Cost object's parent (Laskentakohteen ylätaso)	The parent cost object's identifier and name. When given, they override `fatherid`.
`ishidden`	Validity period (Voimassaoloaika)	`false` = Active for now (Voimassa toistaiseksi). `true` = Inactive (Ei voimassa): the cost object is hidden from the menu.
`activityperiodstart` / `activityperiodend`		The cost object's activity period.

Hide a cost object

dimensiondelete.nv hides an existing cost object, so its validity period (Voimassaoloaika) becomes Inactive (Ei voimassa) and it is hidden from the menu. The cost object is not deleted.

Parameter	Notes
`DimensionName`	The cost object header (Laskentakohdeotsikko) that owns the cost object. Case-sensitive. Required.
`dimensionsubname`	The cost object's full name: its identifier and name separated by a space, for example `1234 KP1` (a cost object without an identifier is just its name, for example `KP1`). When given, `dimensionsubcode` and `dimensionsublabel` are ignored.
`dimensionsubcode` / `dimensionsublabel`	The cost object's identifier and name, used when `dimensionsubname` is empty.

Glossary: English – Finnish

English	Finnish (Netvisor UI)
Voucher	Tosite
Voucher line	Tositerivi
Voucher type	Tositelaji
Voucher number	Tositenumero
Voucher date	Tositteen päiväys
Calculation mode: gross / net	Laskentatapa: brutto / netto
Debit / credit	Debet / kredit
Rounding differences	Pyöristyserot
Unchecked postings	Tarkastamattomat tiliöinnit
Processing history	Käsittelyhistoria
Invalidate	Mitätöidä
Chart of accounts	Tililuettelo
Accounting period	Tilikausi
Account follow-up object	Seurantakohde
Corporation group event	Konsernitapahtuma
Financial obligations	Taloushallinnon velvoitteet
VAT return / VAT summary report	ALV-ilmoitus / yhteenvetoilmoitus
Income tax return	Tuloveroilmoitus
Reconciliation	Täsmäytys
Sales ledger / purchase ledger	Myyntireskontra / ostoreskontra
Cost object (API: dimension)	Laskentakohde
Cost object header	Laskentakohdeotsikko
Cost object's name	Laskentakohteen nimi
Cost object's identifier	Laskentakohteen tunniste
Cost object's parent	Laskentakohteen ylätaso
Header (in the parent list)	Otsikko
Validity period	Voimassaoloaika
Active for now	Voimassa toistaiseksi
Inactive (cost object will be hidden from the menu)	Ei voimassa (laskentakohde piilotetaan valikosta)
Edit cost object	Muokkaa laskentakohdetta

Last updated on

Was this page helpful?