Hoe kan ik gegevens in mijn lokale toepassing in sync houden met de data uit VR

In de publieke API is een 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 geen API Key nodig.

API documentatie: https://publiek.verenigingen.vlaanderen.be/docs/api-documentation.html#tag/Mutatiedienst

Voorbeeld:

GET <publiekURL>/v1/verenigingen/mutaties?sinds=<vorigeMaxSequence>
response body:
[
    {
        "vCode": "V0001027",
        "sequence": 86
    },
    {
        "vCode": "V0001024",
        "sequence": 89
    }
]

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

GET <publiekURL>/v1/verenigingen/mutaties?sinds=89

Goed om weten: Dit endpoint wordt via de publieke API ter beschikking gesteld, maar toch krijg je hier informatie van ALLE vCodes en van ALLE wijzigingen. Deze info is zelfs publiek en anoniem beschikbaar, wat geen kwaad kan, want veel info kan je daaruit niet afleiden. Je ziet alleen maar dat er een vCode bestaat EN dat er een wijziging mee gebeurd is. Je kan hiermee niet zien welke data er beschikbaar is, of welke wijziging er gebeurd is.

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 wanneer je de data van deze vereniging opvraagt 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.

Samengevat: Je ziet wel dat een vereniging gewijzigd is, maar afhankelijk van het type wijziging kunnen deze situaties zich voordoen bij het opvragen van de detaildata van de vereniging in kwestie:

vereniging niet meer terug te vinden
geen wijziging te vinden in de data