KVK Dataservice overheid 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 (Diginetwerk voor overheid aansluitingen);
  • 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.

StandaardVersieOpmerkingen
TLSIETF RFC standaard RFC5246 - TLS (transport layer security v1.2Tweezijdig, Ciphers suites GCM mode SHA256 of hoger
TCP/IPTCPv4 of TCPv6 

KVK Basis profiel

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

StandaardVersie
XMLXML 1.0 (5th edition) 20081126   
XSDXSD 1.1 (20041028)
SOAPSOAP 1.1 (20000508)   
MTOMMTOM
WSDLWSDL 1.1
WSSEC

WS-Security 1.1 (20060217)

X.509Token Profile 1.0

WSAWS-Addressing 1.0
WS-RELWS-ReliableMessaging 1.0

Content niveau

StandaardVersie 
XMLDSIGRFC 3275 XML-Signature Syntax and Processinghttp://www.ietf.org/rfc/rfc3275.txt http://www.w3.org/TR/xmldsig-core/
XMLENCXML Encryption 1.0http://www.w3.org/
CANON10RFC3076 Canonical XMLhttp://www.ietf.org/rfc/rfc3076.txt
XCANONRFC3741 Exclusive XML Canonicalization 1.0http://www.ietf.org/rfc/rfc3741.txt
X.509RFC 5280 - Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile v3RFC6818 en update van RFC5280
UTF-8ISO/IEC 10646http://www.iso.org/iso/home/store/catalogue_ics/catalogue_detail_ics.htm?csnumber=63182

 

Certificaten

Voorwaarden Certificaat voor Overheid aansluitingen

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

  1. Certificaten dienen betrokken te worden van een PKI-Overheid 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 uit de PKI-Overheid Organisatie hiërarchie zijn gegeneerd en zijn voorzien van het Overheidsidentificatie Nummer (OIN) van jouw organisatie;
  5. SSL certificaten voor ontwikkel en test werkzaamheden dienen minimaal uit de PKI-Overheid Domain hiërarchie te zijn gegenereerd en zijn voorzien van het OIN van jouw organisatie. Je kunt er ook voor kiezen om een productie certificaat met OIN te gebruiken voor ontwikkel en test werkzaamheden;
  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 PKI-Overheid certificaten uit de Organisatie of Domain hiërarchie dien je contact op te nemen 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 de Kamer van Koophandel te vertrouwen.

Certificaten overheid vanaf november 2023:

Certificaten afnemers Diginetwerk december 2022:

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 KVK Handelsregister Inschrijving en KVK Handelsregister Vestiging: 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 Overzicht Inschrijvingen UBO: SoapUI voorbeelden (ZIP)
  • SoapUI voorbeeldproject voor product UBO-register Documenten: SoapUI voorbeelden (ZIP)
  • SoapUI voorbeeldproject voor product UBO-register Zoeken op Natuurlijk Persoon: 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 KVK Handelsregister Inschrijving en KVK Handelsregister Vestiging:.NET voorbeelden

Aansluiten pre-productie

 

Aansluiting Versie / Opmerking
Postbus

https://webservices.preprod.kvk.nl/postbus1

https://webservices.preprod.osb.kvk.nl/postbus1

Internet 

Diginetwerk

IP-Adres

176.117.57.67

95.152.160.152

Internet

Diginetwerk

WSDL

KvKDataservice.wsdl

http://schemas.kvk.nl/contracts/kvk/dataservice/catalogus/2015/02/KVK-KvKDataservice.wsdl

2015/02
XSD

Catalogus.xsd

CatalogusGegevensGroepen.xsd
CatalogusMainTypes.xsd
CatalogusRelaties.xsd
CatalogusTypes.xsd
http://schemas.kvk.nl/schemas/kvk/dataservice/catalogus/2015/02/

2015/02
Destination (wsaTo)
Action (wsaAction)
http://es.kvk.nl/KvK-DataservicePP/2015/02
http://es.kvk.nl/ophalenInschrijving
http://es.kvk.nl/ophalenVestiging
 
Destination (wsaTo)
Action (wsaAction)
http://es.kvk.nl/KVK-DataservicePP/2018/01
http://es.kvk.nl/opvragenBeschikbareBoekjaren
http://es.kvk.nl/opvragenBeschikbareJaarrekeningen
http://es.kvk.nl/opvragenJaarrekening
http://es.kvk.nl/opvragenKvkUittrekselUboRegister
http://es.kvk.nl/opvragenKvkOverzichtInschrijvingenUbo
http://es.kvk.nl/opvragenKvkBeschikbareUboRegisterDocumenten
http://es.kvk.nl/opvragenKvkUboRegisterZoekenOpNatuurlijkPersoon
2018/01
Destination (wsaTo)
Action (wsaAction)
http://es.kvk.nl/KVK-DataservicePP/2020/01
http://es.kvk.nl/opvragenKvkHandelsregisterUittrekselRequest
2020/01

 

Aansluiten StUF

 

Aansluiting Versie / Opmerking
Postbus

https://webservices.preprod.kvk.nl/postbus1

https://webservices.preprod.osb.kvk.nl/postbus1

Internet

Diginetwerk

IP-Adres

176.117.57.67

95.152.160.17

Internet

Diginetwerk

Diginetwerk

WSDLkvk-kvk0300_bg0301_verwerkSynchroonVrijBericht.wsdl
http://schemas.kvk.nl/contracts/kvk/dataservice/catalogus/2015/02/stuf/kvk-kvk0300_bg0301_verwerkSynchroonVrijBericht.wsdl
2015/02
XSDkvk0100_bg0301_msg_stuf_vrij.xsd
kvk0300_bg0301_msg_ent_vrij.xsd
kvk0300_bg0301_msg_vrij.xsd
http://schemas.kvk.nl/schemas/kvk/dataservice/stuf/definitie/vrij/2015/02/
2015/02
Destination (wsaTo)http://es.kvk.nl/HandelsregisterIP-DataservicePP/2015/02 
Action (wsaAction)http://es.kvk.nl/StUF/sector/hr/kvk0300/ophalenInschrijving
http://es.kvk.nl/StUF/sector/hr/kvk0300/ophalenVestiging
 

 

Webservice werkingsprincipes

  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.

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 ondertekent. 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 identificeert je als knooppunt enjouw klant bij de KVK. Je dient met de KVK afspraken te maken over de vooraf gedefinieerde URI. De KVK zal je 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 
  • wsa:Action=http://es.kvk.nl/opvragenKvkOverzichtInschrijvingenUbo 

#### 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/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/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 inhoudblok. 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.

Indien je gebruik dient te maken van StUF verwijzen wij je naar het volgende hoofdstuk.

  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. 

Webservice werkingsprincipes in combinatie met StuF

  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. 

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

(1) Template header StUF request bericht 

: StUF berichten voor de KVK Dataservice moeten minimaal voldoen aan de template, zoals getoond in onderstaand voorbeeld: 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:kvk="http://www.kvk.nl/StUF/sector/hr/kvk0300"
xmlns:stuf="http://www.egem.nl/StUF/StUF0301"
xmlns:wsa="http://www.w3.org/2005/08/addressing">
   <soapenv:Header>
    <wsa:To>http://es.kvk.nl/KvK-DataservicePP/2015/02</wsa:To>
    <wsa:Action>http://es.kvk.nl/StUF/sector/hr/kvk0300/[PRODUCT]</wsa:Action>
    <wsa:MessageID>uuid:1234</wsa:MessageID>
   </soapenv:Header>
   <soapenv:Body>
                 <!-- Content -->
   </soapenv:Body>
</soapenv:Envelope> 

(2) WS-Security 

: Voor de ondertekening van het bericht dient de OASIS WS-Security message-level security standaard ver-sie 2004/01 te worden toegepast. Binnen het WS-Security framework maken we gebruik van het Web Ser-vices 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 enjouw klant bij de KVK. Je dient met de KVK afspraken te maken over de vooraf gedefinieerde URI. De KVK zal je 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 ‘.‘.

<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/StUF/sector/hr/kvk0300/ophalenInschrijving
  • wsa:Action=http://es.kvk.nl/StUF/sector/hr/kvk0300/ophalenVestiging

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 IDEA tooling zoals bijvoorbeeld Microsoft Visual Studio voegt “urn:” voor “uuid:”. De KVK Dataservice controles zullen een request met deze syntax afwijzen!

(4) Structuur request bericht StUF

      <kvk:[PRODUCTREQUEST]>
         <kvk:stuurgegevens>
            <stuf:berichtcode>Di02</stuf:berichtcode>
            <stuf:functie>[PRODUCT]</stuf:functie>
         </kvk:stuurgegevens>
         <kvk:klant stuf:entiteittype="KLA" stuf:functie="entiteit">
            <kvk:klantreferentie>[REFERENTIE]</kvk:klantreferentie>
         </kvk:klant>
         <kvk:[SLEUTEL] stuf:noValue="geenWaarde" stuf:exact="true">[WAARDE]</kvk:[SLEUTEL>
      </kvk:[PRODUCTREQUEST]>

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

Onderstaande tabel geeft de mogelijke parameters voor het invullen van het request bericht:

Tabel 8 - parameters request

ParameterWaardeOpmerking
PRODUCTophalenInschrijving
ophalenVestiging
 
PRODUCTREQUESTophalenInschrijvingRequest
ophalenVestigingRequest   
 
KLANTREFERENTIEEen door de afnemer vrij in te vullen referentie b.v. ordernummer ter referentie op de KVK factuurVoor toekomstig gebruik
SLEUTELkvkNummer
Vestigingsnummer
rsin   
 
WAARDE

kvkNummer 

Vestigingsnummer

RSIN

kvkNummer = 8 posities

Vestigingsnummer = 12 posities

RSIN = 9 posities

(5) Structuur response bericht StuF

<soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <kvk:[PRODUCTRESPONSE] xmlns:kvk="http://www.kvk.nl/StUF/sector/hr/0300">
        <kvk:stuurgegevens>
            <StUF:berichtcode xmlns:StUF="http://www.egem.nl/StUF/StUF0301">Du02</StUF:berichtcode>
            <StUF:functie xmlns:StUF="http://www.egem.nl/StUF/StUF0301">[PRODUCT]</</StUF:functie>
        </kvk:stuurgegevens>
        <kvk:informatie StUF:entiteittype="MLD" StUF:functie="entiteit" xmlns:StUF="http://www.egem.nl/StUF/StUF0301">
            <kvk:code>IPD0000</kvk:code>
            <kvk:omschrijving>Het product is succesvol geproduceerd.</kvk:omschrijving>
            <kvk:referentie>[REFERENTIE]</kvk:referentie>
        </kvk:informatie>
        <kvk:inhoud peilmoment="20150819120000000">
        <!-- CONTENT -->
        </kvk:inhoud>
    </kvk: [PRODUCTRESPONSE]>
</soapenv:Body>

De keuze van het product bepaalt het resultaat van het antwoord. Bovenstaande structuur bevat de basis structuur van een succesvol verlopen request bericht.

Het response bericht bestaat uit een header, productresponse en inhoudblok. Het productresponse blok bevat een foutcode, waarschuwingen en/of informatie. Ieder daarvan heeft dezelfde opbouw: code, omschrijving en referentie.

Voor meer informatie raadpleeg de Functionele Dataservice Beschrijvingen en voorbeeldberichten zoals meegeleverd in het aansluitpakket.

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

 

Aansluiting Versie / Opmerking
Postbushttps://webservices.kvk.nl/postbus1
https://webservices.osb.kvk.nl/postbus1

Internet

Diginetwerk

IP-adres176.117.57.68
95.152.160.153

Internet

Diginetwerk

WSDLKvKDataservice.wsdl
http://schemas.kvk.nl/contracts/kvk/dataservice/catalogus/2015/02/KVK-KvKDataservice.wsdl
2015/02
XSDCatalogus.xsd
CatalogusGegevensGroepen.xsd
CatalogusMainTypes.xsd
http://schemas.kvk.nl/schemas/kvk/dataservice/catalogus/2015/02/
2015/02
Destination (wsaTo)
Action (wsaAction)
http://es.kvk.nl/KvK-Dataservice/2015/02
http://es.kvk.nl/ophalenInschrijving
http://es.kvk.nl/ophalenVestiging
2015/02
Destination (wsaTo)
Action (wsaAction)
http://es.kvk.nl/KVK-Dataservice/2018/01
http://es.kvk.nl/opvragenBeschikbareBoekjaren
http://es.kvk.nl/opvragenBeschikbareJaarrekeningen
http://es.kvk.nl/opvragenJaarrekening
http://es.kvk.nl/opvragenKvkUittrekselUboRegister
http://es.kvk.nl/opvragenKvkOverzichtInschrijvingenUbo
http://es.kvk.nl/opvragenKvkBeschikbareUboRegisterDocumenten
2018/01
Destination (wsaTo)
Action (wsaAction)
http://es.kvk.nl/KVK-Dataservice/2020/01
http://es.kvk.nl/opvragenKvkHandelsregisterUittrekselRequest
2020/01

Tabel KVK Dataservice-StUF

 

Aansluiting Versie / Opmerking
Postbushttps://webservices.kvk.nl/postbus1
https://webservices.osb.kvk.nl/postbus1

Internet

Diginetwerk

IP-adres176.117.57.68
95.152.160.153

Internet

Diginetwerk

Diginetwerk

WSDLkvk-kvk0300_bg0301_verwerkSynchroonVrijBericht.wsdl
http://schemas.kvk.nl/contracts/kvk/dataservice/catalogus/2015/02/stuf/kvk-kvk0300_bg0301_verwerkSynchroonVrijBericht.wsdl
2015/02
XSDkvk0100_bg0301_msg_stuf_vrij.xsd
kvk0300_bg0301_msg_ent_vrij.xsd
kvk0300_bg0301_msg_vrij.xsd
http://schemas.kvk.nl/schemas/kvk/dataservice/stuf/definitie/vrij/2015/02/
2015/02
Destination (wsaTo)http://es.kvk.nl/KVK-Dataservice/2015/02 
Action (wsaAction)http://es.kvk.nl/StUF/sector/hr/kvk0300/ophalenInschrijving
http://es.kvk.nl/StUF/sector/hr/kvk0300/ophalenVestiging
 

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.