Playtomic API: Volledige Gids

Met de Playtomic API hebben clubs vanuit externe systemen toegang tot hun reserverings- en betalingsgegevens. In deze gids lees je wie de API kan gebruiken, hoe je inloggegevens krijgt, welke gegevens beschikbaar zijn en wat de limieten zijn.

Wat is de Playtomic API?

De Playtomic API is een veilige interface met alleen-lezentoegang waarmee clubs vanuit andere systemen toegang hebben tot hun reserverings- en betalingsgegevens. Of je nu één of meerdere clubs beheert, je kunt de API gebruiken om:

• Te koppelen met je bestaande systemen, zoals CRM's, marketingtools, loyaliteitsplatforms of software voor facilitair beheer
• Reserveringsgegevens op te halen van de afgelopen 3 maanden en alle toekomstige reserveringen
• Gedetailleerde betalingsgegevens op te halen, ook van periodes van meer dan 1 jaar geleden
• Gegevenssynchronisatie te automatiseren om de dagelijkse gang van zaken in je club te stroomlijnen
• De communicatie met leden te verbeteren via externe tools en platforms

Wie heeft toegang tot de API?

Toegang tot de API is beschikbaar voor:

• Clubs met één locatie met een Champion- of Master-abonnement
• Clubs met meerdere locaties waarbij elke tenant een Champion- of Master-abonnement heeft
• Keteneigenaren, die centrale toegang krijgen tot de gegevens van alle clubs in hun organisatie

Welke gegevens kan ik via de API ophalen?

De API is alleen-lezen. Je kunt gegevens ophalen, maar niet aanmaken, bewerken of verwijderen.

Reserveringen

• Reserverings-ID en tijdstempels (UTC)
• Baangegevens (ID, naam)
• Spelersgegevens (ID's, e-mailadres, communicatievoorkeuren)
• Betalingsgegevens
• En meer (bekijk de volledige gegevensspecificatie)

Betalingen

• Gedetailleerde gegevens van elke betaling en terugbetaling in je club, inclusief betalings-ID en terugbetalings-ID
• Bekijk de documentatie van het Payments-endpoint voor alle velden

Welke functies komen er binnenkort aan?

We werken aan:

• Endpoints voor spelersgegevens (met dezelfde autorisatie)
• Gedetailleerde gegevens over evenementen, activiteiten en clinics

Neem contact op met je accountmanager om specifieke functies aan te vragen.

Hoe krijg ik API-inloggegevens?

Individuele clubs

Je kunt je eigen API-inloggegevens aanmaken en beheren in Playtomic Manager. Ga naar Instellingen > Ontwikkelaarstools. Daar kun je:

• Inloggegevens genereren
• Inloggegevens opnieuw genereren
• Inloggegevens verwijderen
• De documentatie bekijken

📄 Volledige API-documentatie (v1.1)

Let op: kopieer je Client ID en Client Secret en bewaar ze op een veilige plek. Behandel je Client Secret als een wachtwoord: deel het niet openbaar en zet het niet in front-endcode. Ben je het kwijt? Genereer dan nieuwe inloggegevens. Hierdoor worden de vorige ongeldig.

Keteneigenaren

Als je meerdere clubs beheert als onderdeel van een keten:

1. Neem contact op met je Playtomic-accountmanager of met Customer Care via de chat om centrale API-toegang voor al je locaties aan te vragen.
2. Open de beveiligde link die je met je inloggegevens ontvangt. De link is 3 dagen geldig en kan maximaal 3 keer worden geopend.
3. Bewaar je inloggegevens op een veilige plek. De link verloopt en kan niet zomaar opnieuw worden aangemaakt.
4. Lees de documentatie en start je integratie.

Let op: met inloggegevens voor een keten heb je toegang tot alle clubs in je organisatie. Bewaar ze veilig en deel ze alleen met bevoegde teamleden.

Hoe werkt de authenticatie?

De API gebruikt OAuth 2.0:

• Client ID en Client Secret: unieke identificatiegegevens voor je club of systeem
• Toegangstoken: een tijdelijke sleutel (meestal 1 uur geldig) die je gebruikt voor API-aanroepen

Voorbeeld van een tokenaanvraag:

POST <https://thirdparty.playtomic.io/api/v1/oauth/token>
Content-Type: application/json

{
  "client_id": "your_client_id",
  "secret": "your_client_secret"
}

Voorbeeld van een API-aanroep:

GET <https://thirdparty.playtomic.io/api/v1/bookings>
Authorization: Bearer your_access_token

🔒 Tips voor veiligheid:

• Houd je Client Secret geheim.
• Zet inloggegevens nooit in openbare repository's.
• Stel automatische tokenvernieuwing in je systemen in.

Hoeveel gegevens kan ik ophalen en wat zijn de limieten?

Reserveringen

• Eerdere reserveringen: alleen de afgelopen 3 maanden. Oudere reserveringen worden niet teruggegeven.
• Toekomstige reserveringen: beschikbaar zoals ze gepland staan.
• Maximale periode per aanvraag: 365 dagen (bijvoorbeeld de afgelopen 3 maanden plus de komende 9 maanden).

Betalingen

• Maximale periode per aanvraag: 13 maanden. Dit beperkt de lengte van elke aanvraag, niet hoe ver je terug kunt gaan.
• Langere periodes: verdeel ze over meerdere opeenvolgende aanvragen van maximaal 13 maanden per aanvraag. Bijvoorbeeld voor 2024 tot en met 2026:
  1. 1 januari 2024 – 31 januari 2025
  2. 1 februari 2025 – 28 februari 2026
  3. 1 maart 2026 – vandaag
• Geen datumfilter: als je geen datumfilter opgeeft, geeft de API standaard de afgelopen 13 maanden terug.
• Datumtype: elke aanvraag filtert op betaaldatum of op servicedatum, niet op allebei.
• Eerste aanvraag: de API kan antwoorden met 202 Accepted terwijl de betalingsgeschiedenis van je club wordt voorbereid. Dit duurt meestal een paar minuten. Wacht even en probeer het opnieuw.

Tijdzone

• Alle tijdstempels zijn in UTC. Zorg dat je systemen ze omzetten naar je lokale tijdzone.
• Bekijk de tijdzone van je club in Playtomic Manager > Instellingen > Clubinfo.

Aanroeplimieten

API-aanroepen zijn beperkt (meestal 1 aanroep per minuut) om het systeem stabiel te houden. Bekijk de documentatie voor de actuele limieten.

Waarvoor kan ik de API gebruiken?

• CRM-synchronisatie: importeer reserveringsgegevens voor gerichte marketingcampagnes
• Analyses en rapportages: analyseer baanbezetting, hoe vaak spelers spelen en betalingen
• Communicatie met leden: verstuur automatische bevestigingen en herinneringen via externe tools
• Facilitair beheer: koppel slimme deursloten, verlichting of andere IoT-systemen
• Loyaliteitsprogramma's: volg de activiteit van leden voor beloningen en ledenbehoud

Waar kan ik hulp krijgen met de API?

• Accountmanager: haalbaarheidschecks, toegangsaanvragen voor ketens en functieaanvragen
• Technische ondersteuning: probleemoplossing voor de API en hulp bij de integratie
• Documentatie: volledige voorbeelden, parameters en beschrijvingen van endpoints

Er is geen aparte testomgeving. Tijdens de ontwikkeling kun je veilig testen met je echte gegevens door beperkte query's te gebruiken.

Veelgestelde vragen

Authenticatie en toegang

Hoe krijg ik API-inloggegevens? Beheer je één club? Ga dan in Playtomic Manager naar Instellingen > Ontwikkelaarstools en genereer ze zelf. Ben je keteneigenaar? Neem dan contact op met je accountmanager of met Customer Care via de chat. Je ontvangt een beveiligde link (3 dagen geldig, maximaal 3 keer te openen) met je Client ID en Client Secret.

Wat moet ik doen als ik de foutmelding "Unauthorized" (401/403) krijg? Controleer of:

• Je aanvraag de header Authorization: Bearer token bevat.
• Je toegangstoken niet is verlopen. Vernieuw het als dat nodig is.
• Je Client ID en Client Secret kloppen.
• Je de aanroeplimieten niet hebt overschreden.

Kan iemand anders in mijn organisatie nieuwe inloggegevens aanmaken? Ja, maar nieuwe inloggegevens maken de vorige ongeldig. Deel de inloggegevens binnen je organisatie, zodat bestaande integraties niet stoppen met werken.

Toegang tot gegevens

Kan ik via de API reserveringen aanmaken of bewerken? Nee. De API is alleen-lezen. Je kunt gegevens ophalen en analyseren, maar geen reserveringen aanmaken, bewerken of verwijderen.

Hoeveel reserveringsgeschiedenis kan ik ophalen? Reserveringen van de afgelopen 3 maanden en alle toekomstige reserveringen. Elke aanvraag kan maximaal 365 dagen beslaan.

Kan ik betalingen ophalen die ouder zijn dan 13 maanden? Ja. 13 maanden is de maximale periode van één aanvraag, geen limiet op hoe ver de gegevens teruggaan. Wil je een langere periode ophalen? Doe dan meerdere opeenvolgende aanvragen van maximaal 13 maanden per aanvraag.

Kan ik al mijn reserveringen en betalingen van voorgaande jaren ophalen?

• Betalingen: ja, via de API. Verdeel de periode over meerdere aanvragen van maximaal 13 maanden per aanvraag.
• Reserveringen: nee. Zowel de API als de reserveringslijst in Playtomic Manager bevatten alleen de afgelopen 3 maanden.
• Het onderdeel Rapporten in Playtomic Manager toont totalen voor oudere periodes, maar niet elke afzonderlijke reservering of betaling.

In welke tijdzone staan de tijdstempels? Alle tijdstempels zijn in UTC. Je integratie moet ze omzetten naar je lokale tijdzone.

Meerdere locaties en ketenbeheer

Kan ik als keteneigenaar de gegevens van al mijn clubs bekijken? Ja. Keteneigenaren krijgen centrale toegang tot de gegevens van alle clubs in hun organisatie. Je kunt filteren op club of de gegevens van alle locaties ophalen.

Hebben alle locaties een Champion- of Master-abonnement nodig? Ja. Voor toegang tot meerdere locaties heeft elke tenant een Champion- of Master-abonnement nodig.

Technische implementatie

Hoe vaak kan ik de API aanroepen? Er gelden aanroeplimieten (meestal 1 aanroep per minuut). Bekijk de documentatie voor de actuele limieten.

Kan ik de API testen voordat ik live ga? Er is geen aparte testomgeving. Je kunt veilig testen met je echte gegevens door beperkte query's te gebruiken.

Komen er meer functies in de API? Ja. We werken aan endpoints voor spelersgegevens en aan gedetailleerde gegevens over evenementen, activiteiten en clinics. Neem contact op met je accountmanager om specifieke functies aan te vragen.

Ondersteuning

Welke informatie moet ik vermelden als ik contact opneem met de ondersteuning?

• De volledige foutmelding
• Het endpoint dat je aanriep
• Het ID van je club
• De stappen die je al hebt geprobeerd

Met wie neem ik contact op bij welk type probleem?

• Toegang voor ketens: je accountmanager of Customer Care via de chat
• Technische integratie: het technische ondersteuningsteam
• Functieaanvragen: je accountmanager
• Facturering of abonnement: je accountmanager

💬 Hulp nodig?

Heb je vragen of meer hulp nodig? Geen zorgen! 😊 Je kunt altijd contact met ons opnemen. We helpen je graag!