KVK Dataservice: connecting a business

Standards

KVK applies the standards as shown in the tables below.

For connecting, you need to have:

• A network connection + routing over the internet
• A source system that can make a network connection to the KVK Dataservice through a double-sided SSL secured connection;
• Messaging must meet WS-Security requirements;
• Qualified and valid certificate.

Current WSDLs can be found at http://schemas.kvk.nl/contracts/kvk/

Current XSDs can be found at http://schemas.kvk.nl/schemas/kvk/

The overview below shows the standards used by KVK in its online services. Please note any comments on the standards used.

Transport level

Network protocol (using TCP/IP, DNS, etc.)

IETF RFC standard RFC5246 on TLS (transport layer security), as recommended in WS-I BSP 1.0 for transport security.

KVK Basis profile

The table below shows which versions of the followed industry standards are used by the KVK.

Content level

Certificates

Requirements Certificate for Market Connections

The KVK imposes the following requirements on the certificate to be used for connecting to the KVK Data Service:

1. Certificates must be obtained from a recognised certificate service provider;
2. Wildcard certificates are not accepted by the KVK Dataservice;
3. The key pair must at least use RSA keysize 2048 and the SHA-256 algorithm;
4. Your production SSL certificate must meet the quality of an Organisation validation SSL certificate;
5. SSL certificates for development and test work should at least meet the quality Domain validation SSL certificate;
6. The public key of the certificate must be presented to KVK in Base64 (.cer) format as a .txt file in accordance with the following naming convention: <name organisation>-<date>.txt

For more information about Organisation and Domain validation certificates, contact your certificate provider.

PLEASE NOTE: You are responsible for renewing the certificates and submitting the public key(s) of these certificates to KVK in a timely manner.

KVK Certificates 

To use two-way authentication with our interface, you need to trust the KVK certificates.

Certificates from November 2023:

• Certificates 2023 11 PREPROD environment
• Certificates 2023 11 PRD environment

Project examples

We have compiled a number of test projects, so that you can see the setup of the request messages and test to see if they work correctly. How you can make use of these SoapUI project examples is described in the Toelichting KVK SoapUI Project (pdf, in Dutch).

• SoapUI project example for product Inschrijving en Vestigingen (Registration and Offices): SoapUI voorbeelden (zip, in Dutch)
• SoapUI project example for product Jaarrekening (Financial statement): SoapUI voorbeelden (zip, in Dutch)
• SoapUI project example for product Overzicht Deponeringen (Overview of filed documents): SoapUI voorbeelden (zip, in Dutch)
• SoapUI project example for product Uittreksel UBO-Register (UBO Register extract): SoapUI voorbeelden (zip, in Dutch)
• SoapUI project example for product Uittreksel Handelsregister Kamer van Koophandel (KVK Business Register Extract): SoapUI voorbeelden (zip, in Dutch)

Connecting pre-production

Webservice working principles

• Your application composes the request message in accordance with the KVK requirements;
• The request is delivered to the KVK Dataservice;
• KVK checks whether the query is authorised;
• KVK formulates the response;
• The response is returned via the KVK Dataservice to your application.

The naming of the elements is chosen to minimise confusion about the expected value.

(1) Template header request message

Request messages for the KVK Data Service should at least comply with the template, as shown in the example below and in accordance with the SOAP 1.1 standard. If you are a node ([3] in the service model), the wsa:From should be added to the standard template. By means of the wsa:From, your customer is identified in accordance with the agreements you have made with KVK in this respect.

<soapenv:Envelope xmlns:ns="http://schemas.kvk.nl/schemas/hrip/dataservice/2015/02"
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:wsa="http://www.w3.org/2005/08/addressing">

   <soapenv:Header>
        <wsa:MessageID >uuid:1234 </wsa:MessageID>
        <wsa:To >http://es.kvk.nl/kvk-dataservicePP/2015/02</wsa:To>
        <wsa:Action >http://es.kvk.nl/[PRODUCT]</wsa:Action>
   </soapenv:Header>

   <soapenv:Body >
    <!-- BERICHT -->
   </soapenv:Body>
</soapenv:Envelope>

(2) WS Security

For signing the message, the OASIS WS Security message-level security standard version 2004/01 should be applied. Within the WS Security framework, we use the Web Services Security 3 X.509 Certificate Token Profile.

The following message content should be digitally signed:

The following algorithms are used for signing. These should be correctly applied in the CanonicalisationMethod, SignatureMethod and DigestMethod (Transforms) in the message:

• Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"
• Algorithm=”http://www.w3.org/2000/09/xmldsig#rsa-sha1” of “http://www.w3.org/2001/04/xmldsig-more#rsa-sha256”

Response messages:

Response messages from the KVK Dataservice are digitally signed. You as recipient should take into account in the development of your application that only the following algorithms are applied in the response message:

• Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"
• Algorithm=”http://www.w3.org/2001/04/xmldsig-more#rsa-sha256”

(3) WS Addressing

WS Addressing 1.0 version 200508 should be applied to routing (see http://www.w3.org/TR/ws-addr-soap/).

From (wsa:From) – Only for use as a node

You identify the wsa:From as a node and your client with KVK. You need to agree with KVK on the predefined URI. KVK will identify you as a node based on the value generated by KVK. The identification value of your client must be known to KVK. For the value of, only the following characters are accepted: a-z, A-Z, 0-9 and the ‘.’.

```xml
<wsa:From>
    <wsa:Address>http://<knooppuntNaam>/<klantKnooppunt></wsa:Address>
</wsa:From>
```

Destination (wsa:To) - 2015/02

The wsa:To specificies the service being called upon:

• PREPROD: wsa:To=http://es.kvk.nl/kvk-dataservicePP/2015/02
• PROD: wsa:To= http://es.kvk.nl/kvk-Dataservice/2015/02

Action (wsa:Action)

The wsa:Action specificies the service operation and so the product you want the KVK Dataservice to deliver: 

• wsa:Action=http://es.kvk.nl/ophalenInschrijving
• wsa:Action=http://es.kvk.nl/ophalenVestiging

Destination (wsa:To) - 2018/01

The wsa:To specificies the service being called upon:

• PREPROD: wsa:To=http://es.kvk.nl/kvk-dataservicePP/2018/01
• PROD: wsa:To= http://es.kvk.nl/kvk-Dataservice/2018/01

Action (wsa:Action) 

The wsa:Action specificies the service operation and so the product you want the KVK Dataservice to deliver: 

• wsa:Action=http://es.kvk.nl/opvragenBeschikbareBoekjaren 
• wsa:Action=http://es.kvk.nl/opvragenBeschikbareJaarrekeningen 
• wsa:Action=http://es.kvk.nl/opvragenJaarrekening 
• wsa:Action=http://es.kvk.nl/opvragenKvkUittrekselUboRegister 

#### Destination (wsa:To) - 2020/01 

The wsa:To specificies the service being called upon:

• PREPROD: wsa:To=http://es.kvk.nl/KVK-DataservicePP/2020/01
• PROD: wsa:To= http://es.kvk.nl/KVK-Dataservice/2020/0

Action (wsa:Action)

The wsa:Action specificies the service operation and so the product you want the KVK Dataservice to deliver: 

• wsa:Action=http://es.kvk.nl/opvragenKvkHandelsregisterUittrekselRequest

#### Message Id (wsa:MessageID)

The wsa:MessageID contains a unique uuid-based reference specified by you, the customer.

This will be referred to in the response. If no or an incorrect wsa:MessageID is given, the request message will be rejected by the KVK Data Service.

• wsa:MessageID="uuid:<willekeurige-waarde>"
• Example: <wsa:MessageID>uuid:550e8400-e29b-41d4-a716-446655440000</wsa:MessageID>

Please note: Some IDE tooling such as Microsoft Visual Studio, for example, inserts ‘urn:’ before ‘uuid:’. The KVK Data Service checks will reject a request with this syntax!

ReplyTo (wsa:ReplyTo)

Optionally, you can use the 'ReplyTo' element. Use of this is free as long as the element is correctly digitally signed.

Response messages

In the response message from the KVK Dataservice, wsa:RelatesTo is added in the header with the MessageID from the request message as reference (see example below).

<wsa:RelatesTo>
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="[ID-relates-to]">
</wsa:RelatesTo>

(4) Structure request message

    <soapenv:Envelope xmlns:ns="http://schemas.kvk.nl/schemas/hrip/dataservice/2015/02"
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:wsa="http://www.w3.org/2005/08/addressing">

   <soapenv:Header>

        <wsa:MessageID >uuid:7ad97e7a-26d7-4c4e-997c-1f7e0e88aa97</wsa:MessageID>
        <wsa:To >http://es.kvk.nl/kvk-dataservicePP/2015/02</wsa:To>
        <wsa:Action >http://es.kvk.nl/[PRODUCT]</wsa:Action>

   </soapenv:Header>
   <soapenv:Body>
      <ns:[PRODUCTREQUEST]>
         <klantreferentie>[KLANTREFERENTIE]</klantreferentie>
         <ns:[SLEUTEL]>[WAARDE]</ns:[SLEUTEL]>
      </ns:[PRODUCTREQUEST]>
   </soapenv:Body>

</soapenv:Envelope>

The above example shows the structure of the request message.

(5) Structure response message

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/08/addressing">
   <soapenv:Header>
      <wsa:RelatesTo>uuid:12345</wsa:RelatesTo>
</soapenv:Header>
<soapenv:Body wsu:Id="Id-67270ae5-eba5-41eb-acd1-fcf82b23f3b2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
      <ophalenInschrijvingResponse peilmoment="20151209161015653">
         <meldingen>
            <informatie>
               <code>IPD0000</code>
               <omschrijving>Het product is succesvol geproduceerd.</omschrijving>
               <referentie>[REFERENTIE]</referentie>
            </informatie>
         </meldingen>
         <product>
           <!-- Content -->
         </product>
      </ophalenInschrijvingResponse>
   </soapenv:Body>
</soapenv:Envelope>

The choice of the product determines the result of the response. The above structure contains the basic structure of a successfully handled request for the product retrievalSubscription.

The response message consists of a header, product response and content block. The product response block contains error code, warnings, and/or information. Each has the same structure: code, description and reference. See the Data Catalog and/or Functional Data Service Descriptions for associated status messages.

There are different response structures, depending on the content per product. To find out what they are, consult the voorbeelden and gegevenscatalogus (examples and data catalogue, in Dutch) in the connection package.

1. Your application composes the request message according to the KVK requirements;
2. The request is delivered to the KVK Dataservice;
3. KVK checks whether the query is allowed;
4. KVK formulates the response;
5. The response is returned via the KVK Dataservice to your application.

Please note: For the elements below in the body of the response message, the date and time corresponds to time zone UTC +1 (or UTC +2, due to daylight saving time).

• ophalenInschrijvingResponse peilmoment=“20180516133657251”…
• ophalenVestigingResponse peilmoment=“20180516133546143”…

All other times mentioned (outside the response message body) are UTC (Zulu).

The naming of the elements has been chosen to minimise confusion about the expected value.

Technical data

KVK Dataservice table

Message examples

In this section, you can find compressed files containing sample messages of products delivered through our KVK Data Service. Multiple examples of the request and response messages are available for each product. The message examples are all in Dutch.

• Voorbeeldberichten KVK Handelsregister Inschrijving en Vestiging
• Voorbeeldberichten Jaarrekeningen
• Voorbeeldberichten KVK Uittreksel UBO-register
• Voorbeeldberichten Overzicht Deponeringen
• Voorbeeldberichten Uittreksel Handelsregister Kamer van Koophandel