KVK Dataservice bedrijf aansluiten

Lees alles over het aansluiten van je bedrijf op KVK Dataservice. Het begint met het maken van een analyse en oriënteren. Vervolgens vul je de randvoorwaarden en certificaten in. Daarna volgt het aansluiten van de PREPROD omgeving en het testen en als laatste het aansluiten op de productieomgeving.

Standaarden

De KVK past de standaarden toe zoals in onderstaande tabellen is weergegeven.

Voor het aansluiten dien je te beschikken over:

• Een netwerkaansluiting + routering over het internet
• Een bronsysteem dat een netwerkverbinding kan maken met de KVK Dataservice door een dubbelzijdig SSL beveiligde verbinding;
• Het berichtenverkeer moet voldoen aan de eisen van WS-Security;
• Gekwalificeerd en geldig certificaat.

Actuele WSDL’s kun je vinden op http://schemas.kvk.nl/contracts/kvk/

Actuele XSD’s kun je vinden op http://schemas.kvk.nl/schemas/kvk/

In onderstaand overzicht vind je de door de KVK gehanteerde standaarden in het gebruik van haar web services. Wij attenderen je op eventuele opmerkingen m.b.t. de gehanteerde standaarden.

Transport niveau

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

IETF RFC standaard RFC5246 over TLS (transport layer security), zoals aanbevolen in WS-I BSP 1.0 voor transport security.

KVK Basis profiel

Onderstaande tabel toont welke versies van de gevolgde industrie standaarden gehanteerd worden door de KVK.

Content niveau

Certificaten

Voorwaarden Certificaat voor Markt aansluitingen

De KVK stelt de volgende eisen aan het te gebruiken certificaat voor verbinding met de KVK Dataservice:

1. Certificaten dienen betrokken te worden van een erkende certificaat dienstverlener;
2. Wildcard certificaten worden niet geaccepteerd door de KVK Dataservice;
3. Het sleutelpaar moet minimaal gebruik maken van RSA keysize 2048 en het SHA-256 algoritme;
4. Jouw productie SSL certificaat moet voldoen aan de kwaliteit van een Organisatie validatie SSL certificaat;
5. SSL certificaten voor ontwikkeling en test werkzaamheden dienen minimaal te voldoen aan de kwaliteit Domain validatie SSL certificaat;
6. De publieke sleutel van het certificaat dient in Base64 (.cer) formaat bij de KVK als een .txt bestand te worden aangeboden conform de volgende naamgeving conventie: <naam organisatie>-<datum>.txt

Voor meer informatie over Organisatie- en Domain validatie certificaten neem je contact met jouw certificaat leverancier.

LET OP: Je bent zelf verantwoordelijk voor het vernieuwen van de certificaten en tijdig de public key(s) van deze certificaten door te geven aan de KVK.

Certificaat KVK

Om gebruik te kunnen maken van de tweeweg authenticatie met ons koppelvlak, dien je de certificaten van KVK te vertrouwen.

Certificaten vanaf november 2023:

• Certificaten 2023 11 PREPROD omgeving
• Certificaten 2023 11 PRD omgeving

Voorbeeldprojecten

We hebben een aantal testprojecten samengesteld, zodat je de opbouw van de request berichten kunt zien en uitproberen of deze correct werken. Hoe je gebruik kunt maken van deze SoapUI voorbeeldprojecten staat in de Toelichting KVK SoapUI Project (PDF) beschreven.

• SoapUI voorbeeldproject voor product Inschrijving en Vestigingen: SoapUI voorbeelden (ZIP)
• SoapUI voorbeeldproject voor product Jaarrekening: SoapUI voorbeelden (ZIP)
• SoapUI voorbeeldproject voor product Overzicht Deponeringen: SoapUI voorbeelden (ZIP)
• SoapUI voorbeeldproject voor product Uittreksel UBO-Register: SoapUI voorbeelden (ZIP)
• SoapUI voorbeeldproject voor product Uittreksel Handelsregister Kamer van Koophandel: SoapUI voorbeelden (ZIP)

Voor afnemers die geen gebruik maken van een SoapUI koppeling hebben we ook een .NET project welke je kunt laden in Visual Studio. .NET voorbeeldproject voor product Inschrijving en Vestigingen: .NET voorbeelden

Aansluiten pre-productie

Webservice werkingsprincipes

• Jouw applicatie stelt het request bericht samen conform de KVK eisen;
• Het request wordt afgeleverd aan de KVK Dataservice;
• De KVK controleert de bevraging of deze is toegestaan;
• De KVK formuleert de response;
• De response wordt geretourneerd via de KVK Dataservice naar jouw applicatie.

De naamgeving van de elementen is zo gekozen dat zo min mogelijk verwarring kan ontstaan over de verwachte waarde.

(1) Template header request bericht

Request berichten voor de KVK Dataservice moeten minimaal voldoen aan de template, zoals getoond in onderstaand voorbeeld en conform de SOAP 1.1 standaard. Indien je een knooppunt bent ([3] in het servicemodel) dient de wsa:From aan het standaard template te worden toegevoegd. Middels de wsa:From wordt jouw klant geïdentificeerd conform de afspraken die je met de KVK hierover heeft gemaakt.

 

<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

: Voor de ondertekening van het bericht dient de OASIS WS-Security message-level security standaard versie 2004/01 te worden toegepast. Binnen het WS-Security framework maken we gebruik van het Web Services Security 3 X.509 Certificate Token Profile.

De volgende content uit het bericht dient digitaal te worden ondertekend:

Voor het ondertekenen wordt er gebruik gemaakt van onderstaande algoritmen. Deze dienen dan ook correct te worden toegepast in de CanonicalizationMethod, SignatureMethod en DigestMethod (Transforms) in het bericht:

• 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 berichten

: Response berichten vanuit de KVK Dataservice zijn digitaal ondertekend. Je dient als ontvanger rekening te houden in de ontwikkeling van jouw applicatie dat alleen de volgende algoritmen in het response bericht worden toegepast:

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

(3) WS-Addressing

: Voor routering dient WS-Addressing 1.0 versie 200508 te worden toegepast. (zie http://www.w3.org/TR/ws-addr-soap/).

From (wsa:From) – Alleen voor gebruik als knooppunt

: De wsa:From identificeer je als knooppunt en jouw klant bij de KVK. Je dient met de KVK afspraken te maken over de vooraf gedefinieerde URI. De KVK zal jou als knooppunt identificeren op basis van de door de KVK gegenereerde waarde. De identificatie waarde van jouw klant dient bij de KVK bekend te zijn. Voor de waarde van worden alleen de volgende tekens geaccepteerd: a-z, A-Z, 0-9 en de ‘.‘.

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

Destination (wsa:To) - 2015/02

: De wsa:To specificeert de service die wordt aangesproken:

• 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)

: De wsa:Action specificeert de service operatie en dus het gewenste product welke door de KVK Dataservice moet worden geleverd:

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

Destination (wsa:To) - 2018/01

: De wsa:To specificeert de service die wordt aangesproken:

• 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) 

De wsa:Action specificeert de service operatie en dus het gewenste product welke door de KVK Dataservice moet worden geleverd: 

• 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 

De wsa:To specificeert de service die wordt aangesproken: 

• 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)

De wsa:Action specificeert de service operatie en dus het gewenste product welke door de KVK Dataservice moet worden geleverd:

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

#### Message Id (wsa:MessageID)

De wsa:MessageID bevat een unieke door jou als afnemer gespecificeerde referentie op basis van uuid.

Hiernaar zal in het antwoord worden gerefereerd. In het geval er geen of een incorrecte wsa:MessageID wordt meegegeven zal het request bericht worden geweigerd door de KVK Dataservice.

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

LET OP: sommige IDE tooling zoals bijvoorbeeld Microsoft Visual Studio voegt “urn:” voor “uuid:”. De KVK Dataservice controles zullen een request met deze syntax afwijzen!

ReplyTo (wsa:ReplyTo)

Optioneel kun je gebruik maken van het element ‘ReplyTo’. Gebruik hiervan staat vrij zolang het element correct wordt digitaal ondertekend.

Response berichten

In het response bericht vanuit de KVK Dataservice wordt in de header wsa:RelatesTo toegevoegd met als referentie het MessageID uit het request bericht (zie onderstaand voorbeeld).

<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) Structuur request bericht 

    <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>

Bovenstaand voorbeeld geeft een overzicht van de structuur van het request bericht.

(5) Structuur response bericht

<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>

De keuze van het product bepaalt het resultaat van het antwoord. Bovenstaande structuur bevat de basis structuur van een succesvol afgehandeld request voor het product ophalenInschrijving.

Het response bericht bestaat uit een header, product response en inhoud-blok. Het productresponse blok bevat een fout code, waarschuwingen en/of informatie. Ieder daarvan heeft dezelfde opbouw: code, omschrijving en referentie. Zie de GegevensCatalogus en/of Functionele Dataservice Beschrijvingen voor de bijbehorende statusmeldingen.

Voor de verschillen in response structuren met betrekking tot het inhoud per product raadpleeg de in aansluitpakket meegeleverde voorbeelden en de gegevenscatalogus.

1. Jouw applicatie stelt het request bericht samen conform de KVK eisen;
2. Het request wordt afgeleverd aan de KVK Dataservice;
3. De KVK controleert de bevraging of deze is toegestaan;
4. De KVK formuleert de response;
5. De response wordt geretourneerd via de KVK Dataservice naar jouw applicatie.

LET OP: Voor onderstaande elementen in de body van het responsebericht komt de datum en tijd overeen met tijdzone UTC +1 (of UTC +2 i.v.m. zomertijd).

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

Alle andere genoemde tijdstippen (buiten de body van het responsebericht) zijn UTC (Zulu).

De naamgeving van de elementen is zo gekozen dat zo min mogelijk verwarring kan ontstaan over de verwachte waarde.

Technische gegevens

Tabel KVK Dataservice

Voorbeeldberichten

In deze paragraaf kun je gecomprimeerde bestanden vinden met daarin voorbeeldberichten van producten die via onze KVK Dataservice worden geleverd. Voor elk product zijn meerdere voorbeelden van de request- en responseberichten in te zien.

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