Playtomic API: Umfassender Leitfaden

Mit der Playtomic API können Clubs aus externen Systemen auf ihre Buchungs- und Zahlungsdaten zugreifen. In diesem Leitfaden erfährst du, wer die API nutzen kann, wie du Zugangsdaten erhältst, welche Daten verfügbar sind und welche Limits gelten.

Was ist die Playtomic API?

Die Playtomic API ist eine sichere Schnittstelle mit reinem Lesezugriff, über die Clubs aus anderen Systemen auf ihre Buchungs- und Zahlungsdaten zugreifen können. Egal, ob du einen oder mehrere Clubs führst, du kannst sie nutzen, um:

• Sie in deine bestehenden Systeme zu integrieren, z. B. in CRMs, Marketing-Tools, Treueplattformen oder Software für die Anlagenverwaltung
• Auf Buchungsdaten zuzugreifen, und zwar auf die der letzten 3 Monate sowie auf alle zukünftigen Buchungen
• Auf detaillierte Zahlungsdaten zuzugreifen, auch für Zeiträume, die länger als 1 Jahr zurückliegen
• Die Datensynchronisierung zu automatisieren und so die Abläufe im Club zu vereinfachen
• Die Kommunikation mit deinen Mitgliedern zu verbessern, über externe Tools und Plattformen

Wer kann auf die API zugreifen?

Der API-Zugriff ist verfügbar für:

• Clubs mit einem Standort mit einem Champion- oder Master-Abo
• Clubs mit mehreren Standorten, bei denen jeder Tenant ein Champion- oder Master-Abo hat
• Ketteninhaber, die einheitlichen Zugriff auf die Daten aller Clubs ihrer Organisation erhalten

Welche Daten kann ich über die API abrufen?

Die API bietet nur Lesezugriff. Du kannst Daten abrufen, aber nicht erstellen, bearbeiten oder löschen.

Buchungen

• Buchungs-ID und Zeitstempel (UTC)
• Platzinformationen (ID, Name)
• Spielerdaten (IDs, E-Mail, Kommunikationseinstellungen)
• Zahlungsinformationen
• Und mehr (vollständige Datenspezifikation ansehen)

Zahlungen

• Detaillierte Daten zu jeder Zahlung und Rückerstattung in deinem Club, einschließlich Zahlungs-ID und Rückerstattungs-ID
• Alle Felder findest du in der Dokumentation zum Payments-Endpoint

Welche Funktionen kommen als Nächstes?

Wir arbeiten an:

• Endpoints für Spielerdaten (mit derselben Autorisierung)
• Detaillierten Daten zu Events, Aktivitäten und Clinics

Wende dich an deinen Account Manager, um bestimmte Funktionen anzufragen.

Wie erhalte ich API-Zugangsdaten?

Einzelne Clubs

Du kannst deine eigenen API-Zugangsdaten in Playtomic Manager erstellen und verwalten. Gehe zu Einstellungen > Entwickler-Tools. Dort kannst du:

• Zugangsdaten generieren
• Zugangsdaten neu generieren
• Zugangsdaten löschen
• Die Dokumentation ansehen

📄 Vollständige API-Dokumentation (v1.1)

Hinweis: Kopiere deine Client ID und dein Client Secret und bewahre sie an einem sicheren Ort auf. Behandle dein Client Secret wie ein Passwort: Teile es nicht öffentlich und lege es nicht im Frontend-Code offen. Wenn du es verlierst, generiere neue Zugangsdaten. Dadurch werden die bisherigen ungültig.

Ketteninhaber

Wenn du mehrere Clubs als Teil einer Kette verwaltest:

1. Wende dich an deinen Playtomic Account Manager oder per Chat an den Customer Care, um einen einheitlichen API-Zugriff für alle deine Standorte anzufragen.
2. Öffne den sicheren Link, den du mit deinen Zugangsdaten erhältst. Der Link ist 3 Tage gültig und kann höchstens 3-mal geöffnet werden.
3. Bewahre deine Zugangsdaten sicher auf. Der Link läuft ab und kann nicht ohne Weiteres neu erstellt werden.
4. Lies die Dokumentation und starte deine Integration.

Hinweis: Ketten-Zugangsdaten gewähren Zugriff auf alle Clubs deiner Organisation. Bewahre sie sicher auf und teile sie nur mit berechtigten Teammitgliedern.

Wie funktioniert die Authentifizierung?

Die API verwendet OAuth 2.0:

• Client ID und Client Secret: eindeutige Kennungen für deinen Club oder dein System
• Zugriffstoken: ein temporärer Zugangsschlüssel (in der Regel 1 Stunde gültig), den du für API-Aufrufe verwendest

Beispiel für eine Token-Anfrage:

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

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

Beispiel für einen API-Aufruf:

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

🔒 Best Practices für die Sicherheit:

• Halte dein Client Secret geheim.
• Lege Zugangsdaten niemals in öffentlichen Repositorys offen.
• Richte in deinen Systemen eine automatische Token-Erneuerung ein.

Wie viele Daten kann ich abrufen und welche Limits gibt es?

Buchungen

• Vergangene Buchungen: nur die letzten 3 Monate. Ältere Buchungen werden nicht zurückgegeben.
• Zukünftige Buchungen: so verfügbar, wie sie geplant sind.
• Maximaler Zeitraum pro Anfrage: 365 Tage (z. B. die letzten 3 Monate plus die nächsten 9 Monate).

Zahlungen

• Maximaler Zeitraum pro Anfrage: 13 Monate. Das begrenzt die Länge jeder Anfrage, nicht wie weit du zurückgehen kannst.
• Längere Zeiträume: Teile sie in mehrere aufeinanderfolgende Anfragen von jeweils bis zu 13 Monaten auf. Zum Beispiel für 2024 bis 2026:
  1. 1. Januar 2024 – 31. Januar 2025
  2. 1. Februar 2025 – 28. Februar 2026
  3. 1. März 2026 – heute
• Kein Datumsfilter: Wenn du keinen Datumsfilter angibst, liefert die API standardmäßig die letzten 13 Monate.
• Datumstyp: Jede Anfrage filtert entweder nach Zahlungsdatum oder nach Leistungsdatum, nicht nach beidem.
• Erste Anfrage: Die API antwortet möglicherweise mit 202 Accepted, während sie den Zahlungsverlauf deines Clubs vorbereitet. Das dauert in der Regel ein paar Minuten. Warte kurz und versuche es dann erneut.

Zeitzone

• Alle Zeitstempel sind in UTC. Achte darauf, dass deine Systeme sie in deine lokale Zeitzone umrechnen.
• Die Zeitzone deines Clubs findest du unter Playtomic Manager > Einstellungen > Clubinfo.

Ratenlimits

API-Aufrufe sind begrenzt (in der Regel 1 Aufruf pro Minute), damit das System stabil bleibt. Die aktuellen Limits findest du in der Dokumentation.

Wofür kann ich die API nutzen?

• CRM-Synchronisierung: Importiere Buchungsdaten für gezielte Marketingkampagnen.
• Analysen und Berichte: Analysiere Platzauslastung, Spielhäufigkeit der Spieler und Zahlungen.
• Mitgliederkommunikation: Versende automatische Bestätigungen und Erinnerungen über externe Tools.
• Anlagenverwaltung: Binde smarte Türschlösser, Beleuchtung oder andere IoT-Systeme an.
• Treueprogramme: Verfolge die Aktivität deiner Mitglieder für Prämien und Kundenbindung.

Wo erhalte ich Hilfe zur API?

• Account Manager: Machbarkeitsprüfungen, Zugriffsanfragen für Ketten und Funktionswünsche
• Technischer Support: Fehlerbehebung bei der API und Hilfe bei der Integration
• Dokumentation: vollständige Beispiele, Parameter und Beschreibungen der Endpoints

Es gibt keine separate Testumgebung. Während der Entwicklung kannst du mit begrenzten Abfragen sicher mit deinen echten Daten testen.

Häufige Fragen

Authentifizierung und Zugriff

Wie erhalte ich API-Zugangsdaten? Wenn du einen Club verwaltest, gehe in Playtomic Manager zu Einstellungen > Entwickler-Tools und generiere sie selbst. Wenn du Ketteninhaber bist, wende dich an deinen Account Manager oder per Chat an den Customer Care. Du erhältst einen sicheren Link (3 Tage gültig, höchstens 3-mal zu öffnen) mit deiner Client ID und deinem Client Secret.

Was mache ich, wenn ich „Unauthorized“-Fehler (401/403) erhalte? Prüfe Folgendes:

• Deine Anfrage enthält den Header Authorization: Bearer token.
• Dein Zugriffstoken ist nicht abgelaufen. Erneuere es bei Bedarf.
• Deine Client ID und dein Client Secret sind korrekt.
• Du hast die Ratenlimits nicht überschritten.

Kann jemand anderes in meiner Organisation neue Zugangsdaten erstellen? Ja, aber neue Zugangsdaten machen die bisherigen ungültig. Teile die Zugangsdaten innerhalb deiner Organisation, damit bestehende Integrationen nicht unterbrochen werden.

Datenzugriff

Kann ich über die API Buchungen erstellen oder bearbeiten? Nein. Die API bietet nur Lesezugriff. Du kannst Daten abrufen und analysieren, aber keine Buchungen erstellen, bearbeiten oder löschen.

Wie weit reicht der Buchungsverlauf zurück? Buchungen der letzten 3 Monate sowie alle zukünftigen Buchungen. Jede Anfrage kann bis zu 365 Tage abdecken.

Kann ich Zahlungen abrufen, die älter als 13 Monate sind? Ja. 13 Monate sind der maximale Zeitraum einer einzelnen Anfrage, keine Grenze dafür, wie weit die Daten zurückreichen. Für einen längeren Zeitraum stellst du mehrere aufeinanderfolgende Anfragen von jeweils bis zu 13 Monaten.

Kann ich alle meine Buchungen und Zahlungen aus den Vorjahren abrufen?

• Zahlungen: Ja, über die API. Teile den Zeitraum in mehrere Anfragen von jeweils bis zu 13 Monaten auf.
• Buchungen: Nein. Sowohl die API als auch die Buchungsliste in Playtomic Manager enthalten nur die letzten 3 Monate.
• Der Bereich Berichte in Playtomic Manager zeigt Summen für ältere Zeiträume, aber nicht jede einzelne Buchung oder Zahlung.

In welcher Zeitzone sind die Zeitstempel? Alle Zeitstempel sind in UTC. Deine Integration muss sie in deine lokale Zeitzone umrechnen.

Mehrere Standorte und Kettenverwaltung

Kann ich als Ketteninhaber auf die Daten aller meiner Clubs zugreifen? Ja. Ketteninhaber erhalten einheitlichen Zugriff auf die Daten aller Clubs ihrer Organisation. Du kannst nach Club filtern oder die Daten aller Standorte abrufen.

Brauchen alle Standorte ein Champion- oder Master-Abo? Ja. Für den Zugriff auf mehrere Standorte braucht jeder Tenant ein Champion- oder Master-Abo.

Technische Umsetzung

Wie oft kann ich die API aufrufen? Es gelten Ratenlimits (in der Regel 1 Aufruf pro Minute). Die aktuellen Limits findest du in der Dokumentation.

Kann ich die API testen, bevor ich live gehe? Es gibt keine separate Testumgebung. Du kannst mit begrenzten Abfragen sicher mit deinen echten Daten testen.

Werden der API weitere Funktionen hinzugefügt? Ja. Wir arbeiten an Endpoints für Spielerdaten und an detaillierten Daten zu Events, Aktivitäten und Clinics. Wende dich an deinen Account Manager, um bestimmte Funktionen anzufragen.

Support

Welche Informationen sollte ich angeben, wenn ich mich an den Support wende?

• Die vollständige Fehlermeldung
• Den Endpoint, den du aufgerufen hast
• Die ID deines Clubs
• Die Schritte, die du bereits ausprobiert hast

An wen wende ich mich bei welchem Problem?

• Zugriff für Ketten: an deinen Account Manager oder per Chat an den Customer Care
• Technische Integration: an das technische Support-Team
• Funktionswünsche: an deinen Account Manager
• Abrechnung oder Abo: an deinen Account Manager

💬 Brauchst du Hilfe?

Wenn du Fragen hast oder weitere Unterstützung brauchst, keine Sorge! 😊 Du kannst uns jederzeit kontaktieren. Wir sind für dich da!