Events API.
REST + Webhooks. JSON-only. Versioniert via Header apps3k-version: 2024-12-01. Beta: Breaking Changes bis zur GA-Version moeglich.
Authentifizierung
Alle Requests verlangen einen Bearer-Token im Authorization-Header. Tokens werden im Workspace-Settings unter API Keys erzeugt und können auf bestimmte Scopes (events:read, bookings:write …) eingeschränkt werden.
https://api.apps3k.ch/events/v0 Fehler
Wir verwenden konventionelle HTTP-Statuscodes. 2xx = Erfolg, 4xx = Client-Fehler (validate, fix, retry), 5xx = Server-Fehler (idempotent retry mit Backoff).
| Status | Code | Bedeutung |
|---|---|---|
| 400 | invalid_request | Body- oder Query-Validierung fehlgeschlagen. Details in errors[]. |
| 401 | unauthorized | Token fehlt oder ist ungültig. |
| 403 | forbidden_scope | Token hat den benötigten Scope nicht. |
| 404 | not_found | Ressource existiert nicht oder gehört nicht zu diesem Workspace. |
| 409 | conflict | Versionskonflikt; Idempotency-Key ggf. erneut prüfen. |
| 429 | rate_limited | Limit überschritten, Retry-After Header beachten. |
| 503 | temporarily_unavailable | Backend kurz nicht erreichbar; idempotent retry empfohlen. |
Rate-Limits
400 req/min pro Token (Beta-Limit, GA-Version: 800/min). Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset in jeder Antwort.
POST /tickets/{id}/validate
Validiert ein Ticket beim Einlass. Atomar — ein Ticket kann nur einmal validiert werden. Wiederholte Calls mit gleicher ticket_id liefern 409 conflict.
Pfad-Parameter
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| id | string · uuid | Required | Ticket-ID (Pfadparameter). |
Body-Parameter
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| gate | string | Optional | Eingangs-Identifikator, z. B. haupteingang, vip-foyer. |
| validator_id | string · uuid | Optional | ID des einscannenden Mitarbeiters. |
Antworten
| Status | Beschreibung |
|---|---|
| 200 | Ticket erfolgreich validiert. Body enthält Status + Zeitstempel. |
| 400 | Ticket existiert, ist aber für anderes Event gültig. |
| 404 | Ticket-ID nicht gefunden. |
| 409 | Ticket ist bereits validiert. Body enthält den ursprünglichen Validator und Zeitstempel. |