IntegrationHTTP-methodResourceDTDExample
Import an employeePOSTemployee.nvemployee.dtdDownload
Get employee salary parametersGETgetemployeesalaryparameters.nv Download
Import employee salary parametersPOSTemployeesalaryparameters.nvemployeesalaryparameters.xsdDownload
Get salary typesGETpayrollratiolist.nv Download
Import a payroll paycheck batchPOSTpayrollpaycheckbatch.nvpayrollpaycheckbatch.dtdDownload
Import record line for pay periodPOSTpayrollperiodcollector.nvpayrollperiodcollector.dtdDownload
Import pay advancePOSTpayrolladvance.nvpayrolladvance.dtdDownload
Import external salary payment dataPOSTpayrollexternalsalarypayment.nvpayrollexternalsalarypayment.dtdDownload

 

Import an employee

Resource: employee.nv

Import an employee's information.
Querystring parameters:

Parameter nameOccursExampleDescription
Method1AddAdd or Edit

Request:

LevelElement nameType and lengthOccursDescriptionExample
RootrootAggr.1  
1employeeAggr1  
2employeebaseinformationAggr.1  
3foreignemployeeidentificationAggr.0...1Foreign employeeIf given, do not give employeeidentifier value
4identifierText1Identifier23011970
Attr.typeText1Identifier type, allowed values:
taxidentificationnumber
foreignpersonalidentifier
other
foreignpersonalidentifier
4issuingcountryText1CountryAF
Attr.typeText1Country typeISO-3316
4genderText1Gender,
male
female
male
4dateofbirthDate1Date of birth
1970-10-20
Attr.formatText1Date formatansi
3employeeidentifierText1Finnish employee social security number010277-xxxp 
3companyidentifierText0...1Company indentifier (y-tunnus),
when company is added as an employee
0174564-5
3companynameText0...1Name of the companyTest Company
3firstnameText, max 50 1Employee's first name Carl
3lastnameText, max 50 1Employee's last name Customer
3phonenumberText, max 50 1Employee's phone number 0501234567
3emailText, max 100 1Employees E-mail carl.customer@company.fi
2employeepayrollinformationAggr.1  
3streetaddressText, max 2551Employee's address Examplestreet 1
3postnumberText, max 501Employee's post number 56123
3cityText, max 2551Employee's post officeLappeenranta
3municipalityText, max 2550...1Employees's home cityLappeenranta
3countryText, max 20...1Employee's home country. Default is 'fi'fi
3nationalityText, max 2 0...1Employee's nationalityse
3languageText, max 2 0...1Employee's language fi
3employeenumberNumeric0...1Employee's unique identification number 12
3professionText, max, 2550...1Employee's profession Seller
3jobbegindateText, max 100...1Employee's job begin date, yyyy-mm-dd2014-08-10
Attr.formatText 1Date format, always ansiansi
3payrollrulegroupnameText, max 501 Monthly salary
3bankaccountnumberText, maks. 340...1 Employee's bank account numberFI21 1234 xxxx xxxx xx
3bankidentificationcodeText, max. 200...1Bank's identification code  
3accountingaccountnumberNumeric 0...1You can access company's accounting information in Netvisor from ACCOUNTING > Administration -> Accounting basicc information -> Account list1751
3hierarchyText0...1Hierarchy levelOy Yritys Ab 
AttributetypeText1Linking type of hierarchynetvisor - Netvisor ID
or
customer - If identified by name, name has to be unique
Read about company hierarchy
3dimensionAggr.0...n Default dimensions
4dimensionnameText1Dimension header name.
Created if needed
Cost centers
4dimensionitemText1Dimension name. Created if neededDevOps
AttributefatheridNumeric0...1Dimensions parent ID tunnus. IDs can be retrieved with this resource.1
3payslipdeliverymethodText0...1

Payslip delivery method

1 = local printing
2 = printing service
3 = e-salary

AttributetypeText1Linking type of delivery methodAttribute type is always netvisor, which is Netvisor ID
3isjointownerNumeric0...1In a shareholder relationship with payer1=yes
0=no
3isathleteNumeric0...1Athlete1=yes
0=no
3isperformingartistNumeric0...1Performing atrist1=yes
0=no
3employeeincurancetypeNumeric0...1Employee pension insurance type1=Tyel
2=MYEL
3=YEL
 4=No pension insurance
3ispersonworkingonaroadferryonalandislandsNumeric0...1Person working on a road ferry on Åland Islands

1=yes
0=no

3isentrepreneurwithoptionalyelormyelNumeric0...1Entrepreneur, no YEL or MYEL insurance obligation

1=yes
 0=no

1 conbe given only when employeeincurancetype=4

3nosocialsecuritypaymentNumeric0...1Not subject to employer's sickness insurance payment

1=yes
 0=no

2employmentperiodsAggr.0...1Employments 
3employmentperiodAggr.1...nEmployment 
4companystartdateDate0...1Start date of continuous employment2017-01-01
AttributeformatText1Date formatansi
4startdateDate1Start date2017-01-01
AttributeformatText1Date format ansi 
4probationenddateDate0...1End date of probation2017-04-01
AttributeformatText1Date formatansi
4employmentmodeNumeric0...1Form of employment1 = employed
2 = leased employee
3 = self-employed person or
 similar
4 = trainee
5 = voluntary work
AttributetypeText1

Linking type of employment

Attribute type is always netvisor, which is Netvisor ID

4professionText, max 250
1Professional titleTester
4commentText, max 5000...1CommentKnows what she is doing
4enddateDate0...1End date2017-12-31
AttributeformatText1Date formatansi
4endreasonNumeric0...1End reason

 2=Retirement
4=Employee's own request
5=Reason attributable to the employee
6=Fixed-term employment
11=Financial and production-related grounds for termination
12=End of employment by mutual agreement
13=Other reason
 

 (Not in use anymore: 
1 = Normal employment ending
 
  3 = Employee's death
 
7 = Probation period
 8 = Cancellation of the employment
 
 9 = Bankruptcy of the company
 
10 = Change of ownership of the company)

AttributetypeText1 Linking type of endreason   Attribute type is always netvisor, which is Netvisor ID  
4occupationclassificationText0...1Occupation class  TK10-code of occupation class  
AttributetypeText1 Linking type of occupation classification always isco
4employmentcontractNumeric0...1Duration of employment

1 = Permanent
2 = Temporary
Note: For temporary contract must be given end date 

AttributetypeText1 Linking type of employment contract always netvisor
4employmentformNumeric0...1 1 = Full-time
2 = Part-time
AttributetypeText1 Linking type of employment form always netvisor
4parttimepercentNumeric0...1Part-time percentagePermissible value: decimal number from 0 to 100
Note: employmentform must be 2 so that the setting is taken into account.
Rounding to the nearest two decimal places
4regularworkinghoursNumeric0...1Regular working hours

Permissible value: decimal number from 0 to 168
Rounding to the nearest two decimal places

4groundsforemploymentNumeric0...1Grounds for employment0=Other grounds
1=Working or employment relationship
4kevaprofessionalclasscodeNumeric0...1

Keva professional class code, max 20 characters

KEVA information can only be given is company has selected "Company pension insurer is Keva"

Keva's professional class codes: 
Professional class codes
4kevaemploymentregistrationNumeric0...1

Keva employment registration code, max 2 characters.

Keva employment registration codes:
Keva employment registration codes
AttributetypeText1always kevakeva
AttributepensionprovidercodeText0...1Pension company ID code. If not given, default (20) will be used. This defines which values can be given in kevaemploymentregistrationCodes can be found here:Pension company ID codes
 ispaymenttypemonthlywageNumeric0...1Form of payment: Monthly wages1=yes
0=no
4ispaymenttypehourlywageNumeric0...1Form of payment: Hourly wages1=yes
0=no
4ispaymenttypepiecewageNumeric0...1Form of payment: Contract pay1=yes
0=no
4collectiveagreementNumeric0...1Collective agreementIncomes registers collective agreement codes:
Collective agreement codes
AttributetypeText1always cbacodecbacode
4stateemploymentfundNumeric0...1Employed with assistance from the State employment fund1=yes
0=no
4carbenefityearNumeric0...1Year of commissioning of the company car, max 4 characters2012
4isabroadcarbenefitNumeric0...1Company car benefit received in another country1=yes
0=no
2employeesettingsAggr.0...1Settings for the employee 
3payrollserviceText0...1Payroll operations serviceenabled or disabled
3resourcemanagementText0...1Resource management 
2employeesettlementpointsAggr.0...1Settlement points 
3employeeworkpensioninsuranceAggr.0...1Work pension insurance 
4typeText0...1Settlement point handlingnohandling=no handling
automatichandling=automatic handling
under17yearsold=under 17 years old 
17to52yearsold=17 to 52 years old 
53to62yearsold=53 to 62 years old
63to67yearsold=63 to 67 years old
over68yearsold=over 68 years old
4nameText0...1Insurance specific settlement point definition (* 
3employeeunemploymentinsuranceAggr.0...1Unemployment insurance 
4typeText0...1Settlement point handlingautomatichandling =Automatic handling 
under17yearsold=under 17 years old
17to64yearsold=17 to 64 years old
over65yearsold=over 65 years old
partowner=part owner
4nameText0...1Insurance specific settlement point definition (* 
3employeeaccidentinsuranceAggr.0...1Accident insurance 
4typeText0...1Settlement point handlingnohandling or attachedtosettlementpoint
4nameText0...1Insurance specific settlement point definition (* 
3employeegrouplifeinsuranceAggr.0...1Group life insurance 
4typeText0...1Settlement point handlingnohandling or attachedtosettlementpoint
4nameText0...1Insurance specific settlement point definition (* 
3employeeotherinsuranceAggr.0...1Other insurance 
4typeText0...1Settlement point handlingnohandling or attachedtosettlementpoint
4nameText0...1Insurance specific settlement point definition (* 
3employeeunionmembershipfeeAggr.0...1Union membership fee 
4typeText0...1Settlement point handlingnohandling or attachedtosettlementpoint
4nameText0...1Insurance specific settlement point definition (* 
3employeeforeclosureAggr.0...1fore closure 
4typeText0...1Settlement point handlingnohandling or attachedtosettlementpoint
4nameText0...1Insurance specific settlement point definition (* 

 *) Settlement points: Salary>Payroll>Obligations>Settlements

Note when using this resource:

  • Editing employee is also possible when the employee's employment emplyment is not valid
  • If you are updating existing employee and you are not changing Employee number do not give tag
  • With this resource you cannot set holiday accural. This has to be done in Netvisor UI.
    • For a single employee, the information can be set on the employees's information page
    • For multiple employees, information can be set as mass in the management of holiday rights (Salaries > Holiday calculation settings): Select wanted employees, press "Handle select" and "Set holiday accumulation rule", and then select the wanted rule.
  • If employmentperiods-element has been defined, at least one employment has to be imported
    • startdate- and profession-elements are always mandatory
    • If enddate has been defined, then endreason is also mandatory
  • If employmentperiods-element has not been defined, employees employment will be set as it was before (employeepayrollinformation > profession and jobbegindate)
  • If employmentperiods-element has been defined, employment information will override employeepayrollinformation-definitions
  • If employments will be imported through API already existing (if any) employments will be deleted
  • If company is added as employee, do not give basic employee information, like:
    • employeeidentifier
    • firstname
    • lastname
    • foreignemployeeidentification -element

 

 

Get employee salary parameters

Recourse: getemployeesalaryparameters.nv

If the paycheck does not have a value, the value element returns as an empty element (), whereas the zero value returns as a normal value ( 0,0 ).

With this resource it is possible to get employee salary parameters. Parameters used in the request (GET):

ParameterOccursDescription
 identifiertype  1 Value: pin employee personal identity code or number employee number
 identifier  1 

 Identifier defined by the type: employee personal identity code or employee number 

Response:

LevelElement nameType and lengthOccursDescriptionExample
rootrootAggr.1  
1  employeesalaryparameters  Aggr.1  
2salaryparametersAggr.1  
3parameterAggr.0...n  
4rationumberNumeric1Number of the salary parameter123
 4  value  Decimal 1 Value of the salary parameter 12,34

 

Import employee salary parameters

Recourse: employeesalaryparameters.nv

It is possible to import part of the salary parameters (1-24 pcs at a time) in one request and the other part with another request. No changes are made in the salary parameters existing in Netvisor if they are not specified in the request.

If you want to set salary parameter to zero or update its value, a new value is given in the value element.  If the value of an existing salary parameter is to be completely eliminated, the value element is not given at all in the request.

This resource requires payroll accountant role (P role) from API user. 

LevelElement nameType and lengthOccursDescriptionExample
RootrootAggr.1  
1employeesalaryparametersAggr.1  
2employeeidentification Text 1Identification of the employee123456-123A
 Attribute Type Text 1

  Type of the employee identificationi:
pin or number 
 

 pin 
 2 salaryparametersAggr.1  
3  salaryparameter  Aggr.1...24  
 4 rationumber Numeric 1Number of salary parameter's salary type (company-spesific salary types)123
4value Decimal 0...1Value of salary parameter 12,30 

 

Get salary types

Recourse: payrollratiolist.nv

With this resource it is possible to get company-specific salary types. Salary types are used for importing trip expenses and payslips to Netvisor.

 

ParameterOccursDescriptionExample
source1...n

The request is limited by the salary type, which has to be one of the following:

- tripexpensecustomlines
- taxingrules
- collectorratiolines
- userparameters
- companyparameters
- userformula
- tabledata
- foreclosure
- lowsalarysupport

collectorratiolines

Vastaus:

LevelElementType and lengthOccursDescriptionExample
RootrootAggr.1  
1PayrollRatiosAggr.1  
2PayrollRatioAggr.0...n  
3NameText1-3Name of salary typeUlkomaan päiväraha
AttribuuttiISO639-1CodeText1Language information of salary type's name: fi,se, enfi
3IdentifierNumeric1ID of salary type1
3SourceText1Type of salary typeMatkalasku, kulurivit
3RatioNumberNumeric1Number of salary type123
3DefaultDebitAccountNumberNumeric1Debit account for bookkeeping7890
3DefaultCreditAccountNumberNumeric1 Credit account for bookkeeping 2961

 

Import a payroll paycheck batch

Recourse: payrollpaycheckbatch.nv

Import a payslip into Netvisor.

Request:

LevelElement nameType and lengthOccursDescriptionExample
RootrootAggr.1  
1payrollpaycheckbatchAggr.1  
2employeeidentifierText1Has to exist in Netvisor and the employee must be determined for correct wage model in Netvisor before transferring the data10
Attr.typeText1Type of identiier, either employeenumber or finnishpersonalidentifieremployeenumber
2rulegroupperiodstartDate 1Pay period start date. Note! The period or the previous or next period has to exist in Netvisor. If period is not defined in Netvisor it will be added only if it is the first pay period of wage model or it begins right after the last pay period
2018-02-01
Attr.formatText 1Date format, always ansiansi
2rulegroupperiodendDate 1Pay period end date. Note! The period or the previous or next period has to exist in Netvisor. If period is not defined in Netvisor it will be added only if it is the first pay period of wage model or it begins right after the last pay period
2018-02-28
Attr.formatText 1Date format, always ansi ansi
2freetextbeforelinesText 0...1Free text before payroll lines 
2freetextafterlinesText 0...1Free text after payroll lines  
2duedateDate 1Due date 2018-02-17
Attr.formatText 1Date format. always ansiansi
2valuedateDate 1Value date2018-02-17
Attr.formatText 1Date format, always ansiansi
2payrollpaycheckbatchlineAggr.1...n  
3payrollratioidentifierText 1Salary type as number, has to excist in Netvisor1
Attr.typeText 1Always rationumberrationumber
3unitsNumeric 1Number of units 2
3unitamountNumeric 1price of a single unit 39
3linesumNumeric 1Sum of the line, will not be calculated automatically, has to be given in XML78
3linedescriptionText 0...1Description of the line 
3dimensionAggr.0...n  
4dimensionnameText 1Title of the dimension. If not found, it will be created  
4dimensionitemText 1Dimension name. If not found it will be created  

 

Import record line for pay period

Resource: payrollperiodcollector.nv

 

LevelElementType and lengthOccursDescriptionExample
RootRootAggr.1  
1payrollperiodcollectorAggr.1  
2dateDate1Date 
AttribuuttiformatString1Always ansi 
2employeeidentifierString1

Employee number in Netvisor

 
AttribuuttitypeString1number or personalidentificationnumber 
2payrollratiolineAggr.1...n  
3amountNumber1The amount of the record line 
3payrollratioNumber1Number of record type in Netvisor 
AttribuuttitypeString0...1Always number 
3dimensionAggr.0...n  
4dimensionnameString1Title of dimension. If not found, it will be created 
4dimensionitemString1Name of the dimension. If not found, it will be created 
Attribuuttifatherid 0...1Parent id of the dimension 


Import pay advance

Resource: payrolladvance.nv

Import payment for pay advance

LevelElementType and lenghthOccursDescriptionExample
RootRootAggr.1  
1payrolladvanceAggr.1  
2descriptionString0...1Open description of the event 
2employeeidentifierString1Employeee number 
AttribuuttitypeString0...1number or finnishpersonalidentifier 
2paymentdateDate1

Date of pay advance's payment. Can't be earlier than today

 
AttribuuttiformatString0Always ansi (Nptify that in the DTD there is a miskatake in this, if this attribute is given will an error occur) 
2advancesumNumber1Amount of pay advance 
AttribuuttipaymentstatusString0...1

ispaid or notpaid

 
2paymenttypeString1payroll or tripexpence 

 

 

Importing external salary payment data

Resource: payrollexternalsalarypayment.nv

Is used to import external salary payment data. It is not necessary to import the whole
payslip, only the payment data. The data doesn't need to be linked to an employee in
Netvisor. Payment takes place in Netvisor, resource is quite similar to importing bank transfer.

LevelElement nameType and lengthOccursDescriptionExample
RootRootAggr.1  
1payrollexternalsalarypaymentAggr.1  
2descriptionText1Description of the event. Informal definition
External payment
2paymentdateDate1Payment date = Payday, salary will be on employees account on this date2017-01-01
AttributeformatText ansiansi
2duedateDate1Due date, salary will be charged from company's account2017-01-01
AttributeformatText ansiansi
2externalpaymentsumDecimal1Amount of payment (0.01 < sum < 10000000.0)100,0
2ibanText1Employee's bank account numberFI21 1234 xxxx xxxx xx
2bicText1Bank's identification codeNDEAFIHH
2hetuText1Employee's social security number140785-xxyy
2realnameText1Employee's nameErkki Esimerkki

Either paymentdate or duedate will be set

Elements (paymentdate, duedate) terminology is according to SEPA-bank transfer standard:
SEPA Palkat Tiedote Tammikuu 2009

The date when payers account is charged is given in payment order instead of payment date; On this basis banks take care of that salaries and retirement payments are on recipients accounts at the payday in all banks that operate in Finland. This due date has to be banking day and it has must be a banking day before payday.

On the due date (duedate) salary is charged from company's account.
One banking day is added to the due date so that payment date = payday. If due date is eg. Friday, 3 days will be added so that due date is Monday.

Payment date (paymentdate) = payday, payroll is in employees account.
Banking day interpretation is not done at this moment, it will be interpreted in payment.

 


xml
(2.95 KB)
xml
(415 Bytes)
xml
(948 Bytes)
xml
(325 Bytes)
xml
(412 Bytes)
xml
xml
(299 Bytes)
xml
(513 Bytes)

Oliko tästä vastauksesta apua? Kyllä Ei

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.