Functionele Dataservice Beschrijving onderwerp Dataservice Contactgegevens datum 20-04-206 versie Versiebeheer Versie Datum Opmerking 20-04-206 Het afgeleide gegeven in de Persoon /uitgebreiderechtsvorm is aangepast voor de gevallen dat het een BuitenlandseRechtspersoon / Vennootschap is. De /uitgebreiderechtsvorm wordt gevuld met de BuitenlandsevennootschapGegevens.omschrijvingRechtsvorm +"(<BuitenlandsevennootschapGegevens.land van vestiging>)", indien van toepassing aangevuld met "; volgens opgave een formeel buitenlandse vennootschap" Als een adres was afgeschermd, bij opgave via de Indicatie Afgeschermd ("bezoeklocatie", "woonadres" etc.), dan werd er in de Dataservices helemaal niets getoond. Dit is niet conform specificaties en is nu aangepast. De dataservice toont nu het kopje van het object ("bezoeklocatie", "woonadres" etc.) en de Indicator Afgeschermd. Bij de Eigenaar Persoon worden velden geleverd die nog niet of niet juist in de documentatie stonden vermeld: o Bij de Persoon is de datumaanvang toegevoegd o Bij alle Bezoek- en Post adressen is de omschrijving 'adres' vervangen door 'locatie' o het Communicatiegegeven bij de Eigenaar wordt alleen getoond als er GEEN Vestigingen zijn Bij de Onderneming is de datumaanvang in de documentatie toegevoegd Bij de Vestiging worden velden geleverd die nog niet of niet juist in de documentatie stonden vermeld: o Bij de Vestiging is de datumaanvang toegevoegd o Bij het Bezoekadres en Postadres is de omschrijving 'adres' vervangen door 'locatie'.2 9--205 datumaanvang en datumeinde toegevoegd in MaatschappelijkeActiviteit. 9-9-204 Dataservice Contactgegevens inclusief Berichten Box.0 4-2-203 Initiële versie op basis van Gegevenscatalogus 2.3 Pagina van 2
Inhoudsopgave Product Dataservice Contactgegevens (incl. BBox)... 3. Kenmerken... 3.2 Referenties... 3 2 Dataservice Contactgegevens... 4 2. Contactgegevens Request... 4 2.. HeaderRequest... 5 2.2 Contactgegevens Response... 5 2.2. HeaderResponse... 5 3 Inhoud Contactgegevens... 6 3. Maatschappelijke Activiteit... 7 3.2 Eigenaar... 8 3.3 Onderneming... 9 3.4 Vestiging... 0 4 Meldingen... Pagina 2 van 2
Product Dataservice Contactgegevens (incl. BBox) Dit document geeft een functionele beschrijving van de service voor het opvragen van een product via het kanaal Handelsregister gegevenslevering, ook wel Dataservice genoemd. Het beschrijft met welke gegevens de dataservice wordt aangeroepen en welke gegevens er worden geretourneerd. Dit document is bedoeld voor de informatie analist, (software) architect, -ontwikkelaar en tester. Het opvragen van een product bestaat uit een bevraging (request) en een antwoord (response). De afnemer geeft in het request het type product aan dat gewenst wordt. Op basis van een productsleutel geeft de afnemer aan van welk 'onderwerp' hij het product geleverd wil hebben. Dit document beschrijft het opvragen van: Type product: Dataservice Contactgegevens Productsleutel: KvK nummer N.B.: Op dit moment kan het product alleen worden opgevraagd met een KvK-nummer. In een volgende versie wordt het mogelijk om dit product op te vragen op basis van RSI-nummer, vestigingsnummer of BSN. Opvragen op BSN geldt alleen voor die klanten die door de KvK hiertoe geautoriseerd zijn. In hoofdstuk 2 wordt schematisch weergegeven waaruit het request en reponse bericht bestaat. In hoofdstuk 3 wordt schematisch weergegeven welke gegevens uit het handelsregister met dit product worden geleverd. Tot slot worden in hoofdstuk 4 de mogelijke meldingen weergegeven.. Kenmerken Kenmerk Opdrachtgever Project Opmerking V&M Handelsregister Gegevenslevering Dataservices.2 Referenties Referentie Gegevenscatalogus v Gegevenscatalogus v XSD Beschrijving Beschrijving van de handelsregister gegevens die met KvK producten/diensten worden geleverd. De technische vertaling van de gegevenscatalogus in XML. Pagina 3 van 2
2 Dataservice Contactgegevens Dit hoofdstuk geeft schematisch weer waaruit het request en response bericht bestaat. Een bevraging (request) voor een product heeft als resultaat een antwoord (response). Dit antwoord bestaat uit meldingen en de inhoud (gegevens uit het handelsregister). De meldingen kunnen waarschuwingen, informatie en/of foutmeldingen bevatten. Indien de bevraging (request) juist is en het product kan geproduceerd worden, dan bevat het response bericht het bestelde product, de inhoud. Van elk object met een formele historie wordt het registratietijdstip meegeleverd. In de Gegevenscatalogus staat aangeven bij welke objecten en gegevensgroepen een formele historie wordt geregistreerd. De inhoud is gemodelleerd volgens de Gegevenscatalogus. Voor een beschrijving van deze objecten, gegevensgroepen, enzovoort, wordt daarom verwezen naar de Gegevenscatalogus (zie hoofdstuk Referenties). Dataservice Contactgegevens Dataservice Contactgegevens (incl. BBox) «interface» Contactgegevens Request + productnaam: TypeProduct = DSCNTG + productversie: string [] ::HeaderRequest - klantreferentie: Tekst50 [] «productsleutel» + kvknummer: Numeriek8 HeaderRequest A «resulteert in» HeaderResponse «interface» Contactgegevens Response + peilmoment: Tijdstip A +fout +waarschuwing +informatie MeldingType - code: string - omschrijving: string - referentie: string [] +inhoud Inhoud Contactgegevens Response 2. Contactgegevens Request Dit hoofdstuk beschrijft de parameters van het request. Naam Type Waarde Toelichting kvknummer Numeriek8 Het nummer (KvKNummer). Het door de kamer toegekende unieke nummer voor de {{MaatschappelijkeActiviteit}}. productnaam TypeProduct DSCNTG De naam van het product. De afnemer geeft hiermee aan welk product zij wil bevragen. productversie string De versie van het product. Van producten kunnen meerdere versies bestaan. De afnemer geeft aan welke versie van het product gewenst wordt. Wanneer de versie niet wordt opgegeven, dan wordt de laatste versie van het product geleverd. Pagina 4 van 2
2.. HeaderRequest Dit hoofdstuk geeft een overzicht van de attributen van de header van het request bericht. Naam Type Waarde Beschrijving klantreferentie Char Een door de afnemer vrij in te vullen referentie. Deze referentie verschijnt (eventueel) op de factuur. De KvK gebruikt dit gegeven verder niet. 2.2 Contactgegevens Response Dit hoofdstuk beschrijft de parameters van het response. Naam Type Waarde Toelichting peilmoment Tijdstip Het peilmoment geeft de datum aan waarop voor het laatst registraties in het Handelsregister zijn vewerkt. De in het product opgenomen gegevens stonden op dit peilmoment als zodanig in het Handelsregister. 2.2. HeaderResponse Dit hoofdstuk geeft een overzicht van de attributen van de header van het response bericht. Naam Type Waarde Beschrijving fout MeldingType De fout die is opgetreden gedurende het verwerken van de vraag. waarschuwing MeldingType Een waarschuwing die betrekking heeft op het geleverde product informatie MeldingType Een informatieve melding die betrekking heeft op het geleverde product Pagina 5 van 2
3 Inhoud Contactgegevens Onderstaand diagram toont de structuur en verband van de gegevens die worden geleverd bij het opvragen van het product. De inhoud van het product wordt beschreven door te starten met een UML (Unified Modelling Language) raamwerk, waarmee de gehele inhoud van het product in een overzicht wordt gepresenteerd. Daarna worden de verschillende onderdelen van het product in meer detail beschreven door één op één gebruik te maken van het onderliggende HR- Informatiemodel (gegevenscatalogus). Dit betekent dat de onderliggende klassediagrammen niet speciaal voor dit product zijn gemodelleerd, maar dat er hergebruik wordt gemaakt van de bestaande klassediagrammen van de Gegevenscatalogus. Zo wordt de consistentie met het onderliggende HR-Informatiemodel gewaarborgd over de producten heen. Het vet gedrukte element in het schema is het start punt (root element) van het product. Inhoud Contactgegevens Response Inhoud Contactgegevens Eigenaar +Persoon +MaatschappeljikeActiviteit heeft als eigenaar Maatschappelijke Activ iteit Onderneming Manifesteert zich als +MaatschappelijkeActiviteit +Onderneming +MaatschappelijkeActiviteit +Onderneming wordt uitgeoefend in Vestiging +NietCommercieleVestiging +CommercieleVestiging wordt uitgeoefend in Pagina 6 van 2
3. Maatschappelijke Activiteit Onderstaand diagram toont de gegevens en de samenhang van gegevens van de Maatschappelijke activiteit. Maatschappelijke Activiteit Maatschappelijke Activiteit MaatschappelijkeActiviteit - datumaanvang: DatumIncompleet - datumeinde: DatumIncompleet [] «Identificatie, authentiek, trigger» - kvknummer: Numeriek8 «afleiding» - /naam: Tekst500 «niet authentiek» - nonmailing: Indicatie heeft een Berichtenboxadres - Berichtenboxadres: Tekst45 Pagina 7 van 2
3.2 Eigenaar Onderstaand diagram toont de gegevens en de samenhang van gegevens van de Eigenaar van de maatschappelijke Activiteit. Eigenaar Eigenaar Persoon «afleiding» - /uitgebreiderechtsvorm: Tekst500 - /volledigenaam: Tekst500 NatuurlijkPersoon - geboortedatum: DatumIncompleet «Identificatie, authentiek, trigger» - natuurlijkpersoonid: NatuurlijkPersoonId NaamPersoon - naam: Tekst500 [] +Contains NietNatuurlijkPersoon - datumaanvang: DatumIncompleet «Identificatie, authentiek, trigger» - rsin: Numeriek9 BuitenlandseVennootschap BinnenlandseNietNatuurlijkPersoon heeft woonadres Rechtspersoon +Bezoeklocatie +Postlocatie +Bezoeklocatie +Postlocatie Locatie-NatuurlijkPersoon Locatie-NaamPersoon Locatie-BuitenlandseNNP Locatie-Rechtspersoon Locatie «niet authentiek» - afgeschermd: Indicatie - toevoegingadres: Tekst00 [] «afleiding» - /volledigadres: Tekst500 Van Adres Tot en met Communicatiegegeven- Rechtspersoon Nummer - communicatienummer: Alfanumeriek5 - soortcommunicatienummer: SoortCommunicatieNummer - toegangscode: Tekst0 BinnenlandsAdres - huisletter: Letter [] - huisnummer: Numeriek5 [] - huisnummertoevoeging: Tekst5 [] - plaats: Tekst80 - postbusnummer: Numeriek5 [] - postcode: Postcode - straatnaam: Tekst80 [] BuitenlandsAdres - land: Tekst40 - postcodewoonplaats: Tekst200 - regio: Tekst50 [] - straathuisnummer: Tekst200 EmailAdres - adres: Tekst200 Domeinnaam - naam: Tekst300 Communicatiegegev en BAGIdentificatie - identificatieadresseerbaarobject: Tekst6 [] - identificatienummeraanduiding: Tekst6 [] Pagina 8 van 2
3.3 Onderneming Onderstaand diagram toont de gegevens en de samenhang van gegevens van de onderneming. Onderneming Onderneming Onderneming - datumaanvang: DatumIncompleet Pagina 9 van 2
3.4 Vestiging Onderstaand diagram toont de gegevens en de samenhang van gegevens van de vestiging van de maatschappelijke activiteit. Vestiging Vestiging Locatie-Vestiging +Bezoeklocatie (authentiek) +Postlocatie (authentiek) Vestiging - datumaanvang: DatumIncompleet «afleiding» - /eerstehandelsnaam: Tekst500 «Identificatie, authentiek, trigger» - vestigingsnummer: Numeriek2 NietCommercieleVestiging CommercieleVestiging Locatie «niet authentiek» - afgeschermd: Indicatie - toevoegingadres: Tekst00 [] Communicatiegegev en-vestiging «afleiding» - /volledigadres: Tekst500 Van Tot en met Communicatiegegev en Adres EmailAdres - adres: Tekst200 BinnenlandsAdres - huisletter: Letter [] - huisnummer: Numeriek5 [] - huisnummertoevoeging: Tekst5 [] - plaats: Tekst80 - postbusnummer: Numeriek5 [] - postcode: Postcode - straatnaam: Tekst80 [] BAGIdentificatie - identificatieadresseerbaarobject: Tekst6 [] - identificatienummeraanduiding: Tekst6 [] BuitenlandsAdres - land: Tekst40 - postcodewoonplaats: Tekst200 - regio: Tekst50 [] - straathuisnummer: Tekst200 Domeinnaam - naam: Tekst300 Nummer - communicatienummer: Alfanumeriek5 - soortcommunicatienummer: SoortCommunicatieNummer - toegangscode: Tekst0 Pagina 0 van 2
4 Meldingen In dit hoofdstuk staan de mogelijke meldingen beschreven die met het opvragen van dit product/dienst kunnen optreden. Een melding kan als fout, waarschuwing of als aanvullende informatie dienen. Afhankelijk van de context wordt dit bepaald. Het is aan de afnemer om de consequentie van de melding in zijn informatievoorziening te verwerken. Meldingen Meldingen IPD0000 Het product is succesvol geproduceerd IPD000 Eén of meerdere inschrijvingen (Kv Knummers) zijn niet beschikbaar. Het product kan niet worden samengesteld. IPD000 Het gevraagde artikel <productnaam> bestaat niet. IPD002 De gegevens zijn tijdelijk niet leverbaar omdat deze in behandeling zijn. Probeer het later nog eens. IPD0002 De gevraagde versie <versie> van het product <productnaam> bestaat niet. IPD0003 Het klantnummer <klantnummer> is onbekend. IPD005 De gegevens van deze opvraging zijn niet leverbaar in de door u gebruikte v ersie. Voor informatie ov er nieuwe v ersie(s) kunt u contact opnemen met uw AccountManager. IPD0004 Het KvK nummer <kvknummer> is niet valide IPD9998 Algemene invoer parameter fout IPD0005 Op basis v an het KvK-nummer <kvknummer> kan het product niet worden gelev erd. IPD9999 Algemene technische fout IPD0006 Het vestigingsnummer <vestigingsnummer> is niet v alide. IPD0007 Op basis v an het v estigingsnummer <v estigingsnummer> kan het product niet worden gelev erd. IPD0008 Het burgerservicenummer <burgerservicenummer> is niet v alide IPD0009 Op basis v an het burgerserv icenummer <burgerserv icenummer> kan het product niet worden gelev erd. IPD000 Het RSI-nummer <rsin> is niet valide IPD00 Op basis van het RSI-nummer <rsin> kan het product niet worden gelev erd. Code & Omschrijving Type melding Beschrijving IPD0000 Het product is succesvol geproduceerd Informatie Gedurende het produceren (gegevens verzamelen, opmaken en verpakken) van de bestelling zijn er geen verstoringen opgetreden. IPD000 Het gevraagde artikel <productnaam> bestaat niet. IPD0002 De gevraagde versie <versie> van het product <productnaam> bestaat niet. Er wordt een artikel besteld (artikelcode) dat niet bekend is bij de KvK (artikelcode bestaat niet). Er wordt een versie van het artikel besteld dat niet (meer) door de KvK wordt geleverd. Pagina van 2
IPD0003 Het klantnummer <klantnummer> is onbekend. IPD0004 Het KvK nummer <kvknummer> is niet valide IPD0005 Op basis van het KvKnummer <kvknummer> kan het product niet worden geleverd. IPD0006 Het vestigingsnummer <vestigingsnummer> is niet valide. IPD0007 Op basis van het vestigingsnummer <vestigingsnummer> kan het product niet worden geleverd. IPD0008 Het burgerservicenummer <burgerservicenummer> is niet valide IPD0009 Op basis van het burgerservicenummer <burgerservicenummer> kan het product niet worden geleverd. IPD000 Het RSI-nummer <rsin> is niet valide IPD00 Op basis van het RSInummer <rsin> kan het product niet worden geleverd. IPD000 Eén of meerdere inschrijvingen (KvKnummers) zijn niet beschikbaar. Het product kan niet worden samengesteld. IPD002 De gegevens zijn tijdelijk niet leverbaar omdat deze in behandeling zijn. Probeer het later nog eens. IPD005 De gegevens van deze opvraging zijn niet leverbaar in de door u gebruikte versie. Voor informatie over nieuwe versie(s) kunt u contact opnemen met uw AccountManager. IPD9998 Algemene invoer parameter fout Waarschuwing Er is een bestelling geplaatst door een onbekende afnemer. - Onbekend WWW profiel (controleer LDAP/CF beheer) - Er is een fout opgetreden bij de operatie OphalenDebiteur (Generiek boekingsservice) Het opgegeven KvKnummer voldoet niet aan zijn formaat. - 8 posities lang - Voldoet niet aan -proef Er is geen Onderneming of Maatschappelijke activiteit gevonden van het betreffende KvKnummer. - KvKnummer bevindt zich niet in de IPD componenten cache Het opgegeven vestigingsnummer voldoet niet aan zijn formaat. - 2 posities lang Er is geen Vestiging gevonden van het betreffende vestigingsnummer. - De Vestiging bevindt zich niet in de IPD componenten cache Het opgegeven burgerservicenummer voldoet niet aan zijn formaat. - 9 posities lang Er is geen Natuurlijk Persoon gevonden van het betreffende burgerservicenummer. - Natuurlijk Persoon bevindt zich niet in de IPD componenten cache Het opgegeven RSI-nummer voldoet niet aan zijn formaat. - 9 posities lang Er is geen Niet Natuurlijk Persoon gevonden van het betreffende RSI-nummer. - Niet Natuurlijk Persoon bevindt zich niet in de IPD componenten cache Er is een aantekening (noodprocedure) op een KvKnummer dat in het product wordt gebruikt. Er is een blokkade (algemeen) op een KvKnummer dat in het product wordt gebruikt. Een nieuw gegeven of een nieuwe enumeratie of waarde van een opgevraagd veld kan in de, door de gebruiker gehanteerde, versie niet worden geleverd en wordt daarom herleid naar deze IPD005 foutmelding. Het artikel dat wordt besteld wordt met ongeldige of onvolledige parameters opgevraagd. IPD9999 Algemene technische fout Het produceren van het artikel is gefaald door een technische fout. Pagina 2 van 2