Playtomic API: Täydellinen opas

Playtomic API:n avulla klubit voivat käyttää varaus- ja maksutietojaan ulkoisista järjestelmistä. Tässä oppaassa kerrotaan, kuka API:a voi käyttää, miten saat tunnukset, mitkä tiedot ovat saatavilla ja mitä rajoituksia on.

Mikä Playtomic API on?

Playtomic API on turvallinen, vain lukuoikeuden antava rajapinta, jonka avulla klubit voivat käyttää varaus- ja maksutietojaan muista järjestelmistä. Hallinnoitpa yhtä tai useampaa klubia, voit käyttää sitä seuraaviin tarkoituksiin:

• Integrointi nykyisiin järjestelmiisi, kuten CRM-järjestelmiin, markkinointityökaluihin, kanta-asiakasalustoihin tai tilojen hallintaohjelmistoihin
• Varaustietojen käyttö viimeisten 3 kuukauden ajalta sekä kaikista tulevista varauksista
• Yksityiskohtaisten maksutietojen käyttö, myös yli 1 vuoden takaisilta jaksoilta
• Tietojen synkronoinnin automatisointi klubin toiminnan sujuvoittamiseksi
• Jäsenviestinnän parantaminen ulkoisten työkalujen ja alustojen avulla

Kuka voi käyttää API:a?

API on käytettävissä seuraaville:

• Yhden toimipisteen klubit, joilla on Champion- tai Master-tilaus
• Usean toimipisteen klubit, joissa jokaisella tenantilla on Champion- tai Master-tilaus
• Ketjujen omistajat, jotka saavat keskitetyn pääsyn kaikkien organisaationsa klubien tietoihin

Mitä tietoja voin hakea API:n kautta?

API antaa vain lukuoikeuden. Voit hakea tietoja, mutta et voi luoda, muokata tai poistaa niitä.

Varaukset

• Varauksen ID ja aikaleimat (UTC)
• Kentän tiedot (ID, nimi)
• Pelaajien tiedot (ID:t, sähköposti, viestintäasetukset)
• Maksutiedot
• Ja paljon muuta (katso tietojen täydellinen määrittely)

Maksut

• Yksityiskohtaiset tiedot jokaisesta klubisi maksusta ja hyvityksestä, mukaan lukien maksun ID ja hyvityksen ID
• Kaikki kentät löydät maksujen endpointin dokumentaatiosta

Mitä toimintoja on tulossa seuraavaksi?

Työn alla ovat:

• Pelaajatietojen endpointit (samalla valtuutuksella)
• Yksityiskohtaiset tiedot tapahtumista, aktiviteeteista ja clinicseistä

Ota yhteyttä tilivastaavaasi, jos haluat pyytää tiettyjä toimintoja.

Miten saan API-tunnukset?

Yksittäiset klubit

Voit luoda ja hallita omia API-tunnuksiasi Playtomic Managerissa. Siirry kohtaan Asetukset > Kehittäjätyökalut. Siellä voit:

• Luoda tunnukset
• Luoda tunnukset uudelleen
• Poistaa tunnukset
• Lukea dokumentaation

📄 API:n täydellinen dokumentaatio (v1.1)

Huomaa: kopioi Client ID ja Client Secret ja säilytä ne turvallisessa paikassa. Käsittele Client Secretiä kuin salasanaa: älä jaa sitä julkisesti äläkä paljasta sitä front end -koodissa. Jos se katoaa, luo uudet tunnukset. Tämä mitätöi aiemmat tunnukset.

Ketjujen omistajat

Jos hallinnoit useita klubeja osana ketjua:

1. Ota yhteyttä Playtomicin tilivastaavaasi tai Customer Careen chatin kautta ja pyydä keskitettyä API-pääsyä kaikille toimipisteillesi.
2. Avaa suojattu linkki, jonka saat tunnustesi kanssa. Linkki on voimassa 3 päivää, ja sen voi avata enintään 3 kertaa.
3. Säilytä tunnuksesi turvallisesti. Linkki vanhenee, eikä sitä voi helposti luoda uudelleen.
4. Lue dokumentaatio ja aloita integrointi.

Huomaa: ketjun tunnuksilla on pääsy kaikkiin organisaatiosi klubeihin. Säilytä ne turvallisesti ja jaa ne vain valtuutetuille tiimin jäsenille.

Miten todennus toimii?

API käyttää OAuth 2.0 -protokollaa:

• Client ID ja Client Secret: klubisi tai järjestelmäsi yksilölliset tunnisteet
• Käyttötunnus (access token): väliaikainen tunniste (yleensä voimassa 1 tunnin), jota käytät API-kutsuissa

Esimerkki tunnuspyynnöstä:

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

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

Esimerkki API-kutsusta:

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

🔒 Tietoturvan parhaat käytännöt:

• Pidä Client Secret luottamuksellisena.
• Älä koskaan paljasta tunnuksia julkisissa repositorioissa.
• Määritä järjestelmiisi käyttötunnuksen automaattinen uusiminen.

Kuinka paljon tietoja voin hakea, ja mitkä ovat rajoitukset?

Varaukset

• Menneet varaukset: vain viimeiset 3 kuukautta. Vanhempia varauksia ei palauteta.
• Tulevat varaukset: saatavilla aikataulun mukaisesti.
• Enimmäisjakso pyyntöä kohden: 365 päivää (esimerkiksi viimeiset 3 kuukautta ja seuraavat 9 kuukautta).

Maksut

• Enimmäisjakso pyyntöä kohden: 13 kuukautta. Tämä rajoittaa kunkin pyynnön pituutta, ei sitä, kuinka kauas taaksepäin voit hakea tietoja.
• Pidemmät jaksot: jaa ne useaan peräkkäiseen pyyntöön, joista kukin on enintään 13 kuukautta. Esimerkiksi vuosille 2024–2026:
  1. 1.1.2024 – 31.1.2025
  2. 1.2.2025 – 28.2.2026
  3. 1.3.2026 – tähän päivään
• Ei päivämääräsuodatinta: jos et anna päivämääräsuodatinta, API palauttaa oletuksena viimeiset 13 kuukautta.
• Päivämäärän tyyppi: kukin pyyntö suodattaa joko maksupäivän tai palvelupäivän mukaan, ei molempien.
• Ensimmäinen pyyntö: API voi vastata 202 Accepted, kun se valmistelee klubisi maksuhistoriaa. Tämä kestää yleensä muutaman minuutin. Odota ja yritä uudelleen.

Aikavyöhyke

• Kaikki aikaleimat ovat UTC-ajassa. Varmista, että järjestelmäsi muuntavat ne paikalliseen aikavyöhykkeeseesi.
• Tarkista klubisi aikavyöhyke kohdasta Playtomic Manager > Asetukset > Klubin tiedot.

Kutsurajoitukset

API-kutsujen määrää on rajoitettu (yleensä 1 kutsu minuutissa) järjestelmän vakauden takaamiseksi. Tarkista voimassa olevat rajoitukset dokumentaatiosta.

Mihin voin käyttää API:a?

• CRM-synkronointi: tuo varaustiedot kohdennettuja markkinointikampanjoita varten
• Analytiikka ja raportointi: analysoi kenttien käyttöä, pelaajien pelitiheyttä ja maksuja
• Jäsenviestintä: lähetä automaattisia vahvistuksia ja muistutuksia ulkoisten työkalujen kautta
• Tilojen hallinta: integroi älylukkoihin, valaistukseen tai muihin IoT-järjestelmiin
• Kanta-asiakasohjelmat: seuraa jäsenten aktiivisuutta palkitsemista ja sitouttamista varten

Mistä saan apua API:n kanssa?

• Tilivastaava: toteutettavuuden arvioinnit, ketjujen pääsypyynnöt ja toimintopyynnöt
• Tekninen tuki: API:n vianmääritys ja apu integroinnissa
• Dokumentaatio: kattavat esimerkit, parametrit ja endpointien kuvaukset

Erillistä testiympäristöä ei ole. Kehityksen aikana voit testata turvallisesti oikeilla tiedoillasi käyttämällä rajattuja kyselyjä.

Usein kysytyt kysymykset

Todennus ja pääsy

Miten saan API-tunnukset? Jos hallinnoit yhtä klubia, siirry Playtomic Managerissa kohtaan Asetukset > Kehittäjätyökalut ja luo ne itse. Jos olet ketjun omistaja, ota yhteyttä tilivastaavaasi tai Customer Careen chatin kautta. Saat suojatun linkin (voimassa 3 päivää, voi avata enintään 3 kertaa), jossa ovat Client ID ja Client Secret.

Mitä teen, jos saan "Unauthorized"-virheitä (401/403)? Tarkista, että:

• Pyyntösi sisältää otsakkeen Authorization: Bearer token.
• Käyttötunnuksesi ei ole vanhentunut. Uusi se tarvittaessa.
• Client ID ja Client Secret ovat oikein.
• Et ole ylittänyt kutsurajoituksia.

Voiko joku muu organisaatiostani luoda uudet tunnukset? Kyllä, mutta uudet tunnukset mitätöivät aiemmat. Jaa tunnukset organisaatiosi sisällä, jotta nykyiset integraatiot eivät katkea.

Tietojen käyttö

Voinko luoda tai muokata varauksia API:n kautta? Et. API antaa vain lukuoikeuden. Voit hakea ja analysoida tietoja, mutta et voi luoda, muokata tai poistaa varauksia.

Kuinka pitkältä ajalta voin hakea varaushistoriaa? Viimeisten 3 kuukauden varaukset sekä kaikki tulevat varaukset. Kukin pyyntö voi kattaa enintään 365 päivää.

Voinko hakea yli 13 kuukautta vanhoja maksuja? Kyllä. 13 kuukautta on yksittäisen pyynnön enimmäisjakso, ei raja sille, kuinka kauas taaksepäin tiedot ulottuvat. Jos haluat hakea pidemmän jakson, tee useita peräkkäisiä pyyntöjä, joista kukin on enintään 13 kuukautta.

Voinko hakea kaikki varaukseni ja maksuni edellisiltä vuosilta?

• Maksut: kyllä, API:n kautta. Jaa jakso useaan pyyntöön, joista kukin on enintään 13 kuukautta.
• Varaukset: ei. Sekä API että Playtomic Managerin varausluettelo sisältävät vain viimeiset 3 kuukautta.
• Playtomic Managerin Raportit-osio näyttää vanhempien jaksojen kokonaissummat, mutta ei jokaista yksittäistä varausta tai maksua.

Missä aikavyöhykkeessä aikaleimat ovat? Kaikki aikaleimat ovat UTC-ajassa. Integraatiosi täytyy muuntaa ne paikalliseen aikavyöhykkeeseesi.

Useat toimipisteet ja ketjujen hallinta

Voinko ketjun omistajana käyttää kaikkien klubieni tietoja? Kyllä. Ketjujen omistajat saavat keskitetyn pääsyn kaikkien organisaationsa klubien tietoihin. Voit suodattaa klubin mukaan tai hakea kaikkien toimipisteiden tiedot.

Tarvitsevatko kaikki toimipisteet Champion- tai Master-tilauksen? Kyllä. Usean toimipisteen käyttöä varten jokaisella tenantilla on oltava Champion- tai Master-tilaus.

Tekninen toteutus

Kuinka usein voin kutsua API:a? Kutsurajoitukset ovat käytössä (yleensä 1 kutsu minuutissa). Tarkista voimassa olevat rajoitukset dokumentaatiosta.

Voinko testata API:a ennen käyttöönottoa? Erillistä testiympäristöä ei ole. Voit testata turvallisesti oikeilla tiedoillasi käyttämällä rajattuja kyselyjä.

Lisätäänkö API:in uusia toimintoja? Kyllä. Työn alla ovat pelaajatietojen endpointit sekä yksityiskohtaiset tiedot tapahtumista, aktiviteeteista ja clinicseistä. Ota yhteyttä tilivastaavaasi, jos haluat pyytää tiettyjä toimintoja.

Tuki

Mitä tietoja minun pitää antaa, kun otan yhteyttä tukeen?

• Koko virheilmoitus
• Endpoint, jota kutsuit
• Klubisi ID
• Vaiheet, joita olet jo kokeillut

Keneen otan yhteyttä missäkin asiassa?

• Ketjujen pääsy: tilivastaavaasi tai Customer Careen chatin kautta
• Tekninen integrointi: tekniseen tukitiimiin
• Toimintopyynnöt: tilivastaavaasi
• Laskutus tai tilaus: tilivastaavaasi

💬 Tarvitsetko apua?

Jos sinulla on kysyttävää tai tarvitset lisäapua, älä huoli! 😊 Voit aina ottaa meihin yhteyttä. Olemme täällä auttamassa!