Veel gestelde vragen Verenigingsregister

Overstap van feitelijke verenigingen naar verenigingen zonder eigen rechtspersoonlijkheid

Het verenigingsregister stapt over van verenigingstype FV-Feitelijke Vereniging naar type VZER-Vereniging zonder eigen rechtspersoonlijkheid. Achterliggend wordt wel alles voorzien om er voor te zorgen dat bestaande implementaties verder blijven werken zoals het nu het geval is.

Open

Gebruik van de VR-Api-Version header

Zolang je niet de nieuwe request header VR-Api-Version met waarde v2 meegeeft, blijf je de bestaande types terugkrijgen. Onderaan vind je een overzicht.

De request header met key VR-Api-Version en value v2 heeft impact op de volgende endpoints:

• Geef detail van een vCode: https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/6493732963

• Zoek verenigingen: https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/6426034601

Wanneer de header niet mee gegeven wordt, dan worden ALLE verenigingen die niet in KBO geregistreerd staan, weergegeven als “Feitelijke vereniging”

Wanneer de header wel mee gegeven wordt, dan worden deze verenigingen weergegeven als “Vereniging zonder eigen rechtspersoonlijkheid” en komt ook het verenigingssubtype veld beschikbaar

(*) de regel voor VZW geldt ook voor IVZW, PS en SVON: Het type is onafhankelijk van de header en het subtype is afwezig

Gebruik van de nieuwe endpoints voor verenigingen zonder eigen rechtspersoonlijkheid

Nieuwe vereniging registreren

Het nieuwe endpoint om een vereniging zonder eigen rechtspersoonlijkheid (https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/7391052245) is gelijkaardig aan het bestaande endpoint om feitelijke verenigingen te registreren. Sterker zelfs: wanneer je nu nog het bestaande registratie endpoint aanspreekt, wordt deze vraag achterliggend doorgesluisd naar het nieuwe endpoint. Hieronder de verschillen:

• De URL is anders : /vzer in plaats van /feitelijkeverenigingen

• het /feitelijkeverenigingen endpoint zal op termijn afgeschaft worden

• Wanneer er bij registratie potentiële dubbels ontdekt worden (status 409), dan zal het /feitelijkeverenigingen endpoint de dubbels weergeven met verenigingstype: FV, terwijl het /vzer endpoint diezelfde dubbels zal weergeven met verenigingstype: VZER

Open

Wijzigen van het subtype

Na registratie krijgt elke vereniging zonder eigen rechtspersoonlijkheid het subtype met een lege code en naam toegekend.

Het nieuwe endpoint https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/7391543328 maakt het mogelijk om dit subtype aan te passen.

Met behulp van dit endpoint kan je het subtype wijzigen naar de volgende waarden. Afhankelijk van het subtype worden de andere eigenschappen andereVereniging, identificatie en beschrijving genegeerd, verplicht of optioneel.

Voor een vereniging met subtype = SUB, kan je dit endpoint ook gebruiken om de waarden van andereVereniging, identificatie en/of beschrijving aan te passen. In dit geval moet je zeker het veld "subtype": "SUB" opnieuw opgeven. Alle andere velden worden aangepast wanneer ze aanwezig zijn en op hun huidige waarde gelaten wanneer ze niet aanwezig zijn.

Waarom deze wijziging

Vandaag kennen we verschillende types verenigingen, met als grootste onderscheid: de feitelijke verenigingen en de verenigingen die in KBO gekend zijn (VZW, IVZW en de stichtingen).

Wat is een subvereniging

Er bestaat nog een type: de subvereniging. Dit is een onderdeel van een KBO vereniging dat lokaal bevoegdheden heeft gekregen om autonoom te handelen (eventueel met beperkingen opgelegd door de KBO vereniging.

• onderdeel van een KBO vereniging: deze vereniging bestaat niet op zich, het is een wezenlijk onderdeel van de KBO vereniging en kan dus niet bestaan zonder deze KBO vereniging.

• mag lokaal (beperkt) autonoom handelen: alhoewel elke aanvraag voor dienstverlening juridisch gezien uitgevoerd wordt door de bovenliggende KBO vereniging, is het praktisch gezien toch eenvoudiger wanneer de aanvraag kan ingediend worden door de vertegenwoordigers van de lokale subvereniging. Deze staan zelf meer in contact met de lokale overheid dan de bestuurders van de KBO vereniging.

Om dit te realiseren, kan men een subvereniging ook uniek identificeren met een vCode in het verenigingsregister.

Verschil bepalen tussen feitelijke vereniging en een subvereniging

Er zijn verschillende gevallen waarbij een lokale vereniging een link heeft met een centrale koepel. Deze link is niet altijd in de vorm van een subvereniging, maar kan ook als een lidmaatschap gedefinieerd zijn. Het verschil tussen een feitelijke vereniging die lid is van een koepel en een subvereniging van een koepel is niet altijd even duidelijk en is soms voor interpretatie vatbaar (*). We verwachten echter juiste, gevalideerde data in het verenigingsregister. Zolang niet duidelijk is of een vereniging een feitelijke vereniging is of een subvereniging, kunnen we de vereniging toch al registreren als een vereniging zonder (eigen) rechtspersoonlijkheid of afgekort VZER.

(*) Om te bepalen of een VZER al dan niet een subvereniging is, worden nog hulpmiddelen ter beschikking gesteld.

Afkortingen

In onderstaande teksten gebruiken we de volgende afkortingen:

• VZER: Vereniging zonder (eigen) rechtspersoonlijkheid

• FV: feitelijke vereniging

• SUB: subvereniging

Wat gaat er wijzigen

We evolueren naar een systeem waarbij je

• de KBO verenigingen registreert zoals je vandaag al doet (hier geen wijziging)

• een nieuwe vereniging kan registreren als VZER

  • deze VZER daarna kan gaan verfijnen en aanduiden als FV of SUB

Omdat vergissingen steeds mogelijk zijn, voorzien we ook de mogelijkheid om binnen de groep van VZER de waarde te veranderen (VZER, FV, SUB)

Alle verenigingen die tot nu toe geregistreerd werden als feitelijke vereniging, zijn daarvoor niet allemaal feitelijke verenigingen. Het kunnen ook subverenigingen zijn. Om deze onduidelijkheid te vermijden, worden bij opstart alle FV omgevormd naar VZER.

Impact op API endpoints (en timing)

=> Registreer feitelijke vereniging

Op termijn zal dit endpoint verdwijnen. Omwille van compatibiliteit zal dit endpoint nog een hele tijd beschikbaar blijven. Het effect van dit endpoint is wel hetzelfde als het nieuwe endpoint om een VZER te registreren.

=> Registreer VZER

De request en response structuur van dit endpoint is in het begin gelijk aan de structuur van het oude endpoint “Registreer FV”. Het effect is echter dat er een nieuwe vereniging van het type VZER wordt geregistreerd.

=> Beheren van de data

Alle acties die mogelijk waren met een FV, zijn nu ook mogelijk met een VZER

=> GET - zoek en detail endpoints

Omdat niet iedereen tegelijkertijd kan aanpassen naar het nieuwe formaat, voorzien we backwards compatibility, althans voor een bepaalde tijd.

We gaan een extra request header voorzien (key = VR-Api-Version) waarmee je kan aangeven dat je de data in het nieuwe formaat wenst te ontvangen. Zolang je die header niet meegeeft, staat de data in het formaat en qua inhoud zoals vandaag het geval is. Geef je de header wel mee (met waarde v2), dan krijg je de data in het nieuwe formaat.

Voorbeeld : Stel we hebben een vereniging van het type VZER met vCode V0001234.

=> Zonder extra header

=> MET extra header (voorbeeld van response structuur)

Deze transformatie zal van toepassing zijn bij:

• de detail functies (beheer detail en publiek detail)

  • Het type van de vereniging wordt weergegeven als FV of VZER afhankelijk van de request header

• de zoek functies (beheer zoek en publiek zoek)

  • Het type van de verenigingen in het resultaat wordt weergegeven als FV of VZER afhankelijk van de request header

  • wanneer de zoek query verenigingstype.code:FV of verenigingstype.code:VZER bevat wordt dit automatisch vertaald zodat er gezocht wordt naar FV of VZER

• Registreer nieuwe vereniging

  • Wanneer de dubbel detectie potentiële dubbels ontdekt, wordt het type van deze verenigingen weergegeven als FV of VZER

  • Hier is het niet nodig om de extra header mee te geven !! De transformatie is afhankelijk van het gebruikte endpoint

    • registreer FV geeft steeds FV terug

    • registreer VZER geeft steeds VZER terug

=> Extra veld verenigingssubtype om het type VZER te kunnen verfijnen

Wanneer data in het nieuwe formaat wordt opgevraagd, krijg je bij type VZER ook een extra veld verenigingssubtype waarmee aangegeven wordt wat we van deze VZER weten:

• NB-Niet bepaald: Dit is de default waarde bij registratie van een nieuwe VZER. Hiermee wordt aangegeven dat voor deze VZER nog niet bepaald is of het om een FV gaat of over een SUB.

• FV-Feitelijke vereniging: Voor deze VZER is al bepaald dat het een feitelijke vereniging is

• SUB-Subvereniging: Voor deze vereniging is al bepaald dat het om een SUB gaat. In dit geval vind je ook nog bijkomende velden zoals

  • de vCode van de andere vereniging waar deze een subvereniging van is

  • een identificatie (optioneel) die aangeeft met welke unieke sleutel deze vereniging gekend is bij de moeder vereniging

  • een beschrijving (optioneel) die kan gebruikt worden om meer duiding te geven aan deze relatie

=> Extra endpoint voor het beheren van de VZER’s

Met dit endpoint kan je het subtype van de VZER beheren. Zo kan je van een van de 3 mogelijke waarden (NB, FV of SUB) switchen naar een andere waarde van die drie. Wanneer je een SUB aanduidt, zal je verplicht ook de vCode van de andere vereniging moeten meegeven. Wanneer je van SUB naar een andere waarde gaat, zal de link naar de andere vereniging geschrapt worden.

Wat te doen als integrator

Omwille van de backwards compatibiliteit is het niet nodig om jullie wijzigingen synchroon in productie te stellen met onze wijzigingen. We raden wel aan om bij een volgende release van jullie toepassing te controleren op volgende elementen:

=> if type = FV

Wanneer er ergens in de code getest wordt op type = FV (of <> FV), verander deze code dan naar if type = FV OR VZER.

=> Registreer FV

Switch hier naar het endpoint Registreer VZER

=> GET zoek of detail

Gebruik hier de nieuwe waarden voor het verenigingstype. Geef ook de header mee om aan te geven dat je het nieuwe formaat wenst te ontvangen.

=> extra functionaliteit: verfijn VZER naar FV of SUB

Implementeer de extra functionaliteit om een VZER om te vormen naar een FV of naar en SUB (inclusief link naar de andere vereniging). Deze functionaliteit kan je gebruiken om:

• een VZER te verfijnen naar een FV

• een VZER te verfijnen naar een SUB (inclusief link naar andere vCode en identificatie/beschrijving)

• een SUB aan te passen (wijzigen van de vCode, identificatie en/of beschrijving)

• een FV of SUB terug te plaatsen naar subtype Niet bepaald

=> tonen van de juiste waarden

Controleer overal in je toepassing naar het gebruik van het woord FV of Feitelijke vereniging en pas aan naar VZER of Vereniging zonder (eigen) rechtspersoonlijkheid.

Wanneer je ook gebruik maakt van de verfijningen naar FV of SUB, geef dan ook deze data weer.

vCode: waar terug te vinden

Bij het registreren van een nieuwe vereniging (https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/6493733058 ) wordt een nieuwe vCode toegekend. Je kan die terugvinden in de response header met naam Location. Daar wordt de volledige URL weergegeven om het detail van de nieuwe vereniging op te vragen.

Voorbeeld URL in Location:

Om enkel de vCode te verkrijgen, kan je van die URL de laatste 8 karakters nemen of (nog beter) alles wat na de laatste / komt. (bijvoorbeeld V0001060)

Codelijsten opvragen

De codelijsten kan rechtstreeks worden opgevraagd via de publieke API van verenigingsregister. Je hebt daarvoor geen credentials nodig.

Het formaat van de API call = https://<publieke URL>/v1/<Code>, zoals bijvoorbeeld https://publiek.verenigingen.staging-vlaanderen.be/v1/hoofdactiviteitenVerenigingsloket.

De codelijsten die je nu kan opvragen zijn:

• Hoofdactiviteiten Verenigingsloket, code= hoofdactiviteitenVerenigingsloket

Zoek opdrachten

Specifiek voor https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/6426034617

Deze zoek functionaliteit is een elastic search implementatie. De zoekcriteria kan je dus samenstellen zoals je bij elastic search zou doen. Hierbij enkele voorbeelden:

Gebruik van PATCH voor wijzigingen

Om gegevens te wijzigen, wordt een PATCH opdracht gebruikt. Dit biedt je de mogelijkheid om enkel de waarden mee te geven die aangepast moeten worden. De andere velden kan je meegeven, maar dat hoeft niet. De waarden die niet mee in de API call staan blijven hun huidige waarde behouden.

Zo kan je bijvoorbeeld op niveau van de vereniging enkel de korteNaam meegeven om enkel deze waarde aan te passen. Al de andere waarden blijven ongemoeid.

• korteNaam: “VR” → zal de waarde aanpassen naar “VR”

• korteNaam: null → wordt hetzelfde geïnterpreteerd als wanneer je dit veld niet zou opgeven

• korteNaam: ““ → zal het veld korte naam leeg maken

Om een veld leeg te maken moet het expliciet op een lege waarde ("" of []) gezet worden.

Een waarde in de PATCH opdracht die exact gelijk is aan de waarde zoals die momenteel gekend is, zal die waarde ook niet aanpassen. Daarvan is dus ook geen spoor terug te vinden in de historiek van de vereniging.

Wanneer je in een PATCH opdracht een array van waarden aanpast (zoals bvb hoofdactiviteitenVerenigingsloket), dan wordt er verwacht dat alle gegevens van die array opnieuw opgegeven worden, ook al verandert er maar 1 item. De gegevens van de vereniging zullen in hun geheel vervangen worden door hetgeen opgegeven wordt in de patch call.

Event-Sourced systeem

Bij de bron is het verenigingsregister opgezet als een event-sourced systeem.

Het betekent dat de schrijf activiteiten (registreren van nieuwe vereniging, wijzigen van een naam, …) gescheiden worden van de lees-activiteiten (vraag detail gegevens op van een vereniging, zoek verenigingen, …).

Bij elke schrijf actie worden de opgegeven waarden volledig gecontroleerd en krijg je al een OK (status 202 of 200) terug wanneer het event zelf in orde is. Dat wil nog niet zeggen dat de lees-functionaliteiten op dat moment al aangepast zijn. Achterliggend wordt de impact van elk event op de lees-functionaliteiten een voor een aangepakt, waarna het systeem opnieuw volledig consistent is met de vraag. Dit heet eventual consistency.

Open

Naamgeving:

• Schrijf acties noemen we events

• Lees functionaliteiten noemen we projecties

expectedSequence en ETag

Het tijdsverschil tussen het event en het aanpassen van alle projecties is zeer kort, meestal minder dan 1 seconde zelfs, maar toch kan het zijn dat 2 opeenvolgende API-calls (eentje om te schrijven en eentje om te lezen) zo kort op elkaar volgen dat de 2e het effect van de eerste nog niet meeheeft. Daarom is volgend mechanisme beschikbaar:

in het resultaat van de 1e API-call , in de response headers, staat een veld VR-Sequence. Dat is een oplopend versie nummer van de ontvangen events.

Bij het oproepen van de 2e API-call, waarbij je de waarde van een projectie opvraagt, kan je een parameter meegeven in de URL expectedSequence. Daarmee geef je aan dat je de waarde wil zien na het toepassen van (minstens) het event met het opgegeven nummer.

Wanneer de projectie nog niet is aangepast met de effecten van het opgegeven event, dan krijg je een response status 412 - precondition failed. In dat geval moet je even wachten en de call opnieuw proberen tot je een response status 200 - OK terug krijgt.

Deze parameter is enkel beschikbaar

• https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/6493765633

• https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/6493732963

Voorbeeld:

1e call

2e call

Sequence diagram: voorbeeld standaard gebruik expectedSequence en ETag

Concurrency bij schrijf-acties

We willen situaties vermijden waarbij 2 beheerders eenzelfde vereniging tegelijkertijd aanpassen. Dat zou kunnen leiden tot een situatie waar de 2e beheerder de waarden van de 1e beheerder overschrijft. Om dit correct te laten verlopen, vragen we elke beheerder om gebruik te maken van

1. de header waarde Etag in de response van de lees actie (GET)

   1. Dit geeft de huidige versie aan van de gezochte vereniging

2. de header If-Match te gebruiken in de request van de schrijf-actie (PATCH, PUT, …)

   1. hiermee geef je aan dat je enkel wil aanpassen indien de huidige waarde nog steeds overeenkomt met de eerder opgevraagde versie

Wanneer de opgegeven waarde in If-Match nog steeds overeenkomt met de huidige versie van de vereniging, dan wordt het event verwerkt en krijg je een status code 202 of 200. In die response header staat het nieuwe versie nummer van de vereniging. Dit is nuttig wanneer je meerdere events na elkaar wil lanceren voor dezelfde vereniging.

Wanneer de opgegeven waarde in If-Match niet overeenkomt met de huidige versie van de vereniging, krijg je een status code 412 - precondition failed terug.

Voorbeeld scenario

Response code 200 bij schrijfacties + impact op VR-sequence en ETag

Wanneer een schrijf actie succesvol eindigt, wordt standaard een response code 202 teruggestuurd. Dit betekent: “OK we hebben je aanvraag tot wijziging aanvaard”.

Wanneer je echter vraagt om iets te wijzigen dat reeds op die manier gekend is in het verenigingsregister, dan wordt er een status code 200 teruggestuurd. Dit betekent gewoon “OK” want eigenlijk moet er niets gebeuren.

Dit mechanisme komt op 2 plaatsen voor:

• Wanneer alle waarden in de PATCH exact gelijk zijn aan de waarden zoals die gekend zijn, dan gebeurt er dus eigenlijk niets. Om dit te reflecteren, krijg je op dat moment een status code 200 - OK terug in plaats van de standaard status code 202 - aanvaard.

• Wanneer je een KBO vereniging wil registreren terwijl dat KBO-nummer al gekend is, dan wordt ook een status 200 OK teruggegeven. In de header location staat dan de vCode waaronder die KBO vereniging al gekend is.

Omdat er geen wijziging heeft plaatsgehad, zal deze API call ook geen velden VR-Sequence noch ETag terugsturen (zie de secties hierboven voor de betekenis van deze headers). Als die noodzakelijk zijn voor de verdere verwerking in je toepassing, kan je deze waarden steeds ophalen via een API call naar beheer detail van die vereniging.

Manieren om een adres op te geven

Om een adres op te geven als locatie van een vereniging, kan je op 3 manieren tewerk gaan:

• adres met adrescomponenten

• adresID met de identificator uit het adresregister

• de combinatie van beide methoden hierboven

Wanneer je een adres opgeeft met adrescomponenten, dan zijn de velden straat, huisnummer, postcode, gemeente en land verplicht.

Wanneer je adresId opgeeft, dan moet broncode steeds AR zijn - dit is momenteel de enige bron van adressen die we ondersteunen. Voor het adresregister (AR) moet het veld bronwaarde een URI zijn van het adresregister zoals bijvoorbeeld https://data.vlaanderen.be/id/adres/3706808

Tijdens de verdere ontwikkeling van het verenigingsregister zijn nog enkele uitbreidingen voorzien, zoals (alles onder voorbehoud):

• Wanneer adresId opgegeven wordt, gaan we de adres componenten ophalen uit het adresregister

• Wanneer een adres met componenten gedefinieerd wordt, gaan we gebruik maken van de adresmatch APÏ van het adresregister om te proberen om hier een adresId van op te halen

• Wanneer beide opgegeven worden, dan checken we dat de adrescomponenten overeenkomen met het de waarden die we uit het adresregister halen op basis van het adresId.

Geo-locatie opgeven in plaats van een adres

Sommige verenigingen organiseren activiteiten op een locatie die geen exact adres heeft, bijvoorbeeld in een veld of in een bos. Momenteel is het nog niet mogelijk om een locatie aan te maken aan de hand van een geo-locatie in plaats van een adres. In de loop van 2025 zal door het Verenigingsregister bekeken worden of deze mogelijkheid voorzien kan worden.

Beheren van de doelgroep leeftijd

Het object doelgroep is een classificatie gebaseerd op leeftijd. Hierbij kan je twee waardevCode: waar terug te vinden
Codelijsten opvragen
Zoek opdrachten
Gebruik van PATCH voor wijzigingen
Event-Sourced systeem
expectedSequence
Concurrency bij schrijf-acties
Response code 200 bij schrijfacties + impact op VR-sequence en ETag
Manieren om een adres op te geven
Geo-locatie opgeven in plaats van een adres
Beheren van de doelgroep leeftijd
Verduidelijking over de gebeurtenissen in de historiek van een vereniging
Teksten mogen geen HTML code bevatten
Sorteren in beheer zoek
Verplichte velden bij het registreren van een vereniging
Notificaties van wijzigingen in de gegevens van verenigingen
Dubbel detectie
Dubbel markeringn opgeven: minimumleeftijd en maximumleeftijd. Beide waarden zijn optioneel. De default waarden zijn 0 voor de minimumleeftijd en 150 voor de maximumleeftijd.

Wanneer je doelgroep opgeeft, dan moet je telkens beide waarden opgeven. Zo niet wordt de waarde die je niet opgeeft gereset naar de default waarde. Voorbeeld: hier wordt de leeftijdsrange op [8-150] gezet.

Je kan de leeftijdsrange ook volledig terugzetten naar de default waarden door een leeg object doelgroep op te geven. In dit voorbeeld wordt de range gewijzigd naar [0-150]

Verduidelijking over de gebeurtenissen in de historiek van een vereniging

De historiek van een vereniging https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/6493765633 geeft zicht op de wijzigingen op de verenigingsdata zoals terug te vinden in het register.

De gebeurtenissen met naam “xxxWerdGewijzigd” betekenen voor de basisgegevens het volgende:

• data werd toegevoegd (na registratie) → Wijziging van een lege waarde naar een ingevulde waarde

• data werd gewijzigd → van ingevulde waarde naar een andere ingevulde waarde

• data werd verwijderd → van een ingevulde waarde terug naar een lege waarde

Contactgegevens, locaties en vertegenwoordigers maken geen onderdeel uit van de basisgegevens. Wijzigingen op deze data genereren gebeurtenissen met de namen “WerdToegevoegd”, “WerdGewijzigd” en “WerdVerwijderd”.

Teksten mogen geen HTML code bevatten

Om malafide gebruik te vermijden, worden tekstvelden met daarin HTML of javascript code geweigerd. Dit is geldig voor alle tekstvelden: naam, korte naam, korte beschrijving, straatnaam, gemeente, …..

Er wordt gecontroleerd op een stuk tekst dat begint met een < en eindigt op > (regex = ‘<.*?>’ ). Het resultaat wanneer dit toch geprobeerd wordt,  is een status 400 met foutboodschap “Deze waarde bevat niet toegestane tekens.”

Sorteren in beheer zoek

We hebben de sorteer parameter toegevoegd aan de beheer zoek, analoog aan de sorteer mogelijkheden van de publieke zoek.

Voorbeeld: sorteren op dalende volgorde van naam

We kunnen de resultaten sorteren op vCode, naam, korteNaam, roepnaam, status, verenigingstype.code, verenigingstype.naam, doelgroep.minimumleeftijd en doelgroep.maximumleeftijd