Introductie
De Ledenbeheer API's zijn toegankelijk voor geregistreerde API-partners en vereisen authenticatie via een partner-token. Integratiepartners kunnen met behulp van deze API's de leden beheren en inschrijvingen verwerken voor de clubs waarmee ze zijn verbonden.
Voor geïnteresseerde partijen is het mogelijk om een partner-token aan te vragen bij info@ledenbeheer.be.
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. |
| 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/Array | Ja (indien DSV) | 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
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. |
| 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 |
| federation_dsv_designations | String/Array | Ja (indien DSV en niet ingevuld) | 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. |
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
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
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
- 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 - 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