Resources - Customer register : Netvisor

Integration	HTTP-method	Resource	DTD	Schema	Example
Get customer list	GET	customerlist.nv			Download
Get customer details	GET	getcustomer.nv			Download
Import customer details	POST	customer.nv	Download		Download
Delete customer details	GET	deletecustomer.nv
Import customer office	POST	office.nv		Download	Download
Import customer contact person	POST	contactperson.nv
Get sales personnel list	GET	salespersonnellist.nv			Download

Get customer list

Resource: customerlist.nv

This section describes how to retrieve a list of customers from Netvisor. The customer list contains basic information (NetvisorID, name, customer's code, company ID and URI for retrieving detailed customer information). Detailed customer information can then be retrieved with Get Customer Details.

Querystring parameters:

Parameter name	Occurs	Description	Example
keyword	0...1	Filters result list with given keyword. Match is searched from following fields: Name, Customer Code, Organization identifier, CoName
changedsince	0...1	Filters result to contain only customers having change after given date, date in format YYYY-MM-DDTHH:mm:ss	2012-01-01
customercodelist	0...1	Filters result with given customercodes. Customercodes should be separated with comma. The list can include maximum of 100 alfanumeric customer codes. Note! Parameter keyword can be used with customercodelist. Filters result with given customercodes AND with given keyword.

Keyword parameter is used over changedsince

Response:

Level	Element name	Type and length	Occurs	Description	Example
1	Customerlist	Aggr.	1
2	Customer	Aggr.	0...n
3	Netvisorkey	Integer	1	Customer identifier in Netvisor	123
3	Name	String	1	Name of the customer	Customer X
3	Code	String	1	Customer code	234
3	OrganisationIdentifier	String	1	Customers organization identifier if not consumer customer	12345678-9
3	CustomerGroupID	Integer	1	Customer Group ID, where the customer belongs. Can be empty.	2
3	CustomerGroupName	String	1	Customer Group Name, where the customer belongs. Can be empty	Customer group 1
3	Uri	String	1	URI that can be used to get details of current customer	/getcustomer.nv?id=123

Get customer details

Resource: getcustomer.nv

In order to retrieve the wanted customer details, the customer ID is needed. This can be picked from the customerlist.

Querystring parameters:

Parameter name	Occurs	Description	Example
id	1	ID of the customer	123
idlist	0...1	Can be used to get the details of several customers with given id. Max. 500 identifiers	1,2,3
replyoption	0...1	Returns customer's invoicing history details.	1

Response:

Level	Element name	Type and length	Occurs	Description	Example
1	Customer	Aggr.	1
2	CustomerBaseInformation	Aggr.	1
3	NetvisorKey	Integer	1	Customer Netvisor key	1001
3	InternalIdentifier	String	1	Customer code	MM
3	ExternalIdentifier	String	1	Organization identifier	1234567-8
3	OrganizationUnitNumber	Integer	0...1	Organization unit number	0037123456715
3	CustomerGroupNetvisorKey	String	0...1	Netvisor identifier of customer group
3	CustomerGroupName	String	0...1	Name of the customer group
3	Name	String	1	Name of the customer	Matti Meikäläinen
3	NameExtension	String	1	Extension for the name of the customer	Toimitusjohtaja
3	StreetAddress	String	1	Customer's street address	Pajukuja 1
3	AdditionalStreetAddress	String	1	Address extension
3	City	String	1	Customer's post office	Lappeenranta
3	PostNumber	String	1	Customer's post number	53100
3	Country	String	0...1	Country code	FI
Attr.	Type	String	0...1	Always ISO-3166	ISO-3166
3	PhoneNumber	String	1	Customer's phone number	040 123 4567
3	FaxNumber	String	1	Customer's fax number	05 123 4567
3	Email	String	1	Customer's E-mail address	matti.meikalainen@firma.fi
3	EmailInvoicingAddress	String	1	E-mail invoice address	matti.meikalainen@firma.fi
3	HomePageUri	String	1	Customer's web site	www.firma.fi
3	IsActive	Numeric	1	0 or 1, is customer active	1
3	IsPrivateCustomer	Numeric	1	0 or 1. Value 1 indicates customer is a private customer	1
2	CustomerFinvoiceDetails	Aggr.	1
3	FinvoiceAddress	String	1	E-invoice address	FI10970021497
3	FinvoiceRouterCode	String	1	E-invoice operator	NDEAFIHH
2	CustomerDeliveryDetails	Aggr.	1	Customer's default office
3	DeliveryName	String	1	Name for the delivery	Matti Meikäläinen
3	DeliveryStreetAddress	String	1	Delivery address	Pajukuja 1
3	DeliveryCity	String	1	Delivery Post office	Lappeenranta
3	DeliveryPostNumber	String	1	Delivery post number	53100
3	DeliveryCountry	String	0...1	Delivery country	FI
Attr.	type	String	0...1	Always ISO-3166	ISO-3166
2	CustomerContactDetails	Aggr.	1
3	ContactPerson	String	1	Default contact person's name
3	ContactPersonEmail	String	1	Default contact person's E-mail address
3	ContactPersonPhone	String	1	Default contact person's Phone number
2	CustomerContactPersons	Aggr.	0...1
3	CustomerContactPerson	Aggr.	1
4	ContactPersonID	Integer	1	Contact person's NetvisorID	1006
4	ContactPersonFirstName	String	1	Contact person's first name	Eric
4	ContactPersonLastName	String	1	Contact person's last name	Example
4	ContactPersonPhoneNumber	Numeric	1	Contact person's phone number	0501234567
4	ContactPersonEmail	String	1	Contact person's E-mail address	eric.example@company.com
4	ContactPersonOfficeNetvisorKey	Numeric	1	Contact person's office NetvisorID	2
2	CustomerOfficeDetails	Aggr.	0...n	Customer offices details
3	OfficeNetvisorKey	Numeric	1	Office NetvisorID	10
3	OfficeName	String	1	Office name	Helsingin toimisto
3	OfficePhoneNumber	String	1	Office phone	040 312 654
3	OfficeTelefaxNumber	String	1	Office fax	05 321 654
3	OfficeIdentifier	String	1	Office identifier	Officeidentifier
3	OfficeContactAddress	Aggr.	1	Office postal address
4	StreetAddress	String	0...1	Street address	Keskuskatu 1
4	PostNumber	String	0...1	Postcode	00100
4	City	String	0...1	City	Helsinki
4	Country	String	0...1	Country	Finland
3	OfficeVisitAddress	Aggr.	1	Visiting address
4	StreetAddress	String	0...1	Street address	Keskuskatu 1
4	PostNumber	String	0...1	Postcode	00100
4	City	String	0...1	City	Helsinki
4	Country	String	0...1	Country	Finland
3	OfficeFinvoiceDetails	Aggr.	1	Office electronic invoicing details
4	FinvoiceAddress	String	0...1	E-invoice address (IBAN or EIA)	003716264123
4	FinvoiceRouterCode	String	0...1	E-invoice operator code	003721291126
2	CustomerAdditionalInformation	Aggr.	1
3	Comment	String	1	Comment text
3	CustomerAgreementIdentifier	String	1	Contract ID
3	ReferenceNumber	String	1	Standard reference
3	UseCreditorReferenceNumber	Numeric	1	Use RF-reference in invoicing. 1 or 0.	1
3	YourDefaultReference	String	1	Your default reference
3	DefaultTextBeforeInvoiceLines	String	1	Default text before invoice rows
3	DefaultTextAfterInvoiceLines	String	1	Default text after invoice rows
3	DefaultPaymentTerm	String	1	Default payment term	14 days net
Attr.	NetvisorKey	String	1	NetvisorKey (ID)	2
3	TaxHandlingType	String	1	Default tax handling type	countrygroup
3	BalanceLimit	Decimal	1	Customer's balance limit, two decimal accuracy.
3	DefaultSalesPerson	String	0...1	Name of the default sales person
3	DiscountPercentage	Numeric	0...1	Discount percentage	10
3	PriceGroup	String	0...1	Price group in which customer is linked
3	FactoringAccount	String	0...1	Customer's factoring account name	Factoring
Attr.	NetvisorKey	Numeric	1	Factoring account's NetvisorID	1
3	InvoicingLanguage	String	0...1	Customer's invoicing language	FI
Attr.	type	String	1	Always ISO-3166
3	EUStandardFinvoice	Numeric	0...1	E-invoice that complies w/ EU standard. 1= Yes, 0 = No.	1
3	CustomerDimensions	Aggr.	0...1
4	Dimension	Aggr.	0...n
5	DimensionName	String	1	Customer specific dimension header	Animals
Attr.	NetvisorKey	String	1	Dimension header Netvisor ID	4
5	DimensionItem	String	1	Customer specific dimension name	Cats
Attr.	NetvisorKey	String	1	Dimension Netvisor ID	117
2	AdditionalInformation	Aggr.	0...1
3	ReceivablesManagement	Aggr.	1	Customer's invoicing details
4	TurnoverDays	Numeric	1	The turnover days for customer's invoices	42
4	TurnoverDeviation	Numeric	1	The turnover deviation for customer's invoices	28

Import customer details

Resource: customer.nv

With customer.nv old customer details can be edited or a new customer can be added to Netvisor.

When editing existing customer details, the XML should only include details that are intended to be updated. If the XML contains blank fields(elements), are these fields updated as blank in Netvisor.

If customerfinvoicedetails element is given, element content validity is not checked. The operator must be still found from system. Below is list of operator codes that are allowed in Netvisor:

Operator	Code
Aktia/Paikallisosuuspankki	HELSFIHH
Ålandsbanken	AABAFI22
Apix Messaging Oy	003723327487
Apix Messaging Oy (old code)	00372332748700001
BasWare Einvoices Oy	BAWCFI22
CGI Suomi (ent. Logica Suomi Oy)	003703575029
Danske Bank	DABAFIHH
DNB Bank ASA, Finland Branch	DNBAFIHX
Enfo	003714377140
Handelsbanken	HANDFIHH
InExchange Factorum AB	INEXCHANGE
InExchange Factorum AB (old code)	SE556700997101
Liaison Technologies Oy (ent. Anilinker)	003708599126
Maventa	003721291126
Netbox Finland Oy	003726044706
Nordea	NDEAFIHH
Notebeat Oy	003717203971
OpusCapita (can be used until 31.12.2018)	003710948874
OpusCapita Solutions Oy	E204503
Osuuspankki	OKOYFIHH
Pagero	003723609900
POP Pankki	POPFFI22
PostNord Strålfors Oy	003701150617
Ropo Capital	003714377140
Säästöpankki	ITELFIHH
S-Pankki/LähiTapiola	SBANFIHH
Sproom ApS	SPROOM
Telia/CGI Finland Oyj	003703575029
Tieto Oyj	003701011385
Peppol	PEPPOL

Querystring parameters:

Parameter name	Occurs	Description	Example
method	1	Add or Edit	Add
id	0...1	Must be defined if method = Edit, defines customer to update	123

If method has not been supplied or the customer to update is not found for the id, an INVALID_DATA -error with further information is returned.

The id of a customer to update can be obtained with Get Customer List, and salesperson id with Get Salespersonnel List.

The data to import is sent with the query as an XML with the following structure:

Level	Element name	Type and length	Occurs	Description	Example
Root	root	Aggr.	1
1	customer	Aggr	1
2	customerbaseinformation	Aggr.	1
3	internalidentifier	String, max 50	0...1	Customer's identifier	MM123
Attr.	type	String	0...1	automatic (if given and internalidentifier is empty, customer's identifier in Netvisor will be the next free customer identifier)	automatic
3	externalidentifier	String	0...1	Organization identifier or private customer social security number	123456-7
3	organizationunitnumber	String, max 17	0...1	Organization unit number	0037123456715
3	name	String, max 250	0...1	Customer's name	Matti Meikäläinen
3	nameextension	String, max 250	0...1	Extension for name	Toimitusjohtaja
3	streetaddress	String, max 80	0...1	Customer's Street address	Pajukuja 1
3	additionaladdressline	String, max 80	0...1	Additional address line
3	city	String, max 80	0...1	Customer's post office	Lappeenranta
3	postnumber	String, max 50	0...1	Customer's post number	53100
3	country	String,	0...1	Customer's country code	FI
Attr.	type	String	0...1	Always ISO-3166	ISO-3166
3	customergroupname	String, max 50	0...1	Customer is attached to group by its name. If group does not exists, new group is created	Alennusasiakkaat
3	phonenumber	String, max 80	0...1	Customer's phone number	040 123456
3	faxnumber	String, max 80	0...1	Customer's fax number	05 123456
3	email	String, max 200	0...1	Customer's E-mail address	matti.meikäläinen@firma.fi
3	homepageuri	String, max 80	0...1	Customer www-address	www.firma.fi
3	isactive	Integer	0...1	0 or 1, indicates whether customer is active	1
3	isprivatecustomer	Integer	0...1	0 or 1, indicates whether customer is a Private Customer	1
3	emailinvoicingaddress	String, max 500	0...1	Valid e-mail invoice address. Can be given as a list, separated with ;.	matti.meikäläinen@firma.fi
2	customerfinvoicedetails	Aggr.	0...1
3	finvoiceaddress	String	1	E-Invoice address	FI109700021497
3	finvoiceroutercode	String	1	E-invoice operator, see valid values from list above	NDEAFIHH
2	customerdeliverydetails	Aggr.	0...1
3	deliveryname	String, max 250	0...1	Recipient of the delivery	Matti Meikäläinen
3	deliverystreetaddress	String, max 80	0...1	Street address	Pajukuja 1
3	deliverycity	String, max 80	0...1	Post office	Lappeenranta
3	deliverypostnumber	String, max 50	0...1	Post number	53100
3	deliverycountry	String	0...1	Country code	FI
Attr.	type	String	0...1	Always ISO-3166	ISO-3166
2	customercontactdetails	Aggr.	0...1
3	contactname	String	0...1
3	contactperson	String, max 80	0...1	Contact person's name	Matti Meikäläinen
3	contactpersonemail	String, max 200	0...1	Contact person's E-mail	matti.maikalainen@firma.fi
3	contactpersonphone	String, max 80	0...1	Contact person's phone number	040 123 4567
2	customeradditionalinformation	Aggr.	0...1
3	comment	String, max 2500	0...1	Comment for the customer register
3	customeragreementidentifier	String, max 35	0...1	Contract ID
3	customerreferencenumber	String	0...1	standard reference
3	Invoicinglanguage	String	0...1	Invoice language: FI, EN or SE. If the element is not given by message, the default language is Finnish	FI
Attr.	type	String	0...1	Always ISO-3166	ISO-3166
3	invoiceprintchannelformat	Integer	0...1	Invoice print channel format 1= Invoice+bank transfer 2=Invoice	1
Attr.	type	String	1	Always netvisor	netvisor
3	yourdefaultreference	String, max 200	0...1	Your default reference
3	defaulttextbeforeinvoicelines	String, max 500	0...1	Default text before invoice rows
3	defaulttextafterinvoicelines	String, max 500	0...1	Default text after invoice rows
3	defaultpaymentterm	String	0...1	Customer default payment term	14 days net
Attr.	type	String	1	netvisor (ID) or customer (name)	customer
3	defaultsecondname	String	0...1	Default second name	Second name
Attr.	type	String	1	netvisor (ID) or customer (name)	customer
3	paymentinterest	Integer	0...1	Penalty interest, value can be between 0-100	5
3	balancelimit	Integer	0...1	Customer balance limit	5000
3	receivablesmanagementautomationrule	String	0...1	Automatic rule for reminders	Private customers
Attr.	type	String	1	netvisor (ID) or customer (name)	customer
3	factoringaccount	String	0...1	Factoring account	1
Attr.	type	String	1	netvisor (ID) or customer (name)	netvisor
3	taxhandlingtype	String	0...1	Customer tax handling type, valid values are countrygroup, forcedomestic, notaxhandling and domesticconstructionservice	countrygroup
3	eustandardfinvoice	Integer	0...1	E-invoice that complies w/ EU standard. 1= Yes, 0 = No.	1
3	defaultsalesperson	Aggr.	0...1
4	salespersonid	String	0...1	Default salesperson's id
Attr.	type	String	1	Always netvisor	netvisor
2	customerdimensiondetails	Aggr.	0...1
3	dimension	Aggr.	1
4	dimensionname	String	1	Default dimension header name. Created if needed.	Project
4	dimensionitem	String	1	Dimension name. Created if needed.	Project 1

Delete customer details

Resource: deletecustomer.nv

Resource can be used to delete single customer's details from Netvisor. The response is "OK" if the customer can be deleted and if the message fails, API tells the reason e.g. "The customer has invoices".

Query string parameter:

Parameter	Occurs	Description	Example
customerid	1	Customer's NetvisorKey (ID)	12

Import customer office

Resource: office.nv

Importing and editing customer's office details.
Querystring parameters:

Parameter	Occurs	Description	Example
method	1	Add or Edit	Add
customerid	1	Customer's NetvisorID	123
officeid	0...1	Office NetvisorID, mandatory when editing existing	1

Notify these:

With edit you can remove information by giving tag as empty
Office name is mandatory, it can never be empty
FinvoiceAddress needs to be genuine OVT or IBAN-number
FinvoiceOperator accepts all the same ID's than other resources, see list above

Level	Element	Type and length	Occurs	Description	Example
Root	root	Aggr.	1
1	office	Aggr.	1
2	name	String	1	Office name
2	phonenumber	String	0...1	Office phone
2	telefaxnumber	String	0...1	Office fax
2	officeidentifier	String	0...1	Office code
2	emailinvoicingaddress	String	0...1	E-mail invoice address of the office
2	officecontactaddress	Aggr.	0...1	Office postal information
3	streetaddress	String	1	Street name
3	postnumber	String	1	Post number
3	city	String	1	City
3	country	String	1	Country code
Attr.	type	String	1	Always ISO-3166
2	officevisitaddress	Aggr.	0...1	Office visiting address
3	streetaddress	String	1	Street name
3	postnumber	String	1	Post number
3	city	String	1	City
3	country	String	1	Country code
Attr.	type	String	1	Always ISO-3166
2	officefinvoicedetails	Aggr.	0...1	Office electronic invoicing details
3	finvoiceaddress	String	1	E-invoice address (IBAN or OVT)
3	finvoiceroutercode	String	1	E-invoice operator

Import customer contact person

Resource: contactperson.nv

Importing, editing and deleting customer's contact person details.

The data to import is sent with the query as an XML with the following structure:

Level	Element	Type and length	Occurs	Description	Example
Root	root	Aggr.	1
1	contactperson	Aggr.	1
2	method	String	1	add\|edit\|delete
2	customeridentifier	Numeric	1	Customer's netvisorkey	12
Attr.	type	String	1	netvisor	netvisor
2	contactpersonidentifier	String	0...1	Contact person's netvisorkey, if editing or deleting contact person	1
Attr.	type	String	1	netvisor	netvisor
2	isdefault	String	0...1	True, sets contact person as default	true
2	firstname	String, max. 100	1	First name	Example
2	lastname	String, max. 100	1	Last name	Customer
2	language	String	1	FI\|EN\|SE	EN
Attr.	type	String	1	Always ISO-3166	ISO-3166
2	phonenumber	Numeric, max. 80	0...1	Phone number	0401234567
2	email	String, max. 200	0...1	Email address	example@example.com
2	title	String, max. 200	0...1		Director
2	officeidentifier	String	0...1	Contact person's office netvisorkey, reset with value 0	4
Atrr.	type	String	1	netvisor	netvisor
2	positionidentifier	String	0...1	Contact person's position netvisorkey, reset with value 0	1
Attr.	type	String	1	netvisor	netvisor
2	contactpersonaddress	Aggr.	1
3	streetaddress	String, max. 80	0...1	Address	Street 1
3	postnumber	Numeric, max. 50	0...1	Post number	00100
3	city	String, max. 80	0...1	City	Helsinki
3	country	String	0...1	Country	Finland
Attr.	type	String	1	Always ISO-3166	ISO-3166

Get sales personnel list

Resource: salespersonnellist.nv

Returns a list of sales personnel.

Level	Element	Type	Occurences	Description	Example
Root	root	Aggr.	1
1	SalesPersonnelList	Aggr.	1
2	SalesPerson	Aggr.	0...n
Attr.	NetvisorKey	String	1	Sales person's Netvisor id	1
3	FirstName	String	1	Sales person's first name	Matt
3	LastName	String	1	Sales person's last name	Smith
3	ProvisionPercent	Integer	1	Sales person's provision percent	10