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 nameOccursDescriptionExample
Method1add 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
Id0...1Must be defined if method = edit or append165

The following describes the XML message to import (POST) a sales invoice into Netvisor:

LevelElement nameType and lengthOccursDescriptionExample
RootrootAggr.1  
1salesinvoiceAggr.1  
2salesinvoicenumberNumeric max. length 18 digits0...1If number is not given, Netvisor automatically picks next free number. Cannot be given for invoice drafts.  123456
2salesinvoicedateDate1Sales invoice date2019-12-31
Attr.formatString1Always ansiansi
2salesinvoiceeventdateDate0...1Invoice's event date. This forms the voucher date.2020-01-01
Attr.formatString1Always ansiansi
2salesinvoiceduedateDate0...1Sales 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.formatString1Always ansiansi
2salesinvoicevaluedateDate0...1Invoice's valuedate. If given, the net days of payment term are applied to the valuedate2019-12-31
Attr.formatString1Always ansiansi
2salesinvoicedeliverydateDate0...1Sales invoice delivery/arrival date.2020-01-04
Attr.formatString1Always ansiansi
2salesinvoicedeliverytocustomerdateDate or week number0...1Delivery date for customer. Date or week number. For sales order only.2018-W12
Attr.formatString 1Delivery date for customer, formatansi
Attr.typeString1Delivery date for customer. date or weeknumber  weeknumber
2salesinvoicewaybillidentifier
String, max 35 characters0...1Waybill number/identifier. For sales order only.33000050143
2salesinvoiceproductpackagepallet
Number 0...1Sales order package. For sales order only.2
Attr.typeString1Pallet code type, GS1GS1
Attr.amountString0...1Pallet amount2
2salesinvoicereferencenumberReferece0...1Invoice reference number. Must be in correct format with check sum. If not given, Netvisor forms the reference number for invoice.1070
2salesinvoiceamountNumeric1Total 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.iso4217currencycodeString0...1If not given, currency code from company´s information is used. Otherwise code must be given in ISO 4217 standard
USD
Attr.currencyrateString0...1If not given, daily currency rate from European central bank is used. If there is no existing currency rate value, then value 1 used automatically1,33
Attr.pricetypeString0...1netvisor 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
2selleridentifierString0...1Link 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.typeString1Type 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
2sellernameString, max. length 500...1Free form name of the sellerMatti Mallikas
2invoicetypeString0...1invoice, order or invoicedraft.
Default is invoice
invoice
2salesinvoicestatusString1Status of invoice
open or unsent for invoice,
delivered or undelivered for order
open
Attr.typeString1Use netvisornetvisor
2salesinvoicefreetextbeforelinesString, max. length 500 0...1Free text before before invoice lines  
2salesinvoicefreetextafterlinesString, max. length 5000...1Free text after invoice lines  
2salesinvoiceourreferenceString, max. length 200  0...1Information for "our reference" field  
2salesinvoiceyourreferenceString, max. length 200 0...1Information for "your reference" field  
2salesinvoiceprivatecommentString, max. length 5000...1Shown only in Netvisor interface, not printed on invoice form 
2invoicingcustomeridentifierString1Information 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.typeString1 Type of link: netvisor (=Netvisor ID), customer (=customer code), or organizationunitnumber (=OVT-identifier) customer
Attr.contactpersonidString0...1Customer's contact person's Netvisor ID. Can be retreived with getcustomer.nv.4012
2invoicingcustomernameString, max. length 2500...1Will not be collected from NetvisorMatti
2invoicingcustomernameextensionString, max. length 250 0...1Will not be collected from NetvisorMeikäläinen
2invoicingcustomeraddresslineString, max. length 100 0...1Will not be collected from NetvisorPajukuja 1
2invoicingcustomeradditionaladdresslineString, max. length 1000...1Will not be collected from Netvisor 
2invoicingcustomerpostnumberString, max. length 50 0...1Will not be collected from Netvisor53100
2invoicingcustomertownString, max. length 50 0...1Will not be collected from NetvisorLappeenranta
2invoicingcustomercountrycodeString0...1In ISO 3316 format. *)FI
Attr.typeString1Will not be collected from NetvisorISO-3166
2officeidentifierString0...1Office 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.typeString0...1automatic when new office should be created according to to sent message. NOTE! All office details must be given in the message.
2deliveryofficeString0...1Delivery office target to Netvisor delivery office in customer details. NOTE! All delivery office details must be given in the message
Attr.typeString1Target type:
Customer=Delivery office name
Netvisor=Delivery office NetvisorID

2deliveryaddressnameString, max. length 250 0...1Will not be collected from Netvisor. Must be given if delivery details should be shown on invoice PDF.Maija
2deliveryaddresslineString, max. length 100 0...1Will not be collected from NetvisorPajukuja 2
2deliveryaddresspostnumberString, max. length 50 0...1Will not be collected from Netvisor55100
2deliveryaddresstownString, max. length 50 0...1Will not be collected from NetvisorImatra
2deliveryaddresscountrycodeString0...1Will not be collected from NetvisorFI
Attr.typeString1Will not be collected from NetvisorISO-3316
2deliverymethodString, max. length 50 0...1Free form text. If given value is not found from Netvisor, then value is created as new delivery method in NetvisorInstalled
2deliverytermString, max. length 50 0...1Free form text. If given value is not found from Netvisor, then value is created as new delivery term in NetvisorAccording to agreement
2salesinvoicetaxhandlingtypeString0...1countrygroup, forcedomestic, domesticconstructionservice or notaxhandling. *1)
If not given, taxhandlingtype from customer's information will be used
countrygroup
2paymenttermnetdays
Numeric
1Invoice date + paymenttermnetdays = invoice duedate.
Payment term: "14 days net"
14
2paymenttermcashdiscountdays
Numeric0...1Cash discount days for the payment term. Payment term: "14 days net, 5 days"
5
2paymenttermcashdiscount
Numeric0...1Cash discount percent Payment term: "14 days net, 5 days-10%"
10
Attr.typeString1Type of discount, always pecentagepercentage
2paymenttermNumeerinen0...1Payment term's NetvisorKey1
Attr.typeMerkkijono1Payment 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
2expectpartialpaymentsNumeric 0...11 = yes, 0 = no. Default 0. If the invoice accepts partial payments, the invoice is also accepting payments outside the the cash discount tolerances1
2overridevouchersalesreceivablesaccountnumberNumeric0...1When given, this will override the default sales receivables account number in Netvisor. Works only with salesinvoices with status "Open". 1703   
2salesinvoiceagreementidentifierString, max. length 350...1Contract ID 
2printchannelformatString0...1  
Attr.typeString 1netvisor or customernetvisor
2secondnameString 0...1supplementary firm nameExample name
Attr.typeString1netvisor (NetvisorKey) or customer (name)customer
2overriderateofoverdueNumeric0...1Penalty interest-%, overrides Netvisor default5,5
2ordernumberString0...1Order number258741
2proposedaccountNumeric0...1Customer's accounting suggestion1011
2typeString1customercustomer
2accountdimensiontextString, max 350...1Customer'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
2collectioncostNumeric0...1Collection cost. Only positive values (and 0) are allowed. Only for sales invoices.15
2isthirdpartysalesNumeric0...1Triangular trade. 0 or 1, where 1 chooses the option "Triangular trade" for sales invoice. Used only for sales invoices.1
2invoicelinesAggr.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:

LevelElement nameType and lengthOccursDescriptionExample
3invoicelineAggr.1...n  
4salesinvoiceproductlineAggr.1  
5productidentifierString1Product identifier, either netvisorkey or given product code. Product must be founded in Netvisor. 
Attr.typeString1Type of indentifier:
- customer (given product code)
- netvisor (netvisorkey)
- primaryeancode
(given primary EAN-code)
- secondaryeancode
(given secondary EAN-code)
netvisor
5productnameString, max. 2001Name of the product. If element is given empty, will be retrieved from Netvisor.test product
5productunitpriceNumeric, max 12 decimal1Product unit price, not retrieved from Netvisor10,05
Attr.typeString1Type of unit price, net or grossnet
5productunitpurchasepriceNumeric0...1Product unit purchase price1,05
Attr.typeString1Type of unit purchase price, always netnet
5productvatpercentageNumeric1Must not conflict with vat code24
Attr.vatcodeString1For 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
5salesinvoiceproductlinequantityNumeric1Amount of products. Can be integer or decimal. Max eight decimals (e.g. 3,55555555)5
5salesinvoiceproductlinediscountpercentageNumeric0...1Discount percentage. If the attribute given, Netvisor will use the discount percentage from customer details in Netvisor10
Attr.typeString1netvisornetvisor
5salesinvoiceproductlinefreetextString, max. 5120...1Free text for the product line 
5salesinvoiceproductlinevatsumNumeric0...1Tax for the product line. Given if amount calculated by Netvisor is wished to be overridden 11,00
5salesinvoiceproductlinesumNumeric0...1Line's gross total sum. Given if sum calculated by Netvisor is wished to be overridden50,00
 Note! Both salesinvoiceproductlinesum and salesinvoiceproductlinevatsum elements are required if sum calculated by Netvisor is wished to be overridden.
5salesinvoiceproductlineinventoryidNumeric0...1Warehouse ID of productline1
5accountingaccountsuggestionNumeric0...1Suggestion for accounting account. Must be found in the system3000
5dimensionAggr.0...n  
6dimensionnameString, max. 501Dimension title, if the dimension is not found, the system creates it 
6dimensionitemString, max. 2001Name of the dimension item 
5provisionpercentage Numeric0...1Provision percentage12
5accrualruleAggr. 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. 
6startmonthNumeric1Starting month9
6startyearNumeric1Starting year2020
6endmonthNumeric0...1 Ending month (only with equal division)12
6endyearNumeric 0...1 Ending year (only with equal division)2020
6divisioncurvenameString 0...1Allocation curve (only with allocation curve)
Has to be predefined in Netvisor view: 'Financials > Budgeting settings > Allocation curves'
quarter
5productunitnameString, max 140...1Product 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
5deliverydateDate0...1Sales order productline delivery date. For sales order only.2021-04-14
Attr.formatString1Always ansi
5OrderNumberNumeric0...1Product order number.1232
5proposedaccountNumeric0...1Customer's accounting suggestion1011
5typeString1customercustomer
5accountdimensiontextString, max 350...1Customer's dimension for invoice rowcost center

If comment lines are needed, use the following structure for InvoiceLine aggregate:

LevelElement nameType and lengthOccursDescriptionExample
3invoicelineAggr.1...n  
4salesinvoicecommentlineAggr.1  
5commentString, max 60001Comment for the invoice Comment for the invoice 

If sublines are needed, use the following structure for InvoiceLine aggregate:

LevelElement nameType and lengthOccursDescriptionExample
3invoicelineAggr.1...n  
4salesinvoicesublineAggr.1  
5sublinearticleidentifierString, max 350...1Product code1
5sublinearticlenameString, max 1001Product nameProduct
5sublinedescriptionString, max 5120...1Line descriptionDescription
5sublineunitcodeString, max 140...1Product unitpcs
5sublineunitpriceNumeric0...1Unit price10
5sublinedeliveredquantityNumeric0...1Delivered quantity1
5sublinediscountpercentNumeric0...1Discount percent0
5sublinevatpercentNumeric0...1Vat percent24
5sublinesumNumeric0...1Line sum12,4
5sublinevatsumNumeric0...1Vat sum2,4

After the invoice lines, the structure continues as follows:

LevelElement nameType and lengthOccursDescriptionExample
2invoicevoucherlinesAggr.0...1
Add only if a sales invoice voucher is to be generated from the API. Otherwise, Netvisor will generate the sales invoice voucher.
3calculationmodeString0...1Voucher'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
3voucherlineAggr.1...n  
4linesumNumeric1Line sum. Positive value will be recorded as debit, and negative as credit 100
Attr. typeString1Type of sum, net or grossnet
4descriptionString, max. 255 0...1Free description text  
4accountnumberString1Account number, must be found in the system 3000
4vatpercentNumeric1VAT percent. Must not conflict with VAT code 24
Attr.vatcodeNumeric1For 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
4accountdimensionString0...1Voucher's follow-up object
Follow-up object 1
attr.
type
String
1name or netvisorkey (shown only in Netvisor)
name
5dimensionAggr.0...n  
6dimensionnameString1Dimension nameProject 1
6dimensionitemString1Dimension item Payroll
2accrualruleAggr. 0...1Accrual rule for the whole invoice, you can use equal division OR allocation curve. Invoicestatus has to be "open", that the voucher is generated.
 
3startmonthNumeric 1Starting month9
3startyearNumeric1Starting year2020
3endmonthNumeric0...1Ending month (only with equal division)12
3endyearNumeric0...1Ending year (only with equal division)20
3divisioncurvenameString0...1Allocation curve (only with allocation curve)
Has to be predefined in Netvisor view: 'Financials > Budgeting settings > Allocation curves'
quarter
2salesinvoiceattachmentsAggr.0...1  
3salesinvoiceattachmentAggr.1...n  
4mimetypeString1MIME type of the attachment Application/pdf 
4attachmentdescriptionString, max 100 characters 1Description of the attachment  
4filenameString, max 255 characters 1Filename of the attachment project1.pdf
4documentdataString1Base64 encoded data of the attachment  
Attr.typeString0..1Values:
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.)
pdf
4printbydefaultNumeric0...1NOTE! Is not given if the attachment type is Finvoice (otherwise the request is rejected)

1= true, 0 = false
1
2customtagsAggr.0...1

3tagAggr.1...n

4tagnameString1The name of the customer additional field in NetvisorCustomer additional field name
4tagvalueString1Value of the additional fieldAdditional information
Attr.typeString1Type 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

DateType of changeDescription
2.4.2024New 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
Sorry we couldn't be helpful. Help us improve this article with your feedback.