API Playtomic : Guide Complet

L'API Playtomic permet aux clubs d'accéder à leurs données de réservations et de paiements depuis des systèmes externes. Ce guide explique qui peut l'utiliser, comment obtenir des identifiants, quelles données sont disponibles et quelles sont les limites.

Qu'est-ce que l'API Playtomic ?

L'API Playtomic est une interface sécurisée, en lecture seule, qui permet aux clubs d'accéder à leurs données de réservations et de paiements depuis d'autres systèmes. Que tu gères un ou plusieurs clubs, tu peux l'utiliser pour :

• L'intégrer à tes systèmes existants, comme un CRM, des outils marketing, des plateformes de fidélité ou un logiciel de gestion des installations
• Accéder aux données de réservations des 3 derniers mois et à toutes les réservations futures
• Accéder aux données détaillées des paiements, y compris pour des périodes de plus d'1 an
• Automatiser la synchronisation des données pour simplifier la gestion du club
• Améliorer la communication avec les membres grâce à des outils et plateformes externes

Qui peut accéder à l'API ?

L'accès à l'API est disponible pour :

• Les clubs avec un seul site ayant un abonnement Champion ou Master
• Les clubs avec plusieurs sites dont chaque tenant a un abonnement Champion ou Master
• Les propriétaires de chaînes, qui bénéficient d'un accès unifié aux données de tous les clubs de leur organisation

Quelles données puis-je obtenir avec l'API ?

L'API est en lecture seule. Tu peux récupérer des données, mais tu ne peux pas les créer, les modifier ni les supprimer.

Réservations

• ID de la réservation et horodatages (UTC)
• Informations sur le terrain (ID, nom)
• Informations sur les joueurs (ID, e-mail, préférences de communication)
• Informations de paiement
• Et plus encore (voir la spécification complète des données)

Paiements

• Données détaillées de chaque paiement et remboursement de ton club, y compris l'ID du paiement et l'ID du remboursement
• Consulte la documentation de l'endpoint des paiements pour voir tous les champs

Quelles fonctionnalités arrivent bientôt ?

Nous travaillons sur :

• Des endpoints pour les données des joueurs (avec la même autorisation)
• Des données détaillées sur les événements, les activités et les clinics

Contacte ton gestionnaire de compte pour demander des fonctionnalités spécifiques.

Comment obtenir des identifiants API ?

Clubs individuels

Tu peux créer et gérer tes propres identifiants API dans Playtomic Manager. Va dans Paramètres > Outils développeur. Depuis cette page, tu peux :

• Générer des identifiants
• Régénérer des identifiants
• Supprimer des identifiants
• Consulter la documentation

📄 Documentation complète de l'API (v1.1)

Remarque : copie ton Client ID et ton Client Secret et conserve-les en lieu sûr. Traite ton Client Secret comme un mot de passe : ne le partage pas publiquement et ne l'expose pas dans du code front-end. Si tu le perds, génère de nouveaux identifiants. Cela invalide les précédents.

Propriétaires de chaînes

Si tu gères plusieurs clubs au sein d'une chaîne :

1. Contacte ton gestionnaire de compte Playtomic, ou le Customer Care via le chat, pour demander un accès API unifié pour tous tes sites.
2. Ouvre le lien sécurisé que tu reçois avec tes identifiants. Le lien est valable 3 jours et peut être ouvert 3 fois au maximum.
3. Conserve tes identifiants en lieu sûr. Le lien expire et ne peut pas être régénéré facilement.
4. Lis la documentation et commence ton intégration.

Remarque : les identifiants de chaîne donnent accès à tous les clubs de ton organisation. Conserve-les en lieu sûr et ne les partage qu'avec les membres autorisés de ton équipe.

Comment fonctionne l'authentification ?

L'API utilise OAuth 2.0 :

• Client ID et Client Secret : identifiants uniques de ton club ou de ton système
• Jeton d'accès : un identifiant temporaire (généralement valable 1 heure) que tu utilises pour les appels à l'API

Exemple de demande de jeton :

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

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

Exemple d'appel à l'API :

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

🔒 Bonnes pratiques de sécurité :

• Garde ton Client Secret confidentiel.
• N'expose jamais tes identifiants dans des dépôts publics.
• Configure le renouvellement automatique du jeton dans tes systèmes.

Quelle quantité de données puis-je obtenir et quelles sont les limites ?

Réservations

• Réservations passées : 3 derniers mois uniquement. Les réservations plus anciennes ne sont pas renvoyées.
• Réservations futures : disponibles telles qu'elles sont programmées.
• Période maximale par demande : 365 jours (par exemple, les 3 derniers mois et les 9 prochains mois).

Paiements

• Période maximale par demande : 13 mois. Cela limite la durée de chaque demande, pas l'ancienneté des données que tu peux obtenir.
• Périodes plus longues : divise-les en plusieurs demandes consécutives de 13 mois maximum chacune. Par exemple, de 2024 à 2026 :
  1. 1er janvier 2024 – 31 janvier 2025
  2. 1er février 2025 – 28 février 2026
  3. 1er mars 2026 – aujourd'hui
• Sans filtre de date : si tu n'indiques aucun filtre de date, l'API renvoie par défaut les 13 derniers mois.
• Type de date : chaque demande filtre par date de paiement ou par date de service, pas les deux.
• Première demande : l'API peut répondre 202 Accepted pendant qu'elle prépare l'historique des paiements de ton club. Cela prend généralement quelques minutes. Patiente et réessaie.

Fuseau horaire

• Tous les horodatages sont en UTC. Assure-toi que tes systèmes les convertissent dans ton fuseau horaire local.
• Vérifie le fuseau horaire de ton club dans Playtomic Manager > Paramètres > Infos du club.

Limites d'appels

Les appels à l'API sont limités (généralement 1 appel par minute) pour garantir la stabilité du système. Consulte la documentation pour connaître les limites actuelles.

À quoi puis-je utiliser l'API ?

• Synchronisation avec le CRM : importe les données de réservations pour des campagnes marketing ciblées
• Analyses et rapports : analyse l'utilisation des terrains, la fréquence de jeu des joueurs et les paiements
• Communication avec les membres : envoie des confirmations et des rappels automatiques via des outils externes
• Gestion des installations : intègre des serrures connectées, l'éclairage ou d'autres systèmes IoT
• Programmes de fidélité : suis l'activité des membres pour les récompenser et les fidéliser

Où obtenir de l'aide sur l'API ?

• Gestionnaire de compte : études de faisabilité, demandes d'accès pour les chaînes et demandes de fonctionnalités
• Support technique : dépannage de l'API et aide à l'intégration
• Documentation : exemples complets, paramètres et descriptions des endpoints

Il n'existe pas d'environnement de test séparé. Pendant le développement, tu peux faire des tests en toute sécurité avec tes données réelles en limitant tes requêtes.

Questions fréquentes

Authentification et accès

Comment obtenir des identifiants API ? Si tu gères un seul club, va dans Paramètres > Outils développeur dans Playtomic Manager et génère-les toi-même. Si tu es propriétaire d'une chaîne, contacte ton gestionnaire de compte ou le Customer Care via le chat. Tu recevras un lien sécurisé (valable 3 jours, 3 ouvertures au maximum) avec ton Client ID et ton Client Secret.

Que faire si je reçois des erreurs « Unauthorized » (401/403) ? Vérifie que :

• Ta demande inclut l'en-tête Authorization: Bearer token.
• Ton jeton d'accès n'a pas expiré. Renouvelle-le si nécessaire.
• Ton Client ID et ton Client Secret sont corrects.
• Tu n'as pas dépassé les limites d'appels.

Une autre personne de mon organisation peut-elle créer de nouveaux identifiants ? Oui, mais les nouveaux identifiants invalident les précédents. Partage les identifiants au sein de ton organisation pour ne pas interrompre les intégrations existantes.

Accès aux données

Puis-je créer ou modifier des réservations via l'API ? Non. L'API est en lecture seule. Tu peux récupérer et analyser des données, mais tu ne peux pas créer, modifier ni supprimer de réservations.

Jusqu'où puis-je remonter dans l'historique des réservations ? Les réservations des 3 derniers mois, ainsi que toutes les réservations futures. Chaque demande peut couvrir jusqu'à 365 jours.

Puis-je obtenir des paiements de plus de 13 mois ? Oui. 13 mois est la période maximale d'une seule demande, pas une limite sur l'ancienneté des données. Pour obtenir une période plus longue, fais plusieurs demandes consécutives de 13 mois maximum chacune.

Puis-je obtenir toutes mes réservations et tous mes paiements des années précédentes ?

• Paiements : oui, via l'API. Divise la période en plusieurs demandes de 13 mois maximum chacune.
• Réservations : non. L'API et la liste des réservations de Playtomic Manager n'incluent que les 3 derniers mois.
• La section Rapports de Playtomic Manager affiche les totaux des périodes plus anciennes, mais pas le détail de chaque réservation ou paiement.

Dans quel fuseau horaire sont les horodatages ? Tous les horodatages sont en UTC. Ton intégration doit les convertir dans ton fuseau horaire local.

Gestion multisite et des chaînes

En tant que propriétaire d'une chaîne, puis-je accéder aux données de tous mes clubs ? Oui. Les propriétaires de chaînes bénéficient d'un accès unifié aux données de tous les clubs de leur organisation. Tu peux filtrer par club ou obtenir les données de tous les sites.

Tous les sites doivent-ils avoir un abonnement Champion ou Master ? Oui. Pour un accès multisite, chaque tenant doit avoir un abonnement Champion ou Master.

Mise en œuvre technique

À quelle fréquence puis-je appeler l'API ? Des limites d'appels s'appliquent (généralement 1 appel par minute). Consulte la documentation pour connaître les limites actuelles.

Puis-je tester l'API avant la mise en production ? Il n'existe pas d'environnement de test séparé. Tu peux faire des tests en toute sécurité avec tes données réelles en limitant tes requêtes.

D'autres fonctionnalités seront-elles ajoutées à l'API ? Oui. Nous travaillons sur des endpoints pour les données des joueurs et sur des données détaillées sur les événements, les activités et les clinics. Contacte ton gestionnaire de compte pour demander des fonctionnalités spécifiques.

Support

Quelles informations dois-je fournir quand je contacte le support ?

• Le message d'erreur complet
• L'endpoint que tu appelais
• L'ID de ton club
• Les étapes que tu as déjà essayées

Qui contacter pour chaque type de problème ?

• Accès pour les chaînes : ton gestionnaire de compte, ou le Customer Care via le chat
• Intégration technique : l'équipe de support technique
• Demandes de fonctionnalités : ton gestionnaire de compte
• Facturation ou abonnement : ton gestionnaire de compte

💬 Besoin d'aide ?

Si tu as des questions ou besoin d'aide supplémentaire, ne t'inquiète pas ! 😊 Tu peux toujours nous contacter. Nous sommes là pour t'aider !