Resource: customer.nv
HTTP-method: POST
Used to add a new customer or update an existing one. Fetching the customer list or complete customer details is done with different requests.
If e-invoicing data is provided (customerfinvoicedetails), the correctness of the e-invoicing address is not separately checked. However, the e-invoice operator must be found in the system.
A list of allowed e-invoice operators can be found here.
Parameters used in the call:
| Parameter | Occurrences | Example | Description |
| method | 1 | add | add or edit |
| id | 0...1 | 123 | Customer's NetvisorKey Mandatory when editing customer details |
| checkdimensionvalidityperiod | 0...1 | 1 | Enables validity period check against the voucher date. Import fails if the cost object or header is not valid at the time of the voucher. 1=check enabled |
| useonlyexistingdimensions | 0...1 | 1 | Prevents automatic creation of new cost object headers and cost objects. Returns an error if the given cost object does not exist. 1=prevention enabled |
If the method is not provided or the customer to be updated is not found in the system, an INVALID_DATA error with an explanation is returned. The id of the customer to be updated can be obtained by first querying the customer list.
When updating a customer, only the details to be updated are written in the XML message. Do not write data that you do not want to update into the material: otherwise, the interface will update them to empty.
The salespersonid can be obtained using the Salesperson List retrieval.
*In the organizationunitnumber element (receiver's OVT identifier, if the information differs from the company's business id), you can include some customer-specific information that needs to be conveyed to the recipient with the e-invoice material, such as a factory number or other unchanging information required by the recipient. This field's information is mapped to the BuyerOrganisationUnitNumber tag in the Finvoice material. Do not place the customer's e-invoicing address in this field. Organizationunitnumber element has a validation which requires that the OVT identifier introduced in the element should be in the following format:12..17 digits, and its typical format is 0037AAAAAAAABBBBB where:- 0037 is the Finnish Tax Administration code according to ISO standard 6523 (International Code Designator, ICD)- AAAAAAAA is the Business id including the check digit but without the hyphen- BBBBB is the identifier of the organizational part; not mandatory, numeric, up to five digits, aligned to the left edge of the field.
The data to import is sent with the query as an XML with the following structure (POST-data):
| Level | Element | Format | Occurrences | Description | Example |
| root | root | Aggregate | 1 | ||
| 1 | customer | Aggregate | 1 | ||
| 2 | customerbaseinformation | Aggregate | 1 | ||
| 3 | internalidentifier | String, max. 50 | 0...1 | Customer code | MM123 |
| Attr. | type | String | 0...1 | automatic (if given and customer code is left empty, the next free customer number is used automatically) | automatic |
| 3 | externalidentifier | String | 0...1 | Business id or personal identity code | 1967543-8 |
| 3 | organizationunitnumber | Number, max. 17 | 0...1 | OVT identifier (receiver's OVT identifier, if the information differs from the company's Business id)* | 0037AAAAAAAABBBBB |
| 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 | Street address | Pajukuja 1 |
| 3 | additionaladdressline | String, max. 80 | 0...1 | Additional address line | |
| 3 | city | String, max. 80 | 0...1 | Postal address | Lappeenranta |
| 3 | postnumber | String, max. 50 | 0...1 | Post number | 53100 |
| 3 | country | String | 0...1 | Country code (if not provided, Finland is the default) | FI |
| Attr. | type | String | 0...1 | Country code format | ISO-3166 |
| 3 | customergroupname | String, max. 50 | 0...1 | Customer group name, customer is linked to the group by name. If the group does not exist, it is created. | Alennusasiakkaat |
| 3 | phonenumber | String, max. 80 | 0...1 | Phone number | 040 123456 |
| 3 | faxnumber | String, max. 80 | 0...1 | Fax number | 05 123456 |
| 3 | String, max. 200 | 0...1 | Email address | matti.meikalainen@firma.fi | |
| 3 | homepageuri | String, max. 80 | 0...1 | Website address | www.firma.fi |
| 3 | isactive | Number | 0...1 | 0 or 1, indicates whether the customer is active. | 1 |
| 3 | isprivatecustomer | Number | 0...1 | 0 or 1, indicates whether the customer is a private customer (1=private customer). | 0 |
| 3 | emailinvoicingaddress | String, max. 500 | 0...1 | Email invoicing address, must be a valid email address. Can be provided as a list separated by ; | matti.meikalainen@firma.fi |
| 2 | customerfinvoicedetails | Aggregate | 0...1 | ||
| 3 | finvoiceaddress | String, max. 50 | 1 | E-invoice address, cannot be provided without e-invoice operator information | FI109700021497 |
| 3 | finvoiceroutercode | String, max. 50 | 1 | E-invoice operator id, allowed operators. Cannot be provided without e-invoice address. | NDEAFIHH |
| 2 | customerdeliverydetails | Aggregate | 0...1 | Creates a new office to Netvisor customer details | |
| 3 | deliveryname | String, max. 250 | 0...1 | Delivery address name | Maija Mehiläinen |
| 3 | deliverystreetaddress | String, max. 80 | 0...1 | Delivery street address | Pajukuja 2 |
| 3 | deliverycity | String, max. 80 | 0...1 | Delivery postal address | Lappeenranta |
| 3 | deliverypostnumber | String, max. 50 | 0...1 | Delivery post number | 53100 |
| 3 | deliverycountry | String | 0...1 | Delivery country code | FI |
| Attr. | type | String | 0...1 | Country code format, always ISO-3166 | ISO-3166 |
| 2 | customercontactdetails | Aggregate | 0...1 | ||
| 3 | contactname | String | 0...1 | Not visualized in the interface, do not use | |
| 3 | contactperson | String, max. 80 | 0...1 | Contact person's name, information is transferred to the interface's Last Name field | Matti Meikäläinen |
| 3 | contactpersonemail | String, max. 200 | 0...1 | Contact person's email | matti.meikäläinen@firma.fi |
| 3 | contactpersonphone | String, max. 80 | 0...1 | Contact person's phone number | 040 987 254 |
| 2 | customeradditionalinformation | Aggregate | 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 | Reference number with check digit in correct format | 1070 |
| 3 | usecreditorreferencenumber | Numeric | 0..1 | Use RF reference for invoicing, 1=on 0=off | 1 |
| 3 | useorderreferencenumber | Numeric | 0...1 | Use order reference number for invoicing, 1=on 0=off | 1 |
| 3 | invoicinglanguage | String | 0...1 | Customer's invoicing language, FI, EN or SE. If this information is not provided in the message, the default language for the invoice is Finnish | FI |
| Attr. | type | String | Always ISO-3166 | ISO-3166 | |
| 3 | invoiceprintchannelformat | Numeric | 0...1 | Invoice print 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 lines | |
| 3 | defaulttextafterinvoicelines | String, max. 500 | 0...1 | Default text after invoice lines | |
| 3 | defaultpaymentterm | String | 0...1 | Default payment term | 14 days net |
| Attr. | type | String | 1 | Payment term type, netvisor (id) or customer (name) | customer |
| 3 | defaultsecondname | String | 0...1 | Default auxiliary business name | Auxiliary business name |
| Atrr. | type | String | 1 | Default auxiliary business name type, netvisor (id) or customer (name) | customer |
| 3 | paymentinterest | Numeric | 0...1 | Penalty interest percentage If given as a decimal number, a comma should be used as the decimal separator. | 5 |
| 3 | balancelimit | Numeric | 0...1 | Account limit | 5000 |
| 3 | receivablesmanagementautomationrule | String | 0...1 | Automatic rule for reminders | Private customers |
| Attr. | type | String | 1 | Automatic rule type for reminders netvisor (id) or customer (name) | customer |
| 3 | FactoringAccount | String | 0...1 | Factoring account used by the customer | Factoring account |
| Attr. | type | String | 1 | Factoring account type netvisor (id) or customer (name) | customer |
| 3 | taxhandlingtype | String | 0...1 | Customer tax handling type, valid values are countrygroup, forcedomestic, notaxhandling and domesticconstructionservice | countrygroup |
| 3 | eustandardfinvoice | Numeric | 0...1 | Use EU standard compliant e-invoice. 1 = yes, 0 = no. | 1 |
| 3 | denyinvoicecollection | Numeric | 0...1 | Customer-specific collection prohibition, values 0 and 1. Value 1 sets a customer-specific collection prohibition. | 1 |
| 3 | defaultsalesperson | Aggregate | 0...1 | ||
| 4 | salespersonid | String | 0...1 | Default salesperson's id | |
| Attr. | type | String | 1 | Identifier type, always netvisor | netvisor |
| 2 | customerdimensiondetails | Aggregate | 0...1 | ||
| 3 | dimension | Aggregate | 1...n | ||
| 4 | dimensionname | String | 1 | Default cost object header If the header is not found, a new one is created | Project |
| 4 | dimensionitem | String | 1 | Default cost object If the cost object is not found, a new one is created | Project 1 |
| 4 | dimensionitemcode | String | 0...1 | Cost object code (when this is provided, the dimensionitem element is ignored) | DIMC-001 |
| 4 | dimensionitemname | String | 0...1 | Cost object name (when this is provided, the dimensionitem element is ignored) | Item Name 1 |
Did you find it helpful? Yes No
Send feedback