Klucze API i Integration API

Dzięki Integration API Ticsie Twój własny system może pobierać wydarzenia i uczestników oraz odprawiać bilety – w komunikacji serwer–serwer. W tym artykule dowiesz się, jak utworzyć parę kluczy, jakie są dostępne uprawnienia i co potrafi API. Pełną dokumentację referencyjną znajdziesz w dokumentacji API.

Do czego można używać API?

Do pobierania list uczestników do własnego systemu, np. rejestru członków lub systemu akredytacji.
Do budowy własnego pulpitu z danymi o Twoich wydarzeniach.
Do podłączenia własnego skanera lub bramki, która odprawia bilety przez API.

API jest przeznaczone do wywołań serwer–serwer. Kluczy nigdy nie wolno umieszczać w aplikacji ani na stronie internetowej, którą widzą odwiedzający.

Utwórz parę kluczy

Otwórz klucze API. Przejdź do Ustawienia → Klucze API. Potrzebujesz roli Właściciel lub Administrator.
Nazwij klucz. W sekcji Utwórz nową parę kluczy wypełnij pole Nazwa klucza, np. „Rejestr członków” – żeby później wiedzieć, do czego służy.
Wybierz uprawnienia. Zaznacz read i/lub write (zobacz tabelę poniżej).
Wygeneruj. Kliknij Wygeneruj parę kluczy. Otrzymasz klucz publiczny (zaczynający się od ticsie_pk_) i klucz tajny (zaczynający się od ticsie_sk_).
Od razu zapisz klucz tajny. Pod nagłówkiem Zapisz swój klucz tajny teraz klucz tajny jest wyświetlany tylko raz. Kliknij Kopiuj i przechowuj go w bezpiecznym miejscu, np. w menedżerze haseł lub jako zmienną środowiskową na swoim serwerze.

Ważne

Klucz tajny jest wyświetlany tylko raz i nie można go później odzyskać – Ticsie nie przechowuje go w postaci jawnej. Jeśli go zgubisz, unieważnij parę kluczy i utwórz nową.

Uprawnienia

Uprawnienie	W panelu	Daje dostęp do
`read`	Odczyt wydarzeń, zamówień i uczestników	Pobierania wydarzeń i uczestników (żądania GET).
`write`	Tworzenie i modyfikacja danych przez API	Skanowania biletów i odprawiania uczestników (żądania POST).

Nadawaj każdemu kluczowi jak najmniej uprawnień. Klucz, który tylko pobiera listy uczestników, potrzebuje wyłącznie read.

Żądania, endpointy i limity

Każde żądanie wysyłasz na adres https://ticsie.se/api/v1/integration z dwoma nagłówkami:

X-API-Key: ticsie_pk_...
X-API-Secret: ticsie_sk_...

Endpoint	Uprawnienie	Działanie
`GET /events`	read	Zwraca listę Twoich wydarzeń. Filtruj parametrem `period` = `future`, `past` lub `all`.
`GET /events/{id}/attendees`	read	Zwraca listę uczestników (opłacone bilety) danego wydarzenia, po 50 na stronę.
`POST /events/{id}/scan`	write	Odprawia bilet na podstawie jego UUID (wartości zapisanej w kodzie QR biletu).

Limit zapytań: 60 żądań na minutę. Po jego przekroczeniu API odpowiada kodem HTTP 429 – odczekaj chwilę i spróbuj ponownie.
Stronicowanie: listy są dzielone na strony. Kolejną stronę pobierzesz parametrem ?page=2.
Błędy są zwracane jako JSON z polem error_code, np. API_KEY_INVALID lub INSUFFICIENT_PERMISSION.

Przykładowe żądania w kilku językach programowania, formaty odpowiedzi i wszystkie kody błędów znajdziesz w dokumentacji API.

Unieważnianie klucza

Lista w sekcji Klucze API pokazuje wszystkie pary kluczy z nazwą, kluczem publicznym, uprawnieniami i datą utworzenia. Kliknij Unieważnij i potwierdź przyciskiem Tak, unieważnij. Klucz natychmiast przestaje działać. Zawsze unieważniaj klucze, których już nie używasz albo które mogły trafić w niepowołane ręce.

Najczęściej zadawane pytania

Zgubiłem klucz tajny – czy mogę go zobaczyć ponownie?

Nie. Klucz tajny jest wyświetlany tylko podczas tworzenia pary kluczy. Unieważnij starą parę kluczy i utwórz nową.

Dlaczego dostaję błąd INSUFFICIENT_PERMISSION?

Klucz nie ma uprawnienia wymaganego przez dany endpoint. Odprawa przez POST /events/{id}/scan wymaga uprawnienia write. Utwórz nową parę kluczy z właściwym uprawnieniem.

Czy mogę użyć klucza API w aplikacji mobilnej lub na swojej stronie internetowej?

Nie, klucze powinny być używane wyłącznie na serwerze. Do odprawy na telefonie użyj aplikacji Ticsie.

Czy mogę tworzyć wydarzenia lub zamówienia przez API?

Obecnie nie. Integration API udostępnia trzy opisane wyżej endpointy. Czegoś Ci brakuje? Zgłoś pomysł na stronie Suggestions & roadmap (pomysły i roadmapa).