Visma Nmbrs & 2020 API Changes

API Changes

Due to the changes described above, some API calls will be impacted on the scope of contracts and SVW settings.

The calls impacted are the following: 

API v3

The calls impacted by the WAB 2020 changes will have different fields as described in more detail in the next sections. To make sure the current connections with Nmbrs do not break all of a sudden and the API users have time to adapt, we decided to create a new API version. It means that a new endpoint will be available with the modified calls. 

The following is an example of this for the call: Contract_GetCurrentPeriod

The endpoint of the call is Contract_GetCurrentPeriod v2.1. This call will continue to exist and behave the same way on the version v2.1. Therefore, we will have a new API version v3 which will contain the new call with new behaviour: Contract_GetCurrentPeriod v3.

Domain - New field on the header

On the API v3, there will be a new field on the header, the domain. In Nmbrs the domain is used to login into the salary administration environment, for example: nlpayroll.nmbrs.nl. 

In this example the API header will be:

<soap:Header>
    <AuthHeader xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <Username>string</Username>
      <Token>string</Token>
      <Domain>nlpayroll</Domain>
    </AuthHeader>
  </soap:Header>

The goal of this new field is to improve the performance of the API calls. Currently the authentication takes a considerable amount of time because we have many nodes in Nmbrs. Knowing beforehand what the domain is will enable the data to be retrieved faster. 

Update 03-01-2020: the domain instructions previously indicated the domain to be filled in as follows: nlpayroll.nmbrs.nl. This was changed with an update to nlpayroll.

When will the new calls be available? 

We are developing them with maximum priority and they will be released incrementally, starting with the contract calls. Later, we will release the SVW calls. Stay updated about the new calls following the Nmbrs Update Notes.

Update (24-12-2019): the new contract calls for API v3 are available on this page. The new calls for the SVW settings will be made available with the next update.

How will the calls behave in different years?

The Nmbrs API calls are supposed to work independently of the year they are executed on, therefore the fields of the calls are static. It means that the field will return empty if it does not apply in that year anymore. 

For example, if a call is made to retrieve Contract data from an employee in 2020, it will display the tag <EmploymentType> and <EmploymentSequenceTaxId> empty, because in 2020 these fields are part of SVW Settings and not Contract. 

Also, when executing changes in the past (TWK), using the tag <UnprotectedMode>, the data will need to be inputted according to the year that the change will be applied.

Details of the changes

Below, a description and an example is given about the calls and how they will be impacted on the scope of the WAB changes.

↓ Contract_Get

Changes

  • Return empty if year >= 2020
    • EmploymentType
    • EmploymentSequenceTaxId
  • Added fields to the call 
    • Added WrittenContract
    • Added HoursPerWeek

Calls impacted

Example 

Using the call Contract_GetCurrentPeriod as an example, here is what it will look like: 

Request:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthHeader xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
     <Username>string</Username>
      <Token>string</Token>
      <Domain>string</Domain>
    </AuthHeader>
  </soap:Header>
  <soap:Body>
    <Contract_GetCurrentPeriod xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <EmployeeId>int</EmployeeId>
    </Contract_GetCurrentPeriod>
  </soap:Body>
</soap:Envelope> 

Response: 

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Contract_GetCurrentPeriodResponse xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <Contract_GetCurrentPeriodResult>
        <EmployeeId>int</EmployeeId>
        <EmployeeContracts>
          <EmployeeContract>
            <ContractID>int</ContractID>
            <CreationDate>dateTime</CreationDate>
            <StartDate>dateTime</StartDate>
            <TrialPeriod>dateTime</TrialPeriod>
            <EndDate>dateTime</EndDate>
           <EmploymentType>int</EmploymentType>
            <ContractType>int</ContractType>
           <EmploymentSequenceTaxId>int</EmploymentSequenceTaxId>
            <Indefinite>boolean</Indefinite>
           <WrittenContract>boolean</WrittenContract>
           <HoursPerWeek>int</HoursPerWeek>
          </EmployeeContract>
          <EmployeeContract>
            <ContractID>int</ContractID>
            <CreationDate>dateTime</CreationDate>
            <StartDate>dateTime</StartDate>
            <TrialPeriod>dateTime</TrialPeriod>
            <EndDate>dateTime</EndDate>
            <EmploymentType>int</EmploymentType>
            <ContractType>int</ContractType>
           <EmploymentSequenceTaxId>int</EmploymentSequenceTaxId>
            <Indefinite>boolean</Indefinite>
           <WrittenContract>boolean</WrittenContract>
           <HoursPerWeek>int</HoursPerWeek>
          </EmployeeContract>
        </EmployeeContracts>
      </Contract_GetCurrentPeriodResult>
    </Contract_GetCurrentPeriodResponse>
  </soap:Body>
</soap:Envelope>
 

↓ Contract_Insert

Changes

Added fields to the call

  • Added WrittenContract
  • Added HoursPerWeek

Calls impacted

Example

Using the call Contract_Insert_v2 as an example, here is what it will look like:

Request:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthHeader xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <Username>string</Username>
      <Token>string</Token>
      <Domain>string</Domain>
    </AuthHeader>
  </soap:Header>
  <soap:Body>
    <Contract_Insert xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <EmployeeId>int</EmployeeId>
      <Contract>
        <ContractID>int</ContractID>
        <StartDate>dateTime</StartDate>
        <TrialPeriod>dateTime</TrialPeriod>
        <EndDate>dateTime</EndDate>
        <EmploymentType>int</EmploymentType>
        <ContractType>int</ContractType>
        <EmploymentSequenceTaxId>int</EmploymentSequenceTaxId>
        <Indefinite>boolean</Indefinite>
        <PhaseClassification>int</PhaseClassification>
        <WrittenContract>boolean</WrittenContract>
        <HoursPerWeek>int</HoursPerWeek>
      </Contract>
      <UnprotectedMode>boolean</UnprotectedMode>
    </Contract_Insert>
  </soap:Body>
</soap:Envelope> 

Response:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <Contract_InsertResponse xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <Contract_InsertResult>int</Contract_InsertResult>
    </Contract_InsertResponse>
  </soap:Body>
</soap:Envelope>

 

↓ SVW_Get

Changes

  • Added fields to the call and return empty if year <= 2019:
    • Added EmploymentType
    • Added PhaseClassification
    • Added EmploymentSequenceTaxId
  • Renamed fields to English:
    • InvloedVerzekeringsplicht to InfluenceObligedInsurace
    • PremieKorting to WageCostBenefit
    • PremieKortingVerhoging we don't use since 2012 in Nmbrs UI
    • CodeIabZvw to IncomeRelatedContributionZvw
    • RisicoGroep to RiskGroup

Calls impacted

Example

Using the call SVW_Get as an example, here is what it will look like:

Request:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthHeader xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <Username>string</Username>
      <Token>string</Token>
      <Domain>string</Domain>
    </AuthHeader>
  </soap:Header>
  <soap:Body>
    <SVW_Get xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <EmployeeId>int</EmployeeId>
      <Period>int</Period>
      <Year>int</Year>
    </SVW_Get>
  </soap:Body>
</soap:Envelope>

Response:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <SVW_GetResponse xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <SVW_GetResult>
        <Id>int</Id>
        <InfluenceObligedInsurance>string</InfluenceObligedInsurance>
        <WageCostBenefit>int</WageCostBenefit>
        <PremieKortingVerhoging>boolean</PremieKortingVerhoging>
        <CodeCao>int</CodeCao>
        <Wao_Wia>boolean</Wao_Wia>
        <Ww>boolean</Ww>
        <Zw>boolean</Zw>
        <IncomeRelatedContributionZvw>int</IncomeRelatedContributionZvw>
        <CodeZvw>string</CodeZvw>
        <RiskGroup>int</RiskGroup>
        <Sector>int</Sector>
        <EmploymentType>int</EmploymentType>
        <PhaseClassification>int</PhaseClassification>
        <EmploymentSequenceTaxId>int</EmploymentSequenceTaxId>
      </SVW_GetResult>
    </SVW_GetResponse>
  </soap:Body>
</soap:Envelope>

 

↓ SVW_Update

Changes

  • Added fields to the call and return empty if year <= 2019:
    • Added EmploymentType
    • Added PhaseClassification
    • Added EmploymentSequenceTaxId
  • Renamed fields to English:
    • InvloedVerzekeringsplicht to InfluenceObligedInsurance
    • PremieKorting to WageCostBenefit
    • PremieKortingVerhoging we don't use since 2012 in Nmbrs UI
    • CodeIabZvw to IncomeRelatedContributionZvw
    • RisicoGroep to RiskGroup

Calls impacted

Example

Using the call SVW_Update as an example, here is what it will look like:

Request:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthHeader xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <Username>string</Username>
      <Token>string</Token>
      <Domain>string</Domain>
    </AuthHeader>
  </soap:Header>
  <soap:Body>
    <SVW_Update xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService">
      <EmployeeId>int</EmployeeId>
      <SVWSettings>
        <Id>int</Id>
        <InfluenceObligedInsurance>string</InfluenceObligedInsurance>
        <WageCostBenefit>int</WageCostBenefit>
        <PremieKortingVerhoging>boolean</PremieKortingVerhoging>
        <CodeCao>int</CodeCao>
        <Wao_Wia>boolean</Wao_Wia>
        <Ww>boolean</Ww>
        <Zw>boolean</Zw>
        <IncomeRelatedContributionZvw>int</IncomeRelatedContributionZvw>
        <CodeZvw>string</CodeZvw>
        <RiskGroup>int</RiskGroup>
        <Sector>int</Sector>
        <EmploymentType>int</EmploymentType>
        <PhaseClassification>int</PhaseClassification>
        <EmploymentSequenceTaxId>int</EmploymentSequenceTaxId>
      </SVWSettings>
      <Period>int</Period>
      <Year>int</Year>
    </SVW_Update>
  </soap:Body>
</soap:Envelope>

Response:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <SVW_UpdateResponse xmlns="https://api.nmbrs.nl/soap/v2.1/EmployeeService" />
  </soap:Body>
</soap:Envelope>
last update:

Opmerkingen