| Table of Contents |
|---|
vCode: waar terug te vinden
Bij het registreren van een nieuwe vereniging (POST organisaties/verenigingen/verenigingen/feitelijkeverenigingen - v1 ) 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.
...
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 het de publieke API van verenigingsregister. Je hebt daarvoor geen credentials nodig.
...
Hoofdactiviteiten Verenigingsloket, code= hoofdactiviteitenVerenigingsloket
Zoek opdrachten
Specifiek voor Beschrijving Vraag (GET organisaties/verenigingen/verenigingen/zoeken - v1)
...
Query | Wat is het resultaat? |
|---|---|
q=* | Alle verenigingen in het verenigingsregister |
q=vereniging | Alle verenigingen die ergens de tekst vereniging in een zoekveld hebben staan. Dat kan in de naam zijn, maar evengoed in een ander veld dat beschikbaar is in de zoek resultaten |
q=naam:vereniging | Alle verenigingen die het woord vereniging in hun naam hebben. Het moet wel degelijk het volledige woord zijn dat er in zit: “Vereniging van zoekers” zal teruggevonden worden, maar “Zoekvereniging” niet. |
q=naam:*bal* | Alle verenigingen die ergens in hun naam het woord bal hebben. In dit geval kan het ook in het midden van het woord zitten. Zo zal ook de vereniging met naam “voetbalclub de sjotters” in de resultaten aanwezig zijn |
q=doelgroep.minimumleeftijd:<=16 | alle verenigingen die een waarde hebben in het veld |
q=naam:vereniging AND locaties.postcode:9000 | Je kan 2 criteria combineren met |
q=locaties.adresvoorstelling:"Waterhoek 43" | Alle verenigingen die in hun volledige adres “Waterhoek 43” hebben. Er kunnen ook wildcards gebruikt worden. Opgelet: bij gebruik van een spatie zoals in dit voorbeeld, dient URL encoding te worden toegepast. |
q=sleutels.waarde:0220923141 | De vereniging met KBO-nummer 0220.923.141. |
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.
...
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.
...
Schrijf acties noemen we events
Lees functionaliteiten noemen we projecties
expectedSequence
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.
Wanneer je de parameter expectedSequence niet opgeeft, wordt steeds de op dat moment geldende waarde van de projectie meegegeven.
...
| Code Block |
|---|
GET <BasisURL>/v1/organisaties/verenigingen/verenigingen/<vCode>?expectedSequence=254 |
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
de header waarde Etag in de response van de lees actie (GET)
Dit geeft de huidige versie aan van de gezochte vereniging
de header If-Match te gebruiken in de request van de schrijf-actie (PATCH, PUT, …)
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.
| Note |
|---|
Wanneer je de If-Match header niet gebruikt, wordt de waarde van de vereniging sowieso overschreven en loop je dus het risico van de waarden van andere beheerders te overschrijven. |
...
Tijdstip | Beheerder 1 | Beheerder 2 |
|---|---|---|
t1 | GET vCode V0001001 → ETag = W/”123” |
|
t2 |
| GET vCode V0001001 → ETag = W/”123” |
t3 | PATCH vCode V0001001 Header: If-Match: W/”123” → OK , Etag is nu W/”124” |
|
t4 |
| PATCH vCode V0001001 Header: If-Match: W/”123” → NOK , status code 412 |
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”.
...
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:
...
Wanneer
adresIdopgegeven wordt, gaan we de adres componenten ophalen uit het adresregisterWanneer 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 waarden opgeven: minimumleeftijd en maximumleeftijd. Beide waarden zijn optioneel. De default waarden zijn 0 voor de minimumleeftijd en 150 voor de maximumleeftijd.
...
| Code Block |
|---|
"doelgroep": {} |
Verduidelijking over de gebeurtenissen in de historiek van een vereniging
De historiek van een vereniging GET organisaties/verenigingen/verenigingen/{vCode}/historiek - v1 geeft zicht op de wijzigingen op de verenigingsdata zoals terug te vinden in het register.
...
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
| Code Block |
|---|
GET <BeheerURL>/v1/verenigingen/verenigingen/zoeken?q=*&sort=-naam |
We kunnen de resultaten sorteren op vCode, naam, korteNaam, roepnaam, status, verenigingstype.code, verenigingstype.naam, doelgroep.minimumleeftijd en doelgroep.maximumleeftijd
Voor elk van deze sorteercriteria kan je zowel oplopen als aflopend sorteren: oplopend door de naam op te geven, aflopend door een - voor de veldnaam te plaatsen. vb sort=vCode, sort=-vCode
Je kan twee of meerdere zoekcriteria combineren waardoor er eerst op het eerste criterium gesorteerd wordt, en daarbinnen op het tweede, … vb sort=verenigingstype.code, naam
Standaard wordt er gesorteerd op aflopende volgorde van vCode (de meest recent aangemaakt vereniging staat dan als eerste)
Wanneer je een sorteercriterium opgeeft dat de volgorde niet uniek bepaalt (zoals bijvoorbeeld bij het sorteren op verenigingstype.code, dan worden de resultaten steeds op het laagste niveau nog eens gestorteerd op aflopende volgorde van vCode. vb: Sort=verenigingstype.code zal hetzelfde resultaat geven dan sort=verenigingstype.code,-vCode
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)
Verplichte velden bij het registreren van een vereniging
Hoewel het Verenigingsregister verwacht dat de gegevensinitiatoren bij het registreren van een vereniging voldoende relevante gegevens meegeven, wordt dit initieel nog niet afgedwongen via verplichte velden. De enige verplichte velden zijn in eerste instantie de naam bij de registratie van een feitelijke vereniging en het KBO-nummer bij de registratie van een vereniging met rechtspersoonlijkheid.
Deze validaties staan beschreven op respectievelijk https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/6493733081/Beschrijving+Vraag+POST+organisaties+verenigingen+verenigingen+feitelijkeverenigingen+-+v1#Validaties-op-vraag en https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/6493798424/Beschrijving+Vraag+POST+organisaties+verenigingen+verenigingen+kbo+-+v1#Validaties-op-vraag.
Vanuit het Verenigingsregister wordt in de tweede helft van 2024 wel geleidelijk een minimale dataset ingevoerd voor het aanmaken of wijzigen van een vereniging, zie Toekomstige wijziging: Minimum Dataset.