GEBRUIKERSHANDLEIDING DOMEIN ONDERNEMING PUBLICEERONDERNEMINGVKBO 2.0. Versie /// 2.0 Publicatiedatum /// /// Gebruikershandleiding

Transcriptie

1 /// Gebruikershandleiding GEBRUIKERSHANDLEIDING DOMEIN ONDERNEMING PUBLICEERONDERNEMINGVKBO 2.0 Versie /// 2.0 Publicatiedatum ///

2 Informatie Vlaanderen /// Auteur: Elin Vanlierde Datum aanmaak: Wijzigingsdatum: Datum afdruk: Interne bestandsnaam: Gebruikershandleiding PubliceerOndernemingVKBO 2.0 Documenthistoriek: Versie Opmerking Datum Auteur Status 0.1 Eerste opzet Michaël Loedts Concept 0.2 Review Opmerkingen toegevoegd Bart Vingerhoets Concept 0.3 Verwerking review Michaël Loedts Concept 1.0 Publicatie Michaël Loedts Finale versie 2.0 Nieuwe lay-out Elin Vanlierde Finale versie 2 /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0

3 /// Informatie Vlaanderen INHOUD Inhoud Inleiding Doel Opbouw Algemeen Omgevingsinformatie Functionaliteiten Leverancier van de gegevens Gebruiksvoorwaarden Verwante diensten RegistreerDossierOnderneming GeefOndernemingVKBO Interface Algemeen Bestandsnaam Publicatie in XML Algemeen XSD Elementen Uitzonderingen Publicatie in csv Algemeen Elementen Voorbeeld Codetabellen AuthentiekeBron Gebruikershandleiding - Domein Onderneming PubliceerOndernemingVKBO 2.0 /// /// 24

4 Informatie Vlaanderen /// OndernemingOfVestiging StatusKBO SoortOnderneming Werking Verdeling Opties Opkuis en logging Beschikbaarheid Gekende problemen Testgegevens Testbestanden Voorbeeldbestanden XML: publicatie met gegevens XML: geen gegevens te publiceren CSV: publicatie met gegevens Wijzigingen tegenover Algemeen Overzicht wijzigingen Contactgegevens /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0

5 /// Informatie Vlaanderen 1 INLEIDING 1.1 DOEL Dit document beschrijft het gebruik en de werking van de publicatie van OndernemingVKBO zoals deze door MAGDA aangeboden wordt. Deze publicatie beschikbaar sinds mei 2015 zal op termijn de oudere ondernemingspublicaties PubliceerOnderneming 01.01, en vervangen. Met de OndernemingVKBO 2.0 streeft MAGDA VKBO naar éénzelfde formaat voor zowel de GeefOndernemingVKBO 02.00, PubliceerOndernemingVKBO 2.0 en de toekomstige ZoekOndernemingVKBO 2.0. Ten opzicht van de vorige versies bevat de OndernemingVKBO 2.0 bijkomend informatie met betrekking tot de adresdoorhaling en ambtshalve doorhaling. 1.2 OPBOUW Het algemeen overzicht van de functionaliteiten en het gebruik van deze publicatie is opgenomen in hoofdstuk 2. Hoofdstuk 3 behandelt de interface van de publicatie. Hoofdstuk 4 geeft meer informatie over de werking. Hierbij worden onder meer enkele aandachtspunten, de configuratieparameters, de beschikbaarheid en de gekende problemen aangehaald. Hoofdstuk 5 bevat enkele voorbeelden van het gebruik van de dienst. Hoofdstuk 6 bevat de wijzigingen tegenover de publicatie PubliceerOnderneming De contactgegevens zijn opgenomen in hoofdstuk 7. Gebruikershandleiding - Domein Onderneming PubliceerOndernemingVKBO 2.0 /// /// 24

6 Informatie Vlaanderen /// 2 ALGEMEEN 2.1 OMGEVINGSINFORMATIE Naam: PubliceerOndernemingVKBO Versie: Classificatie: niet privacygevoelig 2.2 FUNCTIONALITEITEN MAGDA ontvangt van dinsdag tot en met zaterdag vanuit KBO gegevens met betrekking tot ondernemingen. Deze gegevens worden binnen het MAGDA platform bewaard (in de VKBO-databank) en gepubliceerd naar geïnteresseerde afnemers toe. Elke afnemer heeft daarbij de mogelijkheid om in samenspraak met Informatie Vlaanderen te bepalen welke gegevens gevraagd worden, op basis van welke criteria deze geselecteerd moeten worden en met welke frequentie die zouden moeten aangeleverd worden. De gegevens zijn beschikbaar in xml als csv en worden beschikbaar gesteld op de MAGDA FTP server. De exacte locatie van deze folder en de naam wordt in samenspraak met Informatie Vlaanderen bij aansluiting beslist. De folderstructuur en de manier waarop de gegevens opgehaald kunnen worden, wordt beschreven in de FTP richtlijnen [FTP]. In het geval er geen gegevens geselecteerd zouden worden, wordt er standaard geen bestand aangemaakt, tenzij de afnemer uitdrukkelijk vraagt om in dat geval toch een uitzonderingsbestand aan te leveren. 2.3 LEVERANCIER VAN DE GEGEVENS De oorspronkelijke bron van deze gegevens is KBO. Informatie Vlaanderen is dan ook afhankelijk van deze bron voor de kwaliteit en de aanlevering van de gegevens. 6 /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0

7 /// Informatie Vlaanderen 2.4 GEBRUIKSVOORWAARDEN Afnemers moeten aan volgende voorwaarden voldoen om deze dienst te mogen gebruiken: Toelating tot de publicatie PubliceerOndernemingVKBO Toelating tot het MAGDA platform Meer informatie over deze voorwaarden is terug te vinden in het document Machtigingen en toelatingen [MT]. 2.5 VERWANTE DIENSTEN RegistreerDossierOnderneming Voor het registreren van ondernemingen en vestigingen indien een publicatie op basis van de klantenlijst gewenst is GeefOndernemingVKBO 2.0 Voor het opvragen van de ondernemingsgegevens via een webservice. De input is een ondernemingsnummer (of vestigingsnummer), de output is een onderneming (of vestiging) volgens hetzelfde formaat als de publicatie. Gebruikershandleiding - Domein Onderneming PubliceerOndernemingVKBO 2.0 /// /// 24

8 Informatie Vlaanderen /// 3 INTERFACE 3.1 ALGEMEEN De gegevens zijn beschikbaar in zowel xml als csv en opgebouwd volgens de MAGDA 2.0 richtlijnen. Binnen de 2.0 zijn enkele gegevens toegevoegd (ambtshalve doorhaling en adresdoorhaling) maar ook enkele kleinere aanpassingen. De aanpassingen tegenover de versie 1.03 zijn uitgelegd in hoofdstuk 6. In grote lijnen bevat de OndernemingVKBO 2.0 volgende gegevens: - Status KBO - Aanduiding onderneming of vestiging - Soort onderneming (indien onderneming) - Maatschappelijke zetel (indien vestiging) - Namen o Maatschappelijke naam o Afgekorte naam o Commerciële naam - Adres en adres doorhaling - Contactgegevens - Startdatum, datum inschrijving, datum afsluiting - Rechtstoestand - Rechtsvorm - Ambtshalve doorhaling - Datum en reden stopzetting 3.2 BESTANDSNAAM De exacte bestandsnaam wordt meegedeeld tijdens het aansluitingsproces. Deze is steeds onder de vorm prefix_publicatienaam_timestamp.extensie Voorbeeld: Pub_PubliceerOndernemingVKBO_ xml 8 /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0

9 /// Informatie Vlaanderen 3.3 PUBLICATIE IN XML Algemeen De publicatie bevat een standaard context zoals de andere MAGDA publicaties. Dit naar analogie met de contextbeschrijving voor webservices in het CORVE document voor de afnemers Gebruik MAGDA Webservices. De inhoud bestaat uit een publicatie van één of meerdere ondernemingen. Of in geval dat er een uitzonderingsbestand gevraagd werd, kan dit ook de Uitzondering bevatten (zie ook 3.3.4) XSD De bestanden die worden aangeboden op de outputfolder zijn gevalideerd volgens de PubliceerOndernemingVKBO Service xsd. De actuele xsd is ter beschikking op aanvraag. Onderstaande afbeelding toont een globaal overzicht van de verschillende gegevens in het antwoord. Deze worden in Elementen verder in detail besproken. Er komen geen Metadata-gegevens terug in de publicatie. Gebruikershandleiding - Domein Onderneming PubliceerOndernemingVKBO 2.0 /// /// 24

10 Informatie Vlaanderen /// Elementen Ondernemingsnummer AuthentiekeBron OndernemingOfVestiging StatusKBO SoortOnderneming MaatschappelijkeZetel Namen Adres en adresdoorhaling Uitleg Meest recente datum laatste wijziging over de volledige onderneming / vestiging heen. Formaat: jjjj-mm-dd. Ondernemingsnummer of vestigingsnummer zoals opgegeven in de vraag. Ondernemingsnummer is steeds met een voorloopnul. Bron van de gegevens. Aanduiding of het een onderneming of vestiging betreft. Enkel komen is onder de vorm jjjj-mm-dd Status zoals in KBO gekend is. Enkel Code en Omschrijving komen terug. Aanduiding welk soort onderneming het betreft. Komt enkel terug indien Onderneming, nooit bij een vestiging. Enkel Code en Beschrijving komen terug. Komt enkel terug bij een vestiging. Dit element bevat het ondernemingsnummer van de maatschappelijke zetel van de vestiging. DatumModificatie is onder de vorm jjjj-mm-dd. Drie mogelijke namen kunnen terugkomen. De drie hebben dezelfde structuur: - MaatschappelijkeNaam - AfgekorteNaam - komen terug. Datummodificatie is onder de vorm jjjj-mm-dd. Opgelet: in zeer uitzonderlijke omstandigheden is er geen TaalCode bekend. Mogelijke taalcodes: fr, nl, de, en De adresgegevens alsook eventueel de gegevens betreffende de doorhaling van het adres. onder de vorm jjjj-mm-dd - Straat: rijksregisterstraatcode en straatnaam - Huisnummer - Busnummer - Gemeente: Niscode, postcode en gemeentenaam - Land: Niscode, ISOCode. Landnaam komt momenteel niet terug. - Aanvullingen: 10 /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0

11 /// Informatie Vlaanderen Contact DatumStart DatumInschrijving DatumAfsluiting Rechtstoestand Rechtsvorm Ambtshalve doorhaling Stopzetting o Staat o Tekst: vrij tekstveld. Vb: Bloc 7, Haven 1062 o TaalCode: fr, nl, de, en - Doorhaling: aanduiding dat het adres doorgehaald werd. Gegevens die terugkomen: o Code o Omschrijving o Datum: onder de vorm jjjj-mm-dd Enkel Telefoonnummer, Faxnummer en kunnen terugkomen. Oprichtingsdatum van de onderneming / vestiging. Formaat: jjjj-mm-dd Datum van inschrijving in KBO. Formaat: jjjj-mm-dd Datum van afsluiting onderneming of vestiging. Indien : onderneming of vestiging is niet afgesloten. Enkel gekend bij een onderneming. Enkel Code en Omschrijving komen is onder de vorm jjjj-mm-dd Enkel gekend bij een onderneming. Enkel Code en Omschrijving komen is onder de vorm jjjj-mm-dd Periode en reden van ambtshalve doorhaling. Enkel bij een onderneming. Komen terug: DatumModificatie (jjjj-mm-dd) Code Omschrijving Periode/Begin en indien gekend ook Periode/Einde. Beide onder de vorm jjjj-mm-dd. Datum en reden van stopzetting Komen terug: Datum (jjjj-mm-dd) Code Omschrijving Uitzonderingen Indien er gekozen werd om een uitzonderingsbestand te onvangen, komt er een Uitzondering terug met als foutcode geen gegevens te publiceren. Gebruikershandleiding - Domein Onderneming PubliceerOndernemingVKBO 2.0 /// /// 24

12 Informatie Vlaanderen /// 3.4 PUBLICATIE IN CSV Algemeen MAGDA richtlijnen voor csv worden gevolgd: ISO , alles tussen, ; als delimiter en elk record op een nieuwe lijn. De csv is gebaseerd op de xml vanaf het Onderneming-element. In geval dat er een uitzonderingsbestand gevraagd werd zal het CSV-bestand leeg zijn indien er geen gegevens te publiceren zijn Elementen Onderstaande tabel geeft de kolommen weer binnen de csv. Deze komen overeen met de gegevens in de xsd. Kolom nummer Element binnen xsd Bijkomende informatie 1 DatumModificatie 2 Ondernemingsnummer 3 AuthentiekeBron Code 4 AuthentiekeBron Code Beschrijving 5 AuthentiekeBron Omschrijving Komt niet terug 6 AuthentiekeBron Oorsprong Komt niet terug 7 AuthentiekeBron TaalCode Komt niet terug 8 OndernemingOfVestiging DatumModificatie 9 OndernemingOfVestiging Code 10 OndernemingOfVestiging Code Beschrijving 11 OndernemingOfVestiging Omschrijving Komt niet terug 12 OndernemingOfVestiging Omschrijving Oorsprong 13 OndernemingOfVestiging Omschrijving TaalCode Komt niet terug Komt niet terug 12 /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0

13 /// Informatie Vlaanderen 14 StatusKBO Code 15 StatusKBO Code Beschrijving Komt niet terug 16 StatusKBO Omschrijving 17 StatusKBO Omschrijving Oorsprong Komt niet terug 18 StatusKBO Omschrijving TaalCode Komt niet terug 19 SoortOnderneming Code 20 SoortOnderneming Code Beschrijving 21 SoortOnderneming Omschrijving Komt niet terug 22 SoortOnderneming Omschrijving Oorsprong Komt niet terug 23 SoortOnderneming Omschrijving TaalCode Komt niet terug 24 MaatschappelijkeZetel 25 MaatschappelijkeZetel DatumModificatie 26 MaatschappelijkeNaam 27 MaatschappelijkeNaam TaalCode 28 MaatschappelijkeNaam DatumModificatie 29 AfgekorteNaam 30 AfgekorteNaam TaalCode 31 AfgekorteNaam DatumModificatie 32 CommercieleNaam 33 CommercieleNaam TaalCode 34 CommercieleNaam DatumModificatie 35 Adres DatumModificatie 36 Adres Straat Code 37 Adres Straat Naam 38 Adres Huisnummer 39 Adres Busnummer 40 Adres Gemeente NISCode 41 Adres Gemeente Postcode Gebruikershandleiding - Domein Onderneming PubliceerOndernemingVKBO 2.0 /// /// 24

14 Informatie Vlaanderen /// 42 Adres Gemeente Naam 43 Adres Land NISCode 44 Adres Land ISOCode 45 Adres Land Naam 46 Adres Aanvullingen Staat 47 Adres Aanvullingen Tekst 48 Adres Aanvullingen TaalCode 49 Adres Doorhaling DatumModificatie 50 Adres Doorhaling Code 51 Adres Doorhaling Code Beschrijving Komt niet terug 52 Adres Doorhaling Omschrijving 53 Adres Doorhaling Omschrijving Oorspong Komt niet terug 54 Adres Doorhaling Omschrijving TaalCode Komt niet terug 55 Adres Doorhaling Datum 56 Contact Telefoonnummer 57 Contact Faxnumer 58 Contact Gsm Komt niet terug 59 Contact 60 Contact Website Komt niet terug 61 DatumStart 62 DatumInschrijving 63 DatumAfsluiting 64 Rechtstoestand DatumModificatie 65 Rechtstoestand Code 66 Rechtstoestand Code Beschrijving Komt niet terug 67 Rechtstoestand Omschrijving 68 Rechtstoestand Omschrijving Oorsprong Komt niet terug 69 Rechtstoestand Omschrijving TaalCode Komt niet terug 14 /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0

15 /// Informatie Vlaanderen 70 Rechtsvorm DatumModificatie 71 Rechtsvorm Code 72 Rechtsvorm Code Beschrijving Komt niet terug 73 Rechtsvorm Omschrijving 74 Rechtsvorm Omschrijving Oorsprong Komt niet terug 75 Rechtsvorm Omschrijving TaalCode Komt niet terug 76 AmbtshalveDoorhaling DatumModificatie 77 AmbtshalveDoorhaling Reden Code 78 AmbtshalveDoorhaling Reden Beschrijving Komt niet terug 79 AmbtshalveDoorhaling Reden Omschrijving 80 AmbtshalveDoorhaling Reden Oorsprong Komt niet terug 81 AmbtshalveDoorhaling Reden TaalCode Komt niet terug 82 AmbtshalveDoorhaling Periode Begin 83 AmbtshalveDoorhaling Periode Einde 84 Stopzetting Datum 85 Stopzetting Reden Code 86 Stopzetting Reden Beschrijving Komt niet terug 87 Stopzetting Reden Omschrijving 88 Stopzetting Reden Omschrijving Oorsprong Komt niet terug 89 Stopzetting Reden Omschrijving TaalCode Komt niet terug Voorbeeld Een voorbeeld is terug te vinden in hoofdstuk 5. Gebruikershandleiding - Domein Onderneming PubliceerOndernemingVKBO 2.0 /// /// 24

16 Informatie Vlaanderen /// 3.5 CODETABELLEN Dit zijn de voor VKBO op dit moment gekende codes (mei 2015). Hou er rekening mee dat codes en omschrijvingen (of Beschrijvingen) kunnen wijzigen. De codes van Adresdoorhaling, Rechtsvorm, Rechtstoestand, Ambtshalve doorhaling en Stopzetting zijn niet opgenomen in dit document. Indien nodig kunnen deze aangleverd worden via een generiek publicatiebestand. Neem hiervoor contact op met AuthentiekeBron 03 KBO Code Onderneming 1 Vestiging StatusKBO Code Omschrijving AC Actief ST Stopgezet AF Afgesloten JU Juridisch AN Geannuleerd BK Bekendgemaakt 16 /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0

17 /// Informatie Vlaanderen Code Natuurlijk persoon 1 Rechtspersoon 2 Gebruikershandleiding - Domein Onderneming PubliceerOndernemingVKBO 2.0 /// /// 24

18 Informatie Vlaanderen /// 4 WERKING 4.1 VERDELING De gegevens worden verdeeld op basis van de criteria die besproken worden tijdens het aansluitingsproces of voorafgaande gesprekken. 4.2 OPTIES Volgende afleveropties zijn mogelijk: - compressie van het bestand in.zip - bundeling van bestanden (gezamelijke aflevering van meerde publicaties) - compressie van de bundeling - borderelbestand (oplijsting afgeleverde bestanden, enkel mogelijk indien bundeling) - uitzonderingsbestand / leeg bestand (indien er geen gegevens te publiceren zijn, verkrijgt men toch een bestand) - controlebestand (bevat een md5, gebruikte encoding, gebruikte en volgende herstartdatum) Voor meer informatie rondom deze afleveropties wordt verwezen naar de beschikbare documentatie. 4.3 OPKUIS EN LOGGING De gegevens in het bestand worden bewaard zoals beschreven in het document MAGDA logging [ML]. Bestanden worden gedurende een beperkte tijd aangeboden op de FTP folder zoals beschreven in de FTP richtlijnen. [FTP] 4.4 BESCHIKBAARHEID MAGDA verwerkt de door KBO verkregen gegevens 24 uur op 24 en 7 dagen op /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0

19 /// Informatie Vlaanderen De periodiciteit van aanlevering via MAGDA is te bespreken tijdens het aansluitingsproces of voorafgaande besprekingen. Algemeen beschouwd is het mogelijk de gegevens dagelijks, wekelijks, aan te bieden. 4.5 GEKENDE PROBLEMEN Er zijn momenteel geen problemen gekend. Gebruikershandleiding - Domein Onderneming PubliceerOndernemingVKBO 2.0 /// /// 24

20 Informatie Vlaanderen /// 5 TESTGEGEVENS 5.1 TESTBESTANDEN Testbestanden zijn beschikbaar op aanvraag. 5.2 VOORBEELDBESTANDEN XML: publicatie met gegevens herstart_ondvkbo_ herstart_ XML: geen gegevens te publiceren rownum_ondvkbo _ CSV: publicatie met gegevens To do als de jira opgelost is. 20 /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0

21 /// Informatie Vlaanderen 6 WIJZIGINGEN TEGENOVER ALGEMEEN Dit hoofdstuk bespreekt de doorgevoerde wijzigingen tegenover de PubliceerOnderneming De wijzigingen hebben vooral betrekking tot - het volgen van de MAGDA 2.0 standaarden (gebruik Code / Omschrijving, naamgeving elementen) - de toevoeging van adres doorhaling - de toevoeging van ambtshalve doorhaling 6.2 OVERZICHT WIJZIGINGEN Gegeven OndernemingVKBO Wijziging Er wordt niet meer gesproken over (Publiceer)Onderneming maar over (Publiceer)OndernemingVKBO. Op deze manier wordt er op dienstniveau een duidelijk onderscheid gemaakt welke bron aangesproken wordt: KBO of VKBO. Voor de wijzigingen van types, lenges, cardinaliteiten wordt verwezen naar de xsd. RSZNummer Verwijdering van het RSZNummer uit de xsd AuthentiekeBronCode Element hernoemd naar AuthentiekeBron met een Code/Omschrijving structuur. Gebruikershandleiding - Domein Onderneming PubliceerOndernemingVKBO 2.0 /// /// 24

22 Informatie Vlaanderen /// OndernemingOfVestigingCode Element hernoemd naar OndernemingOfVestiging met een Code/Omschrijving structuur. Toevoeging van het attribuut DatumModificatie. Het attribuut DatumModificatie komt over van StatusKBO waar het onterecht stond. StatusKBOCode SoortOndernemingCode Element hernoemd naar StatusKBO met een Code/Omschrijving structuur. Verwijdering van het attribuut DatumModificatie. Element hernoemd naar SoortOnderneming met een Code/Omschrijving structuur. MZOndNummer Element MZOndNummer hernoemt naar MaatschappelijkeZetel. Namen Bundeling van maatschappelijke naam, commerciële naam en afgekorte naam in het element Namen. Adres (doorhaling) Verwijdering van het element AuthentiekeBronCode, dit doordat er gewoonweg geen broncode van het adres zoals bewaard in KBO beschikbaar is. Straat: hernoeming NISCode naar Code HuisNummer en BusNummer hernoemd naar Huisnummer en Busnummer Land: Omwisseling van volgorde NISCode en ISOCode Doorhaling: toevoeging doorhalinggegevens Contact Uitbreiding contact-element met GSM en Website 22 /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0

23 /// Informatie Vlaanderen RechtstToestandCode Element hernoemd naar Rechtstoestand met een Code/Omschrijving structuur. RechtsVormCode Element hernoemd naar Rechtsvorm met een Code/Omschrijving structuur. AmbsthalveDoorhaling Toevoeging AmbtshalveDoorhaling Stopzetting Reden omgevormd naar Code/Omschrijving structuur Datum Verplicht indien stopgezet. Gebruikershandleiding - Domein Onderneming PubliceerOndernemingVKBO 2.0 /// /// 24

24 Informatie Vlaanderen /// 7 CONTACTGEGEVENS Informatie Vlaanderen is elke werkdag bereikbaar van 9.00 tot uur. Postadres: Herman Teirlinckgebouw - Havenlaan 88, 1000 Brussel Virginie Lovelinggebouw - Koningin Maria Hendrikaplein 70, 9000 Gent Tel: 02/ helpdesk.magda@vlaanderen.be 24 /// /// Gebruikershandleiding Domein Onderneming PubliceerOndernemingVKBO 2.0