Sales invoices, orders and payments – use case guide

This guide explains how to use the Netvisor API correctly for the most common sales scenarios: importing a sales invoice, working with sales orders, reading invoices back into your system and recording payments. It complements the API reference, which describes every element and parameter in detail. Here the focus is on the order of calls, the business rules behind them and how API elements map to the Netvisor user interface.

Netvisor's user interface is mainly used in Finnish, so many end users and accountants will refer to fields by their Finnish names. Throughout this guide the Finnish UI term is shown in italics after the English description, for example invoice date (Laskun päiväys).

Contents

1. Before you start

2. Resources used in the sales flow

3. Use case: import a sales invoice

4. Invoice header – key elements and their UI names

5. Invoice lines

6. Statuses, editing and deleting

7. Amounts, VAT, rounding and currency

8. Credit notes

9. Accruals, vouchers, attachments and custom fields

10. Use case: sales orders

11. Use case: read sales invoices and orders

12. Use case: record and match sales payments

13. Appendix: tax handling clauses and glossary

1. Before you start

Keep the customer and product registers up to date. A sales invoice always refers to an existing customer (asiakas) and to existing products (tuote). Importing an invoice does not create products, so your integration must make sure both exist in Netvisor before the invoice is sent.

Understand the two kinds of identifiers. Most sales elements can be linked either with a Netvisor key or with your own identifier, selected with a type attribute:

Store the Netvisor keys returned by the API in your own system. They are the most reliable way to refer to records in later calls.

Large volumes. If you import invoices in large batches, use salesinvoicebatch.nv. Each item in the batch follows the same structure as a single salesinvoice.nv message, and the batch is processed in the background.

2. Resources used in the sales flow

3. Use case: import a sales invoice

The typical flow for importing a sales invoice from an external system (for example a webshop, ERP or billing system) is shown below.

Step 1 – Make sure the customer exists

Search for the customer with customerlist.nv, using the keyword parameter (name, code or organisation identifier) or customercodelist (up to 100 customer codes). The response gives you the customer's Netvisor key and customer code.

If the customer is not found, create it with customer.nv (method=add). The response returns the new customer's Netvisor key in InsertedDataIdentifier. The most commonly used elements are:

Updating a customer: When you use method=edit, send only the elements you want to update. Any element you include with an empty value will be cleared in Netvisor.

Step 2 – Make sure the products exist

Every product line on an invoice must refer to a product that already exists in Netvisor. Search with productlist.nv (keyword matches product code or name) and create missing products with product.nv. Required product elements include, among others, the product group, name, active and sales product flags, and the default VAT percentage.

Temporary products: Netvisor has a built-in temporary product with the product code TEMP, but it cannot be used through the API. If you need temporary products, create them in the Netvisor UI like any other product (Luo uusi > Tuote).

Step 3 – Collect reference data

Depending on what you want to set on the invoice, fetch the related Netvisor keys:

• payment terms (maksuehto) with paymenttermlist.nv

• sellers (myyjä) with salespersonnellist.nv

• invoice categories (laskulaji) with invoicecategorylist.nv

• VAT codes from Netvisor's list of allowed VAT codes and identifiers (ALV-koodit ja -tunnisteet).

Step 4 – Build the invoice message

The following elements are required for every invoice:

A minimal invoice with one product line looks like this:

Step 5 – Send the request and store the key

Send the message to salesinvoice.nv with method=add. On success, the response returns the new invoice's Netvisor key in InsertedDataIdentifier. Store it: you need it to edit, delete or match payments to the invoice later.

Step 6 – What happens after the import

Sending the invoice to the customer is done in Netvisor. The send channel cannot be given in the message. By default Netvisor suggests the most electronic channel available on the customer card: e-invoice first (verkkolasku), then email invoice (sähköpostilasku), then paper invoice (paperilasku). The user can change the channel in the invoice sending view. E-invoices are created in Finvoice 3.0 format.

E-invoice and email addresses always come from the customer card. They cannot be given in the invoice message, so keep them up to date with customer.nv.

The invoice PDF is created from Netvisor's invoice template. You cannot use your own template as the invoice image. If you need your own invoice image, attach it as an attachment (see section 9).

The invoice language comes from the customer card (Finnish, Swedish or English) and cannot be given in the invoice message.

4. Invoice header – key elements and their UI names

Dates

All dates use format="ansi".

Numbers and references

Customer and addresses

How Netvisor decides which addresses to use:

• If the message contains only invoicingcustomeridentifier, the customer's name, billing address and delivery address are taken from the customer card.

• If the message contains address elements, they are used on the invoice.

• If the customer card has an alternative invoicing customer (vaihtoehtoinen laskutusasiakas), the billing address is always taken from that customer and the billing address in the message is ignored.

Payment terms

Give either a due date or a payment term – never both.

Seller

Texts and other header data

5. Invoice lines

An invoice can contain product lines, comment lines and subtotal lines. The lines appear in Netvisor in the same order as in the message.

Product lines

The product must already exist in Netvisor. Importing an invoice does not create new products. As long as no accounting voucher has been created for the invoice, the product name, price and other line details can still be changed in Netvisor.

VAT on lines

A VAT code is required on every product line. Use the codes in Netvisor's list of allowed VAT codes and identifiers (ALV-koodit ja -tunnisteet). How the VAT code is used depends on the invoice status:

• Status open: the voucher is created with the VAT code given on the line.

• Status unsent: the voucher gets the VAT code of the accounting account behind the Netvisor product.

If salesinvoicetaxhandlingtype is not given, it is taken from the customer. If any line has the VAT code RAMY, the invoice's tax handling type is set to domesticconstructionservice regardless of the value in the message, and all lines must then have the same VAT code.

Dimensions on lines

• Dimensions (laskentakohteet) can only be imported at line level. Invoice-level dimensions are not supported when invoices are imported through an integration. To use dimensions from the API, the company must use line-level dimensions: Myynti > Asetukset > Perustiedot ja asetukset > Myynnin perustiedot > Myyntilaskujen oletuslaskentakohteet > Laskurivikohtainen.

• If invoice-level dimensions are needed, the user sets them manually in Netvisor (Myyntilaskun toiminnot > Laskukohtaiset laskentakohteet).

• If the customer or products have default dimensions, they are applied to imported invoices when line-level dimensions are in use and the message contains no dimension data.

• If the dimension name (laskentakohdeotsikko) given in dimensionname does not exist, Netvisor creates it.

• When dimensionitemcode or dimensionitemname is given, the dimensionitem element is ignored.

Comment lines and subtotal lines

• Comment line (salesinvoicecommentline, kommenttirivi): free text with max 6,000 characters and 35 line breaks. Comment lines do not affect the invoice total.

• Subtotal line (salesinvoicesubline, välisummarivi): a line with its own article name, description, unit, price, quantity, discount, VAT percentage and sums.

6. Statuses, editing and deleting

Invoice and order statuses on import

Methods

Changing the status of an existing invoice

Use updatesalesinvoicestatus.nv to change the status of one or more invoices. The new status is given in the URI. One call can update up to 100 invoices, listed in netvisorkeylist.

• When an invoice is changed from unsent to any other status, its accounting voucher is created automatically.

• If the update fails for any invoice in the call, none of the invoices in that call are updated. The error message tells the reason and the Netvisor key of the failed invoice.

Deleting

deletesalesinvoice.nv deletes an invoice (invoiceid) or an order (orderid). The resource also deletes the related attachments, dimension links and vouchers. Use deletedsalesinvoices.nv and deletedsalesorders.nv to keep your own system in sync with deletions made in Netvisor.

7. Amounts, VAT, rounding and currency

Rounding. Netvisor rounds the net line total and the invoice total to two decimals when invoices are imported. This can sometimes cause rounding differences that must be reconciled with a voucher. To avoid them, send the unit price, line total and VAT amount already rounded to two decimals.

Invoice total. salesinvoiceamount is the total including taxes. If you give it, Netvisor does not recalculate the total from the lines. If you send it as 0 or empty (<salesinvoiceamount />), the total is calculated from the lines. When you import invoices that have already been sent to the customer, giving the total is recommended.

Currency. Give the invoice currency in the iso4217currencycode attribute of salesinvoiceamount. The default is the company's home currency. The currencyrate attribute sets the exchange rate. If it is not given, the European Central Bank's rate for the day is used, and if no rate is found, the rate 1 is used.

Netvisor pricing (hintakertoimet ja asiakashinnat). To apply Netvisor's price multipliers and customer prices to the lines:

1. give salesinvoiceamount the attribute pricetype="netvisor" and the value 0, so that the total is calculated from the line totals, and

2. give each productunitprice the attribute type="netvisor". The value of productunitprice can then be 0.

8. Credit notes

A credit note (hyvityslasku) is imported with the same salesinvoice.nv message structure as an invoice, with these differences:

• the quantity (salesinvoiceproductlinequantity) and the invoice total (salesinvoiceamount) are negative

• the unit price (productunitprice) is positive

• if you give the line VAT amount (salesinvoiceproductlinevatsum) and line total (salesinvoiceproductlinesum), they must also be negative.

A credit note imported through the API is not matched automatically to the original invoice. Match it with matchcreditnote.nv using the Netvisor keys of the credit note (creditnotenetvisorkey) and the original invoice (invoicenetvisorkey), or let the user match it manually in Netvisor. Both invoices must have accounting vouchers, and they must be in the same currency.

9. Accruals, vouchers, attachments and custom fields

Accruals (Jaksotus)

• Accruals can be given at invoice level or line level (accrualrule), using either an equal split (tasajako) or a division curve (jakokäyrä).

• Equal split: give startmonth, startyear, endmonth and endyear.

• Division curve: give startmonth, startyear and divisioncurvename, but not the end month and year. The division curve must exist in Netvisor (Taloushallinto > Budjetoinnin asetukset > Jakokäyrät).

• Accruals can be given for unsent and open invoices. For unsent invoices the accrual vouchers are created after the invoice is sent; for open invoices they are created on import.

• A one-month accrual only works if the accrual month is not the same as the invoice date month. For example, for an invoice dated in April, the accrual can start in May or later. Accruals to past months are not possible.

• The accrual voucher automatically gets the same dimensions as the invoice lines.

Voucher lines (Tositerivit)

Give invoicevoucherlines only if your integration wants to create the invoice's accounting voucher itself. Otherwise Netvisor creates the voucher. When voucher lines are given, Netvisor uses them and does not create the voucher automatically.

• calculationmode is gross (default) or net. With net, Netvisor does not calculate VAT and rounding difference lines automatically.

• In linesum, a positive amount is posted to debit and a negative amount to credit.

• The account in accountnumber must exist in Netvisor.

• Vouchers cannot be imported for orders or drafts.

Attachments

• Add attachments in salesinvoiceattachments with the MIME type, description, file name and the file as Base64 in documentdata.

• The attachment type attribute has no effect: all attachments work with e-invoices, email invoices and paper invoices, and the attribute can be omitted.

• printbydefault = 1 sends the attachment with the invoice by default (Lähetetään laskun mukana). If it is 0 or not given, the attachment is not sent with the invoice by default.

Custom fields (Lisätietokentät)

Use customtags to fill in the company's custom invoice fields. tagname is the name of the custom field in Netvisor, and the type attribute of tagvalue is float, date, text or enum.

10. Use case: sales orders

Import a sales order

A sales order (myyntitilaus) uses the same salesinvoice.nv structure with invoicetype = order and status undelivered (Toimittamaton) or delivered (Laskuttamaton). Some elements are only used for orders:

Rows can be added to an existing order with method=append (see section 6).

Deliver and invoice an order

Use salesorderinvoicing.nv to deliver and/or invoice an existing sales order:

1. Fetch the order list with salesinvoicelist.nv using listtype=preinvoice, and pick the order's Netvisor key.

2. Fetch the order details with getorder.nv to get the Netvisor keys of the order lines.

3. Call salesorderinvoicing.nv with method=deliveryonly (deliver only) or method=billanddelivery (deliver and invoice). For each line, give the line's Netvisor key, delivery date and delivered quantity (deliveryamount, with ispostdelivery indicating a post-delivery).

Optional parameters: copysublines=true copies subtotal lines to the invoice, and updatemidprice=true updates the products' current average price to the invoice lines.

The invoice created with billanddelivery must still be sent separately. Netvisor's automatic sending of sales invoices (myyntilaskujen automaattilähetys) can be used for this.

Undelivered order lines can be removed with deletesalesinvoiceproductline.nv. Order statuses can be changed with updatesalesorderstatus.nv.

Prepayments on orders

A payment imported to an order with salespayment.nv is recorded as a prepayment (ennakkosuoritus). When the order is invoiced, prepayments move to the invoice as payments, and if they cover the full amount, the invoice status becomes Maksettu automatically. When importing a prepayment, give the paymentmethod element the attribute overridesalesreceivableaccountnumber with the prepayment account defined in Netvisor's accounting settings, for example 2861 Saadut ennakot.

11. Use case: read sales invoices and orders

List invoices or orders

salesinvoicelist.nv returns invoices or orders depending on listtype:

Filter by status with invoicestatus. The filter matches both the InvoiceStatus field and its substatus attribute.

Each row in the response contains a Uri element that points to the full record: getsalesinvoice.nv?netvisorkey=… for invoices and getorder.nv?netvisorkey=… for orders.

Keep your system in sync

• Use lastmodifiedstart and lastmodifiedend to fetch only invoices modified within a time window.

• Add includemodifiedpayments=1 (together with the lastmodified parameters) to also get invoices whose payments were added or changed within the window.

• Use invoicesabovenetvisorkey to fetch only invoices created after the last one you processed.

• Other filters include invoice date range, invoice number, customer code, customer Netvisor key, auxiliary business name and the sales invoice batch ID.

Get full details

getsalesinvoice.nv returns one invoice (netvisorkey) or up to 500 at a time (netvisorkeylist). Use the replyoption bitmask to include extra blocks, such as events, accruals, factoring, payment plan, credited invoice, allocated invoices and custom fields. Use pdfimage to choose whether and which invoice PDF is included.

12. Use case: record and match sales payments

Import a payment

salespayment.nv records a sales payment (myyntisuoritus) and matches it to an invoice or order.

Rules to keep in mind:

• The invoice or order must exist before the payment is imported. A payment imported before the invoice is no longer matched automatically.

• A payment is not matched automatically to an invoice that is already paid (Maksettu).

• If the invoice accepts partial payments, the payment is always added with its exact amount. If not, the payment amount must be within the invoice's cash discount tolerance.

• To import a payment to an unsent invoice, the invoice must accept partial payments. For invoices imported through the API, set expectpartialpayments = 1 in the invoice message. For invoices created in Netvisor, this is defined in the sales settings.

• The payment's accounting account comes from the payment method or bank account. You can override the debit account with the overrideaccountingaccountnumber attribute and the receivables account with overridesalesreceivableaccountnumber (Netvisor's default receivables account is 1701).

Match an existing payment

matchpayment.nv matches an existing, unmatched payment to an invoice or order using the Netvisor keys of the payment and the invoice. The handling types work in the same way as in the Netvisor UI:

With notargeting, invoicenetvisorkey is not required. A voucher is then created for the payment according to the payment account and the default sales receivables account, but the payment is not matched to any invoice.

Other payment resources

• salespaymentlist.nv lists payments. Useful filters are limitlinkedpayments (unmatched or matched only), invoicenetvisorkey, lastmodifiedstart / lastmodifiedend and mispayment=1 (payments that could not be matched to an invoice).

• deletesalespayment.nv deletes a payment, and deletedsalespayments.nv lists deleted payments.

• masspayments.nv posts sales payments in bulk into accounting vouchers (myyntisuoritusten massatiliöinti).

13. Appendix

Tax handling clauses (salesinvoicetaxhandlingclause)

The tax clause on the invoice (Veroteksti laskulla) is given as the ID of one of Netvisor's predefined clauses. You cannot add your own text or edit the default texts, and the IDs cannot be queried through the API.

Glossary: English – Finnish