API: Twoje biegi i zapisy w innych programach
API to umówiony sposób, w jaki inne programy - strona internetowa klubu, arkusz, system firmy mierzącej czas - pobierają dane z JogRun albo przesyłają nam zgłoszenia. Bez przepisywania i bez wysyłania plików mailem. Ty niczego nie programujesz: w panelu tworzysz klucz i przekazujesz go programiście albo firmie, z którą współpracujesz.
Bez programisty: widżet na stronę klubu
Jeśli chcesz tylko pokazać swoje biegi na stronie klubu - z datą, miejscowością, dystansami, wolnymi miejscami, dzisiejszą ceną i stanem zapisów - nie potrzebujesz klucza ani programisty. W panelu czeka gotowy fragment HTML, który wklejasz na stronę tak jak film z YouTube. Dalej widżet dba o siebie sam: nowy bieg pojawia się w nim, gdy go opublikujesz, a cena i wolne miejsca zmieniają się bez Twojego udziału.
W panelu wybierz „API i webhooki”. Na górze strony jest „Widżet na stronę klubu”.
Wybierz, czy widżet ma pokazywać wszystkie biegi klubu, czy jeden, i w jakim języku - polskim albo angielskim. Obok od razu widzisz podgląd.
Skopiuj fragment i wklej go na stronę klubu: w WordPressie do bloku „Własny HTML”, w Wiksie do elementu „Osadź HTML”, na zwykłej stronie - w kod, tam gdzie mają być biegi.
- „Zapisz się” otwiera formularz zapisu na naszej stronie, w nowej karcie - po angielsku, gdy widżet jest po angielsku (chyba że biegacz wybrał już u nas inny język). Płatność nigdy nie odbywa się w ramce na cudzej stronie.
- Widżet pokazuje nadchodzące biegi opublikowane w katalogu. Biegi udostępnione tylko z linkiem, czekające na płatności i szkice się w nim nie pojawiają, a w okresie próbnym jest pusty - biegi pojawią się same po aktywacji konta.
- Kolory bierze z brandingu klubu. Nie zapisuje ciasteczek, nie ma w nim analityki ani żadnego formularza.
Do widżetu programista nie jest potrzebny. Klucz API przyda się dopiero wtedy, gdy strona klubu ma robić coś więcej, na przykład przyjmować zgłoszenia we własnym formularzu - o tym dalej.
Co możesz z tym zrobić
Kalendarz biegów na stronie klubu
Strona klubu sama pokazuje Twoje opublikowane biegi: nazwę, datę, miejscowość, link do strony zapisów i to, czy zapisy są teraz otwarte. Nowy bieg pojawia się tam, gdy go opublikujesz, a gdy zapisy się zamkną, strona wie o tym od razu - nikt nie musi jej poprawiać. Biegi udostępnione tylko z linkiem i biegi czekające na płatności się tam nie pokazują.
Uprawnienie: „Odczyt wydarzeń”. Wystarczy klucz publiczny, także w kodzie strony.
Wolne miejsca i aktualna cena
Przy każdym dystansie: limit, ile miejsc jest już zajętych, ile zostało i jaka cena obowiązuje dziś. Gdy zaczyna się kolejny próg cenowy, cena na stronie klubu zmienia się sama. Liczba wolnych miejsc może spóźniać się o kilka sekund - o tym, czy ktoś się zmieści, decyduje chwila zapisu.
Uprawnienie: „Odczyt wydarzeń”. Wystarczy klucz publiczny, także w kodzie strony.
Zapisy przez formularz na stronie klubu
Biegacz wypełnia formularz na stronie Twojego klubu, a strona przesyła zgłoszenie do nas. Rezerwujemy mu miejsce i odsyłamy link, pod którym na naszej stronie zaznacza zgody i płaci; jeśli nie zapłaci na czas, miejsce wraca do puli. Obowiązują te same zasady co przy zapisie u nas: limity miejsc, progi cenowe, zamknięcie zapisów w chwili startu. Zgłoszenie widzisz w panelu jak każde inne, a strona klubu może sprawdzić, czy zostało opłacone. Pola formularza na stronie klubu muszą pasować do formularza biegu w kreatorze - jeśli dodasz tam nowe pole obowiązkowe, dodaj je też u siebie, inaczej zgłoszenie zostanie odrzucone.
Uprawnienia: „Odczyt wydarzeń” i „Tworzenie zgłoszeń”. Tylko klucz sekretny, na serwerze strony - to zadanie dla programisty.
Zgłoszenia prosto do arkusza albo programu klubu
Program klubu sam pobiera listę zgłoszeń - na przykład co noc, tylko opłacone, z jednego dystansu albo ze wszystkich: imię i nazwisko, e-mail, telefon, datę urodzenia, płeć, klub, miejscowość, numer startowy, kategorię i wpisowe. Przyda się do ubezpieczenia, księgowości albo ewidencji członków. To te same dane co w eksporcie z panelu i tak samo trzeba o nie dbać - jesteś ich administratorem. Bez uprawnienia do danych osobowych lista przychodzi bez nich: wystarczy, żeby policzyć zgłoszenia.
Uprawnienia: „Odczyt wydarzeń” i „Dane osobowe uczestników”. Tylko klucz sekretny.
Pomiar czasu bez przesyłania plików
Firma mierząca czas sama pobiera listę startową - całą albo tylko zmiany od poprzedniego razu - więc przekazany numer czy zmiana dystansu dociera do niej bez telefonu do Ciebie. Po biegu wgrywa wyniki: najpierw widzisz je tylko Ty, w panelu, a po publikacji - przez firmę albo przez Ciebie w panelu - trafiają na stronę biegu, a biegacze dostają mail z wynikiem (chyba że z takich maili zrezygnowali). Jeśli mierzy nasz partner, przypinasz go w ustawieniach biegu (Wydarzenia → bieg → Ustawienia → Pomiar czasu) i klucz powstaje sam, ograniczony do tego jednego biegu.
Uprawnienia: lista startowa i wgrywanie wyników, dla jednego biegu. Tylko klucz sekretny.
Pomiar czasu z naszym partnerem - orientacyjny cennik
Jak zacząć - krok po kroku
Klucze działają na aktywnym koncie klubu, czyli po rejestracji i opłacie rejestracyjnej. Na koncie próbnym klucz utworzysz, ale jeszcze nie zadziała.
W panelu wybierz „API i webhooki”, a potem „Nowy klucz”. Klucze tworzy i unieważnia właściciel albo administrator klubu; pozostali członkowie zespołu tylko je widzą.
Nazwij klucz tak, żeby za rok było jasne, kto go używa: „Strona klubu”, „Firma pomiarowa”.
Zaznacz tylko te uprawnienia, których ten jeden program naprawdę potrzebuje - co do czego, mówi lista niżej.
Klucz dla jednego biegu, na przykład dla firmy mierzącej czas, zawęź w polu „Ograniczenie do wydarzenia”. Taki klucz nie zobaczy żadnego innego Twojego biegu.
Jeśli strona klubu ma czytać dane prosto w przeglądarce odwiedzającego, wpisz jej adres w „Dozwolone origin”, na przykład https://klub.example.pl. Programista powie Ci, jaki adres podać.
Kliknij „Utwórz klucz”. Dostaniesz dwa klucze: publiczny (zaczyna się od pk_) i sekretny (od sk_). Sekret pokazujemy tylko raz - skopiuj go od razu. Jeśli zginie, utwórz nowy klucz, a stary unieważnij.
Klucz, który nie jest już potrzebny, unieważnij przyciskiem „Unieważnij”. Przestaje działać od razu. Przy każdym kluczu widzisz datę ostatniego użycia - klucz, którego nikt nie używa od miesięcy, to kandydat do unieważnienia.
Które uprawnienie do czego
Tak uprawnienia są opisane w formularzu nowego klucza - a tak ich używać:
- Odczyt wydarzeń, dystansów, progów cenowych i wolnych miejsc.
- Kalendarz, wolne miejsca, ceny; lista zgłoszeń bez danych osobowych. Działa z kluczem publicznym.
- Dane osobowe uczestników i lista startowa.
- Dane uczestników do własnego arkusza albo programu. Tylko klucz sekretny.
- Tworzenie zgłoszeń w imieniu uczestnika.
- Formularz zapisu na stronie klubu. Tylko klucz sekretny.
- Odczyt wyników po ich opublikowaniu.
- Dziś nic nie otwiera - wyniki są na stronie wyników biegu. Nie zaznaczaj.
- Lista startowa dla pomiaru czasu - imiona i nazwiska, numery, chipy, kategorie; bez e-maili, telefonów i płatności.
- Dla firmy mierzącej czas. Tylko klucz sekretny.
- Wgrywanie wyników i ich publikacja.
- Dla firmy mierzącej czas. Tylko klucz sekretny.
- Zarządzanie webhookami organizatora.
- Dziś nic nie otwiera. Nie zaznaczaj.
Bezpieczeństwo
- Klucz sekretny jest jak hasło do listy Twoich uczestników. Nie wklejaj go do kodu strony, nie wysyłaj na czacie grupowym ani zwykłym mailem - przekaż go osobiście albo przez menedżer haseł.
- Klucz publiczny może być widoczny w kodzie strony klubu. Widzi tylko to, co i tak jest publiczne - biegi, ceny, wolne miejsca - nigdy danych osobowych uczestników, i niczego nie zmieni.
- Gdyby ktoś wkleił klucz sekretny do strony, odrzucimy każde zapytanie wysłane z nim z przeglądarki - błąd wyjdzie od razu, a nie dopiero po wycieku danych.
- Każdy program dostaje osobny klucz, z samymi potrzebnymi uprawnieniami i - gdzie się da - ograniczony do jednego biegu. Unieważnienie jednego klucza nie psuje pozostałych.
- Gdy programista kończy współpracę albo sekret mógł trafić w niepowołane ręce, unieważnij klucz i utwórz nowy.
- Jeśli platforma zawiesi konto klubu, klucze przestają działać, ale nie trzeba ich wymieniać: program dostaje odpowiedź, że konto organizatora jest zawieszone, a po odwieszeniu te same klucze działają znowu.
Limity i koszty
- API nic nie kosztuje. Zgłoszenie z formularza na stronie klubu rozlicza się tak samo jak zapis na naszej stronie.
- Jeden klucz może wysłać do 600 zapytań na minutę - dużo więcej, niż potrzebuje strona klubu czy firma pomiarowa. Program, który przekroczy limit, dostaje prośbę, żeby chwilę poczekał.
- Lista zgłoszeń przychodzi porcjami, do 500 pozycji naraz.
- Miejsce zarezerwowane przez formularz na stronie klubu czeka na płatność tyle samo, co przy zapisie na naszej stronie, potem wraca do puli.
Czego API dziś nie robi
- Nie wysyła powiadomień (webhooków) na adres Twojego programu, choć menu w panelu nazywa się „API i webhooki”. Program, który chce wiedzieć o zmianach, pyta nas co kilka minut - lista startowa podaje wtedy tylko to, co się zmieniło.
- Nie przyjmuje zgód ani płatności. Zgoda musi być oświadczeniem samego uczestnika, więc zapis zawsze kończy się na naszej stronie.
- Nie zmienia ani nie anuluje zgłoszeń - to robisz w panelu.
- Nie podaje wyników do odczytu - wyniki są na stronie wyników biegu.
Co przekazać programiście
Programiście albo firmie, która podłącza API, wystarczy kilka rzeczy:
- Link do opisu technicznego - są tam wszystkie operacje, gotowe przykłady do skopiowania i plik dla generatorów kodu.
- Klucz publiczny i - jeśli program działa na serwerze - klucz sekretny, przekazany bezpiecznie.
- Nazwę biegu albo biegów, których dotyczy praca. Identyfikator biegu programista znajdzie sam w API.
- Informację, że zgody i płatność uczestnik zawsze kończy na naszej stronie, pod linkiem, który program dostanie z API.