Product and inventory guide

Products and inventory – use case guide

This guide explains how to keep Netvisor's product register (tuoterekisteri) in sync with your own system and how to read and update inventory (varasto) through the API. Products are the basis for sales invoice lines, so a correctly maintained product card (tuotekortti) also determines the default prices, VAT rate and accounts used on invoices. For element-level details, see the API reference.

The Finnish UI term is shown in italics after the English description, for example product group (Tuoteryhmä).

Rackbeat inventory management: if the company uses Netvisor's Rackbeat inventory management (Netvisor varasto by Rackbeat), the product and inventory resources in this guide do not apply. Use the Rackbeat API instead.

Resources

Area	Resource	Method	Purpose
Products	productlist.nv	GET	List and search products
	getproduct.nv	GET	Get the full details of one or more products
	extendedproductlist.nv	GET	Get extended product details in pages
	product.nv	POST	Create or update a product
	getproductgroups.nv	GET	List product groups (tuoteryhmät)
	getproductattachment.nv / getproductimage.nv	GET	Get product attachments and images
Structured products	webshopproductlist.nv	GET	Get the structured product list (rakenteellinen tuotelista) for a webshop
	webshopproductimages.nv	GET	Get images of structured products
Inventory	getinventoryplaces.nv	GET	List inventories (varastot) and their shelves
	inventorybywarehouse.nv	GET	Get product balances by inventory (tuotesaldot varastoittain)
	warehouseevent.nv	POST	Import an inventory event (varastotapahtuma)
	warehousereport.nv	GET	Get inventory reports (varastoraportit)

Use case: find a product

Search the product list

productlist.nv returns each product's Netvisor key, product code, name, unit price both excluding VAT (UnitPrice) and including VAT (UnitGrossPrice) with 12 decimals, product group (with the full group hierarchy) and a Uri for fetching the full details. Several parameters can be used at the same time:

Parameter	Use
`keyword`	Products whose name or product code contains the given text.
`changedsince`	Products changed after the given time (`yyyy-MM-ddTHH:mm:ss`). Use this to sync changes made in Netvisor.
`published` / `unpublished`	1 = include published / unpublished products, 0 = exclude them.
`deleted`	1 = return deleted products, 0 = exclude deleted products. If the parameter is not used, deleted products are also returned.

Get full product details

getproduct.nv returns the full product: prices, accounts, inventory details, dimensions, weight and package information. Identify the products with one of:

id (one Netvisor key) or idlist (up to 500 Netvisor keys)
code (one product code) or codelist (up to 500 product codes)
eancode (primary or secondary EAN code).

replyoption 1 returns only active products and 2 only published products. showsubproducts=1 adds the product structure (parent and child products).

Product codes are not unique. Netvisor allows several products with the same product code. Keep this in mind when you search, link or update products by code; the Netvisor key always identifies one product.

Extended product details

extendedproductlist.nv returns product details in pages (page, productsonpage), including translations, prices, purchase information, storage, dimensions, sub-products, images and attachments. Optional sections are selected with the replyoptions bitmask. Without productnetvisorkeys, only published, active products are returned; unpublished products can be fetched by giving their Netvisor keys, and deleted products are never returned.

Use case: create or update a product

product.nv creates a product (method=add) or updates one (method=edit, with the product's Netvisor key in id). The response returns the product's Netvisor key in InsertedDataIdentifier. Find the key of an existing product with productlist.nv.

If method is missing or the product to be updated is not found, the API returns INVALID_DATA with an explanation.
useonlyexistingdimensions=1 prevents Netvisor from creating new dimension names and dimension items automatically. The call then returns an error if a given dimension does not exist.
Extended product management (laajennettu tuotehallinta): new products can be imported through the API, but updating products is not supported for companies using extended product management.

A minimal new product looks like this:

<root>

<productgroup>Books</productgroup>

<name>Example product</name>

</productbaseinformation>

</productbookkeepingdetails>

</product>

</root>

Base information (`productbaseinformation`)

Element	Netvisor UI name	Notes
`productcode`	Tuotekoodi	Product code, max 50 characters.
`productgroup`	Tuoteryhmä	Product group by name. Required. The product is added to the group if it exists; otherwise the group is created.
`name`	Tuotteen nimi	Product name, max 200 characters. Required.
`description`	Kuvaus	Description.
`unitprice`	Yksikköhinta	Unit price. `type` is `net` (excluding VAT) or `gross` (including VAT).
`unit`	Yksikkö	Unit, max 50 characters. Created if it does not exist; otherwise the existing unit is used.
`purchaseprice`	Hankintahinta	Purchase price.
`tariffheading`	Tullinimike	Customs tariff heading.
`comissionpercentage`	Provisioprosentti	Commission percentage.
`isactive`	–	1 = active, 0 = inactive. Required.
`issalesproduct`	Myyntituote	1 = sales product, 0 = not a sales product. Required.
`inventoryenabled`	Varastoitava	1 = stocked product.
`inventorybatchlinkingmode`	Eräkäsittely	Batch handling type, see below.
`countryoforigin`	Alkuperämaa	Country of origin, ISO-3166.
`primaryeancode` / `secondaryeancode`	Ensisijainen / toissijainen EAN-koodi	The `type` attribute (`any`, `ean8`, `ean13` or `code128`) determines how the code's format is validated.
`inventoryalertlimit`	Hälytysraja	Inventory alert limit.

Batch handling types (inventorybatchlinkingmode):

Value	Netvisor UI name
1	No batch handling (Ei eräkäsittelyä)
2	Manual batch selection (Manuaalinen erävalinta)
3	Newest first by delivery date (Toimituspäivän mukaan nuorimmat ensin)
4	Oldest first by delivery date, FIFO (Toimituspäivän mukaan vanhimmat ensin)
5	Newest first by expiry date (Viimeisen käyttöpäivän mukaan uusimmat ensin)
6	Oldest first by expiry date (Viimeisen käyttöpäivän mukaan vanhimmat ensin)
7	Newest first by manufacture date (Valmistuspäiväyksen mukaan uusimmat ensin)
8	Oldest first by manufacture date (Valmistuspäiväyksen mukaan vanhimmat ensin)

Accounting (`productbookkeepingdetails`)

Element	Netvisor UI name	Notes
`defaultvatpercentage`	Alv-kanta	Default VAT rate. Required. If the rate does not exist in Netvisor, an error is returned.
`defaultdomesticaccountnumber`	Kotimaan myyntitili	Domestic sales account.
`defaulteuaccountnumber`	EU-myyntitili	EU sales account.
`defaultoutsideeuaccountnumber`	Yhteisön ulkopuolisen myynnin tili	Sales account for sales outside the EU.

Weight, package, dimensions and custom fields

Element	Netvisor UI name	Notes
`productnetweight` / `productgrossweight`	Nettopaino / Bruttopaino	Net and gross weight.
`productweightunit`	–	Unit of the net and gross weight: `g`, `kg` or `tn`.
`productpackageinformation`	–	Package width, height and length in centimetres.
`dimension`	Laskentakohde	Default dimension. The dimension name (laskentakohdeotsikko) and item are created if needed. When `dimensionitemcode` or `dimensionitemname` is given, `dimensionitem` is ignored.
`productcustomtags`	Lisätietokentät	Custom fields: `tagname`, `tagvalue` and the `datatype` attribute (`date`, `text`, `decimal` or `enum`).

Weight fields: use productnetweight, productgrossweight and productweightunit. The older unitweight element still works for backwards compatibility, but it is not recommended: in the UI, the weight units of all existing products change to kilograms and the weight is shown in the net weight field.

Use case: read inventory balances

Inventories

getinventoryplaces.nv returns the company's active inventories (varastot) with their Netvisor keys, names and shelves. You need the inventory keys or names when filtering balances and importing inventory events.

Balances by inventory

inventorybywarehouse.nv returns product balances per inventory. Filter with:

Parameter	Use
`productid` / `productidlist`	One product or a comma-separated list of products (Netvisor keys).
`inventoryplaceid` / `inventoryplacename`	One inventory, by Netvisor key or name.
`limitvendorid`	Products of one vendor.
`changedsince`	Balances changed after the given time.
`limitunderalertlimit`	1 = only products below their inventory alert limit (hälytysraja).
`productgroupname`	Products in one product group.

For example, inventorybywarehouse.nv?inventoryplaceid=321&limitunderalertlimit=1 returns all products below the alert limit in the inventory with the key 321.

The response contains, for each product and inventory:

Element	Netvisor UI name	Meaning
`ReservedAmount`	Varattu	Reserved from this inventory.
`OrderedAmount`	Tulossa	Ordered to this inventory (incoming).
`InventoryAmount`	–	Open balance in this inventory, excluding reserved and incoming quantities.
`TotalReservedAmount`, `TotalOrderedAmount`, `TotalAmount`	–	The same figures for the product across all inventories.

For more product details, use getproduct.nv with the product's Netvisor key.

Use case: import an inventory event

warehouseevent.nv imports one inventory event (varastotapahtuma) with one or more lines. The whole event is saved at once: if any line fails validation, the entire request is rejected. Inventory management must be in use in the company, and the API user needs write access.

Event header

Element	Netvisor UI name	Notes
`reference`	Viite	Reference, max 50 characters. Required.
`description`	Kuvaus	Description of the event.
`deliverymethod`	Toimitustapa	Must match a delivery method defined in Netvisor.
`distributer`	Toimittaja	Vendor, `type="netvisor"` (Netvisor key) or `type="customer"` (vendor name).

Event lines

Element	Netvisor UI name	Notes
`eventtype`	–	Must match an event type defined in Netvisor, for example Hankinta, Myynti, Inventointi, Korjaus, Varastosiirto or Valmistus. `type` is currently always `customer`.
`product`	Tuote	`type="netvisor"` (Netvisor key) or `type="customer"` (product code).
`inventoryplace`	Varasto	Inventory by name, which must match the inventory's description field in Netvisor, or by Netvisor key with `type="netvisor"`.
`description`	Kuvaus	Line description.
`quantity`	Kappalemäärä	Quantity.
`unitprice`	Yksikköhinta	Unit price excluding VAT.
`valuedate`	Päiväys	Date of the event, `format="ansi"`.
`status`	Tila	See below.

`status`	Netvisor UI status	Meaning
`open`	Avoin	Shown in orders.
`handled`	Käsitelty	Shown in inventory.
`bypassed`	Ohitettu	Bypassed.

Use case: inventory reports

warehousereport.nv returns one of three reports, selected with the required report parameter:

`report`	Content
`ProductInventoryAmounts`	Inventory amounts per product, with a breakdown per inventory.
`SalesInventoryEvents`	Sales-side inventory events grouped by sales invoice or sales order. `salesentitytype` (`salesinvoice` or `salesorder`) is required.
`PurchaseOrderInventoryEvents`	Purchase-side inventory events grouped by purchase order.

The report resource requires inventory management, structured products and purchase order handling to be in use in the company.

Use case: structured products for a webshop

If the company uses structured products (rakenteelliset tuotteet), webshopproductlist.nv returns the product catalogue as configured for the webshop: main products, variations, product groups, prices, images, attributes and stock balances. Use limitChangedSince to fetch only changes, and the limit* and product group parameters to narrow the result. If structured products are not in use, the request is rejected.

webshopproductimages.nv returns the images of one product (identifier = the product's Netvisor key). For a main product, the single main image is returned; for a variation, all linked images.

Product attachments and images of regular products are fetched with getproductattachment.nv and getproductimage.nv. The attachment keys are available from extendedproductlist.nv.

Glossary: English – Finnish

English	Finnish (Netvisor UI)
Product register	Tuoterekisteri
Product / product card	Tuote / tuotekortti
Product code	Tuotekoodi
Product group	Tuoteryhmä
Sales product	Myyntituote
Stocked product	Varastoitava tuote
Extended product management	Laajennettu tuotehallinta
Structured products	Rakenteelliset tuotteet
Purchase price	Hankintahinta
Customs tariff heading	Tullinimike
Country of origin	Alkuperämaa
Batch handling	Eräkäsittely
Inventory alert limit	Hälytysraja
Inventory	Varasto
Inventory event	Varastotapahtuma
Reserved / incoming	Varattu / tulossa
Purchase, sale, stocktaking, correction, transfer, manufacturing	Hankinta, myynti, inventointi, korjaus, varastosiirto, valmistus

Last updated on

Was this page helpful?