We hebben grote kuis gehouden in onze code - de bugs er uit gehaald en de zaken mooier gemaakt waar het nodig was. Zo zijn we klaar voor een nieuwe ronde van verbeteringen.

Bugfixes gelinkt aan upgrades

Door de upgrade naar .net9 zijn er intern een aantal processen die problemen veroorzaakten. Dit had gelukkig geen effect naar buiten toe, maar om onze monitoring niet nodeloos te laten afgaan, hebben we deze toch maar opgelost

Api key toevoegen aan logging publieke API

We loggen vanaf nu ook de API key die gebruikt wordt bij aanroep van de publieke API. Zo kunnen we gerichter zoeken in geval van issues.

Upgrade naar .net9 en update van alle packages

De toepassing is ge-upgrade naar .net 9, waardoor er ook een aantal packages mee moesten upgraden.

Inkorten downtime tijdens installaties

We hebben de rebuilds van de projecties versneld. Dit is vooral nuttig om de down time tijdens de deploy van een nieuwe versie in te korten. Wat vroeger  40 minuten in beslag nam bij elke installatie, duurt nu maar 8 minuten meer.

Publiek zoek sorteren op score

Je kan nu ook de resultaten van de publieke zoek sorteren op het veld score, wat staat voor de matching van de vereniging met de zoekresultaten. Vooral het dalend sorteren op score is hier interessant (sort=-score), omdat je zo de resultaten met de hoogste score eerst krijgt en dus de verenigingen met de beste overeenkomst met de zoekcriteria als eerste te zien krijgt.

Elastic search toevoegen aan health check

De health checks die zichtbaar zijn op de statuspagina, bevatten nu ook de status van de elastic search engines (gebruikt voor de zoek functies).

Zoeken op geotags

In publieke zoek is er een zoekcriterium toegevoegd geotags.identificatie. Met dit veld kan je uitgebreider zoeken op basis van een postcode, gemeente of provincie. Dit veld houdt rekening met de postcodes van alle locaties, maar ook met de werkingsgebieden van een vereniging, en wel als volgt:

• wanneer een postcode als criterium wordt opgegeven, worden alle verenigingen terug gegeven met (1) een locatie met die bewuste postcode OF (2) een werkingsgebied dat de gemeente of provincie beschrijft die hoort bij die postcode

• wanneer een gemeente als criterium wordt opgegeven (in de vorm van het werkingsgebied van die gemeente), worden alle verenigingen terug gegeven met (1) een locatie met een van de postcodes binnen die gemeente OF (2) het gemeentelijk werkingsgebied OF (3) het werkingsgebied dat de provincie beschrijft die hoort bij die gemeente

• wanneer een provincie als criterium wordt opgegeven (in de vorm van het werkingsgebied van die provincie), worden alle verenigingen terug gegeven met (1) een locatie met een van de postcodes binnen die provincie OF (2) een van de werkingsgebieden van de gemeenten binnen die provincie OF (3) het werkingsgebied van die provincie

Voorbeelden

geeft alle verenigingen met een locatie met postcode 9000 maar ook alle verenigingen met werkingsgebied Gent (BE23444021) alsook alle verenigingen met werkingsgebied Oost-Vlaanderen (BE23)

geeft alle verenigingen met een locatie die een postcode heeft in Gent (9000, 9030, 9031, ...) maar ook alle verenigingen met werkingsgebied Gent (BE23444021) alsook alle verenigingen met werkingsgebied Oost-Vlaanderen (BE23)

geeft alle verenigingen met een locatie die een postcode heeft in Oost-Vlaanderen (9000, 9030, 9031, 9820, 9090, ...) maar ook alle verenigingen met werkingsgebied van Gent, Merelbeke-Melle, Aalst, … alsook alle verenigingen met werkingsgebied Oost-Vlaanderen (BE23)

PS: Dit veld kan je enkel als zoek criterium gebruiken. Het wordt dus niet weergegeven in de respons body.

Mutatiedienst zonder API Key

Voor het gebruik van de mutatiedienst in de publieke API, is nu niet langer een API key vereist.

Default subtype voor VZER

Bij registratie van een nieuwe VZER wordt het subtype leeg gezet. Het krijgt dus nog geen waarde. Vanuit de lege waarde kan je deze aanpassen met PATCH subtype naar de waarden NB, FV of SUB (zie eerdere release notes), maar kan je niet meer terug naar de lege waarde.

Ook verenigingen die eerst als feitelijke vereniging waren geregistreerd en daarna gemigreerd zijn naar VZER hebben nu ook de lege waarde als default gekregen.

Voorbeeld:

Bugfix sorteren op leeftijd

In de zoek functies (beheer zoek en publiek) kon je sorteren op minimum- en maximum leeftijd van de leeftijdsdoelgroep. Dit sorteren gebeurde op een alfanumerieke manier waardoor bijvoorbeeld “2” groter was dan “12”. Dit is nu aangepast zodat het sorteren numeriek gebeurt (en dus 2 < 12).

Bugfix synchronisatie werkingsgebieden

Bij het ophalen van de gemeenten uit het adressenregister was er een bug waardoor sommige gemeenten meerdere malen voorkwamen in de lijst met werkingsgebieden. Dit is nu opgelost zodat we weer een lijst van werkingsgebieden hebben die bestaat uit 285 gemeenten in Vlaanderen, 19 in Brussel, 5 provincies in Vlaanderen en 1 in Brussel, en dan ook nog de waarde NVT-Niet van toepassing.

Bugfix dubbele locaties in zoek functie

In heel uitzonderlijke omstandigheden kon het zich voordoen dat een locatie 2x werd toegevoegd aan de zoekfuncties. Deze situatie zou zich waarschijnlijk nooit voordoen in de productie omgeving, maar we hebben ze toch maar preventief behandeld.

Werkingsgebieden aangepast voor gemeente fusies

De lijst van mogelijke werkingsgebieden wordt aangepast volgens de gemeente fusies van jan-25.

Documentatie verbeteringen

De swagger bevat voortaan ook het release nummer om eenvoudig te weten welke twee versies je aan het vergelijken bent

Lokale deploy versie van VR beschikbaar

We hebben het mogelijk gemaakt om de VR software ook lokaal te installeren. Als dit u interesseert, stuur even een bericht via digitaal.vlaanderen@vlaanderen.be .

Subtypes van een VZER

Voor een vereniging zonder eigen rechtspersoonlijkheid (VZER) bestaat er nu ook een eigenschap subtype met mogelijke waarde “feitelijke vereniging” (FV), “subvereniging” (SUB) en “niet bepaald” (NB).

Deze eigenschappen zijn ook zichtbaar in de zoekresultaten of in het detail van een vereniging (enkel wanneer je data opvraagt met header v2).

Wanneer het subtype = SUB, komt er nog een extra veld beschikbaar

Het veld subverenigingVan.naam is enkel beschikbaar in de detail functie en niet in de zoek.

Introductie VZER = Vereniging Zonder Eigen Rechtspersoonlijkheid

We introduceren binnenkort een nieuw concept: de subvereniging. Zowel een subvereniging, als een feitelijke vereniging zijn beide verenigingen zonder eigen rechtspersoonlijkheid (in tegenstelling tot de vereniging met rechtspersoonlijkheid die in KBO gekend zijn). In een eerste stap gaan we alle verenigingen die eerder gekend zijn als feitelijke vereniging nu catalogeren als vereniging zonder eigen rechtspersoonlijkheid. We houden hierbij wel rekening met afnemers en GIs die (nog) niet wijzigen naar de nieuwe versie. Of anders gezegd: als je niets wijzigt aan de manier van integreren, dan zullen de wijzigingen beperkt zijn.

GET’s met of zonder request header

De endpoints publiek zoek en detail kan je vanaf nu op 2 verschillende manieren gebruiken:

• Wanneer je geen extra request header toevoegt (en dus blijft werken zoals nu), dan ga je dezelfde verenigingen kunnen zoeken en opvragen, maar wordt het verenigingstype van deze verenigingen vertaald van VZER naar FV-Feitelijke vereniging. Op deze manier kan alle bestaande logica behouden blijven

• Wanneer je wel een extra request header meegeeft (key = vr-api-version, value = v2), dan krijg je het interne type terug, namelijk VZER-Vereniging zonder eigen rechtspersoonlijkheid

Voorbeeld zonder header

Voorbeeld met header

Bugfix dubbel beheer

Er werd een bug opgelost in verband met dubbel beheer

=> Dubbels mogen niet meetellen in de facets van publiek zoek

Wanneer een vereniging als dubbel werd gemarkeerd, dan werd deze vereniging verkeerdelijk meegeteld bij het aantal vereniging per hoofdactiviteit (facets) in de publieke zoek

Vereniging markeren als dubbel

We voorzien de mogelijkheid om een vereniging te markeren als dubbel van een andere vereniging. Deze actie kan aangevraagd worden met een service ticket. De gevolgen op de publieke API van een dubbel markering zijn hieronder beschreven. Er zijn telkens gevolgen mogelijk voor:

• de dubbele vereniging (diegene die daarna niet meer direct bereikbaar zal zijn)

• de authentieke vereniging (diegene die nog bereikbaar blijft)

publiek zoek

• De dubbele vereniging is niet meer terug te vinden

• Geen wijziging aan de authentieke vereniging

publiek detail

• De dubbele vereniging is niet meer terug te vinden (status 404)

• Geen wijziging aan de authentieke vereniging

mutatiedienst

zowel de dubbele als de authentieke vereniging worden gemarkeerd als gewijzigd

Automatische adreswijzigingen omwille van gemeentefusies

Op 1 januari 2025 veranderen alle adressen van de fusiegemeenten. Hierbij wordt de gemeentenaam aangepast en soms ook de straatnaam en/of het huisnummer. We luisteren naar deze events van het adressenregister en kijken of er impact is in het verenigingsregister. Elke vereniging uit een van de fusiegemeenten, waarvan het adresId gekend is, zal vanaf 1 januari automatisch het nieuwe adres toegekend krijgen. Dit wordt voor alle adressen met een adresId gedaan, behalve voor de maatschappelijke zetel die uit KBO komt. Daar blijven we luisteren naar wijzigingen die in KBO worden uitgevoerd.

Lidmaatschappen

De publieke API bevat nu ook het element lidmaatschappen, waarmee aangegeven kan worden dat de ene vereniging lid is van een andere vereniging. Het lidmaatschap wordt enkel weergegeven bij de vereniging die lid is en dus niet bij de vereniging waarvan die lid is.

Hieronder het voorbeeld bij Publiek detail, ook in de zoek functie kan je de lidmaatschappen terugvinden (daar dan wel zonder het veld naam )

Parameter API voor werkingsgebieden

De lijst van mogelijke waarden voor een werkingsgebied kan je terugvinden via de publieke parameter API. Deze call naar de publieke API kan ook zonder API Key uitgevoerd worden.

De mogelijke werkingsgebieden zijn:

• de NUTS2 codes voor de provincies van Vlaanderen en voor het Brussels hoofdstedelijke gewest

• de NUTS+LAU codes voor de gemeenten van Vlaanderen en van het Brussels hoofdstedelijke gewest

• de speciale waarde NVT - Niet van toepassing

De speciale waarde NVT betekent dat er geen beperkingen zijn qua werkingsgebied. Dit is vooral om het onderscheid te maken met de default waarde voor werkingsgebieden: de lege lijst []. Deze default waarde geeft eigenlijk aan dat de werkingsgebieden (nog) niet bepaald zijn.

Door het verschil in betekenis kan de waarde NVT niet gecombineerd worden met een andere waarde:

bugfix totalcount

Wanneer het zoekresultaat bij Publiek zoek meer dan 10.000 resultaten bevatte, werd het juiste aantal resultaten niet correct weergegeven in metadata.pagination.totalcount. Daar werd het aantal afgetopt op 10.000. Nu wordt weer het juiste aantal zoek resultaten weergegeven.

Werkingsgebied

Een nieuw concept werkingsgebied werd toegevoegd. Dit is een lijst van codes (NUTS&LAU) die aan een vereniging kan toegevoegd worden en die aangeeft welke regio's (gemeente, provincie, …) deze vereniging haar werkingsgebied is.

De huidige werkingsgebieden van een verenigingen kan je terugvinden zowel in publiek detail als via de zoek functie, telkens met zowel de code als de naam. Voorbeeld:

In de zoekfunctie kan je de code van het werkingsgebied gebruiken als zoekcriterium. enkele voorbeelden:

Bugfixes

Er werd een bug gefixt

• publieke zoek: wanneer er meer dan 20 facets in de zoekresultaten zitten, worden er toch maar 20 facets getoond

Export publieke informatie voor externe toepassingen

Er is een nieuw endpoint toegevoegd op de publieke API, waarmee externe partijen met specifieke toelating het recht hebben om alle publieke informatie van alle verenigingen op te vragen met 1 streaming endpoint.

Minimum dataset

Het zal nog steeds mogelijk zijn om vereniging te registreren zonder locatie, vertegenwoordiger of hoofdactiviteit. Maar van zodra een vereniging een van deze elementen bevat, dan zal het niet meer mogelijk zijn om de laatste van zijn soort te verwijderen:

• Wanneer een vereniging al een locatie heeft, dan kan de laatste locatie niet meer verwijderd worden

• Wanneer een vereniging al een vertegenwoordiger heeft, dan kan de laatste vertegenwoordiger niet meer verwijderd worden

• Wanneer een vereniging al een hoofdactiviteit heeft, dan kan de set van hoofdactiviteiten niet meer leeg gemaakt worden

Algemeen: initiële adresmatch

We hebben een proces toegevoegd dat alle adressen overloopt in het register. Elke adres dat nog niet is geverifieerd ten opzichte van het adressenregister, wordt opgezocht via adresmatch. Wanneer een resultaat wordt gevonden, wordt het adresId toegevoegd en worden de adrescomponenten aangepast aan de spelling zoals deze in het adressenregister voorkomt.

Publieke API: Mutatie dienst

In de publieke API is een nieuw endpoint beschikbaar dat kan gebruikt worden voor afnemers die synchroniseren naar hun eigen databank/CRM. Met dit endpoint kan je alle vCodes opvragen waarvoor er een wijziging is gebeurd sinds de laatste keer dat je de synchronisatie hebt uitgevoerd.

Om dit endpoint aan te spreken heb je een API Key nodig.

Voorbeeld:

In dit voorbeeld weet je nu dat V0001027 en V0001024 gewijzigd zijn. Om die te synchroniseren, haal je data op via een of meerdere van volgende (bestaande) endpoints:

• Beheer Detail: <BeheerURLviaMAGDA>/v1/verenigingen/<vCode>

  • om alle gegevens van een vereniging op te vragen

• Publiek Detail: <PubliekURL>/v1/verenigingen/<vCode>

  • om alle publieke gegevens van een vereniging op te vragen - dit gebruik je wanneer jouw organisatie enkel met publieke gegevens werkt OF wanneer je geen recht hebt om alle gegevens via MAGDA op te vragen

• Beheer Historiek: <BeheerURLviaMAGDA>/v1/verenigingen/<vCode>/historiek

  • om meer informatie te bekomen over de wijzigingen die zijn uitgevoerd (enkel wanneer je hier toegang toe hebt)

Na synchronisatie, onthou je de hoogste verwerkte sequence (in het voorbeeld is dat 89) zodat je de volgende keer alle nieuwe wijzigingen kan opvragen via

Goed om weten: in dit endpoint komen ALLE vCodes voor en worden ALLE wijzigingen gereflecteerd. Dit heeft enkele gevolgen die je best mee overweegt bij de implementatie van deze mutatiedienst. Enkele voorbeelden:

• Wanneer er iets veranderd aan een vertegenwoordiger van een vereniging, dan is dit een wijziging, maar via de publieke data stroom zal je geen enkel verschil opmerken.

• Wanneer een vereniging uitgeschreven wordt uit de publieke datastroom, dan komt dit naar voor als wijziging, maar via de publieke datastroom betekent dit dat je de vereniging plots niet meer zal terugvinden. (Publiek detail geeft dan een 404)

• Wanneer een vereniging verwijderd wordt, dan komt dit naar voor als wijziging, maar noch bij publiek, noch bij beheer detail zal je deze vereniging nog terugvinden (respons = 404). Via beheer historiek kan je wel nog terugvinden dat deze vereniging verwijderd is, met daarbij de reden van verwijdering.

Dagelijkse synchronisatie met het adressenregister

Deze kleine update zorgt er voor dat er nu dagelijks automatisch een synchronisatie loopt met het adressenregister.

Wijzigingen aan publieke API

Geen

Info over beheer mogelijkheden

Synchronisatie met het adressenregister

Wanneer een adres wordt opgegeven met een adresId EN adrescomponenten (straatnaam, huisnummer, …) dan wordt dit nu geweigerd.

Wanneer een adres wordt opgegeven met enkel een adresId, dan worden de bijhorende adrescomponenten opgehaald uit het adressenregister, maar enkel wanneer het adresId verwijst naar een bestaand adres in status Ingebruik of Voorgesteld.

Wanneer adresmatch de adrescomponenten wijzigt en hierdoor zou een identieke locatie ontstaan (zelfde locatietype, naam en adres), dan zal een van de identieke locaties verwijderd worden: de locatie die als primair is aangeduid blijft behouden, de andere verdwijnt. Wanneer beide locaties als niet primair stonden aangeduid, dan wordt de nieuwste locatie verwijderd

Bugfix voor lege locatie naam

Stel: een vCode heeft een locatie met type = activiteiten en naam leeg ("naam": ""). Wanneer dan een nieuwe locatie wordt toegevoegd met type = activiteiten en hetzelfde adres maar in de request om toe te voegen wordt het naam veld niet ingevuld, dan werd deze locatie toch niet als dubbel gezien. Dit is nu opgelost, zodat het weglaten van het naam veld hetzelfde reageert als het toevoegen van "naam": ""

Adresmatch op ingevoerde adressen

Alle ingevoerde adressen worden nagekeken of ze al dan niet overeenkomen met een bestaand adres uit het adressenregister. Wanneer een match gevonden wordt, wordt de juiste spelling van het adres overgenomen. Het adres krijgt dan ook een adres ID toegewezen (zie locaties.adresId.bronwaarde)

Statuspagina

Op https://www.vlaanderen.be/digitaal-vlaanderen/status/status-overzicht?product=Verenigingsregister vind je de status van de verschillende API’s op de 2 omgevingen terug. Je kan je ook abonneren op meldingen zodat je hiermee automatisch op de hoogte gebracht wordt van nieuwe releases en/of zware incidenten.

Bugfix voor de synchronisatie met KBO

Na de release op staging van de vorige versie, is gebleken dat er nog problemen waren met de synchronisatie met KBO. Deze bugs zijn in deze versie aangepakt, zodat we nu toch van start kunnen gaan met de KBO synchronisatie.

Synchronisatie met KBO

De gegevens van de verenigingen met rechtspersoonlijkheid worden bij registratie overgenomen uit KBO. Vanaf nu gaan we ook dagelijks de wijzigingen in KBO synchroniseren naar het verenigingsregister. Zowel de naam, korte naam, startdatum, maatschappelijke zetel als de contactgegevens worden daarbij gecontroleerd. Ook wanneer een KBO vereniging stopt in KBO (status in KBO is niet langer Actief of in oprichting), wordt de vereniging gestopt in het verenigingsregister.

Bugfixes JSON-LD

2 kleine wijzigingen aan het JSON-LD output formaat:

• De context bevatte nog een komma op het einde wat een probleem veroorzaakte bij het converteren naar triples

• Bij het veld hoofdactiviteit.code was de prefix act: vergeten

Verbeteringen publiek zoek sorteren

Wanneer de resultaten van de publieke zoek gesorteerd worden op een tekstveld, dan worden ook hier enkele verschillen in schrijfwijze genegeerd om een intuitievere sortering te bekomen.

Bij het sorteren op tekstvelden, negeren we enkele verschillen in schrijfwijze:

• hoofdletter ongevoelig ( A = a, B = b, …)

• accent ongevoelig (é = è = ê = ë = e, à = â = ä = a, …)

• puntjes worden weggewerkt (a.b.c = abc)

• leading spaces (zodat “ AAA” voor “ZZZ” komt)

Output in JSON-LD formaat

Zowel de publieke zoek als de publieke detail endpoints zijn nu in JSON-LD formaat. Om dit te realiseren zijn enkele velden toegevoegd en is ook het context bestand opgevuld. Samen zorgen deze er voor dat de gehele output correct vertaald kan worden naar triples.

verbeteren publieke zoek resultaten

Bij het zoeken op tekstvelden, negeren we enkele verschillen in schrijfwijze:

• hoofdletter ongevoelig ( A = a, B = b, …)

• accent ongevoelig (é = è = ê = ë = e, à = â = ä = a, …)

• puntjes worden weggewerkt (a.b.c = abc)

• leestekens worden genegeerd

toevoegen korte beschrijving aan publieke zoek

In het zoekresultaat werd nu ook de korte beschrijving toegevoegd. Dit veld kan eveneens gebruikt worden als zoekcriterium.

Voorbeeld: Onderstaande URL zoekt naar alle verenigingen die het woord tennis in hun korte beschrijving hebben staan. Het 2e voorbeeld zoekt naar alle verenigingen die het woord tennis in een van de zoekvelden hebben staan, dus niet alleen in de korte beschrijving, maar dit kan ook terug te vinden zijn in de naam, de korte naam, het adres…