Open API Ledenbeheer

Toegang tot de Open API van Ledenbeheer is beschikbaar vanaf de Pro-licentie.

1. Introductie

De Ledenbeheer API maakt het mogelijk om externe toepassingen te koppelen met Ledenbeheer. Integratiepartners kunnen onder andere:

• clubs ophalen waartoe ze toegang hebben;

• gebruikersaccounts ophalen;

• gebruikersaccounts aanmaken en wijzigen;

• actieve leden ophalen;

• cursussen en activiteiten ophalen;

• inschrijvingen verwerken;

• cursusverantwoordelijken ophalen;

• bestel- en betalingsgegevens gekoppeld aan inschrijvingen uitlezen.

De API is toegankelijk voor geregistreerde API-partners en vereist een partner-token.

Een partner-token kan worden aangevraagd via info@ledenbeheer.be.

De Open API wordt verder uitgebreid. Heb je nood aan bijkomende endpoints of gegevens, neem dan contact met ons op.

2. Basis-URL

Alle endpoints bevinden zich onder:

https://integrations.ledenbeheer.be/

Bijvoorbeeld:

https://integrations.ledenbeheer.be/test_connection

3. Authenticatie

Elke API-aanvraag moet worden uitgevoerd met een geldige partner authentication token.

Afhankelijk van het endpoint wordt het token momenteel op één van onderstaande manieren meegestuurd.

3.1 Token als parameter

De bestaande endpoints voor onder andere gebruikersaccounts gebruiken de parameter:

auth=PARTNER_AUTHENTICATION_TOKEN

Voorbeeld:

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

3.2 Bearer-token

Het endpoint get_course_registrations ondersteunt authenticatie via de HTTP-header:

Authorization: Bearer PARTNER_AUTHENTICATION_TOKEN

Bewaar het partner-token steeds op een beveiligde serveromgeving.

Plaats het token nooit rechtstreeks in publiek beschikbare JavaScript-code in een browser.

4. Verbinding en toegangsrechten controleren

Voordat je andere endpoints gebruikt, raden we aan eerst test_connection aan te roepen.

Endpoint

GET /test_connection

Parameters

Voorbeeld

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

Resultaat

Het endpoint geeft onder andere terug:

• welke endpoints voor het token beschikbaar zijn;

• tot welke clubs het token toegang heeft.

Voorbeeld:

{ "availableEndpoints": [ "test_connection", "create_user_account", "edit_user_account", "get_user_accounts" ], "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" }

Gebruik de id uit availableClubs als club-parameter in de overige endpoints.

5. Geldige veldwaarden ophalen

Voor bepaalde velden accepteert Ledenbeheer alleen vooraf bepaalde waarden.

Dit geldt bijvoorbeeld voor:

• address_country

• address_postal_code

• address_city

• nationality

Gebruik hiervoor het endpoint:

get_valid_field_options

De waarden voor Belgische en Nederlandse adressen worden gevalideerd wanneer address_country gelijk is aan BE of NL.

Voor Nederlandse adressen bevat het antwoord onder andere:

• cities_nl

• postals_nl

Gebruik steeds de waarden die via dit endpoint worden teruggegeven.

6. Algemene response

De Ledenbeheer API geeft antwoorden terug in JSON-formaat.

Bij een geslaagde aanvraag bevat result het resultaat van de operatie.

Bij een fout:

{ "result": false, "errors": [ "Beschrijving van de fout" ] }

Controleer bij iedere aanvraag:

1. de HTTP-statuscode;

2. de waarde van result;

3. de inhoud van errors.

7. API-beperkingen

7.1 Rate limit

Een integratiepartner kan maximaal 100 requests per minuut uitvoeren.

Wanneer deze limiet wordt overschreden, kan bijvoorbeeld volgend antwoord worden teruggegeven:

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

7.2 Hoge serverbelasting

Ledenbeheer kan API-aanvragen van integratiepartners tijdelijk beperken wanneer de serverbelasting te hoog is.

De diensten voor clubs die rechtstreeks met Ledenbeheer werken, krijgen hierbij voorrang.

Voorbeeld:

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

Bij een tijdelijke fout, bijvoorbeeld HTTP 503, mag de aanvraag later opnieuw worden geprobeerd.

Gebruik hiervoor bij voorkeur een oplopende wachttijd, bijvoorbeeld:

2 → 5 → 10 → 30 seconden

8. Gebruikersaccounts

8.1 Alle gebruikers van een club ophalen

Gebruik get_user_accounts om alle gebruikersaccounts van een club op te halen.

Endpoint

GET /get_user_accounts

Parameters

Voorbeeld

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

Resultaat

{ "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" } }, "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" } } }, "process_time": 0.255, "request_size": "1526" }

Foutvoorbeeld

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

8.2 Eén gebruiker ophalen

Gebruik get_user_account wanneer je de gegevens van één specifieke gebruiker nodig hebt.

Endpoint

GET /get_user_account

Parameters

Het uid kan onder andere worden verkregen via:

• get_user_accounts

• create_user_account

Voorbeeld

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

Resultaat

{ "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" } }, "process_time": 0.255, "request_size": "1526" }

9. Gebruikersaccount aanmaken

Gebruik create_user_account om een nieuwe gebruiker voor een club aan te maken.

Endpoint

GET /create_user_account

Het endpoint kan zowel:

• hoofdaccounts;

• kindaccounts

aanmaken.

Ledenbeheer voert basisvalidatie uit om dubbele accounts zoveel mogelijk te vermijden.

Een gebruiker die via deze API wordt aangemaakt, wordt automatisch als actief lid beschouwd, ook wanneer er nog geen bestelling of inschrijving voor deze gebruiker bestaat.

Hoofd- en kindaccounts

Voor minderjarige leden kan een kindaccount worden gekoppeld aan het account van een voogd, doorgaans een ouder.

Functionaliteiten zoals beurtenkaarten worden per hoofdaccount beheerd. Het is daarom belangrijk dat ouder- en kindaccounts correct worden gekoppeld.

Parameters

parent_uid

Wanneer parent_uid wordt meegestuurd, maakt Ledenbeheer een kindaccount aan onder het opgegeven hoofdaccount.

De e-mailadressen moeten overeenkomen.

Resultaat

Bij succes bevat result het nieuwe gebruikers-ID:

{ "result": 5468458 }

Bij een fout:

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

Voorbeeld

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

10. Gebruikersaccount wijzigen

Gebruik edit_user_account om een bestaand gebruikersaccount te wijzigen.

Endpoint

GET /edit_user_account

Dezelfde principes rond hoofd- en kindaccounts zijn van toepassing als bij create_user_account.

Parameters

Resultaat

Bij succes:

{ "result": 5468458 }

Bij een fout:

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

Voorbeeld

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

11. Actieve leden ophalen

Gebruik get_active_club_members om de actieve leden van een club op te halen.

Endpoint

GET /get_active_club_members

Parameters

Wanneer IncludeDetails niet wordt opgegeven, wordt standaard alleen een lijst van actieve leden en hun gebruikers-ID's teruggegeven.

12. Cursussen, activiteiten en inschrijvingen ophalen

Gebruik get_course_registrations om cursussen en activiteiten met hun inschrijvingen op te halen.

Dit endpoint bevat naast de cursusgegevens ook informatie over onder andere:

• sessies;

• tarieven;

• extra diensten;

• kortingen;

• inschrijvingen;

• cursusverantwoordelijken;

• gekoppelde bestellingen en betalingen.

Endpoint

GET https://integrations.ledenbeheer.be/get_course_registrations

Authenticatie

Gebruik:

Authorization: Bearer UW_TOKEN

Parameters

De datumfilter selecteert cursussen en activiteiten waarvan de periode overlapt met de opgegeven periode.

Belangrijk

Wanneer geen datums worden opgegeven, loopt de standaardperiode van:

1 januari 1970 tot vandaag.

Toekomstige cursussen worden dan niet teruggegeven.

Geef daarom bij voorkeur altijd zowel startDate als endDate mee.

13. Voorbeelden get_course_registrations

cURL

curl --get "https://integrations.ledenbeheer.be/get_course_registrations" \ -H "Authorization: Bearer UW_TOKEN" \ --data-urlencode "club=12345" \ --data-urlencode "startDate=2026-01-01" \ --data-urlencode "endDate=2026-12-31" \ --data-urlencode "includeCancelled=0"

JavaScript / Node.js

Gebruik deze code alleen op een server en niet rechtstreeks in een browser.

const token = process.env.LEDENBEHEER_TOKEN; const clubId = 12345; const url = new URL( "https://integrations.ledenbeheer.be/get_course_registrations" ); url.searchParams.set("club", clubId); url.searchParams.set("startDate", "2026-01-01"); url.searchParams.set("endDate", "2026-12-31"); url.searchParams.set("includeCancelled", "0"); const response = await fetch(url, { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" } }); const data = await response.json(); if (!response.ok || data.result === false || data.errors?.length) { throw new Error( data.errors?.join(", ") || `HTTP ${response.status}` ); } for (const course of Object.values(data.result)) { console.log( `${course.title}: ${course.registrations.length} inschrijvingen` ); }

PHP

<?php $token = getenv('LEDENBEHEER_TOKEN'); $query = http_build_query([ 'club' => 12345, 'startDate' => '2026-01-01', 'endDate' => '2026-12-31', 'includeCancelled' => 0, ]); $curl = curl_init( 'https://integrations.ledenbeheer.be/get_course_registrations?' . $query ); curl_setopt_array($curl, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $token, 'Accept: application/json', ], CURLOPT_TIMEOUT => 30, ]); $body = curl_exec($curl); $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); if ($body === false) { throw new RuntimeException(curl_error($curl)); } curl_close($curl); $data = json_decode( $body, true, 512, JSON_THROW_ON_ERROR ); if ( $status >= 400 || $data['result'] === false || !empty($data['errors']) ) { throw new RuntimeException( implode( ', ', $data['errors'] ?? ["HTTP-fout {$status}"] ) ); } foreach ($data['result'] as $course) { printf( "%s: %d inschrijvingen\n", $course['title'], count($course['registrations']) ); }

14. Structuur van get_course_registrations

Een verkort antwoord ziet er als volgt uit:

{ "result": { "70001": { "nid": 70001, "title": "Zwemlessen beginners", "type": "course", "status": 1, "startDate": "2026-09-01", "endDate": "2026-12-15", "location": "Sportcentrum", "tariffs": [ { "nid": 70002, "title": "Standaardtarief", "registrationPeriod": [ "2026-06-01 09:00", "2026-08-31" ], "sessionPeriod": [ "2026-09-01", "2026-12-15" ] } ], "sessions": [ { "nid": 70003, "title": "Les 1", "date": "2026-09-01", "from": "18:00", "to": "19:00", "status": 1 } ], "registrations": [ { "uid": 456, "fname": "Jan", "lname": "Janssens", "tariff_label": "Standaardtarief", "oid": 90001 } ] } }, "ordersPerUser": { "456": { "uid": 456, "firstName": "Jan", "lastName": "Janssens", "email": "jan@example.be", "orders": { "90001": { "oid": 90001, "orderID": "BESTELLING-001", "date": "2026-06-15", "status": 1, "amountPaid": 100, "amountOutstanding": 0, "amountTotal": 100 } } } } }

Belangrijkste velden

result

Bevat alle cursussen en activiteiten die binnen de opgevraagde periode vallen.

Het object is geïndexeerd op het ID van de cursus of activiteit.

nid

Uniek ID van onder andere:

• cursus;

• activiteit;

• sessie;

• tarief.

Gebruik nid als stabiele koppelsleutel en niet de titel.

type

Geeft het type item weer, bijvoorbeeld:

• course

• activity

registrations

Bevat de basisgegevens van de inschrijvingen voor de cursus of activiteit.

uid

Uniek gebruikers-ID binnen Ledenbeheer.

Gebruik uid als stabiele koppelsleutel voor personen.

oid

Uniek ID van de bestelling die aan een inschrijving is gekoppeld.

Het oid kan worden gebruikt om de inschrijving te koppelen aan de overeenkomstige bestelling binnen ordersPerUser.

ordersPerUser

Bevat gebruikers die een inschrijving hebben binnen de geselecteerde cursussen of activiteiten.

Hierin kunnen onder andere worden opgenomen:

• contactgegevens;

• kostennota's;

• bestelgegevens;

• betaalgegevens;

• kortingen;

• extra diensten.

status

Geeft de status van bijvoorbeeld een cursus, sessie of bestelling weer.

Wanneer includeCancelled=0 wordt gebruikt, worden geannuleerde bestellingen niet opgenomen.

15. Cursusverantwoordelijken

Een cursusobject uit get_course_registrations kan ook de eigenschap:

responsibleUsers

bevatten.

Dit veld bevat de Ledenbeheer-gebruikers die als verantwoordelijke aan de cursus gekoppeld zijn.

Voorbeeld

{ "nid": "123", "title": "Ballet beginners", "responsibleUsers": { "555": "Kevin Docent", "778": "Anne Lesgever" }, "sessions": [ { "nid": "456", "date": "2026-09-07", "from": "18:00:00", "to": "19:00:00" } ] }

De sleutel van ieder item is het unieke Ledenbeheer-gebruikers-ID, oftewel uid.

De waarde is de zichtbare naam van de verantwoordelijke.

Gebruik voor koppelingen altijd het uid.

Namen:

• kunnen wijzigen;

• zijn niet noodzakelijk uniek.

Persoonsgegevens van verantwoordelijken ophalen

Om meer gegevens van een verantwoordelijke op te halen, zoals:

• voornaam;

• familienaam;

• e-mailadres;

• telefoonnummer;

kan get_user_accounts voor dezelfde club worden gebruikt.

Het uid uit responsibleUsers komt overeen met het uid uit get_user_accounts.

Voorbeeld

Cursus:

{ "responsibleUsers": { "555": "Kevin Docent" } }

Gebruikers:

{ "result": { "555": { "uid": "555", "fname": "Kevin", "lname": "Docent", "email": "kevin@example.be", "phone": "0470000000" } } }

Aandachtspunten voor responsibleUsers

• Een cursus kan nul, één of meerdere verantwoordelijken hebben.

• Een leeg of ontbrekend responsibleUsers betekent dat voor die cursus geen verantwoordelijke werd doorgegeven.

• responsibleUsers is gekoppeld aan de volledige cursus en wordt niet noodzakelijk per sessie herhaald.

• Een integratie die verantwoordelijken per lesmoment plant, kan de cursusverantwoordelijken koppelen aan de sessies binnen die cursus.

• Gebruik het uid en niet de naam als koppelsleutel.

• Bewaar naast het uid ook het cursus-ID nid, zodat dezelfde persoon aan meerdere cursussen kan worden gekoppeld.

• Synchronisaties moeten idempotent zijn. Dezelfde cursus, gebruiker of sessie mag bij een volgende synchronisatie niet dubbel worden aangemaakt.

Verwijder een eerder opgeslagen verantwoordelijke niet onmiddellijk wanneer responsibleUsers tijdelijk ontbreekt. Controleer eerst opnieuw of de koppeling daadwerkelijk uit Ledenbeheer verwijderd werd.

16. Aanwezigheden ophalen via de API

Met de aanwezigheids-API kan je deelnemerslijsten en geregistreerde aanwezigheden van cursussen en activiteiten ophalen. Je kan deze gegevens bijvoorbeeld gebruiken voor een rapport, een dashboard voor lesgevers of een koppeling met externe software.

Er zijn drie endpoints beschikbaar:

16.1 Authenticatie en toegangsrechten

Alle drie de endpoints gebruiken een HTTPS GET-aanvraag. Stuur het partner-token mee via de HTTP-header:

Authorization: Bearer UW_TOKEN

Je ontvangt alleen gegevens van clubs waartoe je integratiepartner toegang heeft. Daarnaast vereist elk endpoint een afzonderlijk recht met dezelfde naam als het endpoint. Een superadministrator stelt deze rechten in op de beheerpagina voor integraties.

Toegang tot get_attendance_bulk geeft dus niet automatisch toegang tot de twee andere aanwezigheidsendpoints. Je hoeft voor deze endpoints geen aparte club-parameter mee te sturen.

Bewaar het token op een beveiligde server. Neem het niet op in een URL, publieke browsercode of logbestand.

16.2 Aanwezigheden van één cursus of activiteit

Gebruik get_attendance om alle sessies met hun deelnemers en aanwezigheden voor één cursus of activiteit op te halen.

Endpoint

GET https://integrations.ledenbeheer.be/get_attendance

Parameters

Voorbeeld met cURL

curl --get 'https://integrations.ledenbeheer.be/get_attendance' --header 'Authorization: Bearer UW_TOKEN' --data-urlencode 'courseOrActivityId=842'

Resultaat

Het veld result bevat de sessies, gegroepeerd per datum. Per datum wordt een lijst teruggegeven, omdat op dezelfde dag meerdere sessies kunnen plaatsvinden.

{ "result": { "2026-09-14": [ { "id": 5001, "startTime": "09:00", "endTime": "10:30", "attendance": { "123": { "id": 123, "name": "Jan Janssens", "registrationTariffIncludesSession": true, "attended": true, "type": "member" } } } ] }, "errors": [] }

Heeft de cursus of activiteit geen sessies, dan is result leeg. Dit kan als een leeg object of een lege array worden teruggegeven. Bij een ongeldig of niet-toegankelijk ID blijft het resultaat leeg en bevat errors een foutmelding.

16.3 Aanwezigheden van meerdere cursussen of activiteiten

Gebruik get_attendance_bulk om meerdere cursussen of activiteiten in één aanvraag te synchroniseren.

Endpoint

GET https://integrations.ledenbeheer.be/get_attendance_bulk

Parameters

Voorbeeld met cURL

curl --get 'https://integrations.ledenbeheer.be/get_attendance_bulk' --header 'Authorization: Bearer UW_TOKEN' --data-urlencode 'courseOrActivityIds=[842,913,999999]'

Resultaat

Het resultaat is geïndexeerd op het cursus- of activiteit-ID. Elk item bevat id, title, type en sessions. Het type is course of activity. De sessies hebben dezelfde structuur als bij get_attendance.

Een verkort voorbeeld met een gedeeltelijk geslaagde aanvraag:

{ "result": { "842": { "id": 842, "title": "Ballet beginners", "type": "course", "sessions": { "2026-09-14": [ { "id": 5001, "startTime": "09:00", "endTime": "10:30", "attendance": {} } ] } } }, "errors": [ { "message": "Course or activity does not exist.", "courseId": 999999 } ] }

Toegankelijke cursussen en activiteiten zonder sessies worden niet opgenomen. Wanneer een opgegeven ID ongeldig of niet toegankelijk is, kunnen de andere resultaten wel worden teruggegeven. Verwerk daarom result en errors afzonderlijk.

16.4 Aanwezigheden op basis van verantwoordelijken

Gebruik get_attendance_for_responsible_users om aanwezigheden op te halen van cursussen en activiteiten waaraan huidige of vroegere verantwoordelijken gekoppeld zijn. Dit is bijvoorbeeld handig voor een lesgeversdashboard of een maandelijks rapport.

Endpoint

GET https://integrations.ledenbeheer.be/get_attendance_for_responsible_users

Parameters

De begin- en einddatum tellen allebei mee. Alleen sessies binnen deze periode worden teruggegeven. Cursussen of activiteiten zonder sessies in de periode worden weggelaten.

Belangrijk: userIds weglaten is niet hetzelfde als userIds=[] meesturen. Een lege array betekent dat er geen gebruikers geselecteerd zijn en levert normaal geen cursussen op.

Voorbeeld met cURL

curl --get 'https://integrations.ledenbeheer.be/get_attendance_for_responsible_users' --header 'Authorization: Bearer UW_TOKEN' --data-urlencode 'userIds=[77,88]' --data-urlencode 'periodStart=2026-09-01' --data-urlencode 'periodEnd=2026-09-30'

Resultaat

Het antwoord heeft dezelfde structuur als bij get_attendance_bulk: per cursus of activiteit ontvang je de basisgegevens en de sessies met hun deelnemers en aanwezigheden. De selectie op verantwoordelijken beperkt dus de cursussen en activiteiten; de aanwezigheidslijst bevat ook de andere deelnemers van de teruggegeven sessies.

16.5 Sessies en aanwezigheidsgegevens

Een datum wordt weergegeven als YYYY-MM-DD en is de geplande lokale sessiedatum. Iedere sessie bevat:

Per gebruiker bevat attendance onderstaande velden:

Let op: attended=false betekent dat de gebruiker niet als aanwezig geregistreerd staat. Het veld maakt geen onderscheid tussen de andere opgeslagen statussen. Of een sessie in het tarief inbegrepen is, staat los van de geregistreerde aanwezigheid.

Types deelnemers

Komt een gebruiker voor meerdere types in aanmerking, dan geldt deze volgorde: responsibleUser → member → trial → pass → other. Een verantwoordelijke die ook ingeschreven is als lid, wordt dus als responsibleUser teruggegeven.

Gewoon ingeschreven leden verschijnen bij elke teruggegeven sessie van hun cursus of activiteit, ook wanneer hun tarief die sessie niet omvat. Controleer daarom altijd registrationTariffIncludesSession.

Verlopen inschrijvingen en inschrijvingen die op goedkeuring wachten, worden alleen opgenomen wanneer de gebruiker ergens binnen die cursus of activiteit een aanwezigheidsregistratie heeft. Geannuleerde en tijdelijke bestellingen worden uitgesloten. Proeflessen worden via proeflesinschrijvingen verwerkt en niet als gewone ledeninschrijvingen.

Historiek van verantwoordelijken

Wanneer de historiek een begin- en eindmoment van een toewijzing bevat, wordt de verantwoordelijke alleen opgenomen bij sessies waarvan het startmoment binnen die toewijzing valt. Een huidige toewijzing heeft geen eindmoment.

Bij oudere cursussen waarvoor alleen de huidige verantwoordelijke bekend is, gebruikt de API die persoon als terugval en verschijnt die bij alle teruggegeven sessies van de cursus.

16.6 Foutafhandeling en synchronisatie

Controleer de HTTP-status en lees result en errors afzonderlijk. Een niet-lege foutenlijst betekent bij bulk- en verantwoordelijkenaanvragen niet dat alle resultaten onbruikbaar zijn.

Fouten over cursussen of gebruikers bevatten een message en, afhankelijk van de fout, een courseId of userId:

{ "message": "Responsible user is not visible to this integration partner.", "userId": 999999 }

Algemene fouten, zoals een ongeldig of uitgeschakeld token of ontbrekende endpointrechten, kunnen als tekst in errors staan:

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

Ondersteun daarom zowel tekstmeldingen als foutobjecten. Los token- en rechtenproblemen eerst op en probeer deze aanvragen niet onbeperkt opnieuw. Tijdelijke verbindings- of serverproblemen kan je met een begrensd aantal pogingen en oplopende wachttijd opnieuw proberen.

Bij het synchroniseren raden we aan om:

• alle sessies per datum te verwerken, ook wanneer er meerdere zijn;

• aanwezigheden te koppelen op basis van cursus-ID, sessie-ID en gebruikers-ID;

• bestaande records bij te werken, zodat een herhaalde import geen dubbels aanmaakt;

• succesvolle resultaten te verwerken en fouten afzonderlijk bij te houden;

• de gebruikte aanvraagperiodes of synchronisatievoortgang te bewaren;

• eventuele extra velden, zoals verwerkingstijd, veilig te negeren als je toepassing ze niet gebruikt.

17. Aanbevolen synchronisatiestrategie

get_course_registrations ondersteunt momenteel:

• geen updatedSince-parameter;

• geen paginering.

De datumfilter kijkt naar de periode van de cursus of activiteit en niet naar het moment waarop de cursus of inschrijving voor het laatst werd gewijzigd.

Het is daarom aan te raden om regelmatig het volledige relevante seizoen opnieuw te synchroniseren.

Aanbevolen werkwijze

1. Haal periodiek het volledige huidige seizoen op.

2. Bewaar cursussen op basis van nid.

3. Bewaar gebruikers op basis van uid.

4. Bewaar bestellingen op basis van oid.

5. Bewaar inschrijvingen bijvoorbeeld op basis van de combinatie:

   • nid

   • uid

   • oid

   • tariff_label

6. Werk bestaande records bij in plaats van ze opnieuw aan te maken.

7. Maak de synchronisatie idempotent.

8. Verwijder records niet onmiddellijk wanneer ze in een volgende synchronisatie ontbreken.

9. Controleer ontbrekende inschrijvingen opnieuw met includeCancelled=1.

Voorbeeld

startDate=2026-01-01 endDate=2026-12-31 includeCancelled=1

Voor een productie-integratie is het meestal beter om een voldoende brede periode te synchroniseren dan enkel de huidige dag of week.

18. Foutafhandeling

Controleer altijd zowel de HTTP-status als de API-response.

Voorbeeld:

{ "result": false, "errors": [ "Invalid token" ] }

Mogelijke fouten zijn onder andere:

• ongeldig token;

• uitgeschakeld token;

• token zonder toegang tot de gevraagde club;

• ontbrekend club-ID;

• ongeldig club-ID;

• ongeldige veldwaarden;

• overschrijding van maximaal 100 requests per minuut;

• tijdelijke overbelasting van de server.

Tijdelijke fouten

Bij tijdelijke serverproblemen, bijvoorbeeld HTTP 503, kan de aanvraag opnieuw worden geprobeerd.

Gebruik bij voorkeur exponential backoff of een vergelijkbare strategie.

Bijvoorbeeld:

1e retry: 2 seconden 2e retry: 5 seconden 3e retry: 10 seconden 4e retry: 30 seconden

Vermijd onbeperkt automatisch opnieuw proberen.

19. Aanbevolen integratieflow

Voor een nieuwe integratie raden we onderstaande volgorde aan.

Stap 1 — Verbinding controleren

Roep test_connection aan en controleer:

• of het token geldig is;

• welke endpoints beschikbaar zijn;

• tot welke clubs het token toegang heeft.

Stap 2 — Geldige waarden ophalen

Gebruik get_valid_field_options voordat je gebruikersgegevens aanmaakt of wijzigt.

Stap 3 — Gebruikers synchroniseren

Gebruik:

• get_user_accounts

• get_user_account

• create_user_account

• edit_user_account

afhankelijk van de gewenste functionaliteit.

Stap 4 — Actieve leden synchroniseren

Gebruik indien nodig:

get_active_club_members

Stap 5 — Cursussen en inschrijvingen ophalen

Gebruik:

get_course_registrations

met een expliciete startDate en endDate.

Stap 6 — Verantwoordelijken koppelen

Lees responsibleUsers uit de cursus en koppel deze via uid aan de gebruikers uit get_user_accounts.

Stap 7 — Bestellingen koppelen

Gebruik het oid van de inschrijving om de overeenkomstige bestelling in ordersPerUser te vinden.

Stap 8 — Periodiek synchroniseren

Synchroniseer het relevante seizoen opnieuw en werk bestaande records bij op basis van stabiele ID's.

Gebruik daarbij zoveel mogelijk:

• nid voor cursussen, activiteiten, sessies en tarieven;

• uid voor gebruikers;

• oid voor bestellingen.

Gebruik geen namen of titels als unieke sleutel.