Open API – documentatie

Introductie

De Ledenbeheer API’s zijn beschikbaar voor geregistreerde API partners en vereisen authenticatie door een partner token.
Integratie partners kunnen via deze API’s de leden van de voor hen opengestelde clubs beheren en registraties doorvoeren.

Geïnteresseerde partijen kunnen info@ledenbeheer.be contacteren om een partner token te bekomen.

API’s aanroepen

Alle API’s kunnen aangeroepen worden, en vereisen een partner authenticatie token en andere endpoint-specifieke parameters.
Een endpoint die voor alle geregistreerde partners beschikbaar gesteld wordt is test_connection, waar enkel de partner authenticatie token vereist is.
Deze endpoint geeft de permissies voor de partner token terug in 2 delen: beschikbare endpoints en beschikbare clubs.

Deze endpoint kan aangeroepen worden via https://integrations.ledenbeheer.be/test_connection?auth=PARTNER_AUTHENTICATION_TOKEN , waar de PARTNER_AUTHENTICATION_TOKEN placeholder vervangen wordt door het uitgereikte token.

Het resultaat van alle Ledenbeheer API’s wordt teruggeven in JSON formaat, zoals het voorbeeld hieronder voor de test_connection endpoint.

{
"availableEndpoints":[
"test_connection",
"create_user_account",
"edit_user_account",
"get_user_accounts",
"get_dsv_annual_periods",
"register_user_account_for_dsv_annual_period"
],
"availableClubs":[
{
"id":102,
"label":"Voorbeeldclub 1"
},
{
"id":103,
"label":"Voorbeeldclub 2"
},
{
"id":104,
"label":"Voorbeeldclub 3"
}
],
"result":true,
"process_time":0.26,
"request_size":"373"
}

Parameters zoals “address_country”, “address_postal_code”, “address_city” en “nationality” vereisen een waarde die in de lijst van mogelijke waardes voorkomt. Je kan deze lijsten verkrijgen door de get_valid_field_options API op te roepen met een geldige partner authenticatie token. Deze waarden worden gecontroleerd als “address_country” gelijk is aan “BE” of “NL”. De NL steden of postcodes kan je alsook vinden in de response van get_valid_field_options onder “cities_nl” en “postals_nl”.

API beperkingen

 

Een integratie partner kan maximum 100 requests uitvoeren per minuut, en de Ledenbeheer server zal een foutmelding weergeven als deze limiet overschreden wordt.

{
"errors”:[“ You have exceeded your maximum amount of requests per minute”]
}

De Ledenbeheer server zal alle requests van integratiepartners blokkeren als de server een hoge belasting heeft.
Dit wordt gedaan om de diensten voor Ledenbeheer klanten te waarborgen, en hun de hoogste prioriteit te geven betreffende server resources.

{
"errors”:[“ Server too busy, try again later”]
}

Gebruikersaccounts aanmaken

Gebruikersaccounts voor clubs op Ledenbeheer kunnen aangemaakt worden met het create_user_account endpoint.
Deze endpoint laat een partner toe om hoofd-accounts end kind-accounts aan te maken, en zal ook basisvalidatie uitvoeren om het aanmaken van gedupliceerde accounts te verhinderen. Alle gebruikeraccounts die aangemaakt worden met deze API worden automatisch aanzien als actieve leden, zelfs als er geen bestellingen of registraties gemaakt worden voor deze gebruiker.

 

Om aan de privacywetgeving te voldoen moet voor alle leden onder 18 jaar een kind-account aangemaakt worden onder de voogd-account voor deze gebruiker (meestal een account van een ouder van het lid).
Functionaliteiten zoals beurtenkaarten worden per hoofd-account beheerd, het is dus belangrijk dat deze accounts correct aangemaakt worden.

Parameters

Onderstaande parameters worden geaccepteerd voor deze API.

 

 

 

Parameter Datatype Vereist Voorbeeld Beschrijving
auth String Ja 123_a402d3f… Partner authenticatie token.
club Integer Ja 102 Club ID, zoals terugegeven in de test_connection endpoint.
fname String Ja Jan De voornaam van de gebruiker.
lname String Ja Jansens De familienaam van de gebruiker.
email String Ja jan@gmail.com Het e-mail adres van de gebruiker.
phone String Ja 012 345 6789 Het telefoonnummer van de gebruiker. Niet-numerieke karakters worden automatisch verwijderd.
parent_uid Integer Nee 123 Optioneel ID van de hoofd-account voor deze gebruiker.

Indien deze parameter meegegeven wordt zal Ledenbeheer een nieuwe kind-gebruiker aanmaken voor deze hoofd-account. De e-mail adressen moeten matchen.

birthdate String Ja 1987-08-29 De geboortedatum van deze gebruiker, in YYYY-MM-DD formaat.
nationality String Ja (indien DSV) Belgisch De nationaliteit van de gebruiker.
sex String Ja male Het geslacht van de gebruiker, ‘male’, ‘female’ of ‘x’.
address_street String Ja (indien DSV) Veldstraat Het straat-gedeelte van het adres van de gebruiker.
address_street_number String Ja (indien DSV) 3 Het nummer-gedeelte van het adres van de gebruiker.
address_unit String Nee 1b Het bus-gedeelte van het adres van de gebruiker, indien dit van toepassing is.
address_postal_code String Ja (indien DSV) 7550 Het postbus-gedeelte van het adres van de gebruiker.
address_city String Ja (indien DSV) Brussel Het stad-gedeelte van het adres van de gebruiker.
address_country String Ja (indien DSV) BE Het land-gedeelte van het adres van de gebruiker, in de internationale 2-karakter standaard.
register_for_dsv_annual_period String Nee De Danssport Vlaanderen lidmaatschapsperiode waarop dit lid geregistreerd moet worden. Dit moet één van de waardes zijn die verkregen kan worden via het get_dsv_annual_periods endpoint, of the String “current” om het lid in de huidige periode in te schrijven.
federation_dsv_membership_no String Nee Het Danssport Vlaanderen lidnummer van deze persoon.
federation_dsv_designations String Nee Eén of meerdere clubstatuten waarmee een clublid geregistreerd kan worden bij Danssport Vlaanderen. De lijst van geaccepteerde clubstatuten is beschikbaar via het get_valid_field_options endpoint.

Al deze parameters zijn ook geldig bij de API om een lid te bewerken

Resultaat

De Ledenbeheer API zal een JSON resultaat afleveren, waar de “result” key ofwel false ofwel het nieuwe ID van de gebruiker zal bevatten.
Indien de “result” key false is zal een foutmelding worden teruggegeven in de “errors” key.

{
"result”:5468458
}

 

{
“result”: false,
"errors”:[“ Invalid email address.”]
}

Voorbeeld URL

https://integrations.ledenbeheer.be/create_user_account?auth=PARTNER_AUTHENTICATION_TOKEN&club=102&fname=Jan&lname=Jansens&email=jan@gmail.com&parent_uid=123&birthdate=1987-08-29&sex=male&phone=0123456789&nationality=Belg&address_street=Veldstraat&address_number=3&address_unit=1b&address_postal_code=7550&address_city=Brussel&address_country=BE

Gebruikersaccounts wijzigen

 

Bestaande gebruikersaccounts voor clubs op Ledenbeheer kunnen gewijzigd worden met het edit_user_account endpoint.
Om aan de privacywetgeving te voldoen moet voor alle leden onder 18 jaar een kind-account aangemaakt worden onder de voogd-account voor deze gebruiker (meestal een account van een ouder van het lid).
Functionaliteiten zoals beurtenkaarten worden per hoofd-account beheerd, het is dus belangrijk dat deze accounts correct aangemaakt worden.

Parameters

Onderstaande parameters worden geaccepteerd voor deze API.

 

Parameter Datatype Vereist Voorbeeld Beschrijving
auth String Ja 123_a402d3f… Partner authenticatie token.
club Integer Ja 102 Club ID, zoals terugegeven in de test_connection endpoint.
uid Integer Ja 13218846 Het ID van de gebruiker die bewerkt wordt.
fname String Nee Jan De voornaam van de gebruiker.
lname String Nee Jansens De familienaam van de gebruiker.
email String Nee jan@gmail.com Het e-mail adres van de gebruiker.
phone String Nee 012 345 6789 Het telefoonnummer van de gebruiker. Niet-numerieke karakters worden automatisch verwijderd.
birthdate String Nee 1987-08-29 De geboortedatum van deze gebruiker, in YYYY-MM-DD formaat.
nationality String Nee Belgisch De nationaliteit van de gebruiker. Indien DSV lid wordt er gecontroleerd of deze persoon reeds een nationaliteit heeft
sex String Nee male Het geslacht van de gebruiker, ‘male’, ‘female’ of ‘x’.
address_street String Nee Veldstraat Het straat-gedeelte van het adres van de gebruiker. Indien DSV lid wordt er gecontroleerd of deze persoon reeds een adres heeft
address_street_number String Nee 3 Het nummer-gedeelte van het adres van de gebruiker. Indien DSV lid wordt er gecontroleerd of deze persoon reeds een adres heeft
address_unit String Nee 1b Het bus-gedeelte van het adres van de gebruiker, indien dit van toepassing is. Indien DSV lid wordt er gecontroleerd of deze persoon reeds een adres heeft
address_postal_code String Nee 7550 Het postbus-gedeelte van het adres van de gebruiker. Indien DSV lid wordt er gecontroleerd of deze persoon reeds een adres heeft
address_city String Nee Brussel Het stad-gedeelte van het adres van de gebruiker. Indien DSV lid wordt er gecontroleerd of deze persoon reeds een adres heeft
address_country String Nee BE Het land-gedeelte van het adres van de gebruiker, in de internationale 2-karakter standaard. Indien DSV lid wordt er gecontroleerd of deze persoon reeds een adres heeft

Resultaat

De Ledenbeheer API zal een JSON resultaat afleveren, waar de “result” key ofwel false ofwel het ID van de gebruiker zal bevatten.

Indien de “result” key false is zal een foutmelding worden teruggegeven in de “errors” key.

{
"result”:5468458
}


{
“result”: false,
"errors”:[“ Invalid phone number.”]
}

Voorbeeld URL

https://integrations.ledenbeheer.be/edit_user_account?auth=PARTNER_AUTHENTICATION_TOKEN&club=102&uid=1351384132&phone=0123456789&nationality=Belg

 

Lijst van gebruikersaccounts voor een club oproepen

De lijst van bestaande gebruikersaccounts voor clubs op Ledenbeheer kan opgeroepen worden met het get_user_accounts endpoint.

Parameters

Onderstaande parameters worden geaccepteerd voor deze API.

 

Parameter Datatype Vereist Voorbeeld Beschrijving
auth String Ja 123_a402d3f… Partner authenticatie token.
club Integer Ja 102 Club ID, zoals terugegeven in de test_connection endpoint.

Resultaat

De Ledenbeheer API zal een JSON resultaat afleveren, waar de “result” key ofwel false ofwel de lijst van gebruikers zal bevatten.
federation_dsv_membership_no wordt enkel meegegeven indien je daarvoor rechten hebt, heb je dit recht nodig dan contacteer je ons om dit in te stellen.

Indien de “result” key false is zal een foutmelding worden teruggegeven in de “errors” key.

{
"result": {
"111855": {
"uid": "111855",
"fname": "John",
"lname": "Smith",
"email": "john.smith@gmail.com",
"parent_uid": 0,
"birthdate": "1997-08-21",
"birthdate_unix": "557107200",
"phone": "0123456789",
"sex": "Man",
"address": {
"street": "Duet",
"streetNumber": "33",
"postal": "7430",
"city": "Gent",
"country": "BE",
"federation_dsv_membership_no": "123456"
}
},
"458436": {
"uid": "458436",
"fname": "Anna",
"lname": "Woods",
"email": "anna.woods@gmail.com",
"parent_uid": 111855,
"birthdate": "1960-12-11",
"birthdate_unix": "-285728400",
"phone": "0476337442",
"sex": "Vrouw",
"address": {
"street": "Duet",
"streetNumber": "33",
"postal": "7430",
"city": "Gent",
"country": "BE",
"federation_dsv_membership_no": "234567"
}
}
},
"process_time": 0.255,
"request_size": "1526"
}


{
“result”: false,
"errors”:[“You don't have permission to access this club.”]
}

Voorbeeld URL

https://integrations.ledenbeheer.be/get_user_accounts?auth=PARTNER_AUTHENTICATION_TOKEN&club=102

Enkele gebruiker oproepen voor een specifieke club

Zelfde response data als van een lijst van gebruikers, maar nu voor een enkele gebruiker, deze kan opgeroepen worden via get_user_account endpoint.

Parameters

Onderstaande parameters worden geaccepteerd voor deze API.

Parameter Datatype Vereist Voorbeeld Beschrijving
auth String Ja 123_a402d3f… Partner authenticatie token.
club Integer Ja 102 Club ID, zoals terugegeven in de test_connection endpoint.
uid Integer Ja 111855 User ID, zoals terugegeven in de get_user_accounts/create_user_account endpoint.

Resultaat

De Ledenbeheer API zal een JSON resultaat afleveren, waar de “result” key ofwel false ofwel de details van de gebruiker zal bevatten.
federation_dsv_membership_no wordt enkel meegegeven indien je daarvoor rechten hebt, heb je dit recht nodig dan contacteer je ons om dit in te stellen.

Indien de “result” key false is zal een foutmelding worden teruggegeven in de “errors” key.

{
"result": {
"uid": "111855",
"fname": "John",
"lname": "Smith",
"email": "john.smith@gmail.com",
"parent_uid": 0,
"birthdate": "1997-08-21",
"birthdate_unix": "557107200",
"phone": "0123456789",
"sex": "Man",
"address": {
"street": "Duet",
"streetNumber": "33",
"postal": "7430",
"city": "Gent",
"country": "BE"
},
"dsv_membership_no": "123456"
},
"process_time": 0.255,
"request_size": "1526"
}


{
“result”: false,
"errors”:[“You don't have permission to access this club.”]
}

Voorbeeld URL

https://integrations.ledenbeheer.be/get_user_account?auth=PARTNER_AUTHENTICATION_TOKEN&club=102&uid=111855

Lijst van actieve leden voor een club oproepen

De lijst van actieve leden voor clubs op Ledenbeheer kan opgeroepen worden met het get_active_club_members endpoint.

Parameters

Onderstaande parameters worden geaccepteerd voor deze API.

club Integer Ja 123_a402d3f… Club ID
IncludeDetails Integer Nee 123_a402d3f… Geef ‘1’ als parameter als je basisinformatie per lid wil ophalen. Standaard wordt enkel een lijst van actieve leden en hun gebruikerID’s weergegeven.

 

Inschrijvingen ophalen via de API

Parameters

  • club, verplicht, het club ID
  • startDate en endDate, optioneel, als je enkel cursussen in een bepaalde periode wil ophalen.
  • includeCancelled, optioneel, standaard 0. Geef waarde van 1 terug als je geannuleerde inschrijvingen ook wil ophalen.

Output

  1. result: dit object lijst alle cursussen en activiteiten op in de opgevraagde tijdsperiode.
    Elk cursus-object bevat de eigenschappen van een cursus, en alle sessies, tarieven, extra diensten, kortingen en inschrijvingen
  2. ordersPerUser: dit object bevat een lijst van alle gebruikers die inschrijvingen hebben op de cursussen in de opgegeven periode, en geeft je details over de kostennota’s die aangemaakt werden voor deze inschrijvingen. Kortingen en extra diensten worden hier ook weergegeven als die deel waren van de kostennota.

Federatie Danssport Vlaanderen: lijst van jaarlijkse lidmaatschapsperiodes oproepen

De lijst van geregistreerde jaarlijkse lidmaatschapsperiodes voor de Danssport Vlaanderen federatie kan opgeroepen worden met het get_dsv_annual_periodsendpoint.

Parameters

Onderstaande parameters worden geaccepteerd voor deze API.

 

Parameter Datatype Vereist Voorbeeld Beschrijving
auth String Ja 123_a402d3f… Partner authenticatie token.

 

Resultaat

De Ledenbeheer API zal een JSON resultaat afleveren, waar de “result” key ofwel false ofwel de lijst van jaarlijkse periodes zal bevatten, in key-value koppels.

Indien de “result” key false is zal een foutmelding worden teruggegeven in de “errors” key.

Elk Ledenbeheer endpoint voor Danssport Vlaanderen die een jaarlijkse lidmaatschapsperiode vereist moet de engelstalige key voor deze periode ontvangen als parameter.

De “currentPeriods” key bevat the lijst van periodes die door Danssport Vlaanderen als huidige lidmaatschapsperiodes gezien worden.

Alle gebruikers die geregistreerd worden voor deze periodes zullen dus actieve leden van Danssport Vlaanderen zijn.

 

{
"result": {
"1 September 2019 - 31 August 2020": "1 september 2019 - 31 augustus 2020",
"1 September 2020 - 31 August 2021": "1 september 2020 - 31 augustus 2021",
"1 September 2021 - 31 August 2022": "1 september 2021 - 31 augustus 2022",
"1 September 2022 - 31 August 2023": "1 september 2022 - 31 augustus 2023",
"1 September 2023 - 31 August 2024": "1 september 2023 - 31 augustus 2024"
},
"currentPeriods": [
"1 September 2020 - 31 August 2021",
"1 September 2021 - 31 August 2022",
"1 September 2022 - 31 August 2023",
"1 September 2023 - 31 August 2024"
],
"process_time": 0.248,
"request_size": "598"
}

 


{
“result”: false,
"errors”:[“You don't have permission to access this club.”]
}

Voorbeeld URL

https://integrations.ledenbeheer.be/get_dsv_annual_periods?auth=PARTNER_AUTHENTICATION_TOKEN

Federatie Danssport Vlaanderen: registreer een gebruiker als lid van Danssport Vlaanderen

Een bestaande gebruiker kan als lid van Danssport Vlaanderen geregistreerd worden met het register_user_account_for_dsv_annual_period endpoint.
Indien een gebruiker reeds geregistreerd is voor de periode zal het aanroepen van deze endpoint geen verdere wijzigingen doorvoeren.

Parameters

Onderstaande parameters worden geaccepteerd voor deze API.

 

Parameter Datatype Vereist Voorbeeld Beschrijving
auth String Ja 123_a402d3f… Partner authenticatie token.
club Integer Ja 102 Club ID, zoals terugegeven in de test_connection endpoint.
uid Integer Ja 13218846 Het ID van de gebruiker die geregistreerd wordt.
period String Ja 1 September 2021 – 31 August 2022 De engelstalige key voor de Danssport Vlaanderen lidmaatschapsperiode, zoals die teruggegeven wordt door het get_dsv_annual_periods endpoint.

Resultaat

De Ledenbeheer API zal een JSON resultaat afleveren, waar de “result” key true of false zal bevatten.

Indien de “result” key false is zal een foutmelding worden teruggegeven in de “errors” key.

{
"result": true,
"process_time": 0.248,
"request_size": "598"
}


{
“result”: false,
"errors”:[“Invalid annual period key.”]
}

Voorbeeld URL

https://integrations.ledenbeheer.be/register_user_account_for_dsv_annual_period?auth=PARTNER_AUTHENTICATION_TOKEN&club=102&uid=13218846&period=1%20September%202120%20-%2031%20August%202022

Nuttig artikel?