Deze pagina geeft per sprint (= elke 2 weken) aan wat de wijzigingen zijn betreffende de API’s en de processen. De meest recente sprint staat bovenaan. Het labeltje “overzicht van wijzigingen” hieronder kan opengeklapt worden om een vorige wijziging op te zoeken.

De legende voor het gebruik van de emoji’s:

Deze wijziging is afgewerkt maar nog niet beschikbaar op de staging omgeving

Deze wijziging is al beschikbaar op de staging omgeving.

Wijzigingen die ervoor kunnen zorgen dat bestaande code om de API’s te gebruiken niet meer werkt.

Wijzigingen die zich weerspiegelen in de swagger definitie van de API.

Dec 13, 2023 [v8.32.2.0] Laatste loodjes voor Go-live van de eerste versie: API Key op Staging, MAGDA Connectie actief,
velden hernoemd, verbetering dubbel detectie, weglaten van het concept afdeling

API Key is actief op Staging (en productie)

De publieke API is nu enkel op te vragen met een API Key. Deze kan je aanvragen met dit formulier: Aanvragen API Key. Indien mogelijk, geef duidelijk aan voor welke toepassing, organisatie je toegang wil + voor welke omgeving (enkel staging of staging en productie.

Het opvragen van context, parameters en API documentatie is mogelijk zonder API Key.

MAGDA connectie staat actief

Voor de beheer API kan je nu ook al connecteren via Magda. De rechtstreekse link naar het verenigingsrgister zal mettertijd geschrapt worden. Diegene die die link gebruiken, wordt dus aangeraden om ook voor de staging omgeving al om te schakelen naar de MAGDA connectie. (Daar heet die omgeving wel T&I).

Velden hernoemd

Als voorbereiding op het publiceren van verenigingsdata als linked open data, zijn op verschillende plaatsen velden hernoemd:

• relaties.type → relaties.relatietype

• contactgegeven.type → contactgegeven.contactgegeventype

• vereniging.type → vereniging.verenigingstype

  • vereniging.verenigingstype.beschrijving → vereniging.verenigingstype.naam

• hoofdactiviteiten.beschrijving → hoofdactiviteiten.naam

Verbeteringen in dubbel detectie

Bij het registreren van een feitelijke vereniging wordt gecontroleerd of er deze vereniging mogelijks al bestaat. Dit zoeken naar die andere vereniging was tot nu toe redelijk strikt. Momenteel accepteren we ook kleine verschillen in de naam of gemeente, zoals extra spaties, leestekens, hoofdletters, extra letters, accenten of verbindingswoorden (zoals de, het, van …).

Dit resulteert in extra resultaten tijdens de dubbel detectie met een grotere kans om diegene te vinden die echt een dubbel is. Aan de andere kant komen er hierdoor wel extra items terug die zeker geen dubbel zijn. We controleren nog steeds op gelijkenissen in naam+postcode OF naam+gemeente.

Voorlopig weglaten van het concept afdeling

Tijdens het verzamelen van de data bij de piloten, hebben we vastgesteld dat er enorm veel begripsverwarring is omtrent de definitie van een afdeling. Hierdoor riskeren we om veel data op te laden met het verkeerde verenigingstype. Om deze reden hebben we voorlopig het onderscheid tussen een feitelijke vereniging en en afdeling laten vallen. We kennen nu dus enkel een vereniging MET een KBO nummer en een vereniging ZONDER een KBO nummer.

Gevolgen:

• Het endpoint om afdelingen te registreren wordt tijdelijk gedeactiveerd (POST <BeheerURL>/v1/verenigingen/afdelingen)

• De collection relaties wordt nog steeds weergegeven in de respons structuren, maar zal steeds leeg zijn

• AFD - Afdeling wordt weggehaald uit de lijst van mogelijke verenigingstypes

Sep 29, 2023 [v8.6.0.0] Sorteren en relaties in de publieke zoekfunctie, KBO-nummer en status in de ACM API,
verwijderen oud pad voor registratie feitelijke verenigingen

datum installatie op staging: Oct 2, 2023

Verbeteringen aan de publieke zoekfunctie

We hebben de publieke zoek functie uitgebreid met 1 extra dataveld en 1 extra mogelijkheid.

Opgelet: deze uitbreidingen zijn enkel toegepast op de publieke zoek functie en niet op de zoekfunctie in de beheer API.

Relaties toegevoegd

We hebben de relaties tussen een afdeling en haar moeder (en omgekeerd) toegevoegd aan de zoekresultaten. Dit maakt het mogelijk om direct een link te tonen vanuit de resultaten en/of om te gaan zoeken op vereniging die een bepaalde relatie hebben met een andere vereniging.

Sorteren van de zoek resultaten

De zoek resultaten kunnen gesorteerd worden door het toevoegen van een sort variabele. De zoekvelden waarop kan gesorteerd worden zijn vCode, naam, korteNaam, roepnaam, type.code, type.beschrijving, doelgroep.minimumleeftijd en doelgroep.maximumleeftijd.

Voorbeeld sorteren op naam:

Wanneer je een sorteerveld opgeeft, wordt er oplopend gesorteerd op dat veld. Je kan de volgorde omdraaien door er een - voor te zetten. Voorbeeld, sorteren op dalende volgorde van naam (namen met een Z komen voor die met een A)

Je kan ook meerdere sorteer velden opgeven waardoor er eerst op het eerste veld gesorteerd wordt en daarbinnen dan op het tweede veld. Bijvoorbeeld: eerst sorteren op naam, dan op dalende volgorde van vCode.

Standaard wordt gesorteerd op aflopende volgorde van vCode. De meest recente vereniging wordt dan eerst getoond. (standaard sorteerveld is dus -vCode).

Wanneer je sorteert op velden die niet uniek zijn, dan wordt er binnen elke waarde standaard op aflopende volgorde van vCode gesorteerd. De volgende twee vragen gaan dus hetzelfde resultaat opleveren.

Toevoegen KBO nummer en status aan ACM API

Wanneer ACM de verenigingen voor een bepaalde persoon komt opvragen, gaan we naast de vCode en de naam ook de huidige status van de vereniging meegeven alsook eventueel het kbo-nummer. Dat biedt ACM de mogelijkheid om al dan niet te filteren op actieve verenigingen , maar ook om de KBO-verenigingen uit het verenigingsregister te matchen met de resultaten die een gelijkaardige vraag in het KBO oplevert.

Verwijderen oude pad voor registratie van feitelijke verenigingen

De URL om een feitelijke vereniging te registreren werd in een vorige versie al gewijzigd naar

In deze versie werd oude pad (zonder extensie feitelijkeverenigingen ) verwijderd en is dus niet meer bruikbaar.

Verwerking ontvangen feedback

Fix inconsistentie beheer api problemdetails

In de swagger werd op sommige plaatsen nog gebruik gemaakt van Microsoft.AspNetCore.Mvc.ProblemDetails of Microsoft.AspNetCore.Mvc.ValidationProblemDetails. Deze zijn nu verwijderd.

Verwijder nullable uit Swagger doc

In de swagger werden sommmige velden als nullable aangeduid, wat problemen opleverde voor de Magda implementatie. Die nullable vermeldingen zijn overal weggehaald.

Fix: Etag wordt niet aangepast in beheer detail na Patch van een KBO contactgegeven

Na het wijzigen van een KBO contactgegeven (PATCH <BeheerURL>/v1/verenigingen/<vCode>/contactgegevens/kbo/<KBOContactgegevenId>) wordt een Etag in de response header meegegeven. Wanneer we vervolgens het Beheer detail van die vereniging opvragen (GET <BeheerURL>/v1/verenigingen/<vCode>) zien we dat daar de Etag niet werd aangepast.

Tijdstip in Beheer historiek wordt nu in Zulu time formaat getoond

Het tijdstip in beheer historiek werd weergegeven in UTC, maar zonder dit expliciet te vermelden. Een wijziging die om 15u werd uitgevoerd, kwam dus gewoon als 13:00:00 terug. Dit werd makkelijk fout geïnterpreteerd als 13u. Om duidelijk aan te geven hoe dit tijdstip moet geïnterpreteerd worden, wordt het nu in Zulu formaat getoond: 2023-09-28T13:00:00Z

Sep 15, 2023 [v7.29.0.0] Verrijken KBO gegevens, Stoppen van een vereniging, Aanpassingen aan swagger

datum installatie op staging: Sep 18, 2023

Verrijken KBO gegevens

Gegevens die we uit KBO obvergenomen hebben, kunnen niet aangepast worden. We maken het nu wel mogelijk om voor deze data objecten de velden in te vullen die niet uit KBO overgenomen zijn.

Wijzigen van de maatschappelijke zetel volgens KBO

Voor de maatschappelijke zetel volgens KBO is het mogelijk om de velden naam en isPrimair aan te passen. Het locatietype, adres en adresID blijven steeds ongewijzigd. Deze actie mogelijk via een apart endpoint

Wijzigen van KBO contactgegevens

Ook voor de contactgegevens die overgenomen worden uit KBO kan je enkel de velden beschrijving en isPrimair aanpassen. Ook hier is dat via een apart endpoint

Tijdelijk nabootsen van functiehouders uit KBO

Zolang we niet de juiste machtiging hebben om persoonsgegevens op te halen uit KBO, zijn we een beetje geblokkeerd om verder te ontwikkelen op de vertegenwoordigers van een KBO vereniging. Om dit euvel te verhelpen, maken we het nu mogelijk om de KBO functiehouders na te bootsen door bij elke registratie van een KBO vereniging een vaste set van personen toe te voegen. Deze set kan op aanvraag aangepast worden (om zelf ook te kunnen testen). Van elke vertegenwoordiger voegen we insz, voor- en achternaam toe. We vinden deze gegevens terug in beheer detail en in beheer historiek

Wijzigen van KBO vertegenwoordigers

Nu we vertegenwoordigers van KBO verenigingen beschikbaar hebben, kunnen we deze gegevens ook aanvullen met gegevens die niet in KBO terug te vinden zijn. Dit zijn exact dezelfde gegevens dan wat je mag wijzigen voor een vertegenwoordiger van een feitelijke vereniging of een afdeling. We gebruiken hier geen specifiek endpoint voor. We controleren wel dat je voor KBO verenigingen geen vertegenwoordigers kan toevoegen, noch verwijderen.

Stoppen van een vereniging

Wanneer een feitelijke vereniging of een afdeling de activiteiten stopt, kan je dat ook aangeven in het verenigingsregister. Voor deze gebeurtenis is een apart endpoint beschikbaar. De einddatum is een verplicht veld, waarvoor geldt: startdatum <= einddatum <= vandaag

Het stoppen van een vereniging heeft enkele gevolgen:

• een nieuwe gebeurtenis wordt toegevoegd in de historiek “VerenigingWerdGestopt"

• De status van de vereniging wordt “Gestopt”. Deze is zichtbaar in beheer detail en beheer zoek

• De vereniging wordt uit de publieke datastroom gehaald.

  • Je kan deze dus niet meer terugvinden via publiek zoek.

  • Bij het opvragen van deze vereniging in publiek detail , krijg je een 404 terug

  • De vereniging wordt ook niet meer getoond als mogelijke dubbel bij het registreren van een andere vereniging

Het is wel nog mogelijk om wijzigingen aan de vereniging uit te voeren.

Ook op de ACM API heeft dit geen impact, zodat je nu nog steeds zal kunnen aanmelden als vertegenwoordiger van een gestopte vereniging.

Je kan de einddatum aanpassen door nogmaals de STOP aan te roepen met de nieuwe einddatum. Dit zal de einddatum aanpassen en een aparte gebeurtenis aanmaken (“EinddatumWerdGewijzigd“)

Aanpassingen aan swagger

Nieuw pad voor het registreren van een feitelijke vereniging

De URL om een feitelijke vereniging te registreren zal gewijzigd worden naar

Voorlopig is het oude pad (zonder extensie feitelijkeverenigingen nog beschikbaar, maar dit zal binnenkort weggehaald worden.

sample data verbeteren

Voor elke mogelijke API call is gecontroleerd dat de sample data in de API documentatie is ingevuld en ook correcte, mogelijek waarden bevat.

Verwijderen van de endpoints voor contexten en parameters uit de beheer API

We hebben de endpoints voor de JSON LD contexten en dat voor de parameters (nu enkel de hoofdactiviteitenVerenigingsloket) weggehaald uit de Beheer API. Voor beide verwijzen we nu naar de Publieke API waar je deze data ook kan opvragen.

Sep 1, 2023 [v7.10.0.0] Verrijken KBO verenigingen, INSZ toevoegen aan beheer detail en verwerking ontvangen feedback

datum installatie op staging: Sep 4, 2023

Verrijken KBO verenigingen

Het is nu ook mogelijk om extra gegevens toe te voegen aan verenigingen met rechtspersoonlijkheid, ook gekend als de KBO-verenigingen. Na registratie van een KBO-vereniging kan je deze verrijken met eigen data (doelgroep leeftijd, roepnaam, correspondentie- en activiteiten locaties en eigen contactgegevens) . De gegevens die overgenomen werden uit KBO mogen niet overschreven of verwijderd worden. Hierbij is gekozen om zoveel mogelijk gebruik te maken van de bestaande endpoints. De URL structuur is ook eenvormig gemaakt. Zo zal elke wijziging aan een bestaande vereniging steeds opgeroepen worden met een URL die begint met <BeheerURL>/v1/verenigingen/<vCode>

Wissel route voor Patch KBO

Door het eenvormig maken van de URL structuur, is het pad om de basis gegevens van een KBO vereniging aan te passen aangepast van <BeheerURL>/v1/verenigingen/kbo/<vCode> naar <BeheerURL>/v1/verenigingen/<vCode>/kbo

Metadata veld beheerBasisUri verwijderd

Door het eenvormig maken van URL structuur en door het maximaal herbruiken van de endpoints voor het verrijken van de KBO verenigingen, is de waarde in het metadataveld beheerBasisUri niet langer geldig. De plek waarmee aangeduid wordt welke endpoint te gebruiken is voor welke data, wordt eerder bepaald door het veld bron (zie verder) dan door een vaste basisURI . Het veld metadata.beheerBasisUri is weggehaald uit beheer detail.

Toevoegen bron van de gegevens

Om duidelijk het verschil te maken tussen de gegevens die overgenomen zijn van KBO (en dus beperkt aanpasbaar zijn) en de gegevens die vrij te beheren zijn, is er een nieuw veld toegevoegd met naam bron en waarden Initiator en KBO. Dit veld is enkel in beheer detail terug te vinden, maar wel op verschillende niveaus:

Doelgroep leeftijd

Net zoals voor feitelijke verenigingen en afdelingen kunnen we nu ook de doelgroep leeftijd van een KBO vereniging beheren. Dit gebeurt via het endpoint voor het wijzigen van de basisgegevens. De regels, validaties en verwachte antwoorden zijn hierbij identiek aan het wijzigen van de doelgroep leeftijd voor feitelijke verenigingen en afdelingen. (zie Release notes - Pre go-live | Wijzigen )

Toevoegen roepnaam voor KBO verenigingen

Voor een KBO verenigingen kunnen we naast de officiële naam (die overgenomen werd uit KBO) ook een roepnaam bepalen. Hiermee kan je aangeven hoe deze vereniging beter gekend is, wat soms afwijkt van de officiële naam zoals die in KBO gekend is. Bij registratie van een KBO verebniging is deze roepnaam leeg (""). Je kan een roepnaam toekennen aan een KBO vereniging, maar deze achteraf ook weer leeg maken. Dit alles gebeurt via hetzelfde endpoint voor het beheren van de basis gegevens van een KBO vereniging.

om terug leeg te maken:

Bijkomende locatie voor een KBO vereniging

De maatschappelijke zetel wordt overgenomen uit KBO. Via decentraal beheer kan je (net zoals voor feitelijke verenigingen en afdelingen) 1 correspondentie adres en meerdere activiteiten locaties toevoegen. Dit gebeurt via het zelfde endpoint als voor de feitelijke verenigingen en afdelingen.

Je kan deze bijkomende locaties toevoegen, maar ook wijzigen en verwijderen. Hierbij zijn de regels, validaties en verwachte antwoorden identiek aan de locaties voor feitelijke verenigingen en afdelingen.

Het is NIET mogelijk om een maatschappelijke zetel volgens KBO via decentraal beheer toe te voegen en het is ook NIET mogelijk om de maatschappelijke zetel volgens KBO te wijzigen of te verwijderen.

Bijkomende contactgegevens voor een KBO vereniging

Na registratie van de KBO vereniging worden de contactgegevens beschikbaar in KBO overgenomen naar het verenigingsregister. Via decentraal beheer kan je bijkomende contactgegevens toevoegen. Dit gebeurt via het zelfde endpoint als voor de feitelijke verenigingen en afdelingen.

Je kan deze bijkomende contactgegevens toevoegen, maar ook wijzigen en verwijderen. Hierbij zijn de regels, validaties en verwachte antwoorden identiek aan de contactgegevens voor feitelijke verenigingen en afdelingen.

Het is NIET mogelijk om een contactgegevens uit KBO via decentraal beheer toe te voegen en het is ook NIET mogelijk om een contactgegeven uit KBO te wijzigen of te verwijderen.

INSZ terug toevoegen aan beheer detail

Eerder werd het INSZ weggehaald uit alle mogelijke antwoorden van het verenigingsregister. Dat gaf echter praktische problemen, o.a. voor het ophalen van de contactgegevens van een persoon die in een loket ingelogd is. We brengen het veld INSZ terug, maar wel enkel in beheer detail

Verwerking ontvangen feedback

Wijzigen direct na registratie geeft issue met If-match

We hebben een bug opgelost waarbij het niet mogelijk was om direct na een registratie van een nieuwe vereniging, de basisgegevens van deze vereniging te wijzigen, waarbij gebruikt gemaakt werd van de If-Match header . Dit bleef steeds een 412 teruggeven. Nu is dit wel mogelijk.

Toevoegen API documentatie voor dubbeldetectie response bij registreer afdeling

Bij registratie van een afdeling wordt een dubbel detectie uitgevoerd. Indien dubbels ontdekt worden, geeft dit status code 409 met in de response de mogelijke duplicates. Dit was voorheen al zo, maar dit stond nog niet gedocumenteerd in de API documentatie. Status code 409 is toegevoegd als mogelijke response.

Consistente status codes bij ontbrekende data

Wanneer je bij het beheren van data een onbekende vCode gebruikt of een onbekend ID van een locatie, contactgegeven of vertegenwoordiger, dan was er voorheen een inconsistentie in de response codes. Meestal werd status code 400 terug gegeven, maar soms ook 404. Dat is nu gelijk getrokken:

• Een onbekende vCode of een onbekend ID geven telkens een 400 terug bij het beheren

  • Dit betekent een aanpassing van de response code bij het beheren van een onbekend contactgegeven

• Een onbekende vCode geeft een 404 terug bij het opvragen van gegevens

  • Dit betekent een aanpassing bij het opvragen van een onbekende context

Aug 18, 2023 [v6.16.2] Integratie met KBO + Correcties aan de bestaande API definitie + verwerking ontvangen feedback

datum installatie op staging: Aug 21, 2023

Integratie met KBO via Magda dienst GeefOnderneming

Validatie KBO nummer bij registratie van een KBO vereniging

Bij registratie van een KBO vereniging, wordt Magda dienst Onderneming.GeefOnderneming-02.00 gebruikt om na te gaan of:

• KBO nummer bestaat

• KBO nummer is een onderneming (en geen vestigingsplaats)

• Rechtsvorm = VZW, iVZW, Private Stichting, Stichting van openbaar nut

• KBO status is actief

Wanneer niet voldaan wordt aan een van deze criteria niet geldig is, faalt de registratie en komt eenzelfde foutboodschap terug: “Er werd voor dit KBO-nummer geen geldige vereniging gevonden.“

Overname van de gegevens

Na correcte validatie van een KBO-nummer worden volgende gegevens overgenomen uit KBO

• Basisgegevens

  • naam, korte naam, startdatum

  • type vereniging (volgens rechtsvorm in KBO)

• locatie met type Maatschappelijke zetel volgens KBO

• de contactgegevens E-mail, telefoon, GSM, website worden gemapt naar algemene contactgegevens. Hierbij worden zowel mobiel als telefoon beide gemapt naar algemeen contactgegeven Telefoon.

In beheer historiek kan je terugvinden welke gegevens overgenomen zijn uit KBO:

• De basisgegevens staan mee in de gebeurtenis

  • VerenigingMetRechtspersoonlijkheidWerdGeregistreerd

• Voor de maatschappelijke zetel bestaat er een aparte gebeurtenis

  • MaatschappelijkeZetelWerdOvergenomenUitKBO

• Per contactgegeven bestaat er ook een aparte gebeurtenis

  • ContactgegevenWerdOvergenomenUitKBO

De data in KBO voldoet niet altijd aan de validaties van het verenigingsregister. Zo vinden we bijvoorbeeld adressen terug met enkel postcode en gemeente, dus zonder straat en huisnummer. In dit geval wordt het adres niet overgenomen. Dit kan je dan terugvinden in de historiek van de vereniging. Daar voegen we dan een gebeurtenis toe MaatschappelijkeZetelKonNietOvergenomenWordenUitKBO . De data van die gebeurtenis bevat de gegevens zoals ze in KBO teruggevonden werden.

Hetzelfde kan zich ook voordoen met de contactgegevens uit KBO. Ook hier nemen we deze contactgegevens niet over en voegen we een gebeurtenis toe ContactgegevenKonNietOvergenomenWordenUitKBO met in de details van die gebeurtenis het contactgegeven zoals het in KBO terug te vinden is.

Correcties aan de bestaande API definitie

Email → E-mail

De correcte schrijfwijze is e-mail met een streepje ertussen. Dit hebben we overal doorgevoerd, maar heeft vooral impact op

• Contactgegevens: het contact type is nu E-mail

• Vertegenwoordigers: Hier is E-mail een aparte eigenschap

• Historiek van de vereniging: telkens wanneer in data een labelE-mail gebruikt wordt

• De tekst van de foutboodschappen bij validatie van de gegevens

Swagger validatie issues opgelost

De swagger van de Beheer API voldoet nu aan de vereisten volgens swagger.io

Maatschappelijke zetel → Maatschappelijke zetel volgens KBO

Locatie type Maatschappelijke zetel (enkel beschikbaar bij het zoeken naar of bij het opvragen van het detail van een vereniging) is hernoemd naar Maatschappelijke zetel volgens KBO

Verwerking ontvangen feedback

Beschrijving in historiek bij beheren van contactgegevens

De beschrijving in de historiek van een vereniging bij toevoegen, wijzigen of verwijderen van en contactgegeven is nu aangepast, en dan vooral het gebruik van de aanhalingstekens. De beschrijving is nu E-mail 'info@vereniging.be' werd toegevoegd. warbij geen aanhalingstekens meer geplaatst worden rond het contact type.

bugfix: bij wijzigen van locaties

We hebben en foutje opgelost waarbij na het wijzigen van een locatie die wijziging niet in rekening gebracht werd bij volgende beheer acties. Zo was het bijvoorbeeld mogelijk om meerdere locaties primaire te maken via de wijzig locaties actie.

Jul 7, 2023 [v6.4.0] Beheren locaties + doelgroep leeftijd + voorbereiding op Magda integratie (initiator, correlation id, opkuis zoekresultaten, JSON-LD context) + behoud sortering van de collections

Beheren locaties

We kunnen nu ook locaties beheren (toevoegen, wijzigen en verwijderen) en dit zeowel met adrescomponenten (straatnaam, huisnummer, …) als met een adres identificator (link naar het adresregister).

Aanpassen structuur locatie object

Eerst en vooral is de structuur van het locatie object aangepast:

• in beheer detail werd een locatieId toegevoegd dat de locatie uniek identificeert binnen deze vereniging

• de eigenschap hoofdlocatie is hernoemd naar isPrimair

• de adrescomponenten zijn nu samengenomen in een adres object

• Er is een nieuw object adresId bijgekomen dat bestaat uit een broncode en een bronwaarde

  • Voor adressen uit het adresregister is broncode = AR en bronwaarde de URI van het adres

• Er is een nieuw locatietype toegevoegd: Maatschappelijke zetel. Dit nieuwe locatie type kan je echter niet opgeven bij het beheren van locaties. Dat is gereserveerd voor de KBO synchronisatie (die later geïmplementeerd zal worden. Het is dus enkel zichtbaar in de swagger bij de GET operaties. (zoeken en detail)

Dit nieuwe formaat kan je terugvinden wanneer je via beheer detail de gegevens van een vereniging opvraagt.

Wijzigingen aan het registreren van een nieuwe feitelijke vereniging of afdeling

Wanneer je een locatie wil opgeven bij registratie van een nieuwe feitelijke vereniging of een nieuwe afdeling, dan moet je nu de nieuwe structuur van het locatie object gebruiken.

Je kan tevens kiezen of je een adres gebruikt of een adresId of beide. Een van beide is wel verplicht om op te geven.

Wanneer je een adres opgeeft, dan zijn de velden straatnaam, huisnummer, postcode, gemeente en land nog steeds verplicht. Busnummer blijft optioneel

Wanneer je een adresId opgeeft, dan zijn zowel broncode als bronwaarde beide verplicht in te vullen. Broncode kan enkel de waarde AR bevatten en bronwaarde moet een URI zijn van het adresregister (begint met https://data.vlaanderen.be/id/adres/)

Toevoegen van een nieuwe locatie

Dit kan enkel voor een feitelijke vereniging of een afdeling. Je kan een nieuwe locatie toevoegen aan een bestaande vereniging met een POST API call waarin je een locatie object opgeeft. Ook hier kan je kiezen tussen een adres, een adresId of beide.

Verwijderen van een bestaande locatie

Om een bestaande locatie te verwijderen, kan je een DELETE actie uitvoeren waarbij je verwijst naar de locatieId die je wil verwijderen

Wijzigen van een locatie

Om een bestaande locatie te wijzen, gebruik je een PATCH method waarbij je verwijst naar de locatieId die je wil wijzigen. Hierbij toch enkele aandachtspunten:

• In de request body moet je niet altijd alle velden opgeven. Het is voldoende om enkel de velden op te geven die gewijzigd moeten worden

• Wanneer je een adres wil wijzigen, dan moet je wel het gehele object adres opgeven. Als bijvoorbeeld enkel huisnummer zou wijzigen, dan moet je toch nog steeds straatnaam, postcode, gemeente en land mee opgeven.

• Wanneer je een adresId wil wijzigen, dan moet je wel het gehele object adresId opgeven. Dus zowel broncode als bronwaarde.

• Wanneer de bestaande locatie een adresId heeft en je geeft in de PATCH enkel een adres op, dan wordt adres vervangen door hetgeen in de PATCH staat en adresId wordt op null gezet.

• Omgekeerd is hetzelfde geldig: Wanneer de bestaande locatie een adres heeft en je geeft in de PATCH enkel een adresId op, dan wordt adresId vervangen door hetgeen in de PATCH staat en adres wordt op null gezet.

• Wanneer je in de PATCH geen adres opgeeft en ook geen adresId, dan blijven deze informatie objecten staan zoals ze waren.

Doelgroep leeftijd

We introduceren een doelgroep classificatie gebaseerd op leeftijd. Hierbij kan je voor elke vereniging een range definiëren van leeftijden waarvoor de vereniging activiteiten aanbiedt. Deze minimum en maximum leeftijd kan je opgeven bij registratie van een feitelijke vereniging of een afdeling en kan je achteraf ook wijzigen.

Beide waarden zijn optioneel. De default waarden zijn 0 voor de minimumleeftijd en 150 voor de maximumleeftijd.

Bij registratie

Wijzigen

Het wijzigen van de leeftijdsrange kan je uitvoeren met het PATCH commando waarmee je de andere basisgegevens wijzigt.

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

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]

Zoeken op leeftijd

De minimum- en maximum leeftijd zijn ook beschikbaar als zoekcriterium in de 2 zoek functies (beheer zoek en publiek zoek). Hiermee kan je zoeken naar verenigingen voor personen van een bepaalde leeftijd - bij wijze van voorbeeld de query om te zoeken naar alle verenigingen voor een 14-jarige

Voorbereiding op de Magda integratie

Onze Beheer API zal binnenkort beschikbaar gesteld worden als een Magda dienst. Om deze integratie voor te bereiden, waren enkele wijzigingen noodzakelijk.

Verplichte headers x-correlation-id en VR-initiator

Elke call naar de Beheer API moet verplicht deze 2 headers bevatten:

• x-correlation-id bevat een GUID die de link vormt tussen de Magda call en onze verwerking daarvan. Van deze header wordt nu enkel geverifieerd dat deze een waarde bevat in het GUID formaat.

• VR-initiator: deze header was al verplicht op te geven bij de POST, PATCH en DELETE calls van de beheer API. Nu is deze ook verplicht op te geven bij elke GET. (beheer detail, beheer historiek, beheer zoek maar ook beheer parameters)

De API documentatie van de Beheer API is natuurlijk nog steeds zonder deze headers op te vragen.

Opkuis van de zoekresultaten

In de zoekresultaten kon je tot nu toe nog enkele velden vinden met gegenereerde data, zoals activiteiten en doelgroep. Deze velden zijn niet relevant en zijn er nu dus uitgehaald.

Json-LD Context

De API documentatie beschrijft nu ook het pad naar de JSON-LD contexten, en dit zowel in de publieke API als in de beheers API.

Voor beheer historiek werd eveneens een link naar een JSON-LD context toegevoegd.

Sortering van de collections blijft behouden na wijziging

Wanneer je wijzigingen aanbrengt aan een vertegenwoordiger, een contactgegeven of een locatie, dan werd voorheen steeds de laatst gewijzigde onderaan in de collection geplaatst. We geven de waarden nu telkens terug gesorteerd op het interne id (zoals bvb locationId).

Voorbeeld:

• Stel we hebben een vereniging met 3 locaties: 1, 2 en 3.

• Na registratie was de volgorde 1, 2, 3

• We wijzigen nu locatie 2

• Vroeger was de volgorde 1, 3, 2

• Nu blijft de volgorde 1, 2, 3

Jun 23, 2023 [v3.28.1] Beheer zoek + Opt-Out voor verenigingen + Controle kbonummer uniek + relatie tussen moeder en afdeling

Zoek functie in beheer API

De zoek functie die bestond in de publieke API is nu ook beschikbaar via de beheer API, met slechts enkele verschillen:

• De link naar het detail van de vereniging is een link naar het beheer detail van de vereniging (o.a. inclusief vertegenwoordigers)

• de facets zijn hier niet terug te vinden

Deze functie is beveiligd zoals de rest van de beheer API.

Opt-out voor feitelijke verenigingen

Een feitelijke vereniging kan er voor kiezen om zich te registreren, maar niet zichtbaar te zijn in de publieke stroom. Deze keuze wordt weergegeven door het veld isUitgeschrevenUitPubliekeDatastroom. Wanneer deze aan staat (waarde = true), dan is deze vereniging niet terug te vinden in de publieke zoek functie en kan je van deze vereniging ook niet het publieke detail opvragen. De vereniging is wel terug te vinden in de beheer zoek en beheer detail functie.

Je kan deze waarde (optioneel) opgeven bij het registreren van een nieuwe feitelijke vereniging

Je kan deze achteraf wijzigen samen met de rest van de basisgegevens van een vereniging.

Controleer dat een KBO nummer uniek is

Wanneer we een KBO vereniging registreren met een KBO nummer dat al bestaat in VR, dan resulteert dit in status code 200 (in plaats van 202). De location header bevat in dit geval de plek waar je deze KBO vereniging kan gaan raadplegen. (analoog aan de registratie van een nieuwe KBO vereniging)

Relatie tussen moeder en afdeling wanneer moeder ook in VR zit

Wanneer de moeder vereniging reeds geregistreerd was in het verenigingsregister wanneer een afdeling van deze moeder wordt geregistreerd dan krijgen zowel moeder als afdeling een relatie die verwijst naar de andere. In deze relatie staan zowel de vCode als een link naar de andere.

In beheer detail van de moeder vind je dan:

(publiek detail is gelijkaardig, maar de detail link zal dan verwijzen naar publiek detail van de afdeling)

terwijl je bij beheer detail van de afdeling het volgende terugvind:

(publiek detail is gelijkaardig, maar de detail link zal dan verwijzen naar publiek detail van de moeder)

Jun 9, 2023 [v3.17.0] Beheer basisgegevens voor KBO vereniging + verwijder INSZ uit respons + toevoegen voor- en achternaam + registreer afdeling + parameters in beheer API

Beheer basisgegevens voor KBO vereniging

Voor een vereniging met rechtspersoonlijkheid (soms ook een KBO vereniging genoemd) kan je nu ook de basisgegevens aanpassen. Omdat de gegevens uit KBO niet mogen overschreven worden, blijft er in het PATCH commando enkel de korte beschrijving en de hoofdactiviteiten over. (naam, korte naam en startdatum komen uit KBO). We gebruiken hiervoor een ander pad, dat start met /v1/verenigingen/kbo. Dit pad zal later ook gebruikt worden voor alle andere aanpassingen aan KBO verenigingen.

Wanneer je een aanpassing probeert uit te voeren voor een KBO vereniging op het pad foor de andere verenigingen (of omgekeerd), dan krijg je de foutboodschap “Deze actie kan niet uitgevoerd worden op dit type vereniging.“

Verwijder INSZ uit respons

Voor de bescherming van de persoonsgegevens, gaan we vanuit het verenigingsregister nergens het INSZ van een persoon teruggeven. Deze velden werden weggehaald uit beheer detail en beheer historiek.

Toevoegen voor- en achternaam

De toegang tot het rijksregister, en bij uitbreiding het KSZ vereist een machtiging van het RR. We voorzien dat we deze machtiging pas gaan krijgen na opstart van het verenigingsregister. Tot we alle toelatingen verkregen hebben, gaan we de voor- en achternaam van de personen toch moeten opvragen aan de gegevens initiatoren. We hebben deze velden toegevoegd aan alle requesten waar ook een INSZ nummer opgegeven wordt:

• registreren van een nieuwe vereniging met vertegenwoordigers

• toevoegen van een nieuwe vertegenwoordiger

De voor- en achternaam zijn verplichte velden, met volgende validaties:

• Er mag geen cijfer in voorkomen

• Er moet minstens 1 karakter in voorkomen (a-z of A-Z)

Registreer afdeling

Je kan nu ook een nieuwe vereniging registreren die een afdeling is van een KBO vereniging. Die KBO vereniging moet daarvoor nog niet geregistreerd te zijn in het verenigingsregister. Voor de registratie gebruiken we een ander pad /v1/verenigingen/afdelingen. De structuur van de request is identiek aan die van de feitelijke vereniging, behalve het extra (verplichte) veld kboNummerMoedervereniging.

Na succesvolle registratie, krijg je in beheer detail en publiek detail voor dit type vereniging een relatie te zien.

Parameters in beheer API

Je kan n u ook de lijst met mogelijke waarden van parameters (zoals hoofdactiviteitenVerenigingsloket) ophalen via de beheer API. Het resultaat is identiek aan de gelijkaardige call in de publieke API.

May 26, 2023 Onderscheid bij het registreren tussen een feitelijke vereniging en een vereniging met rechtspersoonlijkheid

Wanneer we een vereniging registreren op de gebruikelijke manier, dan is het nu expliciet gemaakt dat het hier gaat om een feitelijke vereniging. Een nieuwe eigenschap type wordt toegevoegd aan de vereniging. Deze eigenschap is zichtbaar wanneer je de details van vereniging ophaalt. Dit type kan je ook terugvinden in de publieke zoek API en in het publiek DETAIL van een vereniging.

Je kan nu ook een vereniging met rechtspersoonlijkheid registreren op basis van het KBO nummer. In een latere fase gaan we op dat moment alle gegevens van deze vereniging ophalen uit KBO. Momenteel wordt enkel gecontroleerd dat het KBO nummer een geldig KBO nummer zou kunnen zijn en de juiste rechtsvorm heeft.

Voorlopig is de naam van elke vereniging het vaste formaat “VZW <KBOnr>”. In de details van de vereniging kan je ook een nieuw element terugvinden sleutels. Hier vind je nu de sleutel in KBO, het KBO nummer. Het type van deze KBO vereniging is (nu nog) steeds een VZW.

May 5, 2023 Wijzig vertegenwoordigers + Verplaatsen initiator naar de headers

Wijzig vertegenwoordigers

Op het endpoint van vertegenwoordigers kan je nu ook de gegevens van een vertegenwoordiger wijzigen. Je kan alle gegevens wijzigen, behalve het INSZ. Het is een PATCH commando. je moet dus enkel de gegevens doorgeven die effectief gewijzigd zijn. De niet-gewijzigde gegevens mag je doorgeven, maar het hoeft niet.

Verplaatsen initiator naar headers

Het veld initiator is verplicht bij elke actie waarbij data gewijzigd wordt. (zie ook https://vlaamseoverheid.atlassian.net/wiki/spaces/AGB/pages/6285361348/API+documentatie#Initiator-verplicht-bij-elke-schrijfopdracht ). Dit veld staat niet langer in de request body, maar wel in een header met naam VR-Initiator.

Apr 28, 2023 Beheer hoofdactiviteiten + Toevoegen en verwijderen vertegenwoordigers + Uitbreiding documentatie

Beheer hoofdactiviteiten

Het PATCH commando waarmee je al enkele gegevens van en vereniging kon aanpassen zoals naam, korte naam, ... kan nu ook gebruikt worden om de hoofdactiveitenVerenigingsloket aan te passen. Hierbij geef je telkens de volledig nieuwe set door.

Toevoegen en verwijderen van vertegenwoordigers

Er is een nieuw endpoint om vertegenwoordigers toe te voegen en te verwijderen. Om dit te realiseren is er in de beheer detail (GET) een vertegenwoordigerId toegevoegd. Tegelijkertijd is het veld primairContactPersoon hernoemd naar isPrimair om consistent te zijn met de dataset van contactgegevens.

Je kan een nieuwe vertegenwoordiger toevoegen met een POST call op het vertegenwoordigers endpoint

Je kan een vertegenwoordiger verwijderen door een DELETE call waarbij je het vertegenwoordigerId opgeeft

Uitbreiding documentatie

De documentatie van de Beheer API, de Publieke API en de ACM API bevat nu een uitleg voor elk veld in de parameters, maar ook in de request - en response bodies.

De documentatie van de publieke API bevat ook de nodige informatie over de API Key: hoe deze te gebruiken maar ook hoe die kan aangevraagd worden.

Apr 21, 2023 contactgegevens vertegenwoordiger + historiek data voor registreer vereniging + API key voor publieke API + licentie + lege tekst velden als ““

Contactgegevens vertegenwoordiger

Op aanvraag hebben we de contactgegevens van een vertegenwoordiger hervormd en daardoor sterk vereenvoudigd. Je kan per vertegenwoordiger slechts 1 email, 1 telefoon, 1 mobiel nummer en 1 social Media account toevoegen. Bij het registreren van een nieuwe verenigingen ziet dat gedeelte er dan als volgt uit:

Historiek bij registreer vereniging

Om de historiek van de verenigingsdata volledig te kunnen reconstrueren, is er nu extra data toegevoegd bij de eerste gebeurtenis, het registreren van een nieuwe vereniging

API Key voor de publieke API

Om de publieke API te kunnen aanspreken, is voortaan een API Key vereist. Deze API Key kan meegegeven worden als request header vr-api-key of als path parameter

Als request header

Als Path parameter

De API Key is vereist voor publiek zoeken, publiek detail als voor het ophalen van de mogelijke waarden. Enkel de API documentatie is nog vrij beschikbaar. Wanneer je de publieke API aanspreekt zonder API key, wordt status code 403 teruggegeven.

Je kan een API Key aanvragen in onze CRM toepassing. Het aanvraag formulier is terug te vinden via deze link

Licentie

Om duidelijk de rechten en plichten van gebruikers van de API aan te geven, hebben we deze ondergebracht onder de Modellicentie Gratis Hergebruik - v1.0

Lege tekst velden als ““

We gaan nu consistent lege tekst velden teruggeven als "" in plaats van null.

Apr 7, 2023 Nieuwe vorm contactgegevens + Beheren ervan

Nieuwe vorm contactgegevens

Naar aanleiding van de feedback ontvangen bij demo’s en bij contact met lokale besturen, is het formaat voor de algemene contactgegevens van een vereniging aangepast:

• We ondersteunen 4 contacttypes: Email, Telefoon, Website en SocialMedia

• Van elk type mogen er meerdere per vereniging aanwezig zijn

• Per vereniging en per type kan je er maximum 1 (0 of 1 dus) markeren als het primaire

• Je kan aan elk contactgegeven een beschrijving toekennen, maar dat hoeft niet

• De combinatie type + beschrijving + waarde moet uniek zijn per vereniging

Dat betekent voor het registreren van een nieuwe vereniging:

Beheren van contactgegevens

Het is nu ook mogelijk om de contactgegevens van een vereniging aan te passen, meer bepaald een contactgegeven toevoegen, wijzigen of verwijderen. Om dit te realiseren is bij de beheer detail een contactgegevenId toegevoegd:

Om dit contactgegeven te wijzigen, is er de PATCH call. In deze call kan je waarde, beschrijving en/of isPrimair meegeven. Het type kan je niet wijzigen. Het is in deze call mogelijk om enkel de gewijzigde properties op te geven, maar je mag ze natuurlijk steeds allemaal doorgeven.

Om dit contactgegeven te verwijderen, is er de DELETE call. Hierbij geef je enkel de initiator mee in de request body.

Om een nieuw contactgegeven toe te voegen, gebruik je de POST call. Hierbij zijn initiator, type en waarde verplicht. beschrijving en isPrimair kan je meegeven. Doe je dat niet, dan wordt beschrijving op ““ gezet en isPrimair op false.

Mar 24, 2023 Meer info in de historiek van een vereniging

De historiek van een vereniging is uitgebreid met de velden beschrijving en data. De beschrijving kan je gebruiken om een gebruiker aan te geven wat de verandering was. De gebeurtenis samen met de relevante data kunnen gebruikt worden om te integreren in een toepassing.

beschrijving en data hebben geen vaste structuur, maar zijn afhankelijk van de gebeurtenis die heeft plaatsgehad, zoals in dit voorbeeld:

Mar 17, 2023 Wijzigen ContactInfo van de vereniging

Voor een bestaande vereniging kan je nu ook de contactInfo van de vereniging aanpassen. Dit is een uitbreiding op het bestaande PATCH endpoint, met dezelfde afspraken zoals vermeld in Datamodel verenigingsregister | Gebruik van PATCH voor wijzigingen. Je hebt dus de mogelijkheid om:

• property contactInfoLijst weg te laten => geen wijziging aan de contactgegevens

• contactInfoLijst: [] op te geven => alle contactgegevens worden gewist

• contactInfoLijst op te geven met een set van contactnamen en hun waarden => de contactgegevens worden in hun geheel vervangen door de nieuwe waarden uit de call.

Deze change resulteert in slechts 1 event ContactInfoLijstWerdGewijzigd, maar achterliggend wordt wel bijgehouden welke contactnamen toegevoegd, gewijzigd of verwijderd zijn.

Mar 10, 2023 Wijzigen startdatum

Behalve de naam, korte naam en korte beschrijving kan je nu ook de startdatum wijzigen voor een bestaande vereniging. Dit is een uitbreiding op het bestaande PATCH endpoint, met dezelfde afspraken zoals vermeld in Datamodel verenigingsregister | Gebruik van PATCH voor wijzigingen. Om de startdatum leeg te maken, kan je "startdatum": "" gebruiken in de request body.

Mar 3, 2023 Dubbel detectie v1

Bij het registreren van een nieuwe vereniging wordt eerst gecontroleerd of deze vereniging mogelijks al bestaat. Als er potentiële dubbels gevonden worden, wordt de vereniging niet geregistreerd, maar krijg je deze lijst van dubbels in het antwoord terug.

Na verificatie door de gebruikers kan je de vereniging toch nog laten registreren door een token mee te geven dat in het eerste antwoord werd opgegeven.

Deze eerste versie van de dubbel detectie zoekt naar alle verenigingen met:

• dezelfde naam (zonder rekening te houden met hoofdletters)

• een postcode of gemeente die overeenkomt (hier wordt nu wel rekening gehouden met hoofdletters)

De technische details zijn terug te vinden in de technische documentatie.

Later zal de dubbel detectie veel verfijnder geïmplementeerd worden, maar de proces flow (teruggave van potentiële dubbels, mogelijkheid om toch te registreren met het token) blijft gelijk.

Feb 24, 2023 Verbetering contactgegevens - Bug ivm busnummer - vCode case insensitive - check op correct JSON formaat

Validatie op contactgegevens

Er werd extra validatie toegevoegd op de de contactgegevens, zowel die van de vereniging, als die van de vertegenwoordigers:

• De eigenschap contactnaam is nu verplicht en moet uniek zijn voor de vereniging of per vertegenwoordiger.

• We kunnen een primair contact aanduiden (met eigenschap primairContactInfo) - default value = false. Er mag slechts 1 contact als primair worden aangeduid voor de vereniging of per vertegenwoordiger.

• We controleren op het formaat van de contactgegevens:

  • een email moet aan het volgende formaat voldoen (naam@domein.vlaanderen) waarbij

    • de naam moet beginnen met een letter of cijfer, gevolgd door 0 of meerdere letters, cijfers of speciale karakters ('!#$%&'*+/=?^_`{|}~-') en moet eindigen op een letter of cijfer

    • het domein moet beginnen met een letter of cijfer en enkel een liggend streepje mag bevatten of punt voor subdomeinen

    • het top level domein moet minstens 2 letters bevatten en enkel uit letters bestaan.

  • een telefoon moet minstens 1 cijfer bevatten - verder mogen ook de karakters whitespace, ()+./-

  • een website moet beginnen met http:// of https:// en moet minstens 1 punt bevatten

  • socialMedia : zie website

Andere wijzigingen

• De request body wordt gecontroleerd of dit een correct JSON body formaat is.

• Bij het definieren van een vCode in de URL (bij publiek detail, beheer detail, beheer historiek, …) wordt nu ook getolereerd dat de vCode met een kleine v wordt weergegeven.

• Wanneer het busnummer van een locatie niet is ingevuld, dan zal het samengestelde adres niet langer het woord “bus + <blanco>” bevatten. Dat deel wordt dan weggelaten.

Feb 17, 2023 ACM projectie met echte data en Hoofdactiviteiten Verenigingsloket

ACM Projectie met echte data

Bij registreren van een nieuwe vereniging met vertegenwoordigers, dan zijn die vertegenwoordigers ook onmiddellijk gekoppeld aan de vereniging zodat ze zich kunnen aanmelden. Anders gezegd : de ACM API is nu in sync gebracht met de beheer detail en is dus niet langer gebaseerd op statische data.

De gegevens in de ACM API worden aangepast bij registreren, van een nieuwe vereniging EN bij wijzigen van de naam van een vereniging

De enige API die hierbij gewijzigd is, is de ACM API, waar property en parameter met naam rijksregisternummer gewijzigd is naar insz.

Hoofdactiviteiten Verenigingsloket

Ook de hoofdactiviteiten uit het verenigingsloket die bij een vereniging horen, zijn niet langer gebaseerd op gegenereerde data (de fameuze brolfeeder) maar wel op data zoals aangegeven bij het registreren.

Ophalen van de lijst met mogelijke waarden via de publieke API:

De request body heeft een extra property hoofdactiviteitenVerenigingsloket. Hiermee kan je 0..21 waarden mee geven. Voorbeeld:

Na correcte verwerking worden de hoofdactiviteiten Verenigingsloket ook zichtbaar in

• beheer detail

• publiek detail

• publieke zoek (zowel in de gegevens van de vereniging als in de facets)

Voorbeeld beheer detail, (publiek detail heeft eenzelfde structuur voor deze property)

voorbeeld Publieke zoek

Feb 3, 2023 Vertegenwoordigers en hun contactgegevens

Bij het registreren van een nieuwe vereniging kan je nu 0..n vertegenwoordigers mee opgeven en voor elke vertegenwoordiger 0..n contactgegevens.

De request body heeft een extra property vertegenwoordigers, voorbeeld:

Na correcte verwerking worden de vertegenwoordigers ook zichtbaar in beheer detail , aangevuld met (dummy) achternaam en voornaam. De publieke zoek en publiek detail bevatten deze gegevens niet.

Voorbeeld: