1 De beschikbare API’s
- 1.1 Publieke API [voor iedereen]
  - 1.1.1 Mogelijkheden
  - 1.1.2 Toegang
- 1.2 Beheer API [voor instanties die toegang hebben tot alle gegevens en gegevens mogen bewerken]
2 Gebruik van de Publieke API
- 2.1 vCode: formaat
- 2.2 Zoek opdrachten
- 2.3 Codelijsten
- 2.4 Mutatiedienst
- 2.5 Formaat van het antwoord
  - 2.5.1 Gebruik van de VR-Api-Version header

De beschikbare API’s

Het verenigingsregister kent 2 API’s voor externe afnemers:

De publieke API - Deze API biedt een subset van de verenigingsdata aan, enkel de gegevens die publiek mogen gemaakt worden. Met deze API kan je enkel data lezen, je kan hier niets mee aanpassen.
De Beheer API - Met deze API kan je alle gegevens ophalen uit het verenigingsregister, ook de beschermde. Deze API biedt zowel lees- als schrijf- mogelijkheden aan. Deze API wordt naar buiten gebracht als een MAGDA dienst.

Publieke API [voor iedereen]

Staging omgeving
- URL: https://publiek.verenigingen.staging-vlaanderen.be/v1/verenigingen
- Documentatie: https://publiek.verenigingen.staging-vlaanderen.be/docs/api-documentation.html l
Productie omgeving
- URL: https://publiek.verenigingen.vlaanderen.be/v1/verenigingen
- API Documentatie: https://publiek.verenigingen.vlaanderen.be/docs/api-documentation.html

Mogelijkheden

Zoeken naar een vereniging op basis van naam, postcode, gemeente..
De publiek beschikbare detailgegevens van een vereniging opvragen
Opvragen van de mogelijke waarden van codelijsten
Mutatiedienst voor het ondersteunen van lokale data synchronisatie

De publieke API bevat een selectie van de verenigingsgegevens uit het register. Je krijgt volgende gegevens/verenigingen niet te zien:

vertegenwoordigersgegevens (persoonsdata)
verenigingen die gestopt zijn
feitelijke verenigingen die zich “uitgeschreven” hebben uit de publieke datastroom

Toegang

Publiek beschikbaar maar een API Key is wel vereist voor publiek zoeken en publiek detail. Het ophalen van de mogelijke waarden en de API documentatie zijn vrij beschikbaar.

De API Key kan je aanvragen in onze CRM Toepassing. De API Key kan je gebruiken als request header vr-api-key of als parameter in de URL

Als request header

curl
  --request GET 
  --url 'https://publiek.verenigingen.test-vlaanderen.be/v1/verenigingen/V0001001' 
  --header 'vr-api-key: api-key'

Als Path parameter

GET <Publiek URL>/v1/verenigingen/<vCode>?vr-api-key=<apikey>

Beheer API [voor instanties die toegang hebben tot alle gegevens en gegevens mogen bewerken]

De beheer API is beschikbaar via MAGDA. Gebruik onderstaande linken voor de MAGDA documentatie en voor het interesseformulier om aan te sluiten op het Verenigingsloket (met als bouwsteen het Verenigingsregister):

Mogelijkheden:

Registreren van een nieuwe vereniging
Wijzigen van de gegevens van een vereniging
Zoeken naar een vereniging op basis van naam, postcode, gemeente
Alle gegevens van een vereniging opvragen
Historiek opvragen van een vereniging

Gebruik van de Publieke API

vCode: formaat

De unieke identificatie van een vereniging is de vCode. Dit is een code die begint met de letter V (van Vereniging) gevolgd door 7 cijfers. Die cijfers hebben geen betekenis en worden gewoon sequentieel toegekend, startend vanaf 1001. Voorbeeld: V0001042.

Zoek opdrachten

De publieke API bevat een ZOEK functionaliteit. Deze zoek functionaliteit is een elastic search implementatie. De zoekcriteria kan je dus samenstellen zoals je bij elastic search zou doen. (zie algemene syntax) Hierbij enkele voorbeelden:

Query	Wat is het resultaat?

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 `doelgroep.leeftijd` die kleiner of gelijk is aan 16.
q=naam:vereniging AND locaties.postcode:9000	Je kan 2 criteria combineren met `AND`, `OR` en ook met haakjes `()`
q=locaties.postcode:(1234 OR 5678)	Je kan filteren op verschillende mogelijke waarden door deze tussen haakjes te plaatsen en te scheiden door `OR`

Codelijsten

Om deze functionaliteit te gebruiken, heb je geen API Key nodig.

Codelijsten = lijsten met mogelijke waarden voor een bepaald veld, kunnen opgevraagd worden via de publieke API. 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
Werkingsgebieden, code = werkingsgebieden

Mutatiedienst

Als afnemer van de data van het verenigingsregister, kan je er voor kiezen om de data steeds rechtstreeks en real-time op te vragen. In sommige omstandigheden kan het echter beter uitkomen om de data ook lokaal te synchroniseren, naar een eigen CRM of databank bijvoorbeeld. Om de regelmatige synchronisatie van data te ondersteunen is er deze mutatiedienst. Deze geeft je immers aan welke verenigingen (vCodes) gewijzigd zijn sinds de laatste keer dat je de synchronisatie hebt uitgevoerd.

Om deze mutatiedienst te begrijpen, is het belangrijk om te weten dat elke wijziging in VR gebeurt op basis van gebeurtenissen (events). Elk event krijgt een uniek, oplopend nummer, genaamd sequence. Wanneer je lokaal synchroniseert, dan heb je alle wijzigingen mee tot een bepaalde sequence. Die moet je dan onthouden. Met de mutatiedienst kan je alle vCodes opvragen die gewijzigd zijn sinds die laatste sequence.

Voorbeeld:

Bij opstart neem je alle gegevens over en zoek je naar de hoogste sequence sinds dat moment. Dat kan je doen door deze API call:

GET <publiekURL>/v1/verenigingen/mutaties/sinds=0

Deze call geeft je ALLE verenigingen weer samen met hun hoogste sequence. Voorbeeld:

[
    {
        "vCode": "V0015811",
        "sequence": 34873
    },
    {
        "vCode": "V0015815",
        "sequence": 34875
    },
    {
        "vCode": "V0003012",
        "sequence": 34881
    }
]

Deze lijst is oplopend gesorteerd op sequence. De hoogste sequence is de allerlaatste in de rij. Onthou deze waarde als maxSequence. In dit voorbeeld is dat dus 34881.

Bij de volgende synchronisatie vraag je alle vCodes op die gewijzigd zijn sinds je vorige synchronisatie. Hierbij gebruik je maxSequence zoals je de vorige keer hebt opgeslagen.

GET <publiekURL>/v1/verenigingen/mutaties/sinds=34881

Je krijgt nu de lijst van verenigingen waarvan de hoogste sequence strikt groter is dan 34881. Dat zijn dus de verenigingen die gewijzigd zijn sinds je laatste synchronisatie.

De mutatiedienst geeft enkel aan dat er IETS is gewijzigd aan die vCode, niet wat er juist is gewijzigd. Om dat te weten te komen, kan je 2 dingen doen:

de detail gegevens van de vereniging opvragen en vergelijken met de gegevens die je lokaal hebt gesynchroniseerd - opgelet: het kan zijn dat er gegevens zijn gewijzigd die je niet lokaal synchroniseert.
de historiek opvragen van de vereniging (enkel via MAGDA API op te vragen) - daar krijg je de lijst van alle wijzigingen, inclusief wie de wijziging geïnitieerd heeft en wanneer die uitgevoerd is.

tip voor ontwikkelaars: de lijst van gewijzigde vCodes is oplopend gesorteerd per sequence. Dat geeft de mogelijkheid om de wijzigingen in stukken te doen (een voor een of per 10 bijvoorbeeld). Als je bij elk gedeelte de sequence onthoudt, dan kan dit proces (na een eventuele crash) herstart worden zonder dat je wijzigingen nogmaals moet verwerken.

Formaat van het antwoord

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.

Gebruik van de VR-Api-Version header

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

Hiertoe voorzien we een extra request header (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

GET /verenigingen/<vCode>
{
  ...
  "vCode": "V0001234",
  "verenigingstype": {
    "code": "FV",
    "naam": "Feitelijke vereniging"
  }
}

=> MET extra header (voorbeeld van response structuur)

GET /verenigingen/<vCode>
Header: "VR-Api-Version": "v2"
{
  ...
  "vCode": "V0001234",
  "verenigingstype": {
    "code": "VZER",
    "naam": "Vereniging zonder (eigen) rechtspersoonlijkheid",
  },
  "verenigingssubtype": {
    "code": "FV",
    "naam": "Feitelijke vereniging"
  }
}

Deze transformatie zal van toepassing zijn bij:

de detail functie
- Het type van de vereniging wordt weergegeven als FV of VZER afhankelijk van de request header
de zoek functie
- 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

Type	Gebruik header?	Type in het antwoord	Subtype

Type	Gebruik header?	Type in het antwoord	Subtype
VZER	Zonder header	FV	afwezig
	Met header	VZER	aanwezig
VZW(*)	Zonder header	VZW	afwezig
	Met header	VZW	afwezig

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