API di Playtomic: Guida Completa

L'API di Playtomic permette ai club di accedere ai propri dati di prenotazioni e pagamenti da sistemi esterni. Questa guida spiega chi può usarla, come ottenere le credenziali, quali dati sono disponibili e quali sono i limiti.

Che cos'è l'API di Playtomic?

L'API di Playtomic è un'interfaccia sicura e di sola lettura che permette ai club di accedere ai propri dati di prenotazioni e pagamenti da altri sistemi. Che tu gestisca uno o più club, puoi usarla per:

• Integrarla con i sistemi che già usi, come CRM, strumenti di marketing, piattaforme fedeltà o software di gestione della struttura
• Accedere ai dati delle prenotazioni degli ultimi 3 mesi e a tutte le prenotazioni future
• Accedere a dati dettagliati sui pagamenti, anche per periodi di oltre 1 anno fa
• Automatizzare la sincronizzazione dei dati per semplificare la gestione del club
• Migliorare la comunicazione con i soci tramite strumenti e piattaforme esterni

Chi può accedere all'API?

L'accesso all'API è disponibile per:

• Club con una sola sede con un piano di abbonamento Champion o Master
• Club con più sedi in cui ogni tenant ha un abbonamento Champion o Master
• Proprietari di catene, che ottengono un accesso unificato ai dati di tutti i club della loro organizzazione

Quali dati posso ottenere dall'API?

L'API è di sola lettura. Puoi recuperare i dati, ma non puoi crearli, modificarli o eliminarli.

Prenotazioni

• ID della prenotazione e timestamp (UTC)
• Informazioni sul campo (ID, nome)
• Dati dei giocatori (ID, e-mail, preferenze di comunicazione)
• Informazioni sul pagamento
• E altro ancora (consulta la specifica completa dei dati)

Pagamenti

• Dati dettagliati su ogni pagamento e rimborso del tuo club, inclusi l'ID del pagamento e l'ID del rimborso
• Consulta la documentazione dell'endpoint dei pagamenti per vedere tutti i campi

Quali funzionalità arriveranno prossimamente?

Stiamo lavorando a:

• Endpoint per i dati dei giocatori (con la stessa autorizzazione)
• Dati dettagliati su eventi, attività e clinic

Contatta il tuo account manager per richiedere funzionalità specifiche.

Come ottengo le credenziali dell'API?

Club singoli

Puoi creare e gestire le tue credenziali dell'API in Playtomic Manager. Vai su Impostazioni > Strumenti per sviluppatori. Da qui puoi:

• Generare le credenziali
• Rigenerare le credenziali
• Eliminare le credenziali
• Consultare la documentazione

📄 Documentazione completa dell'API (v1.1)

Nota: copia il tuo Client ID e il tuo Client Secret e conservali in un luogo sicuro. Tratta il Client Secret come una password: non condividerlo pubblicamente e non esporlo nel codice front-end. Se lo perdi, genera nuove credenziali. In questo modo, le precedenti non saranno più valide.

Proprietari di catene

Se gestisci più club che fanno parte di una catena:

1. Contatta il tuo account manager di Playtomic o il Customer Care via chat per richiedere l'accesso unificato all'API per tutte le tue sedi.
2. Apri il link sicuro che riceverai con le tue credenziali. Il link è valido per 3 giorni e può essere aperto al massimo 3 volte.
3. Conserva le tue credenziali in un luogo sicuro. Il link scade e non può essere rigenerato facilmente.
4. Leggi la documentazione e inizia la tua integrazione.

Nota: le credenziali della catena danno accesso a tutti i club della tua organizzazione. Conservale in un luogo sicuro e condividile solo con i membri autorizzati del tuo team.

Come funziona l'autenticazione?

L'API usa OAuth 2.0:

• Client ID e Client Secret: identificativi univoci del tuo club o sistema
• Token di accesso: una credenziale temporanea (di solito valida per 1 ora) che usi per le chiamate all'API

Esempio di richiesta del token:

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

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

Esempio di chiamata all'API:

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

🔒 Buone pratiche di sicurezza:

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

Quanti dati posso ottenere e quali sono i limiti?

Prenotazioni

• Prenotazioni passate: solo degli ultimi 3 mesi. Le prenotazioni più vecchie non vengono restituite.
• Prenotazioni future: disponibili come programmate.
• Intervallo massimo per richiesta: 365 giorni (ad esempio, gli ultimi 3 mesi più i prossimi 9 mesi).

Pagamenti

• Intervallo massimo per richiesta: 13 mesi. Questo limita la durata di ogni richiesta, non quanto indietro nel tempo puoi andare.
• Periodi più lunghi: suddividili in più richieste consecutive di massimo 13 mesi ciascuna. Ad esempio, dal 2024 al 2026:
  1. 1° gennaio 2024 – 31 gennaio 2025
  2. 1° febbraio 2025 – 28 febbraio 2026
  3. 1° marzo 2026 – oggi
• Nessun filtro per data: se non indichi alcun filtro per data, l'API restituisce per impostazione predefinita gli ultimi 13 mesi.
• Tipo di data: ogni richiesta filtra per data di pagamento o per data del servizio, non per entrambe.
• Prima richiesta: l'API potrebbe rispondere 202 Accepted mentre prepara lo storico dei pagamenti del tuo club. Di solito ci vogliono pochi minuti. Attendi e riprova.

Fuso orario

• Tutti i timestamp sono in UTC. Assicurati che i tuoi sistemi li convertano nel tuo fuso orario locale.
• Controlla il fuso orario del tuo club in Playtomic Manager > Impostazioni > Info Centro sportivo.

Limiti di frequenza

Le chiamate all'API hanno un limite di frequenza (di solito 1 chiamata al minuto) per mantenere stabile il sistema. Consulta la documentazione per i limiti attuali.

Per cosa posso usare l'API?

• Sincronizzazione con il CRM: importa i dati delle prenotazioni per campagne di marketing mirate
• Analisi e report: analizza l'utilizzo dei campi, la frequenza dei giocatori e i pagamenti
• Comunicazione con i soci: invia conferme e promemoria automatici tramite strumenti esterni
• Gestione della struttura: integra serrature intelligenti, illuminazione o altri sistemi IoT
• Programmi fedeltà: monitora l'attività dei soci per premi e fidelizzazione

Dove posso ricevere aiuto con l'API?

• Account manager: verifiche di fattibilità, richieste di accesso per le catene e richieste di funzionalità
• Supporto tecnico: risoluzione dei problemi dell'API e aiuto con l'integrazione
• Documentazione: esempi completi, parametri e descrizioni degli endpoint

Non esiste un ambiente di test separato. Durante lo sviluppo puoi fare test in sicurezza con i tuoi dati reali usando query limitate.

Domande frequenti

Autenticazione e accesso

Come ottengo le credenziali dell'API? Se gestisci un solo club, vai su Impostazioni > Strumenti per sviluppatori in Playtomic Manager e generale tu stesso. Se sei proprietario di una catena, contatta il tuo account manager o il Customer Care via chat. Riceverai un link sicuro (valido per 3 giorni e apribile al massimo 3 volte) con il tuo Client ID e il tuo Client Secret.

Cosa devo fare se ricevo errori "Unauthorized" (401/403)? Controlla che:

• La tua richiesta includa l'header Authorization: Bearer token.
• Il tuo token di accesso non sia scaduto. Rinnovalo se necessario.
• Il tuo Client ID e il tuo Client Secret siano corretti.
• Tu non abbia superato i limiti di frequenza.

Un'altra persona della mia organizzazione può creare nuove credenziali? Sì, ma le nuove credenziali invalidano le precedenti. Condividi le credenziali all'interno della tua organizzazione per non interrompere le integrazioni esistenti.

Accesso ai dati

Posso creare o modificare prenotazioni tramite l'API? No. L'API è di sola lettura. Puoi recuperare e analizzare i dati, ma non puoi creare, modificare o eliminare prenotazioni.

Quanto storico delle prenotazioni posso ottenere? Le prenotazioni degli ultimi 3 mesi e tutte le prenotazioni future. Ogni richiesta può coprire fino a 365 giorni.

Posso ottenere pagamenti più vecchi di 13 mesi? Sì. 13 mesi è l'intervallo massimo di una singola richiesta, non un limite su quanto indietro risalgono i dati. Per ottenere un periodo più lungo, fai più richieste consecutive di massimo 13 mesi ciascuna.

Posso ottenere tutte le prenotazioni e i pagamenti degli anni precedenti?

• Pagamenti: sì, tramite l'API. Suddividi il periodo in più richieste di massimo 13 mesi ciascuna.
• Prenotazioni: no. Sia l'API sia l'elenco delle prenotazioni in Playtomic Manager includono solo gli ultimi 3 mesi.
• La sezione Report di Playtomic Manager mostra i totali dei periodi precedenti, ma non ogni singola prenotazione o pagamento.

In quale fuso orario sono i timestamp? Tutti i timestamp sono in UTC. La tua integrazione deve convertirli nel tuo fuso orario locale.

Gestione di più sedi e catene

Come proprietario di una catena, posso accedere ai dati di tutti i miei club? Sì. I proprietari di catene ottengono un accesso unificato ai dati di tutti i club della loro organizzazione. Puoi filtrare per club oppure ottenere i dati di tutte le sedi.

Tutte le sedi hanno bisogno di un abbonamento Champion o Master? Sì. Per l'accesso a più sedi, ogni tenant ha bisogno di un abbonamento Champion o Master.

Implementazione tecnica

Con quale frequenza posso chiamare l'API? Si applicano limiti di frequenza (di solito 1 chiamata al minuto). Consulta la documentazione per i limiti attuali.

Posso testare l'API prima di usarla in produzione? Non esiste un ambiente di test separato. Puoi fare test in sicurezza con i tuoi dati reali usando query limitate.

Verranno aggiunte altre funzionalità all'API? Sì. Stiamo lavorando a endpoint per i dati dei giocatori e a dati dettagliati su eventi, attività e clinic. Contatta il tuo account manager per richiedere funzionalità specifiche.

Supporto

Quali informazioni devo includere quando contatto il supporto?

• Il messaggio di errore completo
• L'endpoint che stavi chiamando
• L'ID del tuo club
• I passaggi che hai già provato

Chi devo contattare per ogni tipo di problema?

• Accesso per le catene: il tuo account manager o il Customer Care via chat
• Integrazione tecnica: il team di supporto tecnico
• Richieste di funzionalità: il tuo account manager
• Fatturazione o abbonamento: il tuo account manager

💬 Hai bisogno di aiuto?

Se hai domande o hai bisogno di ulteriore assistenza, non preoccuparti! 😊 Puoi sempre contattarci. Siamo qui per aiutarti!