Wymiana danych

Parkour Design udostępnia obecnie skoordynowaną usługę zasobów tylko do odczytu, zawierającą podsumowania Wydarzeń i projektów parkurów. Pełna geometria projektu, pliki, operacje zapisu i synchronizacja wymagają odrębnego kontraktu z partnerem.

Status kontraktu: Poniższe endpointy opisują obecnie wdrożone działanie dla zatwierdzonych klientów. Nie stanowią jeszcze wersjonowanego, ogólnego API. Nie twórz integracji korzystającej z tych endpointów, dopóki Parkour Design nie potwierdzi dostępu, zakresów uprawnień, limitów i kontraktu uruchomieniowego.

Bazowy adres URL i uwierzytelnianie

Jako bazowego adresu URL API użyj wystawcy wybranego dla danego środowiska OAuth:

Token dostępu Parkour Design wysyłaj z usługi backendowej:

Authorization: Bearer <access_token>
Accept: application/json

Token dostępu musi być ważny dla skonfigurowanego wystawcy i odbiorcy parkour-api, zawierać token_use o wartości access_token, a obecnie także openid.

API nie udostępnia obecnie dostępu z przeglądarki między różnymi źródłami. Nie ujawniaj tokena dostępu ani tokena odświeżania kodowi JavaScript frontendu.

Lista Wydarzeń

GET /api/events

Przykładowe żądanie:

curl "${ISSUER}/api/events" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"

Przykładowa odpowiedź:

{
  "items": [
    {
      "id": "abcdefghijklmnopqrstuv",
      "name": "Example Event",
      "startDate": "2026-07-24T00:00:00Z",
      "endDate": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T18:42:10Z",
      "designCount": 4
    }
  ]
}

Obecny typ odpowiedzi:

type EventSummary = {
  id: string;
  name: string;
  startDate: string | null;
  endDate: string | null;
  updatedAt: string | null;
  designCount: number;
};

type EventsResponse = {
  items: EventSummary[];
};

Wydarzenia są zestawiane na podstawie nieusuniętych projektów uwierzytelnionego użytkownika. Projekty bez identyfikatora Wydarzenia są pomijane.

Traktuj id jako wartość nieprzezroczystą. Skopiuj ją bez zmian do żądania podsumowań projektów. Nie wnioskuj o jej formacie ani nie generuj jej w systemie partnera.

Lista podsumowań projektów dla Wydarzenia

GET /api/events/{eventId}/designs

Przykładowe żądanie:

curl "${ISSUER}/api/events/${EVENT_ID}/designs" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"

Przykładowa odpowiedź:

{
  "event": {
    "id": "abcdefghijklmnopqrstuv",
    "name": "Example Event",
    "startDate": "2026-07-24T00:00:00Z",
    "endDate": "2026-07-26T00:00:00Z",
    "updatedAt": "2026-07-26T18:42:10Z",
    "designCount": 4
  },
  "items": [
    {
      "id": "design-record-id",
      "localId": "design-local-id",
      "eventId": "abcdefghijklmnopqrstuv",
      "title": "Grand Prix",
      "eventName": "Example Event",
      "eventDate": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T18:42:10Z",
      "authorName": "Course Designer",
      "shortDescr": "Competition description"
    }
  ]
}

Obecny typ odpowiedzi:

type DesignSummary = {
  id: string;
  localId: string | null;
  eventId: string;
  title: string;
  eventName: string;
  eventDate: string | null;
  updatedAt: string | null;
  authorName: string | null;
  shortDescr: string;
};

type EventDesignsResponse = {
  event: EventSummary;
  items: DesignSummary[];
};

Daty, jeśli występują, są ciągami znaków zgodnymi z ISO 8601 w strefie UTC. Klienci muszą obsługiwać wartość null dla opcjonalnych dat i pola localId.

Własność i widoczność

Atrybut sub tokena bearer identyfikuje właściciela zasobów Parkour Design. Odpowiedzi zawierają wyłącznie nieusunięte projekty należące do tego użytkownika.

Obecna usługa nie zapewnia:

• dostępu na poziomie całej organizacji ani zespołu;
• dostępu do udostępnionych lub publicznych projektów innego użytkownika;
• filtrowania zasobów właściwego dla danego klienta;
• usuniętych projektów;
• danych dotyczących subskrypcji, profilu ani płatności.

Zarówno nieistniejące Wydarzenie, jak i Wydarzenie należące do innego użytkownika zwracają 404. Nie używaj tej odpowiedzi do wnioskowania, czy zasób innego użytkownika istnieje.

Obecne limity i kolejność

Obecne endpointy nie przyjmują parametrów filtrowania, sortowania, stronicowania, kursorów ani synchronizacji przyrostowej.

• /api/events zwraca zestawioną listę Wydarzeń w jednej odpowiedzi.
• /api/events/{eventId}/designs zwraca maksymalnie 500 podsumowań.
• Odpowiedź nie informuje obecnie o obcięciu wyników ani nie udostępnia kursora kontynuacji.
• Kolejność wynika z obecnej implementacji i nie jest jeszcze gwarantowana przez wersjonowany kontrakt.

Przed zatwierdzeniem integracji produkcyjnej Parkour Design i partner muszą potwierdzić, że oczekiwany wolumen danych mieści się w tych limitach. Partner wymagający pełnego stronicowania lub aktualizacji przyrostowych nie może obchodzić ograniczeń przez pobieranie danych metodą screen scrapingu ani odgadywanie identyfikatorów; wymaga to zmiany kontraktu.

Odpowiedzi błędów

Błędy używają zwartego obiektu JSON:

{"error": "not_found"}

Nieoczekiwane awarie usługi nie mają jeszcze odrębnego, wersjonowanego schematu błędów. Klienci powinni uznawać inne odpowiedzi 5xx za kwalifikujące się do ponowienia wyłącznie w przypadku idempotentnych operacji GET, stosując ograniczone wykładnicze wydłużanie czasu oczekiwania z losowym odchyleniem.

Dane nieudostępniane przez to API

Podsumowanie projektu nie jest kompletnym projektem parkuru. Obecne API zasobów nie udostępnia:

• geometrii parkuru ani trasy;
• przeszkód, grup, układu placu ani obiektów rysunkowych;
• wygenerowanych plików PDF, podglądów, obrazów ani adresów URL pobierania;
• operacji tworzenia, aktualizowania, usuwania ani przesyłania;
• wyszukiwania pojedynczego projektu według jego identyfikatora;
• webhooków ani strumienia zmian;
• tokenów dostępu Eqify, sesji, Konkursów, aktywności ani zapisanych miejsc docelowych.

Nie przedstawiaj odpowiedzi z podsumowaniem jako projektu parkuru gotowego do wydruku lub edycji.