Nextens Web API: Functional specification

Nextens Web API: Functional specification

Nextens Web API v1.6.

Overview The Web API allows third party agents to interact with ‘Nextens’ through a HTTP-REST service. These services are ideal for such interaction due to their stateless and lightweight nature. This service gives an external integration client the ability to supply ‘Client’ data expressed through two models: - PersoonModel - OndernemingModel This document will provide detailed information on the usage of this API, including token based authentication and its exposed functions. Examples will be given using screenshots of SoapUi, a Soap and Rest testing tool.


Endpoints Two endpoints will be available for the Web API, a production endpoint and an acceptance endpoint: Production endpoint Acceptance endpoint

https://api.elseviernextens.nl https://apiacc.elseviernextens.nl

The production endpoint is linked to the online production environment of Nextens. The acceptance endpoint can be used for testing purposes.

Authentication In order for external parties to be able to communicate with the Web API, authentication must be established via an access token. For security reasons the access token will only be valid for a short period of time (30 minutes). An access token can be obtained by calling the /token function with a Post containing the following required parameters: grant_type client_id client_secret refresh_token

Must be set to “refresh_token” The identifier for an external party provided by RBI The secret code for the client_id provided by RBI The refresh token provided by RBI

The refresh token will be valid for a long period (currently five years).

Figure 1: obtaining a refresh token

As seen in Figure 1, the authentication call will return with an xml object containing the access_token element that can be used to call the other Web API functions.


The access token must be used when calling other API functions. This can be done by adding an ‘Authorization’ header to the call with value ‘bearer ’ + the access token as can be seen in figure 2.

Figure 2: sending the Authorization header with the bearer access token


API Functions There are two API functions exposed for sending client data:  /klanten/persoon  /klanten/onderneming Each requiring their own model for transferring the data to the API. Detailed information of the models can be found in the two sections below. Both ‘persoon’ and ‘onderneming’ functions require a set of fields that will be used as lookup-fields to determine if the action should create a new or update an existing: For Persoon: 

BSN

For Onderneming 

FiscalNumber and Followup-number (volgnummer)

If the lookup models provide no existing data, the record will be handled as new. The data will be inserted in Nextens.


POST klanten/person Request Information

URI Parameters None.

Body Parameters PersoonModel Name

Type

Achternaam

string

None.

Bsn

string

None.

Voorletters

string

None.

Tussenvoegsels

string

None.

Titel

string

None.

Achtervoegsels

string

None.

Geboortedatum

GeboortdatumOnbekend Model

None.

Geslacht

Geslacht

None.

Klantnummer

string

None.

Kantoor

string

None.

Beconnummer

string

None.


Additional info

Description

Name

Type

VolmachtOntvangen

boolean

None.

KlantSinds

date

None.

KlantTot

date

None.

TelefoonnummerThuis

string

None.

TelefoonnummerMobiel

string

None.

TelefoonnummerWerk

string

None.

Faxnummer

string

None.

EmailAdres

string

None.

Straatnaam

string

None.

Huisnummer

string

None.

HuisnummerToevoeging

string

None.

Postcode

string

None.

Plaats

string

None.

LandCode

string

None.

TeamDossiernummer

string

None.

Opmerkingen

string

None.

BelastingdienstkantoorCode

integer

None.


Additional info

Description

ISO 3166-1 alpha 3

Request Formats application/xml, text/xml Sample: 1 720a30a9-b8ad-4ad2-9c02-52f22e446cab sample string 1 sample string 6 sample string 9 sample string 2 <EmailAdres>sample string 14 sample string 13 2014-10-20T13:58:34.5040828+02:00 true Man sample string 16 sample string 17 sample string 8 2014-10-20T13:58:34.5050828+02:00 2014-10-20T13:58:34.5050828+02:00 sample string 7 sample string 20 sample string 22 sample string 19 sample string 18 <Straatnaam>sample string 15 sample string 21 sample string 11 sample string 10 sample string 12 <Titel>sample string 5 sample string 4


true sample string 3


POST klanten/onderneming Request Information

URI Parameters None.

Body Parameters OndernemingModel Name

Type

Additional info

Klantnummer

string

None.

Fiscaalnummer

string

Required

Volgnummer

integer

Required Range: inclusive between 0 and 99

Werkzaamheden

String

Not required. Values: “Vpb”, “Btw”, “Vpb Btw”

NaamOnderneming

string

None.

VolmachtOntvangen

boolean

None.

KlantSinds

date

None.

KlantTot

date

None.

Telefoonnummer

string

None.


Description

The types of products the client will be using. If no value is provided, the correct value will be determined based on existing entitlements.

Name

Type

Additional info

Faxnummer

string

None.

EmailAdres

string

None.

PostadresStraatnaam

string

None.

PostadresHuisnummer

string

None.

PostadresHuisnummerToevoeging

string

None.

PostadresPostcode

string

None.

PostadresPlaats

string

None.

PostadresLandCode

string

None.

BezoekadresStraatnaam

string

None.

BezoekadresHuisnummer

string

None.

BezoekadresHuisnummerToevoeging

string

None.

BezoekadresPostcode

string

None.

BtwPeriodInterval

BtwPeriodInterval

None.

BookYearStartDate

date

None.

BookYearEndDate

date

None.

ICPPeriodInterval

ICPPeriodInterval

None.

BankAccountNumber

string

None.


Description

ISO 3166-1 alpha 3

Name

Type

Additional info

BezoekadresPlaats

string

None.

BezoekadresLandCode

string

None.

TeamDossiernummer

string

None.

Opmerkingen

string

None.

EindeBedrijfsactiviteitenMetIngangVan

date

None.

InvoerenDueDateDays

integer

None.

ControlerenDueDateDays

integer

None.

AccorderenDueDateDays

integer

None.

BelastingdienstkantoorCode

integer

None.

Description

Request Formats application/xml, text/xml Sample: 1 d8002d93-064e-4d51-8273-33a5dd358311 1 sample string 17 sample string 14 sample str 15 sample string 19 sample string 18 sample string 16 sample string 13


2014-10-20T13:57:16.3000828+02:00 2014-10-20T13:57:16.3000828+02:00 NotSet 1 <EindeBedrijfsactiviteitenMetIngangVan>2014-10-20T13:57:16.3000828+02:00 <EmailAdres>sample string 6 sample string 5 sample string 2 NotSet 1 2014-10-20T13:57:16.2990828+02:00 2014-10-20T13:57:16.2990828+02:00 sample string 1 sample string 3 sample string 21 sample string 8 sample string 9 sample string 12 sample string 11 sample string 10 sample string 7 sample string 20 sample string 4 1 true


GeboortdatumOnbekendModel Name

Type

Additional information

Geboortedatum

date

None.

GeboortedatumOnbekend

boolean

None.

Geslacht Possible enumeration values:

Name

Man

Vrouw

BtwPeriodInterval Possible enumeration values:

Name

NotSet

PerMonth PerQuarter


Name

PerJaar BoekJaarQuarterV1 BoekJaarQuarterV2

ICPPeriodInterval Possible enumeration values:

Name

NotSet

PerMonth PerQuarter PerJaar PerTweeMaanden

Notes In case a non required field is unknown to the client, he has the ability to either send a ‘nil’ value, or not send the field at all. Take note that an omitted/nulled value results in not saving the field in the system at all. If it is intended to persist an empty field, the client will need to send the field with an empty string as content. The following example shows how the field ‘Tussenenvoegsels’ is omitted (not persisted) and included as empty (persisted). Nextens Web API v1.6.

application/xml, text/xml Sample: Excluding the ‘tussenvoegsels’ field by not providing it at all 720a30a9-b8ad-4ad2-9c02-52f22e446cab J Doe 123443210

application/xml, text/xml Sample: Excluding the ‘tussenvoegsels’ field by sending a nil value 720a30a9-b8ad-4ad2-9c02-52f22e446cab J Doe 123443210

application/xml, text/xml Sample: Including the ‘tussenvoegsels’ field by sending an empty string 720a30a9-b8ad-4ad2-9c02-52f22e446cab J Doe 123443210


Apendix 1: BelastingdienstkantoorCodes Possible enumeration values: Code

(No column name)

2

Amsterdam (Kingsfordweg 1)

4

Hoofddorp (Mercuriusplein 37)

5

Helmond (Stationsplein 9)

11

Gorinchem (Vroedschapstraat 15)

12

Apeldoorn (Stationsplein 50)

13

Arnhem (Groningensingel 21)

14

Almere (Willem Dreesweg 24)

15

Doetinchem (Hamburgerbroeklaan 12)

16


18

Maastricht (Terra Nigrastraat 10)

21

Roermond (Kapellerpoort 1)

23

Almelo (Stationsstraat 5)

27

Eindhoven (Karel de Grotelaan 4)

30

Den Bosch (Kooikersweg 1)

31

Goes (Stationsplein 21)

33

Oss (Lievekamplaan 1)

35

Terneuzen (Rosegracht 1)

36

Tilburg (Prof. CobbenhagenLn 9)

42

Groningen (Kempkensberg 12)

50



53

Heerlen (Kloosterweg 22)

66

Den Haag (Prinses Beatrixlaan 512)

68

Rotterdam (Laan op Zuid 45)

73

Amersfoort (Inputplein 1)

77

Gouda (Prinses Beatrixlaan 512)

78

Hilversum (Stationsplein 12)

80

Leiden (Willem de zwijgerlaan 2)

82

Utrecht (Herman Gorterstraat 55)

87


92

Enschede (Hengelosestraat 75)

93

Emmen (Verlengde spoorstraat 2)

97

Zwolle (Burg. Drijbersingel 27)

99

Heerlen BUIT (Kloosterweg 22)

101

Leeuwarden (Tesselschadestraat 4)

103

Nijmegen (Stieltjesstraat 2)

105

Dordrecht (Spuiboulevard 220)

106

Haarlem (Surinameweg 4)

107

Amsterdam (Kingsfordweg 1)

108


109

Groningen (Dr C Hofstede de Gr.kd 11)

110

Oss (Lievekamplaan 1)

111

Heerlen (Kloosterweg 22)

112

Heerenveen (Stationsplein 4)

113

Emmen (Verlengde spoorstraat 2)


114


115

Apeldoorn (Stationsplein 50)

116

Den Haag (Prinses Beatrixlaan 512)

117

Eindhoven (Karel de Grotelaan 4)

118

Roermond (Kapellerpoort 1)

119

Maastricht (Terra Nigrastraat 10)

120


121

Zwolle (Burg. Drijbersingel 27)

122


123

Enschede (Hengelosestraat 75)

124

Doetinchem (Hamburgerbroeklaan 12)

125


126


127

Leiden (Willem de zwijgerlaan 2)

128

Rijswijk (Prinses Beatrixlaan 512)

129

Hoorn (Nieuwe Steen 4)

130

Alkmaar (Robonsbosweg 1)

131

Zaandam (Bossingschaaf 20)

132

Hoofddorp (Mercuriusplein 37)

133

Breda (Gasthuisvelden 11)

134

Roosendaal (Mill Hillplein 1)

135

Venlo (Hogeweg 85)

136

Heerlen BUIT (Kloosterweg 22)

137

Den Haag (Stationsplein 75)


138


139


140


141


142

Rotterdam (Laan op Zuid 45)

143

Hilversum (Stationsplein 12)

144

Gorinchem (Vroedschapstraat 15)

145

Gouda (Prinses Beatrixlaan 512)

146

Amsterdam 1 (Kingsfordweg 1)

147

Amsterdam 2 (Kingsfordweg 1)

148

Helmond (Stationsplein 9)

149

Den Bosch (Kooikersweg 1)

150

Rotterdam 1 (Laan op Zuid 45)

151

Rotterdam 2 (Laan op Zuid 45)

152

Tilburg (Prof. CobbenhagenLn 9)

153

Goes (Stationsplein 21)

154

Amersfoort (Inputplein 1)

155

Hoorn (Nieuwe Steen 4)

156

Alkmaar (Robonsbosweg 1)

157

Zaandam (Bossingschaaf 20)

159


160

Roosendaal (Mill Hillplein 1)

161

Venlo (Hogeweg 85)

162

Dordrecht (Spuiboulevard 220)


163


164

Leeuwarden (Tesselschadestraat 4)

165

Nijmegen (Stieltjesstraat 2)

166

Terneuzen (Rosegracht 1)


Nextens Web API: Functional specification

Recommend Documents