Context

Doel: Een persoon wil zich aanmelden op een website in naam van een vereniging.

Open

1. Vertegenwoordiger gaat naar website en vraagt om zich aan te melden

2. Website verwijst door naar ACM/IDM, met doelgroep verenigingen. Daar wordt vertegenwoordiger gevraagd om zich te identificeren als persoon (bvb met itsme)

3. ACM/IDM vraagt aan bron de gegevens van alle verenigingen waarvoor deze persoon vertegenwoordiger is

4. Nadat de vertegenwoordiger de juiste vereniging gekozen heeft, keert ACM/IDM terug naar de website met het verenigingsnummer (en persoons ID)

5. De website kan nu via publieke of beveiligde API extra data opvragen over deze vereniging

Realisatie in VR

Om stap 3 te realiseren, is er een API geïmplementeerd (zie tekening “Link Persoon/Vereniging”) met volgende kenmerken:

• Beveiligde API, enkel bereikbaar door ACM

• Input = INSZ (identificatienummer sociale zekerheid = rijksregisternummer of bis nummer)

• Output = lijst van verenigingen (kan leeg zijn) die horen bij dit INSZ

Beschrijving

API documentatie: https://acm.verenigingen.vlaanderen.be/docs/api-documentation.html

Korte beschrijving van de mogelijkheden

Deze API bestaat in 2 varianten, de GET en de POST variant.

Met beide varianten kan je de lijst opvragen van verenigingen die horen bij een INSZ.

Met de POST variant kan je ook nog een lijst met KBO nummers doorgeven en zo opvragen of deze reeds gekend zijn in VR, en indien niet, of deze kunnen geregistreerd worden (wordt de rechtsvorm ondersteund?).

• GET variant: GET <acmURL>/v1/verenigingen/<insz>

• POST variant: POST <acmURL>/v1/verenigingenmet in request body:

  • insz

  • kboNummers: een lijst van items met elk de velden kboNummer en rechtsvorm

Validaties

Beide varianten:

• Deze API is beveiligd via oAuth met scope dv_verenigingsregister_hoofdvertegenwoordigers (voorbehouden voor ACM)

• insz moet aanwezig zijn, wel geen enkele controle op het formaat van dit veld

POST Variant:

• lijst kboNummers MAG aanwezig zijn, indien afwezig wordt een lege lijst verondersteld.

• lijst kboNummers MAG leeg zijn → []

• Voor elk element in lijst kboNummers:

  • kboNummer moet ingevuld zijn

  • rechtsvorm moet ingevuld zijn

Antwoord: verenigingen van een INSZ

We zoeken naar alle verenigingen waar dit INSZ voorkomt als identificatie van een van de vertegenwoordigers. Elke vereniging in deze lijst moet voldoen aan deze voorwaarden:

• type van de vereniging

  • Als de optionele parameter includeKboVerenigingen = true dan worden ook KBO verenigingen terug gegeven in het antwoord

  • Als deze gelijk is aan false of niet opgegeven wordt, dan worden de KBO verenigingen niet weergegeven in het antwoord

• status van de vereniging = Actief of Gestopt (dus niet Dubbel en ook niet Verwijderd)

Voor elke vereniging tonen we de volgende velden

Antwoord: kboNummer lijst

Dit is enkel in de POST variant van toepassing.Voor elk item in de lijst van kboNummers uit de input wordt een item in de lijst van kboNummers in de output weergegeven. We onderscheiden daarbij verschillende situaties:

• 1 - de rechtsvorm wordt niet ondersteund door VR

• 2 - rechtsvorm wordt ondersteund en het kboNummer is reeds gekend in VR

• 3 - rechtsvorm wordt ondersteund en het kboNummer is niet gekend in VR

De ondersteunde rechtsvormen zijn gecodeerd volgens het coderingssysteem in KBO:

Voor elk kboNummer in de output tonen we volgende velden, afhankelijk van de situatie