Den Verein erkunden

Diese Anleitung führt durch die häufigsten Leseoperationen: Herausfinden, auf welche Vereine Ihr Konto Zugriff hat, und anschließendes Abrufen von Spielern, Trackern, Mannschaften und Sessions — alles mit einfachen HTTP-Aufrufen, die Sie direkt mit curl ausführen können.

Die in diesen Beispielen verwendete Staging-URL ist:

https://api.dp.dev.tracktics.systems

Ersetzen Sie <ihr-firebase-jwt> in allen Anfragen durch das Firebase-ID-Token Ihres Kontos.

---

Schritt 1 — Ihre Vereine abrufen

Der erste Aufruf ist fast immer GET /my_clubs. Er gibt alle Vereine zurück, auf die Ihr Konto Zugriff hat, zusammen mit Ihren Rollen in jedem Verein.

curl -s \
  -H "Authorization: Bearer <ihr-firebase-jwt>" \
  https://api.dp.dev.tracktics.systems/my_clubs

Beispielantwort

{
  "clubs": [
    {
      "club_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "FC Beispiel",
      "avatar": "/avatars/fc-beispiel.png",
      "timestamp": "2025-01-15T10:00:00Z",
      "revision": 1
    }
  ],
  "roles": [
    ["club admin", "club editor"]
  ]
}

Das roles-Array ist parallel zum clubs-Array aufgebaut — roles[0] enthält die Rollen für clubs[0] usw.

Notieren Sie sich die club_id; Sie wird für alle weiteren Aufrufe benötigt.

---

Schritt 2 — Vollständigen Vereins-Snapshot abrufen (BFF)

Der BFF-Endpunkt GET /v1/bff/club/{club_id} liefert Spieler, Tracker, Rollen und Tracker-Spieler-Zuordnungen in einer einzigen Anfrage. Dies ist der empfohlene Ausgangspunkt für jede Vereinsansicht, da dadurch mehrere Einzelabrufe entfallen.

CLUB_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"

curl -s \
  -H "Authorization: Bearer <ihr-firebase-jwt>" \
  "https://api.dp.dev.tracktics.systems/v1/bff/club/${CLUB_ID}"

Beispielantwort

{
  "club": {
    "club_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "FC Beispiel",
    "avatar": "/avatars/fc-beispiel.png",
    "timestamp": "2025-01-15T10:00:00Z",
    "revision": 1
  },
  "players": [
    {
      "player_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "club_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Alice Müller",
      "avatar": "/avatars/alice.png",
      "timestamp": "2025-01-15T10:30:00Z",
      "revision": 1
    },
    {
      "player_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "club_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Bob Schmidt",
      "avatar": "/avatars/bob.png",
      "timestamp": "2025-01-15T10:35:00Z",
      "revision": 1
    }
  ],
  "trackers": [
    {
      "tracker_id": "d4e5f6a7-b8c9-0123-def1-234567890123",
      "club_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Tracker 01",
      "timestamp": "2025-01-15T11:00:00Z",
      "revision": 1
    }
  ],
  "roles": [
    {
      "role_id": "e5f6a7b8-c9d0-1234-ef12-345678901234",
      "club_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_id": "f6a7b8c9-d0e1-2345-f123-456789012345",
      "roles": ["club admin", "club editor"],
      "timestamp": "2025-01-15T09:00:00Z",
      "revision": 1
    }
  ],
  "tracker_player_relations": [
    {
      "relation_id": "a7b8c9d0-e1f2-3456-a123-456789012345",
      "tracker_id": "d4e5f6a7-b8c9-0123-def1-234567890123",
      "player_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "club_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "timestamp": "2025-01-15T11:30:00Z",
      "revision": 1
    }
  ]
}

Feld	Inhalt
club	Vereinsmetadaten (Name, Avatar)
players	Alle im Verein registrierten Spieler
trackers	Alle GPS-Tracker des Vereins
roles	Nutzer-Rollen-Zuweisungen innerhalb des Vereins
tracker_player_relations	Aktuelle Tracker ↔ Spieler-Zuordnungen

---

Schritt 3 — Mannschaften auflisten

Mannschaften sind Untermengen des Vereins. Verwenden Sie den Standard-Listen-Endpunkt:

curl -s \
  -H "Authorization: Bearer <ihr-firebase-jwt>" \
  "https://api.dp.dev.tracktics.systems/clubs/${CLUB_ID}/teams"

Beispielantwort

[
  {
    "team_id": "f7a8b9c0-d1e2-3456-f123-456789012345",
    "club_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Erste Mannschaft",
    "timestamp": "2025-01-10T08:00:00Z",
    "revision": 1
  },
  {
    "team_id": "07b8c9d0-e1f2-4567-0123-456789012345",
    "club_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "U17",
    "timestamp": "2025-01-10T08:05:00Z",
    "revision": 1
  }
]

Notieren Sie sich die team_id-Werte — sie werden für die Abfrage von Sessions in Schritt 4 benötigt.

---

Schritt 4 — Sessions einer Mannschaft auflisten

Sessions sind einer Mannschaft zugeordnet. Ersetzen Sie team_id durch den Wert aus Schritt 3:

TEAM_ID="f7a8b9c0-d1e2-3456-f123-456789012345"

curl -s \
  -H "Authorization: Bearer <ihr-firebase-jwt>" \
  "https://api.dp.dev.tracktics.systems/clubs/${CLUB_ID}/teams/${TEAM_ID}/sessions"

Beispielantwort

[
  {
    "session_id": "17c8d9e0-f1a2-5678-1234-567890123456",
    "club_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "team_id": "f7a8b9c0-d1e2-3456-f123-456789012345",
    "name": "Training 2025-01-15",
    "start": "2025-01-15T16:00:00Z",
    "end": "2025-01-15T17:30:00Z",
    "timestamp": "2025-01-15T16:00:00Z",
    "revision": 1
  }
]

Für einen bestimmten Zeitraum können from und until als Query-Parameter (ISO 8601) angegeben werden:

curl -s \
  -H "Authorization: Bearer <ihr-firebase-jwt>" \
  "https://api.dp.dev.tracktics.systems/clubs/${CLUB_ID}/teams/${TEAM_ID}/sessions?from=2025-01-01T00:00:00Z&until=2025-02-01T00:00:00Z&order=asc"

---

Paginierung

Alle Listen-Endpunkte (/teams, /sessions, /players, /trackers) unterstützen cursor-basierte Paginierung über den Pagination-Next-Token-Response-Header. Ist der Header vorhanden, gibt es weitere Ergebnisse:

# Erste Seite
curl -si \
  -H "Authorization: Bearer <ihr-firebase-jwt>" \
  "https://api.dp.dev.tracktics.systems/clubs/${CLUB_ID}/teams/${TEAM_ID}/sessions?limit=10" \
  | grep -E "Pagination-Next-Token|^\["

# Nächste Seite — Token aus dem Header verwenden
curl -s \
  -H "Authorization: Bearer <ihr-firebase-jwt>" \
  "https://api.dp.dev.tracktics.systems/clubs/${CLUB_ID}/teams/${TEAM_ID}/sessions?limit=10&next_token=<token-aus-header>"

Parameter	Standard	Beschreibung
limit	100	Einträge pro Seite (Maximum 100)
next_token	—	Cursor aus dem Pagination-Next-Token-Header
order	desc	asc für älteste zuerst, desc für neueste zuerst
from	—	Nur Einträge ab diesem Zeitstempel zurückgeben
until	—	Nur Einträge bis zu diesem Zeitstempel zurückgeben

---

Nächste Schritte

• Live-Positionsdaten einer Session über WebSocket-Kanäle abonnieren
• Historische Positionsdaten über den REST-Positions-Endpunkt abfragen (GET /clubs/{club_id}/trackers/{tracker_id}/positions)