Toekomstige wijziging: VZER en subvereniging
- Frank Wambacq
Deze wijziging wordt in verschillende fases doorgevoerd. De eerste fase zorgt voor backwards compatility, met andere woorden : deze fase zorgt er voor dat de directe impact van deze wijziging herleidt wordt tot quasi nul. Deze fase staat vandaag al in productie.
Dat maakt het ons ook mogelijk om alle volgende fases een voor een door te voeren en in productie te plaatsen. In de sectie “Impact op API endpoints” gaan we aanduiden wat vandaag al mogelijk is of tegen wanneer we die wijziging verwachten.
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. Momenteel zijn we deze aan het toetsen op bruikbaarheid.
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 (& 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.
De omleiding van registreer FV naar registreer VZER is vandaag al beschikbaar op staging/TNI. Tegen eind maart 2025 verwachten we die ook in productie.
=> 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.
Het nieuwe endpoint registreer VZER is vandaag al beschikbaar op staging/TNI, maar nog niet via MAGDA. Tegen juni 2025 verwachten we dat MAGDA dit endpoint ook ter beschikking zal stellen.
=> Beheren van de data
Alle acties die mogelijk waren met een FV, zijn nu ook mogelijk met een VZER
Dit is vandaag al mogelijk en zal ook mogelijk blijven. Hier geen impact
=> 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 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, 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
GET <publiekURL>/v1/verenigingen/<vCode>
{
...
"vCode": "V0001234",
"verenigingstype": {
"code": "FV",
"naam": "Feitelijke vereniging"
}
}=> MET extra header (voorbeeld van response structuur, exact formaat nog te bepalen)
GET <publiekURL>/v1/verenigingen/<vCode>
Header: "NaamNogTeBepalen": "InhoudNogTeBepalen"
{
...
"vCode": "V0001234",
"verenigingstype": {
"code": "VZER",
"naam": "Vereniging zonder (eigen) rechtspersoonlijkheid",
"subtype": FV
}
}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:FVofverenigingstype.code:VZERbevat 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
Deze extra header mogelijkheid is vandaag al beschikbaar in de publieke API, en dit voor alle omgevingen.
Om de extra header ook te gebruiken in de beheer API is het nog even wachten tot de MAGDA implementatie voltooid is. (juni 2025).
=> 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
We verwachten dit extra veld beschikbaar te hebben in de publieke API tegen eind maart 2025 Voor de beheer API zal het beschikbaar zijn wanneer de MAGDA implementatie klaar is.(juni 2025)
=> 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.
We verwachten dit extra endpoint tegen eind maart beschikbaar te hebben op de staging/TNI omgeving. Het zal pas beschikbaar zijn voor gebruik via MAGDA van zodra hun implementatie afgerond is (juni 2025)
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.