{"openapi":"3.1.0","info":{"title":"tapja Public API","version":"1","description":"REST-API für Kasse, Shop und CRM eines Betriebs (Tarif Lieblingskette). Erfolgreiche Antworten stehen in `{ data, timestamp }`, Fehler in `{ error: { code, message } }`.\n\nRate-Limit: 300 Anfragen pro Minute je Key über alle Endpunkte (über dem Limit 429 mit Retry-After). Unbekannte Felder im Body werden mit 400 abgelehnt; Antworten können jederzeit neue Felder bekommen.\n\nAlle POST-Endpunkte akzeptieren `Idempotency-Key` (je Key, gebunden an Methode, Pfad und Inhalt, höchstens 255 Zeichen). Antworten werden 7 Tage gespeichert; Stempeln und Prämien-Einlösen sind zusätzlich dauerhaft über das Buchungsjournal geschützt (Details am Parameter).\n\nJede Buchung nennt employeeId und locationId (Attribution). Kein Testmodus: jeder Key bucht echt.\n\nWebhooks: siehe Abschnitt `webhooks`. Zusätzlich gibt es das nicht abonnierbare Test-Ereignis `ping` (`data: { message }`). Zustellung höchstens einmal eingereiht; Empfänger gleichen bei Bedarf über GET ab.\n\nSignatur prüfen (Node.js, roher Body als String):\n```js\nimport { createHmac, timingSafeEqual } from 'node:crypto';\nfunction verify(rawBody, headers, secret) {\n  const ts = headers['x-tapja-timestamp'];\n  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;\n  const expected = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');\n  const given = String(headers['x-tapja-signature'] ?? '');\n  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));\n}\n```\nPython:\n```python\nimport hmac, hashlib, time\ndef verify(raw_body: bytes, headers, secret: str) -> bool:\n    ts = headers['X-tapja-Timestamp']\n    if abs(time.time() - int(ts)) > 300:\n        return False\n    expected = 'sha256=' + hmac.new(secret.encode(), f'{ts}.'.encode() + raw_body, hashlib.sha256).hexdigest()\n    return hmac.compare_digest(headers.get('X-tapja-Signature', ''), expected)\n```\n\nAnleitung und Referenz: https://www.tapja.de/hilfe/integrationen/ (Maschinenlesbar: diese Datei, GET /api/v1/public/openapi.json)","contact":{"name":"tapja Entwickler-Support","email":"hallo@tapja.de","url":"https://www.tapja.de/hilfe/integrationen/"}},"externalDocs":{"description":"Entwickler-Referenz","url":"https://www.tapja.de/hilfe/integrationen/"},"servers":[{"url":"https://api.tapja.de/api/v1/public","description":"Produktion"}],"security":[{"apiKey":[]}],"paths":{"/passes":{"post":{"operationId":"createPassLink","summary":"Anmeldelink für einen neuen Gast","description":"Liefert einen signierten Anmeldelink (7 Tage gültig, mehrfach nutzbar, an keinen Gast gebunden). Der Gast stimmt dort den Teilnahmebedingungen zu und legt die Karte selbst in die Wallet; den Pass meldet der Webhook pass.created. Keine Karte ohne Einwilligung.","security":[{"apiKey":["pass:write"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePassLinkRequest"}}}},"responses":{"201":{"description":"Anmeldelink","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"$ref":"#/components/schemas/PassLink"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"400":{"$ref":"#/components/responses/Error400","description":"BAD_REQUEST (Validierung), LOCATION_WRONG_COMPANY, IDEMPOTENCY_KEY_INVALID"},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED, EMPLOYEE_NOT_AT_LOCATION, ACTOR_ROLE_NOT_ALLOWED"},"404":{"$ref":"#/components/responses/Error404","description":"EMPLOYEE_NOT_FOUND, CARD_NOT_FOUND"},"409":{"$ref":"#/components/responses/Error409","description":"CARD_ARCHIVED, CARD_NOT_AT_LOCATION (Karte an diesem Standort nicht ausgegeben), LOCATION_DEACTIVATED, IDEMPOTENCY_KEY_REUSED"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"REQUEST_IN_PROGRESS"}}}},"/passes/by-serial/{serial}":{"get":{"operationId":"getPassBySerial","summary":"Pass über die Seriennummer aus dem Wallet-Barcode","security":[{"apiKey":["pass:read"]}],"parameters":[{"name":"serial","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pass","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"$ref":"#/components/schemas/Pass"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED"},"404":{"$ref":"#/components/responses/Error404","description":"PASS_NOT_FOUND (auch storniert)"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen"}}}},"/passes/{id}":{"get":{"operationId":"getPass","summary":"Aktueller Stand eines Passes","security":[{"apiKey":["pass:read"]}],"parameters":[{"$ref":"#/components/parameters/PassId"}],"responses":{"200":{"description":"Pass","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"$ref":"#/components/schemas/Pass"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED"},"404":{"$ref":"#/components/responses/Error404","description":"PASS_NOT_FOUND (auch storniert)"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen"}}}},"/passes/{id}/stamp":{"post":{"operationId":"stamp","summary":"Stempel/Punkte buchen","description":"Auf einer Angebotskarte bucht der Aufruf einen Besuch. Dieser ist wie Angebot einlösen nur 7 Tage über den Idempotency-Key geschützt: Bricht die Erstanfrage mittendrin ab, wird sie nie erneut ausgeführt (erst 503 REQUEST_IN_PROGRESS, dann 409 REQUEST_ABANDONED).","security":[{"apiKey":["pass:write"]}],"parameters":[{"$ref":"#/components/parameters/PassId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StampRequest"}}}},"responses":{"201":{"description":"Neuer Stand","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"$ref":"#/components/schemas/PassState"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"400":{"$ref":"#/components/responses/Error400","description":"BAD_REQUEST (Validierung), LOCATION_WRONG_COMPANY, IDEMPOTENCY_KEY_INVALID, STAMP_MODE_AMOUNT, STAMP_MODE_VISIT, AMOUNT_REQUIRED, AMOUNT_BELOW_MINIMUM, AMOUNT_TOO_SMALL, POINTS_REQUIRED, POINTS_BALANCE_LIMIT, STAMP_CAP_EXCEEDED, CARD_HAS_NO_BALANCE, PACKAGE_USE_REQUIRED, MEMBERSHIP_ACTION_REQUIRED"},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED, EMPLOYEE_NOT_AT_LOCATION, ACTOR_ROLE_NOT_ALLOWED, COOLDOWN_ACTIVE, STAMP_LIMIT_REACHED, CARD_FULL"},"404":{"$ref":"#/components/responses/Error404","description":"EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND"},"409":{"$ref":"#/components/responses/Error409","description":"LOCATION_DEACTIVATED, PASS_VOIDED, IDEMPOTENCY_KEY_REUSED, REQUEST_ABANDONED (nur Besuch auf einer Angebotskarte: abgebrochene Erstanfrage wird nicht erneut ausgeführt)"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"REQUEST_IN_PROGRESS, RETRY"}}}},"/passes/{id}/redeem":{"post":{"operationId":"redeem","summary":"Prämie einlösen","description":"Manager-Eskalation ab Warenwert-Schwelle wie an der Theke (PIN_REQUIRED, wenn employeeId nicht MANAGER/OWNER ist).","security":[{"apiKey":["pass:redeem"]}],"parameters":[{"$ref":"#/components/parameters/PassId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemRequest"}}}},"responses":{"201":{"description":"Neuer Stand","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"$ref":"#/components/schemas/PassState"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"400":{"$ref":"#/components/responses/Error400","description":"BAD_REQUEST (Validierung), LOCATION_WRONG_COMPANY, IDEMPOTENCY_KEY_INVALID, REWARD_AUTO_ISSUED (wird automatisch als Gutschein ausgestellt), PACKAGE_USE_REQUIRED, MEMBERSHIP_ACTION_REQUIRED"},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED, EMPLOYEE_NOT_AT_LOCATION, ACTOR_ROLE_NOT_ALLOWED, PIN_REQUIRED (Manager-Eskalation), GUEST_EMAIL_UNVERIFIED, REDEEM_NOT_AT_LOCATION, REWARD_THRESHOLD_NOT_REACHED, NOT_ENOUGH_POINTS, REWARD_ALREADY_REDEEMED, REWARD_QUOTA_EXHAUSTED, REWARD_NOT_YET_VALID, REWARD_EXPIRED, REWARD_WRONG_LOCATION, REWARD_TIER_REQUIRED, REWARD_MEMBERSHIP_REQUIRED, REWARD_MIN_PURCHASE, REWARD_LIMIT_REACHED, REWARD_NOT_COMBINABLE"},"404":{"$ref":"#/components/responses/Error404","description":"EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND, REWARD_NOT_FOUND"},"409":{"$ref":"#/components/responses/Error409","description":"LOCATION_DEACTIVATED, PASS_VOIDED, IDEMPOTENCY_KEY_REUSED"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"REQUEST_IN_PROGRESS, RETRY"}}}},"/passes/{id}/offers":{"get":{"operationId":"listOffers","summary":"Angebote eines Passes (Angebotskarte)","security":[{"apiKey":["offer:read"]}],"parameters":[{"$ref":"#/components/parameters/PassId"}],"responses":{"200":{"description":"Angebote","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"$ref":"#/components/schemas/OfferList"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED"},"404":{"$ref":"#/components/responses/Error404","description":"PASS_NOT_FOUND, NOT_FOUND (Angebote nicht aktiviert)"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen"}}}},"/passes/{id}/redeem-offer":{"post":{"operationId":"redeemOffer","summary":"Angebot einlösen","description":"Dieselbe Prüfung wie an der Theke: Verfügbarkeit des Angebots (je Grund ein eigener OFFER_*-Code), bestätigte E-Mail des Gastes, Manager-Eskalation ab Warenwert. Angebote haben keinen dauerhaften Doppelschutz im Buchungsjournal: Ein Idempotency-Key schützt 7 Tage; eine abgebrochene Erstanfrage wird nie erneut ausgeführt (409 REQUEST_ABANDONED).","security":[{"apiKey":["offer:redeem"]}],"parameters":[{"$ref":"#/components/parameters/PassId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemOfferRequest"}}}},"responses":{"201":{"description":"Einlösung","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"$ref":"#/components/schemas/OfferRedemption"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"400":{"$ref":"#/components/responses/Error400","description":"BAD_REQUEST (Validierung), LOCATION_WRONG_COMPANY, IDEMPOTENCY_KEY_INVALID, OFFERS_NOT_ON_CARD (keine Angebotskarte), COUPON_NOT_COMBINABLE (heute schon ein nicht kombinierbarer Gutschein eingelöst)"},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED, EMPLOYEE_NOT_AT_LOCATION, ACTOR_ROLE_NOT_ALLOWED, PIN_REQUIRED (Manager-Eskalation), GUEST_EMAIL_UNVERIFIED, OFFER_COOLDOWN, OFFER_EXHAUSTED, OFFER_NOT_STARTED, OFFER_EXPIRED, OFFER_NOT_ELIGIBLE, OFFER_WRONG_LOCATION"},"404":{"$ref":"#/components/responses/Error404","description":"EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND, OFFER_NOT_FOUND, NOT_FOUND (Angebote nicht aktiviert)"},"409":{"$ref":"#/components/responses/Error409","description":"LOCATION_DEACTIVATED, PASS_VOIDED, IDEMPOTENCY_KEY_REUSED, CARD_ARCHIVED, OFFER_USED_UP (im Fenster schon eingelöst), OFFER_ALREADY_REDEEMED (gleichzeitige Einlösung war schneller), REQUEST_ABANDONED"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"REQUEST_IN_PROGRESS"}}}},"/passes/{id}/cancel":{"post":{"operationId":"cancelPass","summary":"Karte stornieren (MANAGER+)","description":"Verlangt einen Key mit Akteursgrenze MANAGER oder OWNER; standortgebundene Keys können nicht stornieren. Eine Wiederholung mit demselben Idempotency-Key liefert innerhalb von 7 Tagen dieselbe Erfolgsantwort, auch wenn die Karte inzwischen storniert ist; ohne Key antwortet eine zweite Stornierung mit 409 PASS_VOIDED.","security":[{"apiKey":["pass:cancel"]}],"parameters":[{"$ref":"#/components/parameters/PassId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelRequest"}}}},"responses":{"201":{"description":"Storniert","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"type":"object","required":["id","cancelled"],"properties":{"id":{"type":"string"},"cancelled":{"type":"boolean","const":true}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"400":{"$ref":"#/components/responses/Error400","description":"BAD_REQUEST (Validierung), LOCATION_WRONG_COMPANY, IDEMPOTENCY_KEY_INVALID"},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED, EMPLOYEE_NOT_AT_LOCATION, ACTOR_ROLE_NOT_ALLOWED, ROLE_NOT_ALLOWED"},"404":{"$ref":"#/components/responses/Error404","description":"EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND"},"409":{"$ref":"#/components/responses/Error409","description":"LOCATION_DEACTIVATED, PASS_VOIDED, IDEMPOTENCY_KEY_REUSED"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"REQUEST_IN_PROGRESS, RETRY"}}}},"/customers":{"get":{"operationId":"findCustomerByEmail","summary":"Gast über die E-Mail finden","description":"Zusätzliches Limit: 60 Suchen pro Minute je Key und 120 je Betrieb über alle Keys (eigene Töpfe neben dem Gesamt-Limit). Nicht für standortgebundene Keys.","security":[{"apiKey":["customer:read"]}],"parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","format":"email","maxLength":254}}],"responses":{"200":{"description":"Gast","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit-customerLookup":{"schema":{"type":"integer"},"description":"Limit der E-Mail-Suche je Minute"},"X-RateLimit-Remaining-customerLookup":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"$ref":"#/components/schemas/Customer"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"400":{"$ref":"#/components/responses/Error400","description":"BAD_REQUEST: email fehlt oder ist ungültig, unbekannte Query-Parameter"},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED"},"404":{"$ref":"#/components/responses/Error404","description":"CUSTOMER_NOT_FOUND"},"429":{"$ref":"#/components/responses/Error429CustomerLookup","description":"RATE_LIMITED: Gesamt-Limit je Key (Header Retry-After-api) oder Limit der E-Mail-Suche (Header Retry-After-customerLookup); Retry-After trägt immer die Wartezeit"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen"}}}},"/customers/deleted":{"get":{"operationId":"listDeletedCustomers","summary":"Gelöschte Gäste seit einem Zeitpunkt","description":"Abgleich für verpasste `customer.deleted` (z. B. während ein Webhook pausiert war). Älteste zuerst, cursor-basiert, höchstens 500 je Seite (Standard 100). Abrufbar sind die letzten 30 Tage; empfohlen ist ein täglicher Abgleich ab dem letzten `deletedAt`. Nicht für standortgebundene Keys.","security":[{"apiKey":["customer:read"]}],"parameters":[{"name":"since","in":"query","required":true,"description":"ISO-8601-Zeitpunkt; Löschungen ab einschließlich","schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":64}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"Lösch-Nachweise","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"$ref":"#/components/schemas/DeletedCustomerPage"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"400":{"$ref":"#/components/responses/Error400","description":"BAD_REQUEST: since fehlt oder ist kein ISO-8601-Zeitpunkt, limit außerhalb 1 bis 500"},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen"}}}},"/customers/{id}":{"get":{"operationId":"getCustomer","summary":"Gast (minimale Sicht)","description":"Nicht für standortgebundene Keys.","security":[{"apiKey":["customer:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Gast","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"$ref":"#/components/schemas/Customer"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED"},"404":{"$ref":"#/components/responses/Error404","description":"CUSTOMER_NOT_FOUND"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen"}}}},"/notifications/push":{"post":{"operationId":"push","summary":"Karten-Update an Gäste mit Werbe-Einwilligung","description":"Erreicht nur Gäste mit Werbe-Einwilligung (marketingConsent). Während der Plattform-Ruhezeit (nachts, Standard 22 bis 8 Uhr Europe/Berlin) wird der Aufruf mit 400 QUIET_HOURS abgelehnt, nichts wird versendet. Frequenz-Grenzen je Gast gelten: Gäste über ihrer Grenze werden still übersprungen, recipients kann deshalb kleiner sein. Moderation lehnt anstößige Texte mit 422 ab. Nicht für standortgebundene Keys. Ein abgebrochener Versand wird nie erneut ausgeführt: Die Wiederholung mit demselben Idempotency-Key liefert 503 REQUEST_IN_PROGRESS, solange die Erstanfrage laufen könnte, danach endgültig 409 REQUEST_ABANDONED (vorher prüfen, ob die Nachricht ankam, dann mit neuem Key senden).","security":[{"apiKey":["notification:send"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushRequest"}}}},"responses":{"201":{"description":"Versendet","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"type":"object","required":["recipients"],"properties":{"recipients":{"type":"integer","description":"Zahl der erreichten Gäste"}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"400":{"$ref":"#/components/responses/Error400","description":"BAD_REQUEST (Validierung), PLACEHOLDER_UNKNOWN (unbekannter Platzhalter), QUIET_HOURS (Plattform-Ruhezeit), IDEMPOTENCY_KEY_INVALID"},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED"},"404":{"$ref":"#/components/responses/Error404","description":"CARD_NOT_FOUND (cardId gehört nicht zum Betrieb)"},"409":{"$ref":"#/components/responses/Error409","description":"IDEMPOTENCY_KEY_REUSED, REQUEST_ABANDONED"},"422":{"$ref":"#/components/responses/Error422","description":"UNPROCESSABLE (Text von der Moderation abgelehnt)"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"REQUEST_IN_PROGRESS"}}}},"/analytics":{"get":{"operationId":"analytics","summary":"Übersicht: letzte 30 Tage und Bestand","description":"cardsIssued, stampsAdded, redemptions und newCustomers zählen die letzten 30 Tage (deltas: Vergleich mit den 30 Tagen davor); cardPrograms, activeCards und totalCustomers sind Bestandszahlen. Standortgebundene Keys sehen nur ihre Standorte, cardPrograms zählt immer den ganzen Betrieb. Die Antwort wird bis zu 60 s zwischengespeichert.","security":[{"apiKey":["analytics:read"]}],"responses":{"200":{"description":"Übersicht","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"$ref":"#/components/schemas/AnalyticsOverview"},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen"}}}},"/cards":{"get":{"operationId":"listCards","summary":"Aktive Kartenprogramme mit Prämien","security":[{"apiKey":["setup:read"]}],"responses":{"200":{"description":"Kartenprogramme","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Card"}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen"}}}},"/locations":{"get":{"operationId":"listLocations","summary":"Standorte (standortgebundene Keys: nur die eigenen)","security":[{"apiKey":["setup:read"]}],"responses":{"200":{"description":"Standorte","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen"}}}},"/employees":{"get":{"operationId":"listEmployees","summary":"Aktive Mitarbeiter mit Rolle und Standorten","description":"Beschäftigtendaten (Name, Rolle): nur Systemen geben, die sie brauchen.","security":[{"apiKey":["setup:read"]}],"responses":{"200":{"description":"Mitarbeiter","headers":{"X-RateLimit-Limit-api":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining-api":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset-api":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","required":["data","timestamp"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt der Antwort (UTC)"}}}}}},"401":{"$ref":"#/components/responses/Error401","description":"UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)"},"403":{"$ref":"#/components/responses/Error403","description":"SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED"},"429":{"$ref":"#/components/responses/Error429","description":"RATE_LIMITED (Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After)"},"500":{"$ref":"#/components/responses/Error500","description":"INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)"},"503":{"$ref":"#/components/responses/Error503","description":"SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen"}}}}},"webhooks":{"pass.created":{"post":{"summary":"Karte ausgegeben (jede Ausgabe). Über einen API-Anmeldelink: employeeId/locationId aus dem Link, channel = API, solange der Link gültig war. Ist der erzeugende API-Key inzwischen widerrufen oder abgelaufen, meldet sich der Gast trotzdem an, aber ohne Zuordnung (employeeId und locationId null).","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"pass.created"},"data":{"type":"object","required":["passId","cardId","customerId","employeeId","locationId","channel"],"properties":{"passId":{"type":"string"},"cardId":{"type":"string"},"customerId":{"type":"string"},"employeeId":{"type":["string","null"]},"locationId":{"type":["string","null"]},"channel":{"type":["string","null"]}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"pass.stamped":{"post":{"summary":"Stempel/Punkte gebucht (Theke, App, Selbststempeln, API). timestamp = Gerätezeit bei offline nachgereichten Buchungen.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"pass.stamped"},"data":{"type":"object","required":["passId","cardId","stampCount","pointsBalance","employeeId","locationId","channel"],"properties":{"passId":{"type":"string"},"cardId":{"type":"string"},"stampCount":{"type":"integer"},"pointsBalance":{"type":"integer"},"employeeId":{"type":["string","null"]},"locationId":{"type":["string","null"]},"channel":{"type":["string","null"]}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"pass.redeemed":{"post":{"summary":"Prämie oder Gutschein eingelöst. timestamp = Gerätezeit bei offline nachgereichten Buchungen.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"pass.redeemed"},"data":{"type":"object","required":["passId"],"properties":{"passId":{"type":"string"},"rewardId":{"type":"string"},"locationId":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"pass.cancelled":{"post":{"summary":"Karte storniert.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"pass.cancelled"},"data":{"type":"object","required":["passId","cardId"],"properties":{"passId":{"type":"string"},"cardId":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"pass.reactivated":{"post":{"summary":"Stornierte Karte nach nachgeholter E-Mail-Bestätigung wieder aktiv.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"pass.reactivated"},"data":{"type":"object","required":["passId","customerId"],"properties":{"passId":{"type":"string"},"customerId":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"pass.corrected":{"post":{"summary":"Stand korrigiert, vom System gutgeschrieben oder durch Verfall (Punkte/Stempel laufen nach den Regeln der Karte ab) gesenkt. System-Buchungen und Verfall kommen ohne employeeId/locationId. timestamp = Gerätezeit bei offline nachgereichten Korrekturen.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"pass.corrected"},"data":{"type":"object","required":["passId","field","value"],"properties":{"passId":{"type":"string"},"field":{"type":"string","enum":["stampCount","pointsBalance"]},"value":{"type":"integer"},"employeeId":{"type":"string"},"locationId":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"reward.ready":{"post":{"summary":"Prämie neu erreicht und einlösbar: wie beim Einlösen geprüft (Schwelle und Punktekosten, Stufe, Gültigkeit, Limits, Gesamt-Kontingent der Prämie; Standort und Mindestumsatz prüft erst das Einlösen), nur bei bestätigter E-Mail des Gastes, nur laufende Runde, nie für automatisch ausgestellte Gutscheine. Bestätigt der Gast seine E-Mail erst später, kommen dann alle schon erreichten, einlösbaren Prämien seiner aktiven Karten.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"reward.ready"},"data":{"type":"object","required":["passId","cardId","rewardIds"],"properties":{"passId":{"type":"string"},"cardId":{"type":"string"},"rewardIds":{"type":"array","items":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"offer.redeemed":{"post":{"summary":"Angebot eingelöst.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"offer.redeemed"},"data":{"type":"object","required":["passId","offerId"],"properties":{"passId":{"type":"string"},"offerId":{"type":"string"},"locationId":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"package.used":{"post":{"summary":"Einheit(en) einer Paketkarte genutzt.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"package.used"},"data":{"type":"object","required":["passId","quantity","units","employeeId"],"properties":{"passId":{"type":"string"},"quantity":{"type":"integer"},"units":{"type":"integer"},"employeeId":{"type":"string"},"locationId":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"customer.created":{"post":{"summary":"Neuer Gast. Bei der Anmeldung (Selbstanmeldung, Anmeldelink) erst nach erfolgreicher Kartenausgabe und meist nach pass.created; beim Anlegen im Dashboard sofort, auch ohne Karte.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"customer.created"},"data":{"type":"object","required":["customerId"],"properties":{"customerId":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"customer.deleted":{"post":{"summary":"Gast gelöscht (Art. 17): im eigenen System ebenfalls löschen.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"customer.deleted"},"data":{"type":"object","required":["customerId","passIds"],"properties":{"customerId":{"type":"string"},"passIds":{"type":"array","items":{"type":"string"}}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"customer.consent_changed":{"post":{"summary":"Werbe-Einwilligung eines bestehenden Gastes geändert (nicht bei der Erstanmeldung).","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"customer.consent_changed"},"data":{"type":"object","required":["customerId","marketingConsent"],"properties":{"customerId":{"type":"string"},"marketingConsent":{"type":"boolean"}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"campaign.sent":{"post":{"summary":"Kampagne versendet.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"campaign.sent"},"data":{"type":"object","required":["campaignId","recipients"],"properties":{"campaignId":{"type":"string"},"recipients":{"type":"integer"}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}},"ping":{"post":{"summary":"Verbindungstest („Test senden\" in der Verwaltung). Nicht abonnierbar; kommt auch bei pausiertem Webhook an. Beispiele abonnierter Ereignisse kommen unter ihrem echten Namen mit test: true.","parameters":[{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Event","description":"Name des Ereignisses"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Delivery","description":"Kennung der Zustellung (= id im Body), stabil über Wiederholungen"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Timestamp","description":"Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)"},{"in":"header","required":true,"schema":{"type":"string"},"name":"X-tapja-Signature","description":"`sha256=<hex>`: HMAC-SHA256 mit dem Webhook-Secret über `${X-tapja-Timestamp}.${roher Body}`"},{"in":"header","name":"X-tapja-Test","required":false,"schema":{"type":"string","const":"1"},"description":"Nur bei Tests („Test senden\"): `1`. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","event","data","timestamp"],"properties":{"id":{"type":"string","description":"evt_…, stabil über Wiederholungen (Dedupe)"},"event":{"type":"string","const":"ping"},"data":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time","description":"Zeitpunkt des Ereignisses (UTC)"},"test":{"type":"boolean","const":true,"description":"Nur bei Tests aus „Test senden\" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz."}}}}}},"responses":{"2XX":{"description":"Quittiert. Alles andere (auch Timeout nach 10 s) gilt als Fehlschlag und wird wiederholt (1 + 5 Versuche)."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_live_<48 hex>","description":"Company-scoped API-Key aus Verwaltung › Integrationen. Nur serverseitig verwenden. Scopes je Endpunkt stehen in `security`."}},"parameters":{"PassId":{"name":"id","in":"path","required":true,"schema":{"type":"string","maxLength":64}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Je Vorgang neu (z. B. Bonnummer). Gilt je API-Key, gebunden an Methode, Pfad und Inhalt. Wiederholung mit demselben Schlüssel und Inhalt liefert dieselbe Antwort (beim Anmeldelink einen frischen Link); anderer Inhalt → 409 IDEMPOTENCY_KEY_REUSED. Läuft die Erstanfrage noch → 503 REQUEST_IN_PROGRESS (gleich erneut versuchen). Gespeichert wird nur eine erfolgreiche Antwort, 7 Tage lang. Dauerhaft (über die 7 Tage hinaus) geschützt sind nur Stempeln und Prämien-Einlösen, über das Buchungsjournal des Betriebs, solange es aktiv ist (Standard): Derselbe Pass mit demselben Schlüssel wird nicht doppelt gebucht, die Antwort liefert den aktuellen Stand; ein anderer Pass mit demselben Schlüssel → 409 IDEMPOTENCY_KEY_REUSED. Bricht eine Stempel- oder Einlöse-Anfrage mittendrin ab, übernimmt eine Wiederholung nach etwa 60 s; das Journal verhindert dabei eine Doppelbuchung. Ausnahme: der Besuch auf einer Angebotskarte. Er ist wie Angebot einlösen, Stornieren und Push nur die 7 Tage geschützt. Bricht die Erstanfrage bei Angebot einlösen, Besuch auf einer Angebotskarte oder Push mittendrin ab, wird sie nie erneut ausgeführt: erst 503 REQUEST_IN_PROGRESS, dann endgültig 409 REQUEST_ABANDONED.","schema":{"type":"string","maxLength":255,"pattern":"^[\\x21-\\x7E]+$"}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Anfragen je Minute und Key"},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Verbleibende Anfragen im Fenster"},"RateLimitReset":{"schema":{"type":"integer"},"description":"Sekunden bis zum neuen Fenster"}},"responses":{"Error400":{"description":"Ungültige Anfrage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error401":{"description":"API-Key fehlt, ist ungültig, widerrufen oder abgelaufen (UNAUTHORIZED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error403":{"description":"Nicht erlaubt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error404":{"description":"Nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error409":{"description":"Konflikt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error422":{"description":"Inhalt abgelehnt (UNPROCESSABLE), z. B. durch die Moderation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error429":{"description":"Zu viele Anfragen (RATE_LIMITED); Header Retry-After","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Sekunden bis zum nächsten erlaubten Versuch (bei jeder 429, auch bei der IP-Bremse)"},"Retry-After-api":{"schema":{"type":"integer"},"description":"Sekunden, bis der Key wieder Anfragen stellen darf (fehlt bei der IP-Bremse gegen falsche Keys)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error500":{"description":"Unerwarteter Fehler (INTERNAL_ERROR); die Meldung enthält bewusst keine Details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error503":{"description":"Vorübergehend nicht verfügbar; später mit demselben Idempotency-Key wiederholen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error429CustomerLookup":{"description":"Zu viele Anfragen (RATE_LIMITED): Gesamt-Limit je Key (Retry-After-api) oder höchstens 60 E-Mail-Suchen pro Minute je Key bzw. 120 je Betrieb (Retry-After-customerLookup)","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Sekunden bis zum nächsten erlaubten Versuch (bei jeder 429, auch bei der IP-Bremse)"},"Retry-After-api":{"schema":{"type":"integer"},"description":"Sekunden, bis der Key wieder Anfragen stellen darf (fehlt bei der IP-Bremse gegen falsche Keys)"},"Retry-After-customerLookup":{"schema":{"type":"integer"},"description":"Sekunden bis zur nächsten erlaubten E-Mail-Suche (nur beim Such-Limit)"},"X-RateLimit-Limit-customerLookup":{"schema":{"type":"integer"},"description":"Limit der E-Mail-Suche je Minute"},"X-RateLimit-Remaining-customerLookup":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stabiler, maschinenlesbarer Code. Integrationen verzweigen nur hierüber. Vollständige Liste: `PublicErrorCode` plus `PUBLIC_API_ERROR_CODES` (siehe `10-api.md`); neue Codes sind eine additive Änderung.","examples":["COOLDOWN_ACTIVE","PASS_NOT_FOUND","SCOPE_MISSING"]},"message":{"type":"string","description":"Für Menschen; meist deutsch, bei Formfehlern (Validierung) teils englisch."}}}}},"Pass":{"type":"object","required":["id","cardId","customerId","serialNumber","stampCount","pointsBalance","tier","lastStampAt","createdAt"],"properties":{"id":{"type":"string"},"cardId":{"type":"string"},"customerId":{"type":"string"},"serialNumber":{"type":"string","description":"Seriennummer aus dem Wallet-Barcode"},"stampCount":{"type":"integer"},"pointsBalance":{"type":"integer"},"tier":{"type":["string","null"],"description":"Aktuelle Treuestufe oder null"},"lastStampAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"PassState":{"type":"object","description":"Neuer Stand nach Stempeln/Einlösen.","properties":{"id":{"type":"string"},"cardId":{"type":"string"},"customerId":{"type":"string"},"serialNumber":{"type":"string","description":"Seriennummer aus dem Wallet-Barcode"},"stampCount":{"type":"integer"},"pointsBalance":{"type":"integer"},"tier":{"type":["string","null"],"description":"Aktuelle Treuestufe oder null"},"lastStampAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"lifetimeProgress":{"type":"integer","description":"Monotoner Gesamtfortschritt"},"stampCycle":{"type":"integer","description":"Laufende Runde der Stempelkarte"}}},"PassLink":{"type":"object","required":["cardId","addUrl","expiresAt"],"properties":{"cardId":{"type":"string"},"addUrl":{"type":"string","format":"uri","description":"Anmeldelink (7 Tage gültig, mehrfach nutzbar, an keinen Gast gebunden). Bei einer idempotenten Wiederholung entsteht ein frischer Link."},"expiresAt":{"type":"string","format":"date-time"}}},"Customer":{"type":"object","description":"Minimale Gast-Sicht (kein Geburtstag, kein Besuchsverhalten). Jeder Abruf wird protokolliert.","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"customerNumberLabel":{"type":"string"},"marketingConsent":{"type":"boolean","description":"Werbe-Einwilligung. Werbe-E-Mails aus dem eigenen System nur, wenn true UND emailVerifiedAt gesetzt ist."},"emailVerifiedAt":{"type":["string","null"],"format":"date-time"},"anonymous":{"type":"boolean","description":"true = der Betrieb nimmt Gäste ohne Name und E-Mail auf. name, email und emailVerifiedAt sind dann immer null; das Einlösen ist trotzdem möglich."},"createdAt":{"type":"string","format":"date-time"}}},"DeletedCustomer":{"type":"object","description":"Lösch-Nachweis: im eigenen System Gast und Karten ebenfalls löschen. Nur IDs, 30 Tage abrufbar.","required":["id","customerId","passIds","deletedAt"],"properties":{"id":{"type":"string","description":"Eintrag (Cursor)"},"customerId":{"type":"string"},"passIds":{"type":"array","items":{"type":"string"}},"deletedAt":{"type":"string","format":"date-time"}}},"DeletedCustomerPage":{"type":"object","required":["items","nextCursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DeletedCustomer"}},"nextCursor":{"type":["string","null"],"description":"Als `cursor` für die nächste Seite übergeben; null = Ende"}}},"Offer":{"type":"object","properties":{"offerId":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"translations":{"type":["object","null"],"description":"Rohe Übersetzungen von title/description"},"highlightToday":{"type":"boolean"},"kind":{"type":"string","enum":["PERCENT","AMOUNT","BOGO","FREE_ITEM","FREE_FOR_GUEST","CUSTOM"]},"valuePercent":{"type":["integer","null"]},"valueCents":{"type":["integer","null"]},"taxRate":{"type":["string","null"]},"valueSplit":{"type":["object","null"]},"status":{"type":"string","enum":["available","used_up","cooldown","exhausted","not_started","expired","not_eligible","wrong_location"]},"remaining":{"type":"integer"},"validUntil":{"type":["string","null"],"format":"date-time"},"availableAgainAt":{"type":["string","null"],"format":"date-time"},"lastRedeemedAt":{"type":["string","null"],"format":"date-time"},"order":{"type":"integer"}}},"OfferList":{"type":"object","properties":{"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"openCount":{"type":"integer"}}},"OfferRedemption":{"type":"object","properties":{"offerId":{"type":"string"},"title":{"type":"string"},"remaining":{"type":"integer","description":"Wie oft der Gast das Angebot im Fenster noch einlösen kann"},"openCount":{"type":"integer"}}},"Card":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["STAMP","POINTS","OFFERS","PACKAGE","MEMBERSHIP"]},"stampGoal":{"type":["integer","null"]},"rewards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"threshold":{"type":"integer"},"valueCents":{"type":["integer","null"]},"pointsCost":{"type":"integer","description":"Wirksame Punktekosten (ohne eigenen Wert = threshold)"},"autoIssue":{"type":"boolean","description":"Wird automatisch als Gutschein ausgestellt (nicht über /redeem einlösbar)"}}}}}},"Location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["OPEN","CLOSED"]}}},"Employee":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"role":{"type":"string","enum":["OWNER","MANAGER","EMPLOYEE"]},"locationIds":{"type":"array","items":{"type":"string"}}}},"AnalyticsOverview":{"type":"object","description":"Zeitraum-Zahlen (cardsIssued, stampsAdded, redemptions, newCustomers) über die letzten 30 Tage, Bestandszahlen (cardPrograms, activeCards, totalCustomers) zum Abrufzeitpunkt. Bei standortgebundenen Keys zählen nur deren Standorte (außer cardPrograms). Bis zu 60 s zwischengespeichert.","properties":{"cardPrograms":{"type":"integer","description":"Bestand: nicht archivierte Kartenprogramme des ganzen Betriebs (auch bei standortgebundenen Keys nicht nach Standort gefiltert)"},"cardsIssued":{"type":"integer","description":"Ausgegebene Karten, letzte 30 Tage"},"stampsAdded":{"type":"integer","description":"Stempel-/Punktebuchungen, letzte 30 Tage"},"redemptions":{"type":"integer","description":"Einlösungen (Prämien und Angebote), letzte 30 Tage"},"activeCards":{"type":"integer","description":"Bestand: nicht stornierte Gastkarten"},"totalCustomers":{"type":"integer","description":"Bestand: Gäste"},"newCustomers":{"type":"integer","description":"Neue Gäste, letzte 30 Tage"},"deltas":{"type":"object","description":"Vergleich mit den 30 Tagen davor je Kennzahl (stampsAdded, redemptions, cardsIssued, newCustomers)","additionalProperties":{"type":"object","properties":{"current":{"type":"integer"},"previous":{"type":"integer"},"changePct":{"type":["number","null"]}}}}}},"CreatePassLinkRequest":{"type":"object","additionalProperties":false,"required":["cardId","employeeId","locationId"],"properties":{"cardId":{"type":"string","maxLength":64,"description":"Kartenprogramm (`GET /cards`)"},"employeeId":{"type":"string","maxLength":64,"description":"Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (`GET /employees`). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen."},"locationId":{"type":"string","maxLength":64,"description":"Standort der Buchung (`GET /locations`); bei standortgebundenen Keys einer der freigegebenen."},"employeeRef":{"type":"string","maxLength":120,"description":"Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen)."}}},"StampRequest":{"type":"object","additionalProperties":false,"required":["employeeId","locationId"],"description":"Ohne Betrag ein Besuch; mit amountCents Umsatzpunkte; mit points direkte Punkte. Welcher Weg passt, entscheidet die Karte (sonst 400).","properties":{"employeeId":{"type":"string","maxLength":64,"description":"Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (`GET /employees`). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen."},"locationId":{"type":"string","maxLength":64,"description":"Standort der Buchung (`GET /locations`); bei standortgebundenen Keys einer der freigegebenen."},"employeeRef":{"type":"string","maxLength":120,"description":"Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen)."},"amountCents":{"type":"integer","minimum":1,"maximum":100000000},"points":{"type":"integer","minimum":1,"maximum":100000}}},"RedeemRequest":{"type":"object","additionalProperties":false,"required":["rewardId","employeeId","locationId"],"properties":{"rewardId":{"type":"string","maxLength":64,"description":"Prämie (`GET /cards` → rewards)"},"valueCents":{"type":"integer","minimum":0,"maximum":100000000,"description":"Warenwert für Mindestumsatz und Manager-Eskalation"},"employeeId":{"type":"string","maxLength":64,"description":"Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (`GET /employees`). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen."},"locationId":{"type":"string","maxLength":64,"description":"Standort der Buchung (`GET /locations`); bei standortgebundenen Keys einer der freigegebenen."},"employeeRef":{"type":"string","maxLength":120,"description":"Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen)."}}},"RedeemOfferRequest":{"type":"object","additionalProperties":false,"required":["offerId","employeeId","locationId"],"properties":{"offerId":{"type":"string","maxLength":64,"description":"Angebot (`GET /passes/{id}/offers`)"},"employeeId":{"type":"string","maxLength":64,"description":"Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (`GET /employees`). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen."},"locationId":{"type":"string","maxLength":64,"description":"Standort der Buchung (`GET /locations`); bei standortgebundenen Keys einer der freigegebenen."},"employeeRef":{"type":"string","maxLength":120,"description":"Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen)."}}},"CancelRequest":{"type":"object","additionalProperties":false,"required":["employeeId","locationId"],"description":"employeeId muss Rolle MANAGER oder OWNER haben (sonst ROLE_NOT_ALLOWED).","properties":{"employeeId":{"type":"string","maxLength":64,"description":"Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (`GET /employees`). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen."},"locationId":{"type":"string","maxLength":64,"description":"Standort der Buchung (`GET /locations`); bei standortgebundenen Keys einer der freigegebenen."},"employeeRef":{"type":"string","maxLength":120,"description":"Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen)."}}},"PushRequest":{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":240,"description":"Kartentext; nur bekannte Platzhalter wie {Kundenname}, {Betrieb} (sonst 400 PLACEHOLDER_UNKNOWN). Anstößige Inhalte lehnt die Moderation ab (422)."},"cardId":{"type":"string","maxLength":64,"description":"Optional: nur Gäste dieses Kartenprogramms"}}}}}}