Belegungsdaten Häufige Fragen API
Jawengo API

Weitere Endpunkte

API Konzept

Diese Übersicht listet die Adressen der Jawengo API, die mit einem API-Schlüssel erreichbar sind. Jede Adresse steht auch mit dem Präfix /api/v1/ zur Verfügung. Alle Anfragen senden den Header API_KEY, wie in der Authentifizierung beschrieben. Die Daten stammen aus dem Center; welche Endpunkte verfügbar sind, hängt von den installierten Modulen ab.

Begriffe

Begriff Bedeutung Beispiel Sportcenter Seebach
Endpunkt Eine Adresse der API mit fester Aufgabe. /api/sports liefert alle Sportarten
GET Daten lesen; verändert nichts. Belegung eines Standorts abfragen
POST, DELETE Daten anlegen, ändern oder stornieren. Eine Reservierung anlegen oder stornieren

Antwortformat

Lesende Endpunkte (GET) liefern das JSON direkt. Schreibende Endpunkte (POST, DELETE) antworten immer mit einem JSON-RPC-Umschlag; der HTTP-Status bleibt 200, auch bei Fehlern des Controllers, die im Feld result stehen:

{"jsonrpc": "2.0", "id": null, "result": "cancel"}

Ein fehlender, ungültiger oder gesperrter Schlüssel liefert dagegen den HTTP-Status 403.

Lesende Endpunkte

Adresse Liefert Parameter
GET /api/ping Text pong; Verbindungstest –
GET /api/sports Sportarten mit Standorten und Plätzen –
GET /api/sports/<id> Eine Sportart –
GET /api/pitches Plätze mit Standort und Sportart –
GET /api/location/<id>/power Belegung je Zeitfenster, siehe Belegungsdaten date
GET /api/sports/<id>/availability Freie Zeitfenster (time_slots) mit freien Plätzen; Preis nur mit location location, date, duration, time_from, time_to
GET /api/reservation Reservierungen des Benutzers und seiner Firma sport, location, date_from, date_to, state

Die Suche nach Reservierungen zeigt ohne Datumsangabe die nächsten 30 Tage und blendet stornierte Reservierungen aus.

Schreibende Endpunkte

Diese Endpunkte erwarten einen JSON-Inhalt im Körper der Anfrage und den Header Content-Type: application/json. Senden Sie die Felder flach, ohne JSON-RPC-Umschlag: Ein Umschlag mit jsonrpc und params wird nicht ausgewertet, die Felder gelten dann als fehlend.

Adresse Aufgabe Wichtige Felder
POST /api/pitch/<id>/availability Prüft, ob ein Platz frei ist (Antwort true oder false) date, time_from, time_to
POST /api/reservation Legt eine Reservierung an; mit reservation_id ändert sie eine bestehende date, time_from, time_to, pitch_id
DELETE /api/reservation/<id> Storniert eine Reservierung, Antwort ist der neue Status leerer JSON-Körper {}

Beim Ändern sind Datum, Zeiten und Platz gesperrt; dafür stornieren Sie und legen neu an.

Beispiele (Zeiten als Dezimalzahl in Stunden, 10.0 steht für 10:00):

# Reservierung anlegen
curl -X POST "https://<jawengo-url>/api/reservation" \
     -H "API_KEY: <api-key>" -H "Content-Type: application/json" \
     -d '{"date": "2026-10-12", "time_from": 10.0, "time_to": 11.0, "pitch_id": 65}'

# Platz auf Verfügbarkeit prüfen
curl -X POST "https://<jawengo-url>/api/pitch/65/availability" \
     -H "API_KEY: <api-key>" -H "Content-Type: application/json" \
     -d '{"date": "2026-10-12", "time_from": 10.0, "time_to": 11.0}'

# Reservierung stornieren (auch hier ist ein JSON-Körper nötig)
curl -X DELETE "https://<jawengo-url>/api/reservation/<id>" \
     -H "API_KEY: <api-key>" -H "Content-Type: application/json" -d '{}'

Die Antwort beim Anlegen enthält die neue Reservierung mit Nummer, Status draft, Datum, Zeiten, Betrag und Plätzen:

{"jsonrpc": "2.0", "id": null, "result": {"id": 38, "name": "RES2026-00038", "state": "draft", "date": "2026-10-12", "time_from": 10.0, "time_to": 11.0, "amount": 50.0, "pitch_ids": [65]}}

Die Prüfung der Verfügbarkeit antwortet mit "result": true (frei) oder "result": false (belegt). Das Stornieren antwortet mit dem neuen Status: "result": "cancel", bei abgelaufener Stornofrist "result": "late_cancel".

Fehler

Fehler stehen im Feld result der Antwort in zwei Formen:

Form Codes Beispiel
result, error_code, error REQUIRED_VALUE_MISSING, RESERVATION_NOT_FOUND, UPDATE_NOT_ALLOWED siehe unten
error, message (ohne result und error_code) PITCH_NOT_FREE, RESERVATION_TIME_IN_PAST {"error": "PITCH_NOT_FREE", "message": "..."} 
{
  "result": "ERROR",
  "error_code": "REQUIRED_VALUE_MISSING",
  "error": "The following attributes are required: date, time_from, time_to, pitch_id"
}

Gebäude-Integration (nur mit Jawengo abgestimmt)

Diese Adressen dienen ausschliesslich der Gebäudeautomation und sind nur für die Gebäude-Integration gedacht; setzen Sie sie nur in Abstimmung mit Jawengo ein. Sie sind verfügbar, wenn die Gebäudeautomation installiert ist, und richten sich an eine Steuerung wie Node-RED. Jeder Schlüssel sieht dort nur das eigene Unternehmen.

Adresse Aufgabe
GET /api/building/config Konfiguration, Standorte und Plätze abholen
GET /api/building/overrides Aktive manuelle Übersteuerungen abholen
POST /api/building/status Zustand eines Platzes oder Standorts melden
POST /api/building/alert Störung melden
POST /api/building/heartbeat Lebenszeichen der Steuerung melden

Tipp: Beginnen Sie mit den lesenden Endpunkten. Schreibende Aufrufe ändern echte Reservierungen, testen Sie sie zuerst auf einer Testinstanz.

Achtung: DELETE /api/reservation/<id> storniert die Reservierung sofort, ohne Rückfrage. Der Benutzer der Kopplung braucht dafür eine E-Mail-Adresse.

In diesem Kapitel

Belegungsdaten
Häufige Fragen API