Een API-sleutel aanmaken en de documentatie doorgeven aan een externe partij

Met de Partner API van Club Planner kan een externe partij — je webbouwer, een marketingtool, een boekhoudpakket of een eigen app — rechtstreeks gegevens uit jouw platform lezen of erin wegschrijven. Die toegang verloopt altijd via een API-sleutel die je zelf aanmaakt, beperkt en op elk moment weer kan intrekken.

In dit artikel lees je hoe je zo'n sleutel aanmaakt, welke rechten je best toekent, en wat je precies moet doorgeven aan de externe partij.

1. Voor je begint

Spreek met de externe partij eerst kort af:

• Welke gegevens ze nodig hebben (leden, agenda, verkopen, check-in, …).
• Of ze enkel moeten lezen, of ook schrijven (gegevens aanpassen of toevoegen).
• Of de koppeling tijdelijk is — dan geef je de sleutel een vervaldatum.

Hoe beperkter je de sleutel instelt, hoe veiliger. Je kan achteraf altijd rechten bijzetten. Om API-sleutels te beheren heb je toegang tot Instellingen nodig.

2. Waar vind je de API-sleutels?

Ga in Club Planner naar Instellingen → Algemeen → Platform en klik op het tabblad Partner API. Je ziet daar alle bestaande sleutels van je platform; naast de naam van het tabblad staat het aantal.

De schermafbeeldingen in dit artikel komen uit de Engelstalige interface; in jouw taal zijn de labels vertaald.

3. Een nieuwe sleutel aanmaken

Stap 1 — Nieuwe sleutel starten. Klik op Toevoegen onderaan de lijst. Heb je nog geen enkele sleutel, dan klik je op API-sleutel aanmaken.

Stap 2 — Naam van de sleutel. Vul bovenaan een duidelijke naam in, bijvoorbeeld Studio Nova - Website of Exact Online. Gebruik één sleutel per partner of per toepassing: zo kan je later één koppeling stopzetten zonder de andere te raken.

Stap 3 — Algemeen.

• Club — voor welke club de sleutel bedoeld is. Werk je met één club, dan laat je dit op Alle clubs staan.
• Vervalt op — optionele einddatum. Vanaf die datum werkt de sleutel niet meer, dus kies de dag ná de laatste dag dat hij nog moet werken. Laat leeg voor een sleutel zonder einddatum.

Stap 4 — Gebruik en logging.

• Verzoeklimiet — het maximum aantal oproepen dat de sleutel mag doen, en over welke periode (Per 5 minuten, Per 15 minuten, Per uur, Per dag, Per maand of Totaal). Standaard staat dit op 25 per 5 minuten.
• Logging — Uit, Normaal of Uitgebreid. Met logging aan wordt elke oproep bijgehouden (tijdstip, methode, pad, statuscode, duur, IP). Handig tijdens het opzetten van een koppeling of bij problemen.

Hogere limiet nodig? Alles boven de standaard van 25 oproepen per 5 minuten vraagt een override-code. Klik op Hogere limiet aanvragen en contacteer Club Planner support om de code te krijgen. Zonder correcte code kan je de sleutel niet bewaren.

Stap 5 — Toegang. Hier bepaal je per onderdeel wat de sleutel mag. Je kiest telkens tussen (geen), Alleen lezen en Lezen + schrijven.

• General — clubgegevens, openingsuren, betaalwijzen, documenten, e-mailsjablonen, taken en platformlogs
• Employee — medewerkers: lijst, detail en foto
• Members — leden: fiche, abonnementen, betalingen en contracten, krediet, bezoeken, status/blokkering en communicatie
• Planner — agenda's, activiteiten, agenda-items en reservaties
• Leads — leads (prospecten), hun verkoopstappen en de verkoopagenda's
• Financial — kassaverkopen, ledenkrediet, geld in/uit, saldi, artikelen, omzet- en kassagroepen, coupons, facturen en bestellingen
• Check-in — QR-codes voor leden, toestellen koppelen, in- en uitchecken van leden en medewerkers
• IO — aansturing van licht en poorten via een Loxone-relais
• Chat — gesprekken van de chatbot op je website (enkel lezen)

Zet alles wat de partner niet nodig heeft op (geen). Een sleutel die enkel gegevens moet ophalen, zet je overal op Alleen lezen.

Stap 6 — Aanmaken en de sleutel kopiëren. Klik op Aanmaken. De sleutel verschijnt nu één keer in een venster.

Kopieer deze sleutel meteen. Hij wordt hierna niet meer getoond en kan niet opnieuw worden opgehaald — later zie je enkel nog de eerste tekens ter herkenning. Ben je hem kwijt, dan maak je gewoon een nieuwe sleutel aan en verwijder je de oude. Klik op Kopiëren en bewaar de sleutel veilig (bijvoorbeeld in een wachtwoordbeheerder), of plak hem meteen in het bericht voor je externe partij.

4. Wat geef je door aan de externe partij?

In het blok API-documentatie bovenaan elke sleutel staat de link naar de volledige technische documentatie van jouw platform. Klik op Kopiëren om de link over te nemen, of op Openen om ze zelf te bekijken. De link ziet er zo uit:

https://[jouw-clubplanner-adres]/api/partner/docs

Die pagina bevat álle beschikbare endpoints, met de exacte velden en voorbeeldcode. Meer hoeft een ontwikkelaar niet te krijgen. Een kant-en-klaar bericht:

• Documentatie: https://[jouw-clubplanner-adres]/api/partner/docs
• Basis-URL: https://[jouw-clubplanner-adres]/api/partner/v1/
• API-sleutel: cp_…
• Meesturen als header: X-API-Key bij elke oproep (Authorization: Bearer <sleutel> werkt ook)
• Testen: GET /api/partner/v1/ping voor de verbinding, daarna GET /api/partner/v1/club om de juiste clubId op te halen
• Toegekende rechten en limiet: vermeld welke onderdelen je hebt opengezet en welke verzoeklimiet je instelde

Stuur de sleutel niet via een openbaar kanaal en publiceer hem nooit in code die in een browser of app terechtkomt.

Tip voor technische partners: wie met AI-tools werkt (Claude Desktop, Cursor, …) kan de officiële MCP-server @clubplanner/partner-api-mcp gebruiken. Die voegt de sleutel automatisch toe en laat de assistent alle endpoints zelf ontdekken. De volledige uitleg staat bovenaan de documentatiepagina.

5. Een bestaande sleutel opvolgen en beheren

Klik in de lijst op een sleutel om ze open te klappen.

• Actief / Inactief — met de schakelaar bovenaan pauzeer je een sleutel tijdelijk zonder ze te verwijderen.
• Laatst gebruikt — toont wanneer de sleutel voor het laatst een oproep deed. Handig om te zien of een koppeling nog leeft.
• Logboek — via de knop onder de logging-instellingen bekijk je per dag alle oproepen: tijdstip, methode, pad, status, duur en IP-adres. Klik een lijn open voor de details.
• Rechten aanpassen — wijzig de niveaus onder Toegang en klik op Opslaan.
• Verwijderen — via het prullenbak-icoon. De sleutel werkt daarna definitief niet meer.

Aanpassingen zijn binnen de minuut actief; de externe partij moet niets herstarten.

6. Veelvoorkomende foutmeldingen

• 401 — sleutel ontbreekt, is fout, verlopen of gedeactiveerd. Staat de sleutel op Actief? Is de datum bij Vervalt op al gepasseerd? Wordt de X-API-Key-header correct meegestuurd?
• 403 — de sleutel heeft onvoldoende rechten voor dat onderdeel. Zet het juiste onderdeel onder Toegang op Alleen lezen of Lezen + schrijven.
• 404 — het endpoint of de gegevens bestaan niet. Controleer het pad in de documentatie.
• 429 — de verzoeklimiet is bereikt. Verhoog de Verzoeklimiet (override-code nodig) of laat de partner minder frequent oproepen.

Zet bij twijfel Logging op Uitgebreid: in het logboek zie je dan precies welke oproepen binnenkomen en welke status ze krijgen.

7. Goede gewoontes

• Eén sleutel per partner of toepassing — zo trek je één koppeling in zonder de rest te hinderen.
• Geef enkel de rechten die nodig zijn en start bij voorkeur met Alleen lezen.
• Zet een vervaldatum bij tijdelijke projecten of proefopstellingen.
• Deel de sleutel via een veilig kanaal en bewaar ze in een wachtwoordbeheerder.
• Stopt de samenwerking? Zet de sleutel op inactief of verwijder ze meteen.
• Controleer af en toe de kolom Laatst gebruikt en ruim sleutels op die niemand nog gebruikt.