Resource: salesinvoice.nv
HTTP-method: POST
The API makes it possible to add or edit a sales invoice, it's product-, sub- and comment lines, attachments, voucher lines and customer specific fields in Netvisor.
The required fields for importing a sales invoice are:
- Date of the invoice
- Sum total
- Invoice status
- Customer's linking information
- Net day of the terms of payment or due date
- At least one invoice line with the following information
- Product linking information
- Product name
- Product's unit price
- Product's VAT percentage and code
- Product's unit count
The salesinvoice can be imported as a salesinvoice draft with status "invoicedraft". It is not possible to give invoice number or import invoice voucherlines for invoice drafts. Invoice draft can be updated to salesinvoice with the parameter edit.
Credit note is imported trough the API with the same message structure. The only difference is that unit count and sum total are set to negative numbers. Also productline vat sum and productline sum are set to negative numbers if they are given. Credit note is not automatically matched to existing sales invoice. Connecting credit note and sales invoice must be done either via API using resource matchcreditnote.nv or manually in Netvisor UI.
Netvisor rounds invoice line rowsum and invoice total sum by 2 digits when importing XML
Billing and delivery customer is focused to sales invoice by Netvisor key or by customer code. Netvisor key is database ID and customer code is individual code given in customer register by Netvisor user. These can be fetched by using customerlist.nv resource.
When only Invoicingcustomeridentifier is given in the Sales Invoice XML and no other invoicing address or delivery address details are on the XML, the API will retrieve this information automatically from customer register. In other hand if any other billing customer detail (i.e. postal address) is given, nothing is retrieved from the customer register.
If an alternative billing customer has been determined to target customer, the API will automatically retrieve the alternative customers information to the imported invoice. In this case, the billing address information in the imported material is not used.
The sales invoice can be accrued either on invoice or invoice row level using either equal division or allocation curve. Accrual can be imported for both unsent or open invoices. The accrual voucers are generated according to data on the xml after the invoice is sent or when importing open invoices, when the invoice is imported automaticallyby the system. Please note that accruing one month is possible only when the accrual is not on the same month as the invoice date. E.g. if the sales invoice date is in April the accrual can be done earliest for May or for any time after that. The accrual cannot be done to the past. It is possible to edit a sales invoice imported in Unsent mode afterwards. If a sales invoice is imported in open mode, editing is disabled.
Querystring parameters:
Parameter name | Occurs | Description | Example |
Method | 1 | add or edit and with sales order append. When using method edit, all original order/invoice details must be given if wish to keep them. It is not possible to edit invoice, if invoice had voucher. When using method append, the order must be in the undelivered or uninvoiced status. Full details must be given in the header, without invoice rows only the header details can be updated. The new rows are added to the end of the order and added to the order total sum if the total (salesinvoiceamount) was not provided in the request. | edit |
Id | 0...1 | Must be defined if method = edit or append | 165 |
The following describes the XML message to import (POST) a sales invoice into Netvisor:
Level | Element name | Type and length | Occurs | Description | Example |
Root | root | Aggr. | 1 | ||
1 | salesinvoice | Aggr. | 1 | ||
2 | salesinvoicenumber | Numeric max. length 18 digits | 0...1 | If number is not given, Netvisor automatically picks next free number. Cannot be given for invoice drafts. | 123456 |
2 | salesinvoicedate | Date | 1 | Sales invoice date | 2019-12-31 |
Attr. | format | String | 1 | Always ansi | ansi |
2 | salesinvoiceeventdate | Date | 0...1 | Invoice's event date. This forms the voucher date. | 2020-01-01 |
Attr. | format | String | 1 | Always ansi | ansi |
2 | salesinvoiceduedate | Date | 0...1 | Sales invoice due date. Compulsory if payment term is not given. When due date is given, Netvisor sets payment term automatically to 'Due date'. The message can not include both due date and payment term, only other element is given. | 2020-01-14 |
Attr. | format | String | 1 | Always ansi | ansi |
2 | salesinvoicevaluedate | Date | 0...1 | Invoice's valuedate. If given, the net days of payment term are applied to the valuedate | 2019-12-31 |
Attr. | format | String | 1 | Always ansi | ansi |
2 | salesinvoicedeliverydate | Date | 0...1 | Sales invoice delivery/arrival date. | 2020-01-04 |
Attr. | format | String | 1 | Always ansi | ansi |
2 | salesinvoicedeliverytocustomerdate | Date or week number | 0...1 | Delivery date for customer. Date or week number. For sales order only. | 2018-W12 |
Attr. | format | String | 1 | Delivery date for customer, format | ansi |
Attr. | type | String | 1 | Delivery date for customer. date or weeknumber | weeknumber |
2 | salesinvoicewaybillidentifier | String, max 35 characters | 0...1 | Waybill number/identifier. For sales order only. | 33000050143 |
2 | salesinvoiceproductpackagepallet | Number | 0...1 | Sales order package. For sales order only. | 2 |
Attr. | type | String | 1 | Pallet code type, GS1 | GS1 |
Attr. | amount | String | 0...1 | Pallet amount | 2 |
2 | salesinvoicereferencenumber | Referece | 0...1 | Invoice reference number. Must be in correct format with check sum. If not given, Netvisor forms the reference number for invoice. | 1070 |
2 | salesinvoiceamount | Numeric | 1 | Total amount of the invoice. If given, amount is not calculated from the invoice rows. Possible to give as empty value </salesinvoiceamount>, then the amount is calculated from the invoice rows Notice that if you are importing already sent invoices, we recommend that you give the amount. | 100,99 |
Attr. | iso4217currencycode | String | 0...1 | If not given, currency code from company´s information is used. Otherwise code must be given in ISO 4217 standard | USD |
Attr. | currencyrate | String | 0...1 | If not given, daily currency rate from European central bank is used. If there is no existing currency rate value, then value 1 used automatically | 1,33 |
Attr. | pricetype | String | 0...1 | netvisor or customer. Customer does nothing but if value is netvisor, Netvisor's price groups and customer prices will be used for invoice rows. SalesInvoiceAmount -value should be 0 so that invoice amout is calculated correctly from invoice rows. | netvisor |
2 | selleridentifier | String | 0...1 | Link seller to the invoice. If you want to link the seller information to the seller found on Netvisor, you must set both the seller's link information (selleridentifier) and the seller's name (the next element 'sellername'). Netvisor's seller information can be retrieved from the resource: Get sales personnel list, the list returns the Netvisor Key used to link the seller. | 1 |
Attr. | type | String | 1 | Type of link: netvisor (netvisorkey) or customer (name) Linking can be done with the seller's Netvisor Key (primary) or the seller's name. When the linking information and the name of the seller (element sellername) are imported, the name of the seller corresponding to the ID in Netvisor becomes the seller on the invoice. If the link is made by name, then the given string is compared forward and backward to the list of Netvisor seller. If seller cannot be found on Netvisor, the interface will response incomplete information. | netvisor |
2 | sellername | String, max. length 50 | 0...1 | Free form name of the seller | Matti Mallikas |
2 | invoicetype | String | 0...1 | invoice, order or invoicedraft. Default is invoice | invoice |
2 | salesinvoicestatus | String | 1 | Status of invoice open or unsent for invoice, delivered or undelivered for order | open |
Attr. | type | String | 1 | Use netvisor | netvisor |
2 | salesinvoicefreetextbeforelines | String, max. length 500 | 0...1 | Free text before before invoice lines | |
2 | salesinvoicefreetextafterlines | String, max. length 500 | 0...1 | Free text after invoice lines | |
2 | salesinvoiceourreference | String, max. length 200 | 0...1 | Information for "our reference" field | |
2 | salesinvoiceyourreference | String, max. length 200 | 0...1 | Information for "your reference" field | |
2 | salesinvoiceprivatecomment | String, max. length 500 | 0...1 | Shown only in Netvisor interface, not printed on invoice form | |
2 | invoicingcustomeridentifier | String | 1 | Information used to link invoicing customer to invoice. Customer must be already in Netvisor. Value can be customer code or id of customer record in Netvisor (see type attribute) | MM |
Attr. | type | String | 1 | Type of link: netvisor (=Netvisor ID), customer (=customer code), or organizationunitnumber (=OVT-identifier) | customer |
Attr. | contactpersonid | String | 0...1 | Customer's contact person's Netvisor ID. Can be retreived with getcustomer.nv. | 4012 |
2 | invoicingcustomername | String, max. length 250 | 0...1 | Will not be collected from Netvisor | Matti |
2 | invoicingcustomernameextension | String, max. length 250 | 0...1 | Will not be collected from Netvisor | Meikäläinen |
2 | invoicingcustomeraddressline | String, max. length 100 | 0...1 | Will not be collected from Netvisor | Pajukuja 1 |
2 | invoicingcustomeradditionaladdressline | String, max. length 100 | 0...1 | Will not be collected from Netvisor | |
2 | invoicingcustomerpostnumber | String, max. length 50 | 0...1 | Will not be collected from Netvisor | 53100 |
2 | invoicingcustomertown | String, max. length 50 | 0...1 | Will not be collected from Netvisor | Lappeenranta |
2 | invoicingcustomercountrycode | String | 0...1 | In ISO 3316 format. *) | FI |
Attr. | type | String | 1 | Will not be collected from Netvisor | ISO-3166 |
2 | officeidentifier | String | 0...1 | Office identifier. Office identifier in Netvisor. NOTE! This is not Office's Netvisorkey. Office identifier can be given in the message and given particular office (or first match) is searched or new office is created (type=automatic). NOTE! When using this element, all office details must be given in the message. | |
Attr. | type | String | 0...1 | automatic when new office should be created according to to sent message. NOTE! All office details must be given in the message. | |
2 | deliveryoffice | String | 0...1 | Delivery office target to Netvisor delivery office in customer details. NOTE! All delivery office details must be given in the message | |
Attr. | type | String | 1 | Target type: Customer=Delivery office name Netvisor=Delivery office NetvisorID | |
2 | deliveryaddressname | String, max. length 250 | 0...1 | Will not be collected from Netvisor. Must be given if delivery details should be shown on invoice PDF. | Maija |
2 | deliveryaddressline | String, max. length 100 | 0...1 | Will not be collected from Netvisor | Pajukuja 2 |
2 | deliveryaddresspostnumber | String, max. length 50 | 0...1 | Will not be collected from Netvisor | 55100 |
2 | deliveryaddresstown | String, max. length 50 | 0...1 | Will not be collected from Netvisor | Imatra |
2 | deliveryaddresscountrycode | String | 0...1 | Will not be collected from Netvisor | FI |
Attr. | type | String | 1 | Will not be collected from Netvisor | ISO-3316 |
2 | deliverymethod | String, max. length 50 | 0...1 | Free form text. If given value is not found from Netvisor, then value is created as new delivery method in Netvisor | Installed |
2 | deliveryterm | String, max. length 50 | 0...1 | Free form text. If given value is not found from Netvisor, then value is created as new delivery term in Netvisor | According to agreement |
2 | salesinvoicetaxhandlingtype | String | 0...1 | countrygroup, forcedomestic, domesticconstructionservice or notaxhandling. *1) If not given, taxhandlingtype from customer's information will be used | countrygroup |
2 | paymenttermnetdays | Numeric | 1 | Invoice date + paymenttermnetdays = invoice duedate. Payment term: "14 days net" | 14 |
2 | paymenttermcashdiscountdays | Numeric | 0...1 | Cash discount days for the payment term. Payment term: "14 days net, 5 days" | 5 |
2 | paymenttermcashdiscount | Numeric | 0...1 | Cash discount percent Payment term: "14 days net, 5 days-10%" | 10 |
Attr. | type | String | 1 | Type of discount, always pecentage | percentage |
2 | paymentterm | Numeerinen | 0...1 | Payment term's NetvisorKey | 1 |
Attr. | type | Merkkijono | 1 | Payment term's type: netvisor = allocating to the payment term based on payment term's NetvisorKey customerdefault = customer's default payment term companydefault = company's default payment term default = primary customer's default payment term. If not set, the company's default payment term is used | netvisor |
2 | expectpartialpayments | Numeric | 0...1 | 1 = yes, 0 = no. Default 0. If the invoice accepts partial payments, the invoice is also accepting payments outside the the cash discount tolerances | 1 |
2 | overridevouchersalesreceivablesaccountnumber | Numeric | 0...1 | When given, this will override the default sales receivables account number in Netvisor. Works only with salesinvoices with status "Open". | 1703 |
2 | salesinvoiceagreementidentifier | String, max. length 35 | 0...1 | Contract ID | |
2 | printchannelformat | String | 0...1 | ||
Attr. | type | String | 1 | netvisor or customer | netvisor |
2 | secondname | String | 0...1 | supplementary firm name | Example name |
Attr. | type | String | 1 | netvisor (NetvisorKey) or customer (name) | customer |
2 | overriderateofoverdue | Numeric | 0...1 | Penalty interest-%, overrides Netvisor default | 5,5 |
2 | ordernumber | String | 0...1 | Order number | 258741 |
2 | proposedaccount | Numeric | 0...1 | Customer's accounting suggestion | 1011 |
2 | type | String | 1 | customer | customer |
2 | accountdimensiontext | String, max 35 | 0...1 | Customer's dimension for whole invoice. In Netvisor UI this can be found from sales invoice's Additional information under Additional customer information fields. Can also be imported for invoice rows, see documentation below. | cost center |
2 | collectioncost | Numeric | 0...1 | Collection cost. Only positive values (and 0) are allowed. Only for sales invoices. | 15 |
2 | isthirdpartysales | Numeric | 0...1 | Triangular trade. 0 or 1, where 1 chooses the option "Triangular trade" for sales invoice. Used only for sales invoices. | 1 |
2 | invoicelines | Aggr. | 1 |
Invoice lines can be either product lines, sublines or comment lines. Product in a product line must exist in Netvisor and be linked to the line either with Netvisor-key or customer specific key. However product name, price and other information can be altered.
VAT-code is compulsory for product lines. You can check the VAT-codes from the table below. The given VAT-code is used on the voucher if the status of the imported invoice is open. If the invoice status is unsent the VAT-code on the voucher is taken from the accounting account settings.
If the imported invoice has both product- and comment lines, their order will be the same as in the imported material.
The sales invoice can be accrued on invoice row level using either equal division or allocation curve. When using equal division elements endmonth and endyear are given on the xml. When using allocation curve these elements are not used but the element divisioncurvename is given on the xml. Please note that accruing one month is possible only when the accrual is not on the same month as the invoice date. E.g. if the sales invoice date is in April the accrual can be done earliest for May or for any time after that. The accrual cannot be done to the past.
If product lines are needed, structure for InvoiceLine aggregate is this:
Level | Element name | Type and length | Occurs | Description | Example |
3 | invoiceline | Aggr. | 1...n | ||
4 | salesinvoiceproductline | Aggr. | 1 | ||
5 | productidentifier | String | 1 | Product identifier, either netvisorkey or given product code. Product must be founded in Netvisor. | |
Attr. | type | String | 1 | Type of indentifier: - customer (given product code) - netvisor (netvisorkey) - primaryeancode (given primary EAN-code) - secondaryeancode (given secondary EAN-code) | netvisor |
5 | productname | String, max. 200 | 1 | Name of the product. If element is given empty, will be retrieved from Netvisor. | test product |
5 | productunitprice | Numeric, max 12 decimal | 1 | Product unit price, not retrieved from Netvisor | 10,05 |
Attr. | type | String | 1 | Type of unit price, net or gross | net |
5 | productunitpurchaseprice | Numeric | 0...1 | Product unit purchase price | 1,05 |
Attr. | type | String | 1 | Type of unit purchase price, always net | net |
5 | productvatpercentage | Numeric | 1 | Must not conflict with vat code | 24 |
Attr. | vatcode | String | 1 | For example: NONE, KOOS, EUOS, EUUO, EUPO, 100, KOMY, EUMY, EUUM, EUPM312, EUPM309, MUUL, EVTO, EVPO, RAMY, RAOS or EVRO. Check list of allowed vat codes here. | KOMY |
5 | salesinvoiceproductlinequantity | Numeric | 1 | Amount of products. Can be integer or decimal. Max eight decimals (e.g. 3,55555555) | 5 |
5 | salesinvoiceproductlinediscountpercentage | Numeric | 0...1 | Discount percentage. If the attribute given, Netvisor will use the discount percentage from customer details in Netvisor | 10 |
Attr. | type | String | 1 | netvisor | netvisor |
5 | salesinvoiceproductlinefreetext | String, max. 512 | 0...1 | Free text for the product line | |
5 | salesinvoiceproductlinevatsum | Numeric | 0...1 | Tax for the product line. Given if amount calculated by Netvisor is wished to be overridden | 11,00 |
5 | salesinvoiceproductlinesum | Numeric | 0...1 | Line's gross total sum. Given if sum calculated by Netvisor is wished to be overridden | 50,00 |
Note! Both salesinvoiceproductlinesum and salesinvoiceproductlinevatsum elements are required if sum calculated by Netvisor is wished to be overridden. | |||||
5 | salesinvoiceproductlineinventoryid | Numeric | 0...1 | Warehouse ID of productline | 1 |
5 | accountingaccountsuggestion | Numeric | 0...1 | Suggestion for accounting account. Must be found in the system | 3000 |
5 | dimension | Aggr. | 0...n | ||
6 | dimensionname | String, max. 50 | 1 | Dimension title, if the dimension is not found, the system creates it | |
6 | dimensionitem | String, max. 200 | 1 | Name of the dimension item | |
5 | provisionpercentage | Numeric | 0...1 | Provision percentage | 12 |
5 | accrualrule | Aggr. | 0...1 | Accrual rule for invoice row, you can use equal division OR allocation curve. Invoicestatus has to be "open", that the voucher is generated. | |
6 | startmonth | Numeric | 1 | Starting month | 9 |
6 | startyear | Numeric | 1 | Starting year | 2020 |
6 | endmonth | Numeric | 0...1 | Ending month (only with equal division) | 12 |
6 | endyear | Numeric | 0...1 | Ending year (only with equal division) | 2020 |
6 | divisioncurvename | String | 0...1 | Allocation curve (only with allocation curve) Has to be predefined in Netvisor view: 'Financials > Budgeting settings > Allocation curves' | quarter |
5 | productunitname | String, max 14 | 0...1 | Product unit. If not given, Netvisor will use the product unit from product details in Netvisor. Cannot be given if the compay is using Extended product management. | pcs |
5 | deliverydate | Date | 0...1 | Sales order productline delivery date. For sales order only. | 2021-04-14 |
Attr. | format | String | 1 | Always ansi | |
5 | OrderNumber | Numeric | 0...1 | Product order number. | 1232 |
5 | proposedaccount | Numeric | 0...1 | Customer's accounting suggestion | 1011 |
5 | type | String | 1 | customer | customer |
5 | accountdimensiontext | String, max 35 | 0...1 | Customer's dimension for invoice row | cost center |
If comment lines are needed, use the following structure for InvoiceLine aggregate:
Level | Element name | Type and length | Occurs | Description | Example |
3 | invoiceline | Aggr. | 1...n | ||
4 | salesinvoicecommentline | Aggr. | 1 | ||
5 | comment | String, max 6000 | 1 | Comment for the invoice | Comment for the invoice |
If sublines are needed, use the following structure for InvoiceLine aggregate:
Level | Element name | Type and length | Occurs | Description | Example |
3 | invoiceline | Aggr. | 1...n | ||
4 | salesinvoicesubline | Aggr. | 1 | ||
5 | sublinearticleidentifier | String, max 35 | 0...1 | Product code | 1 |
5 | sublinearticlename | String, max 100 | 1 | Product name | Product |
5 | sublinedescription | String, max 512 | 0...1 | Line description | Description |
5 | sublineunitcode | String, max 14 | 0...1 | Product unit | pcs |
5 | sublineunitprice | Numeric | 0...1 | Unit price | 10 |
5 | sublinedeliveredquantity | Numeric | 0...1 | Delivered quantity | 1 |
5 | sublinediscountpercent | Numeric | 0...1 | Discount percent | 0 |
5 | sublinevatpercent | Numeric | 0...1 | Vat percent | 24 |
5 | sublinesum | Numeric | 0...1 | Line sum | 12,4 |
5 | sublinevatsum | Numeric | 0...1 | Vat sum | 2,4 |
After the invoice lines, the structure continues as follows:
Level | Element name | Type and length | Occurs | Description | Example |
2 | invoicevoucherlines | Aggr. | 0...1 | Add only if a sales invoice voucher is to be generated from the API. Otherwise, Netvisor will generate the sales invoice voucher. | |
3 | calculationmode | String | 0...1 | Voucher's calculation mode. net (vat lines are not calculated automatically) or gross (vat lines are calculated automatically). If element is not given, the voucher calculation mode is gross. | net |
3 | voucherline | Aggr. | 1...n | ||
4 | linesum | Numeric | 1 | Line sum. Positive value will be recorded as debit, and negative as credit | 100 |
Attr. | type | String | 1 | Type of sum, net or gross | net |
4 | description | String, max. 255 | 0...1 | Free description text | |
4 | accountnumber | String | 1 | Account number, must be found in the system | 3000 |
4 | vatpercent | Numeric | 1 | VAT percent. Must not conflict with VAT code | 24 |
Attr. | vatcode | Numeric | 1 | For example: NONE, KOOS, EUOS, EUUO, EUPO, 100, KOMY, EUMY, EUUM, EUPM312, EUPM309, MUUL, EVTO, EVPO, RAMY, RAOS or EVRO. Must not conflict with VAT percent. Check allowed codes here. | KOMY |
4 | accountdimension | String | 0...1 | Voucher's follow-up object | Follow-up object 1 |
attr. | type | String | 1 | name or netvisorkey (shown only in Netvisor) | name |
5 | dimension | Aggr. | 0...n | ||
6 | dimensionname | String | 1 | Dimension name | Project 1 |
6 | dimensionitem | String | 1 | Dimension item | Payroll |
2 | accrualrule | Aggr. | 0...1 | Accrual rule for the whole invoice, you can use equal division OR allocation curve. Invoicestatus has to be "open", that the voucher is generated. | |
3 | startmonth | Numeric | 1 | Starting month | 9 |
3 | startyear | Numeric | 1 | Starting year | 2020 |
3 | endmonth | Numeric | 0...1 | Ending month (only with equal division) | 12 |
3 | endyear | Numeric | 0...1 | Ending year (only with equal division) | 20 |
3 | divisioncurvename | String | 0...1 | Allocation curve (only with allocation curve) Has to be predefined in Netvisor view: 'Financials > Budgeting settings > Allocation curves' | quarter |
2 | salesinvoiceattachments | Aggr. | 0...1 | ||
3 | salesinvoiceattachment | Aggr. | 1...n | ||
4 | mimetype | String | 1 | MIME type of the attachment | Application/pdf |
4 | attachmentdescription | String, max 100 characters | 1 | Description of the attachment | |
4 | filename | String, max 255 characters | 1 | Filename of the attachment | project1.pdf |
4 | documentdata | String | 1 | Base64 encoded data of the attachment | |
Attr. | type | String | 0..1 | Values: finvoice Files to be attached to electronic invoice pdf Files to be attached for printing Note that all attachments work with both e-invoicing, e-mail and paper invoices. The element is optional. More info here. Previous instructions in brackets below. (Whether the attachment is sent with the online invoice or e.g. through a printing service. The default is pdf if the attribute is not given.) | |
4 | printbydefault | Numeric | 0...1 | NOTE! Is not given if the attachment type is Finvoice (otherwise the request is rejected) 1= true, 0 = false | 1 |
2 | customtags | Aggr. | 0...1 | ||
3 | tag | Aggr. | 1...n | ||
4 | tagname | String | 1 | The name of the customer additional field in Netvisor | Customer additional field name |
4 | tagvalue | String | 1 | Value of the additional field | Additional information |
Attr. | type | String | 1 | Type of the additional field: float (selection list), date, text or enum (decimal number) | text |
1*) If value is other than DomesticConstructionService is used in SalesInvoiceTaxHandling field, then value of this field is overriden with value DomesticConstructionService if invoice contains at least one line containing tax code Construction_Service_Sales. All lines in invoice must have same tax code.
2*) While importing a sales invoice, the material can include separate voucher lines, if the voucher is wanted to be formed manually. The system will use the voucher lines of the imported material, and not form voucher lines automatically if they have been included. The voucher lines in sales invoice are similar to those in Get Accounting Data request. Allowed VAT-classes and VAT-codes are listed here.
Changelog
Date | Type of change | Description |
2.4.2024 | New element added | When importing a sales invoice, it is now possible to import the follow-up object of the voucher in the accountdimension element. |
Did you find it helpful? Yes No
Send feedback