Invoice batches – use case guide

Invoice batches (laskuerät) let you import a large number of sales invoices or purchase invoices in one request. The batch is queued and processed in the background, and you follow its progress with separate status calls. This guide explains how to build a batch, how to follow its processing and how to find the invoices and errors it produced. For element-level details, see the API reference.

When to use batches

• Batches are meant for bulk imports of sales invoices and purchase invoices. Netvisor recommends importing at most 500 invoices in one batch.

• Sales orders and purchase orders cannot be imported in batches. Import them one at a time with salesinvoice.nv and purchaseorder.nv.

• Purchase invoice batches require the purchase ledger (ostoreskontra) to be in use in the company.

Resources

Use case: import invoices as a batch

Step 1 – Build the batch

A batch consists of items, each of which contains one invoice:

The overall structure of a sales invoice batch looks like this:

A purchase invoice batch has the same structure with the root element purchaseinvoicebatch.

Step 2 – Add shared attachments (optional)

Attachments can be added in sharedattachments. Each attachment is linked to invoices in the batch with itemlink / itemidentifier, which refers to the identifier of an item.

Step 3 – Send the batch and store the batch ID

Send the batch to salesinvoicebatch.nv or purchaseinvoicebatch.nv. The response returns the Netvisor key of the new batch. Store it: you need it to follow the batch's processing.

Step 4 – Follow the processing

Use getbatchstatus.nv with the batch ID in id. For purchase invoice batches, give batchtype=purchaseinvoice; without it, the resource looks for sales invoice batches.

The response summary contains:

The batch status only tells how far Netvisor has got in processing the batch. It says nothing about what has happened to the invoices after that, for example whether sales invoices have been sent to customers.

Step 5 – Handle errors

Errors in a batch are only reported through getbatchstatus.nv. Unlike single-invoice imports, the import call does not return errors for individual invoices, so your integration must check the batch status to find out which invoices failed.

Failed invoices are listed in ItemErrorDescriptions. Each ItemError contains the Identifier you gave the invoice in the batch and one or more Error elements. The error's Type attribute is the same error type the API returns for single requests, for example INVALID_DATA, PERIOD_LOCK or TECHNICAL_ERROR, and Value describes the error. Use the type to decide how to handle the error, for example whether to correct the data and import the invoice again.

Step 6 – Link the created invoices to your own data

To find out which Netvisor invoice was created from which item, add addsalesinvoicelinkinformation (sales invoice batches) or addpurchaseinvoicelinkinformation (purchase invoice batches, together with batchtype=purchaseinvoice) to the getbatchstatus.nv call. The response then contains a SalesInvoiceLinkInformation or PurchaseInvoiceLinkInformation element, where each Link pairs your ItemIdentifier with the NetvisorKey of the created invoice. Store the Netvisor keys in your own system for later calls.

Invoices imported in a batch can also be listed by batch ID: use salesinvoicebatchid with salesinvoicelist.nv and purchaseinvoicebatchid with purchaseinvoicelist.nv.

List batches

getbatchlist.nv lists batches with their ID, processing status and import time. Filter by processing status with status (pending, processing or finished); for example, pending returns only batches whose processing has not started yet. Give batchtype=purchaseinvoice to list purchase invoice batches; without it, sales invoice batches are returned.

Glossary: English – Finnish