Purchase invoices, orders, vendors and payments – use case guide

This guide explains how to use the Netvisor API correctly for the most common purchase scenarios: importing a purchase invoice, moving it through review, approval and accounting, managing vendors, working with purchase orders and creating outgoing bank transfers. 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 due date (Eräpäivä).

Contents

1. Before you start

2. Resources used in the purchase flow

3. Use case: import a purchase invoice

4. Purchase invoice – key elements and their UI names

5. Invoice image and attachments

6. Use case: review, approve and post a purchase invoice

7. Use case: accrue a purchase invoice

8. Use case: manage vendors

9. Use case: purchase orders

10. Use case: outgoing bank transfers and purchase payments

11. Use case: read purchase data back into your system

12. Appendix: statuses and glossary

1. Before you start

Transaction fee. Every purchase invoice imported through the API is charged as an e-invoice transaction (verkkolaskun transaktiomaksu).

Vendor data on the invoice is not taken from the vendor card. Unlike sales invoices, where the customer's details are fetched from the customer card, a purchase invoice uses only the vendor details given in the message. If the company pays its purchase invoices from Netvisor, the payment file sent to the bank is built from the payee details in the imported invoice, so the vendor's name, address, bank account and payment reference must be complete in the message.

Vendor data is not updated from invoices. Importing a purchase invoice never updates an existing vendor card. Use vendor.nv to maintain vendor master data.

Large volumes. Purchase invoices can also be imported in batches with purchaseinvoicebatch.nv. Each item in the batch follows the purchaseinvoice.nv structure, and the batch is processed in the background. Follow its progress with getbatchstatus.nv and getbatchlist.nv. Batch import requires the purchase ledger (ostoreskontra) to be in use in the company.

Store the Netvisor keys. Successful imports return the new record's Netvisor key in InsertedDataIdentifier. Store it in your own system: you need it to approve, post, accrue or fetch the invoice later.

2. Resources used in the purchase flow

3. Use case: import a purchase invoice

The typical flow for importing purchase invoices from an external system (for example a scanning service, procurement system or another accounting system) is shown below.

Step 1 – Decide how the vendor is matched

You do not need to create the vendor before importing the invoice. Netvisor matches the invoice to a vendor in this order:

1. a vendor whose name and business ID (Y-tunnus) match the invoice

2. a vendor whose business ID matches the invoice

3. a vendor whose vendor code (toimittajakoodi) matches vendorcode

4. a vendor whose name matches the invoice.

If none of these match, Netvisor creates a new vendor card. If vendorcode is given and a new vendor is created, the code is saved on the new vendor; it is not updated on existing vendors.

To change the matching priority, give primaryvendormatchtype with code, name or organizationid. If no vendor is found with that field, the normal matching order is used.

If you want full control over vendor master data (bank accounts, default accounts, reviewers), create or update vendors first with vendor.nv (see section 8).

Step 2 – Build the invoice message

The following elements are required:

Value date: according to Netvisor's support documentation, valuedate (Arvopäivä) is currently needed for invoice imports even though it is marked as optional in the DTD. Include it in your messages.

Give the vendor details in the same message (see Step 1 and section 4). A minimal invoice with one line looks like this:

Step 3 – Send the request and store the key

Send the message to purchaseinvoice.nv. On success, the response returns the new invoice's Netvisor key in InsertedDataIdentifier.

If invoicesource is finvoice, the import takes about a minute longer, because the invoice is routed through Netvisor's Finvoice handler (see section 5).

Step 4 – Continue the process

After the import, the invoice continues in Netvisor's purchase invoice process. Depending on your integration, you can:

• set the review and approval circulation with purchaseinvoicecirculation.nv

• review, approve or post the invoice with purchaseinvoicepostingdata.nv

• accrue the invoice with purchaseinvoiceaccrual.nv

• create a bank transfer with payment.nv, or let the company pay the invoice from Netvisor.

4. Purchase invoice – key elements and their UI names

Dates, status and accounting

Vendor details

Payment details

Other header elements

Invoice lines

Subtotal lines (purchaseinvoicesublines) and comment lines (purchaseinvoicecommentlines) can also be imported.

5. Invoice image and attachments

Attachments are imported in purchaseinvoiceattachments with the MIME type, description, file name and the file as Base64 in documentdata.

To create an invoice image (Laskun kuva) in Netvisor's purchase invoice view, invoicesource must be finvoice. The same applies if you want Netvisor's automation rules (automaatiosäännöt) to be applied to the invoice. The attachment used as the invoice image can be:

• a Finvoice XML file: Netvisor generates the invoice image from the Finvoice data. TEAPPS files are not supported. A Finvoice file can be downloaded from Netvisor with Ostolaskun toiminnot > Lataa Finvoice-aineisto.

• a PDF file: the PDF is used as the invoice image and is shown under the invoice's attachments (Laskun liitteet).

The documenttype attribute of documentdata is invoiceimage (default) or otherattachment. If several attachments have the type invoiceimage, only the first one is shown. To import several attachments, give the others the type otherattachment.

Attachments of an existing invoice can be fetched with getattachments.nv (attachmentsource=purchaseinvoice). PDF attachments can optionally be returned as one image per page with convertpdfstoimages=true.

6. Use case: review, approve and post a purchase invoice

Set the review and approval circulation

purchaseinvoicecirculation.nv sets, changes or removes an invoice's review and approval circulation (asiatarkastus- ja hyväksyntäkierto). The circulation is set either from a circulation list (kiertolista) or person by person:

• Circulation list: give the list's Netvisor key in circulationlistidentifier. Get the keys with getcirculationlists.nv. If a circulation list is given, persons cannot be given, and vice versa.

• Persons: give the reviewers (factualverificator, asiatarkastaja) and the approver (approver, hyväksyjä) by email address. If the person has an email address set in their own Netvisor settings under company-specific exceptions (Yrityskohtaiset poikkeukset), that address is used. The email address must be unique within the company.

The invoice is identified by its Netvisor key or invoice number. Rules:

• The persons must have sufficient ledger rights for their role in Netvisor, and a possible vendor or amount limit must not prevent them from being set.

• The API user needs the ledger right for setting circulations.

• One call can set circulations for several invoices. If the call returns OK, all circulations were set. If it returns an error, none were set. The response contains a ValidDataIdentifier element for each invoice that could have been set without errors.

• The last reviewer becomes the invoice's main reviewer (pääasiatarkastaja).

• To remove a circulation, send the invoice without reviewers and approver.

• Once someone in the circulation has reviewed or approved the invoice, the circulation can no longer be changed through the API.

• The optional comment (max 250 characters) is added to the invoice's processing history (käsittelyhistoria).

Review, approve, reject or post

purchaseinvoicepostingdata.nv is used to reject, review or approve an invoice and to post it (tiliöinti). The invoice is identified by purchaseinvoicenetvisorkey.

Rules:

• The statuses must be given in the order above. An invoice cannot be returned to an earlier status, and the status it already has cannot be given again.

• To review, approve or reject an invoice, its payment status must be open (avoin) or overdue (erääntynyt).

• isreadyforaccounting = 1 makes Netvisor create the accounting voucher automatically. With 0, the actual posting must be done manually in Netvisor.

• Posting without changing the status: give isreadyforaccounting = 1 and leave out status. Depending on the invoice's status, this pre-posts or posts the invoice, in the same way as in the UI. With isreadyforaccounting = 0 and no status, the message only updates the posting lines without posting the invoice.

• The invoice must not be in a locked period.

• comment (max 3,000 characters) is shown in the invoice's processing history.

Posting lines. purchaseinvoicepostingline elements have the same content as purchase invoice lines, plus a VAT code (vatcode attribute of vatpercent, ALV-tunnus). The posting lines you send replace the lines on the invoice, so one invoice line can be split into several posting lines. The posting lines determine the invoice amount in Netvisor: if their total differs from the invoice's original total, the invoice amount changes to match the posting lines when the invoice is approved. The UI then shows the note "Laskun summa poikkeaa laskun alkuperäisestä summasta", and the original amount is shown on the posting lines as "Laskun alkuperäinen summa".

Posting lines can be edited, added and removed when the invoice is in one of the statuses new invoice (Uusi lasku), reviewed (Asiatarkastettu), approved (Hyväksytty) or posted (Tiliöity). If the invoice is approved, editing requires the accountant role (KP-rooli). Once the invoice has an accounting voucher, posting lines can only be edited with the accountant role.

Required rights. The posting rights of the owner of the API credentials are checked on every call. To review, approve or post invoices or to edit posting lines, the API user needs at least the purchase ledger user profile (Ostoreskontran käyttäjä) and, in the sales and purchase ledger rights, the rights to review and approve purchase invoices.

Add comments

purchaseinvoicecomment.nv adds comments to one or more existing purchase invoices. Comment is added to the invoice's history, and AdditionalInformation overwrites the invoice's additional information field. Use it for notes that should be visible in the approval flow without changing the invoice's accounting data.

7. Use case: accrue a purchase invoice

purchaseinvoiceaccrual.nv accrues (jaksottaa) a purchase invoice identified by its Netvisor key or invoice number.

• Equal split (tasajako): give a start month and year and an end month and year. The invoice lines are spread evenly over the period; for example, 3/2021–4/2021 accrues 50 % to March and 50 % to April.

• Division curve (jakokäyrä): give a start month and year and divisioncurvename. The curve name must be unique, and the curve can define monthly percentages.

• The end of the accrual cannot be before the start, and the start can be no earlier than the month of the invoice's posting date.

• Invoices cannot be accrued to a locked period.

• By default, no accrual is created if the invoice already has an accounting voucher or an accrual. To change an existing accrual or to accrue an invoice that has already been posted, give removeexistingaccrual = true. If the invoice has no voucher or accrual, this element has no effect.

8. Use case: manage vendors

Create or update a vendor

vendor.nv creates a new vendor (method=add) or updates an existing one (method=edit, with the vendor's Netvisor key in the netvisorkey parameter). The response returns the vendor's Netvisor key. Store it if you need to update or fetch the vendor later.

The vendor's Netvisor key can also be found:

• through the API with getvendor.nv and the changedSince parameter

• in the Netvisor UI by opening the vendor card and checking the id in the address bar (for example id=123).

Bank accounts

Vendor bank accounts are divided into domestic and foreign accounts, up to eight of each:

• Domestic accounts (vendordomesticbankaccount): IBAN and bank name.

• Foreign accounts (vendorforeignbankaccount): BBAN, BIC, bank name, country and currency, plus optional clearing code, clearing number and bank address. includeaddresssinforeignpayments adds the bank's address details to the payment file in addition to the BIC.

• If a bank account has no netvisorkey, it is added to the vendor as a new account. If the netvisorkey is found, that account is updated.

• isdefault = True makes the account the default. If several accounts have True, the last one in the message becomes the default.

9. Use case: purchase orders

Create a purchase order

purchaseorder.nv creates (method=add) or updates (method=edit, with the order's Netvisor key in id) a purchase order (ostotilaus). A new order requires:

Things to note:

• When editing an order, send only the data you want to change. The required elements do not have to be included.

• The payment term (maksuehto), delivery term (toimitusehto) and delivery method (toimitustapa) are looked up with the given data. If no match is found, a new one is created.

• productcode links the line to the product register only when its type attribute is given: netvisor (product's Netvisor key) or customer (product code, tuotekoodi). Without type, the line is not linked to a product.

• unitprice is the product's unit price excluding VAT, in the order currency.

• privatecomment is an internal comment that is not printed, while comment is printed on the order.

Edit order lines

Each purchaseorderproductline has a method attribute. All methods except add require the line's netvisorkey.

Comment lines (purchaseordercommentline) support add, edit and delete. When deleting, the comment line must be empty.

Record deliveries

Deliveries are recorded per line in purchaseorderproductlinedeliverydetails (or in the partial delivery rows):

Partial delivery rows can also carry batch information for the delivered products: batch number (max 20 characters), manufacture date, packaging date, best-before date and expiry date.

Link orders and invoices

A purchase invoice is linked to purchase orders by giving the order numbers in purchaseinvoicerelatedpurchaseordernumbers when the invoice is imported. purchaseorderlist.nv with haslinktopurchaseinvoice=1 returns only orders linked to at least one purchase invoice, together with the linked invoices.

10. Use case: outgoing bank transfers and purchase payments

Create a bank transfer

payment.nv creates a new bank transfer (tilisiirto), which is then approved or paid in Netvisor's transfer view (tilisiirtonäkymä). One XML message contains one transfer.

Rules:

• Transfers can be made within the SEPA area, and the recipient's account number must be in IBAN format. The account number is validated on import. The BIC is validated if Netvisor cannot identify the bank from the recipient's account number.

• The currency is always euro.

• If the due date is in the past, Netvisor changes it to the current date when the transfer is sent for payment.

• Imported transfers can be edited in Netvisor afterwards.

• Several imported transfers can be paid in the same payment batch (maksuerä), and transfers imported through the API can be combined with transfers created in Netvisor. All transfers sent for payment at the same time with the same payment account and payment date are paid in one batch.

• The paymentgroup element is legacy and no longer needs to be used.

Check the transfer status

unprocessedoutgoingpayments.nv returns the status of transfers sent through the API. Give the InsertedDataIdentifier values returned by payment.nv in idlist. The response status is 2 (OK) or 3 (failed, with the reason in StatusDescription). While the payment is being processed and no response has been received from the bank, the resource returns nothing.

List purchase payments

paymentlist.nv lists payments recorded against purchase invoices, including the linked invoice and the accounting voucher. Use limitAboveNetvisorKey to fetch only new payments since the last one you processed, or filter by date range, reference number or invoice Netvisor key (limitInvoiceID). Deleted payments can be listed with deletedpurchasepayments.nv.

11. Use case: read purchase data back into your system

Purchase invoices

purchaseinvoicelist.nv lists purchase invoices. Useful filters:

• begininvoicedate / endinvoicedate and invoicenumber

• invoicestatus: open, approved or accepted (see the appendix)

• paymentstatus: unpaid or paid

• lastmodifiedstart / lastmodifiedend in the format yyyy-MM-ddTHH:mm:ss, for fetching only invoices changed within a time window

• purchaseinvoicebatchid for invoices imported in a given batch.

Each row contains the invoice's Netvisor key, number, date, vendor and business ID, total, paid amount, open amount and a Uri pointing to the full record.

getpurchaseinvoice.nv returns one invoice (netvisorkey) or up to 500 at a time (netvisorkeylist). Optional sections, such as actions, handling history, payment information, invoice image, circulation list, Finvoice data and attachments, are included with the include parameter. omitattachments=true returns only the attachment count, which is faster for invoices with large attachments. With version=2, dimensions are returned inside each line.

Use deletedpurchaseinvoices.nv to keep your system in sync with invoices deleted in Netvisor.

Purchase orders

purchaseorderlist.nv filters by order number range, order date range, status, vendor (Netvisor key, vendor code or business ID), comment text and modification time. getpurchaseorder.nv returns the full order, and deletedpurchaseorders.nv lists deleted orders.

Vendors

getvendor.nv returns one vendor (NetvisorKey), several vendors (NetvisorKeyList, up to 500) or all vendors changed since a given date (changedSince), with up to 500 vendors per page (page).

12. Appendix

Purchase invoice statuses

Status on import (purchaseinvoiceonround) and in the list filter (invoicestatus):

Status changes with purchaseinvoicepostingdata.nv are listed in section 6.

Glossary: English – Finnish