Med Playtomic API kan klubbar komma åt sina reservations- och betalningsdata från externa system. I den här guiden får du veta vem som kan använda API:et, hur du får inloggningsuppgifter, vilka data som finns tillgängliga och vilka begränsningar som gäller.
Vad är Playtomic API?
Playtomic API är ett säkert, skrivskyddat gränssnitt som låter klubbar komma åt sina reservations- och betalningsdata från andra system. Oavsett om du driver en eller flera klubbar kan du använda det för att:
- Integrera med dina befintliga system, till exempel CRM, marknadsföringsverktyg, lojalitetsplattformar eller programvara för anläggningshantering
- Komma åt reservationsdata från de senaste 3 månaderna och alla framtida reservationer
- Komma åt detaljerade betalningsdata, även för perioder som ligger mer än 1 år tillbaka i tiden
- Automatisera datasynkroniseringen för att effektivisera klubbens verksamhet
- Förbättra kommunikationen med medlemmarna via externa verktyg och plattformar
Vem kan få tillgång till API:et?
API-åtkomst finns för:
- Klubbar med en anläggning som har ett Champion- eller Master-abonnemang
- Klubbar med flera anläggningar där varje tenant har ett Champion- eller Master-abonnemang
- Kedjeägare, som får samlad åtkomst till data från alla klubbar i sin organisation
Vilka data kan jag hämta från API:et?
API:et är skrivskyddat. Du kan hämta data, men du kan inte skapa, redigera eller radera dem.
Reservationer
- Reservations-ID och tidsstämplar (UTC)
- Information om banan (ID, namn)
- Spelaruppgifter (ID:n, e-post, kommunikationsinställningar)
- Betalningsinformation
- Och mer (se den fullständiga dataspecifikationen)
Betalningar
- Detaljerade data för varje betalning och återbetalning i din klubb, inklusive betalnings-ID och återbetalnings-ID
- Se dokumentationen för Payments-endpointen för alla fält
Vilka funktioner kommer härnäst?
Vi arbetar med:
- Endpoints för spelardata (med samma auktorisering)
- Detaljerade data om evenemang, aktiviteter och clinics
Kontakta din kontoansvarige för att be om specifika funktioner.
Hur får jag inloggningsuppgifter till API:et?
Enskilda klubbar
Du kan skapa och hantera dina egna API-inloggningsuppgifter i Playtomic Manager. Gå till Inställningar > Utvecklarverktyg. Där kan du:
- Generera inloggningsuppgifter
- Generera nya inloggningsuppgifter
- Radera inloggningsuppgifter
- Läsa dokumentationen
📄 Fullständig API-dokumentation (v1.1)
Obs! Kopiera ditt Client ID och din Client Secret och förvara dem på ett säkert ställe. Behandla din Client Secret som ett lösenord: dela den inte offentligt och exponera den inte i frontend-kod. Om du tappar bort den, generera nya inloggningsuppgifter. De tidigare blir då ogiltiga.
Kedjeägare
Om du hanterar flera klubbar som en del av en kedja:
- Kontakta din kontoansvarige på Playtomic eller Customer Care via chatten för att begära samlad API-åtkomst för alla dina anläggningar.
- Öppna den säkra länken som du får med dina inloggningsuppgifter. Länken är giltig i 3 dagar och kan öppnas högst 3 gånger.
- Förvara dina inloggningsuppgifter på ett säkert ställe. Länken slutar gälla och kan inte enkelt skapas på nytt.
- Läs dokumentationen och påbörja din integration.
Obs! Inloggningsuppgifter för kedjor ger åtkomst till alla klubbar i din organisation. Förvara dem säkert och dela dem bara med behöriga teammedlemmar.
Hur fungerar autentiseringen?
API:et använder OAuth 2.0:
- Client ID och Client Secret: unika identifierare för din klubb eller ditt system
- Åtkomsttoken: en tillfällig inloggningsuppgift (oftast giltig i 1 timme) som du använder för API-anrop
Exempel på tokenbegäran:
POST <https://thirdparty.playtomic.io/api/v1/oauth/token>
Content-Type: application/json
{
"client_id": "your_client_id",
"secret": "your_client_secret"
}
Exempel på API-anrop:
GET <https://thirdparty.playtomic.io/api/v1/bookings> Authorization: Bearer your_access_token
🔒 Tips för säkerheten:
- Håll din Client Secret hemlig.
- Exponera aldrig inloggningsuppgifter i offentliga kodförråd.
- Ställ in automatisk förnyelse av token i dina system.
Hur mycket data kan jag hämta och vilka begränsningar finns?
Reservationer
- Tidigare reservationer: endast de senaste 3 månaderna. Äldre reservationer returneras inte.
- Framtida reservationer: tillgängliga enligt schemat.
- Maximal period per begäran: 365 dagar (till exempel de senaste 3 månaderna plus de kommande 9 månaderna).
Betalningar
- Maximal period per begäran: 13 månader. Det begränsar längden på varje begäran, inte hur långt tillbaka du kan gå.
-
Längre perioder: dela upp dem i flera på varandra följande begäranden på högst 13 månader vardera. Till exempel för 2024 till 2026:
- 1 januari 2024 – 31 januari 2025
- 1 februari 2025 – 28 februari 2026
- 1 mars 2026 – i dag
- Inget datumfilter: om du inte anger något datumfilter returnerar API:et som standard de senaste 13 månaderna.
- Datumtyp: varje begäran filtrerar på betalningsdatum eller tjänstedatum, inte båda.
- Första begäran: API:et kan svara 202 Accepted medan det förbereder klubbens betalningshistorik. Det tar oftast några minuter. Vänta en stund och försök igen.
Tidszon
- Alla tidsstämplar anges i UTC. Se till att dina system konverterar dem till din lokala tidszon.
- Kontrollera klubbens tidszon i Playtomic Manager > Inställningar > Klubbinfo.
Anropsbegränsningar
Antalet API-anrop är begränsat (oftast 1 anrop per minut) för att hålla systemet stabilt. Se dokumentationen för aktuella begränsningar.
Vad kan jag använda API:et till?
- CRM-synkronisering: importera reservationsdata för riktade marknadsföringskampanjer
- Analys och rapportering: analysera banbeläggning, hur ofta spelarna spelar och betalningar
- Medlemskommunikation: skicka automatiska bekräftelser och påminnelser via externa verktyg
- Anläggningshantering: integrera med smarta dörrlås, belysning eller andra IoT-system
- Lojalitetsprogram: följ medlemmarnas aktivitet för belöningar och för att behålla medlemmar
Var kan jag få hjälp med API:et?
- Kontoansvarig: genomförbarhetskontroller, åtkomstförfrågningar för kedjor och önskemål om funktioner
- Teknisk support: felsökning av API:et och hjälp med integrationen
- Dokumentation: fullständiga exempel, parametrar och beskrivningar av endpoints
Det finns ingen separat testmiljö. Under utvecklingen kan du testa säkert med dina riktiga data genom att använda begränsade frågor.
Vanliga frågor
Autentisering och åtkomst
Hur får jag inloggningsuppgifter till API:et? Om du hanterar en klubb går du till Inställningar > Utvecklarverktyg i Playtomic Manager och genererar dem själv. Om du är kedjeägare kontaktar du din kontoansvarige eller Customer Care via chatten. Du får en säker länk (giltig i 3 dagar, kan öppnas högst 3 gånger) med ditt Client ID och din Client Secret.
Vad gör jag om jag får felet "Unauthorized" (401/403)? Kontrollera att:
- Din begäran innehåller headern
Authorization: Bearer token. - Din åtkomsttoken inte har gått ut. Förnya den vid behov.
- Ditt Client ID och din Client Secret är korrekta.
- Du inte har överskridit anropsbegränsningarna.
Kan någon annan i min organisation skapa nya inloggningsuppgifter? Ja, men nya inloggningsuppgifter gör de tidigare ogiltiga. Dela inloggningsuppgifterna inom organisationen så att du inte bryter befintliga integrationer.
Åtkomst till data
Kan jag skapa eller redigera reservationer via API:et? Nej. API:et är skrivskyddat. Du kan hämta och analysera data, men du kan inte skapa, redigera eller radera reservationer.
Hur långt tillbaka kan jag hämta reservationer? Reservationer från de senaste 3 månaderna samt alla framtida reservationer. Varje begäran kan omfatta upp till 365 dagar.
Kan jag hämta betalningar som är äldre än 13 månader? Ja. 13 månader är den maximala perioden för en enskild begäran, inte en gräns för hur långt tillbaka data finns. För att hämta en längre period gör du flera på varandra följande begäranden på högst 13 månader vardera.
Kan jag hämta alla mina reservationer och betalningar från tidigare år?
- Betalningar: ja, via API:et. Dela upp perioden i flera begäranden på högst 13 månader vardera.
- Reservationer: nej. Både API:et och reservationslistan i Playtomic Manager innehåller bara de senaste 3 månaderna.
- Avsnittet Rapporter i Playtomic Manager visar totaler för äldre perioder, men inte varje enskild reservation eller betalning.
Vilken tidszon har tidsstämplarna? Alla tidsstämplar anges i UTC. Din integration behöver konvertera dem till din lokala tidszon.
Flera anläggningar och kedjehantering
Kan jag som kedjeägare komma åt data från alla mina klubbar? Ja. Kedjeägare får samlad åtkomst till data från alla klubbar i sin organisation. Du kan filtrera per klubb eller hämta data för alla anläggningar.
Behöver alla anläggningar ett Champion- eller Master-abonnemang? Ja. För åtkomst till flera anläggningar behöver varje tenant ett Champion- eller Master-abonnemang.
Teknisk implementering
Hur ofta kan jag anropa API:et? Det finns anropsbegränsningar (oftast 1 anrop per minut). Se dokumentationen för aktuella begränsningar.
Kan jag testa API:et innan jag går live? Det finns ingen separat testmiljö. Du kan testa säkert med dina riktiga data genom att använda begränsade frågor.
Kommer fler funktioner att läggas till i API:et? Ja. Vi arbetar med endpoints för spelardata och detaljerade data om evenemang, aktiviteter och clinics. Kontakta din kontoansvarige för att be om specifika funktioner.
Support
Vilken information ska jag ta med när jag kontaktar supporten?
- Hela felmeddelandet
- Den endpoint du anropade
- Din klubbs ID
- De steg du redan har provat
Vem ska jag kontakta för olika typer av problem?
- Åtkomst för kedjor: din kontoansvarige eller Customer Care via chatten
- Teknisk integration: det tekniska supportteamet
- Önskemål om funktioner: din kontoansvarige
- Fakturering eller abonnemang: din kontoansvarige
💬 Behöver du hjälp?
Om du har frågor eller behöver mer hjälp, oroa dig inte! 😊 Du kan alltid kontakta oss. Vi finns här för att hjälpa dig!
Kommentarer
logga in för att lämna en kommentar.