L'API del Centro sportivo di Playtomic consente ai proprietari dei centri sportivi di integrare senza problemi i loro dati di prenotazione con sistemi esterni, ottimizzando le operazioni e migliorando l'esperienza dei membri. Questa guida completa copre tutto ciò che devi sapere sull'accesso e l'utilizzo della nostra API.

Cos'è l'API del Centro sportivo di Playtomic?

L'API del Centro sportivo di Playtomic è un'interfaccia sicura e di sola lettura che consente ai centri sportivi di accedere ai loro dati di prenotazione in modo programmatico. Che tu gestisca una singola sede o più strutture, l'API ti consente di:

• Integrare con sistemi esistenti come CRM, strumenti di marketing, piattaforme di fidelizzazione o software di gestione delle strutture
• Accedere ai dati di prenotazione in tempo reale e storici degli ultimi 3 mesi
• Automatizzare la sincronizzazione dei dati per ottimizzare le operazioni del centro sportivo

• Migliorare la comunicazione con i membri attraverso strumenti e piattaforme esterne

   

  📋 Nota per i Centri sportivi Syltek: Puoi utilizzare l'API con la stessa visibilità dei dati presente in Manager. Mentre le prenotazioni si sincronizzano da Syltek, tieni presente che non tutti gli elementi del programma (come le lezioni) potrebbero essere sincronizzati.

Chi può accedere all'API?

L'accesso all'API è disponibile per:

• Centri sportivi con una sola sede con piani di abbonamento Champion o Master
• Centri sportivi con più sedi dove ogni tenant ha un abbonamento Champion o Master
• Proprietari di catene che ottengono accesso unificato a tutti i dati del centro sportivo all'interno della loro organizzazione

Funzionalità attuali dell'API

La nostra API di sola lettura fornisce accesso a dati di prenotazione completi, inclusi:

• ID di prenotazione e timestamp (formato UTC)
• Informazioni sul campo (ID, nome)
• Dettagli del giocatore (ID, email, preferenze di comunicazione)
• Informazioni sui pagamenti
• E molto altro (visualizza la specifica completa dei dati)

Funzionalità in arrivo

Stiamo espandendo attivamente l'API con:

• Endpoint dei dati dei giocatori (utilizzando la stessa autorizzazione)
• Accesso migliorato alla cronologia dei pagamenti
• Dati dettagliati su eventi, attività e cliniche

Contatta il tuo account manager per richiedere funzionalità specifiche o esprimere interesse per le capacità in arrivo.

Iniziare

1. Richiedere l'accesso

1. Contatta il tuo account manager di Playtomic o il Servizio Clienti tramite chat per richiedere l'accesso all'API
2. Ricevi le tue credenziali tramite un link sicuro (valido per 3 giorni, massimo 3 aperture)
3. Conserva le credenziali in modo sicuro - il link temporaneo scadrà
4. Accedi alla documentazione e inizia l'integrazione

📄 Documentazione completa dell'API (v1.1)

⚠️ Importante: Salva immediatamente le tue credenziali poiché il link di accesso scade rapidamente e non può essere rigenerato facilmente.

2. Comprendere l'autenticazione

L'API utilizza OAuth 2.0 per un accesso sicuro:

Le tue credenziali:

• Client ID & Client Secret: Identificatori unici per il tuo centro sportivo/sistema
• Access Token: Credenziale temporanea (tipicamente valida per 1 ora) per le chiamate API

Esempio di richiesta token:

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

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

Eseguire chiamate API:

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

🔒 Migliori pratiche di sicurezza:

• Mantieni il tuo Client Secret riservato
• Non esporre mai le credenziali in repository pubblici
• Implementa il rinnovo automatico del token nei tuoi sistemi

Specifiche e limitazioni dei dati

Gestione del fuso orario

• Tutti i timestamp sono in UTC - assicurati che i tuoi sistemi convertano al fuso orario locale
• Verifica le impostazioni del fuso orario del tuo centro sportivo in Playtomic Manager > Impostazioni > Info Centro sportivo

Disponibilità dei dati

• Dati storici: Ultimi 90 giorni
• Prenotazioni future: Disponibili come pianificato
• Intervallo massimo di richiesta: 365 giorni (90 passati + 275 futuri, o 365 futuri)

Limiti di velocità

Le chiamate API sono soggette a limitazioni di velocità (tipicamente 1 chiamata al minuto) per garantire la stabilità del sistema. Controlla la documentazione per i limiti attuali.

Casi d'uso comuni

Trasforma le operazioni del tuo centro sportivo con queste integrazioni popolari:

• Sincronizzazione CRM: Importa dati di prenotazione per campagne di marketing mirate
• Analisi e reportistica: Analizza l'utilizzo del campo e i modelli di frequenza dei giocatori
• Comunicazione con i membri: Invia conferme e promemoria automatici tramite strumenti esterni
• Gestione delle strutture: Integra con serrature intelligenti, illuminazione o altri sistemi IoT
• Programmi di fidelizzazione: Traccia l'attività dei membri per programmi di premi e fidelizzazione

Risoluzione dei problemi e supporto

Ottenere aiuto

• Account Manager: Valutazione di fattibilità e richieste di accesso
• Supporto Tecnico: Risoluzione dei problemi API e assistenza all'integrazione
• Documentazione: Esempi completi, parametri e descrizioni degli endpoint

Testare la tua Integrazione

Sebbene non forniamo un ambiente di test separato, puoi testare in sicurezza con i tuoi dati di prenotazione effettivi utilizzando query limitate durante lo sviluppo.

Domande Frequenti (FAQ)

Autenticazione & Accesso

D: Come posso ottenere le credenziali API?

R: Contatta il tuo account manager di Playtomic o il team di supporto. Una volta approvato, riceverai un link sicuro (valido 3 giorni, massimo 3 aperture) contenente il tuo Client ID e Client Secret.

D: Cosa devo fare se ricevo errori "Non autorizzato" (401/403)?

R: Soluzioni comuni:

• Verifica che l'intestazione Authorization: Bearer token sia inclusa
• Controlla se il tuo token di accesso è scaduto (aggiorna se necessario)
• Conferma che il tuo Client ID e Client Secret siano corretti

• Assicurati di non aver superato i limiti di velocità

   

D: Qualcun altro nella mia organizzazione può richiedere nuove credenziali?

R: Sì, ma importante: Le nuove richieste di credenziali revocheranno quelle vecchie. Condividi le credenziali all'interno della tua organizzazione per evitare di interrompere le integrazioni esistenti.

Accesso ai Dati & Capacità

D: Posso creare o modificare prenotazioni tramite l'API?

R: No, l'API attuale è solo in lettura. Puoi recuperare e analizzare i dati di prenotazione ma non puoi creare, aggiornare o eliminare prenotazioni.

D: Quanti dati storici posso accedere?

R: Puoi accedere ai dati di prenotazione degli ultimi 90 giorni più tutte le prenotazioni future. L'intervallo massimo di richiesta è di 365 giorni totali.

D: In quale fuso orario sono i timestamp dell'API?

R: Tutti i timestamp sono in UTC. La tua integrazione deve convertirli nel tuo fuso orario locale. Verifica che il fuso orario del tuo centro sportivo sia impostato correttamente in Playtomic Manager.

Gestione Multi-Location & Catena

D: Come proprietario di una catena, ho accesso ai dati di tutti i miei centri sportivi?

R: Sì! I proprietari di catene ricevono accesso unificato ai dati di prenotazione di tutti i centri sportivi nella loro organizzazione. Puoi filtrare le richieste per centri specifici o recuperare dati per tutte le sedi.

D: Tutte le sedi necessitano di abbonamenti Champion/Master?

R: Sì, per l'accesso multi-location, ogni tenant deve avere un piano di abbonamento Champion o Master.

Implementazione Tecnica

D: Quanto spesso posso chiamare l'API?

R: Sono in atto limiti di velocità (tipicamente 1 chiamata al minuto) per garantire la stabilità del sistema. Controlla la documentazione per i limiti attuali e pianifica la tua integrazione di conseguenza.

D: Posso testare l'API prima di andare in produzione?

R: Sebbene non ci sia un ambiente di test separato, puoi testare in sicurezza con i tuoi dati di prenotazione effettivi utilizzando query limitate durante lo sviluppo.

D: Verranno aggiunte più funzionalità all'API?

R: Sì! Stiamo sviluppando attivamente:

• Endpoint dei dati dei giocatori (stessa autorizzazione)
• Storico dei pagamenti migliorato
• Dati dettagliati di eventi e cliniche

Contatta il tuo account manager per richiedere funzionalità specifiche.

Supporto & Risoluzione dei Problemi

D: Quali informazioni dovrei fornire quando richiedo supporto?

R: Includi:

• Messaggio di errore completo
• Endpoint specifico che stavi chiamando
• Il tuo ID Centro Sportivo

• Passaggi che hai già provato

   

D: Chi dovrei contattare per diversi tipi di problemi?

R:

• Richieste di accesso: Account manager o Customer Care via chat per richiedere l'accesso API
• Integrazione tecnica: Team di supporto tecnico
• Richieste di funzionalità: Account manager
• Fatturazione/abbonamento: Account manager

Hai bisogno di ulteriore assistenza? Contatta il tuo account manager di Playtomic o il nostro team di Customer Care per un aiuto personalizzato con la tua integrazione API.