API reference
Endpoints, webhooks, error codes
Generated from the OpenAPI description of the interface. Base URL: https://api.tapja.de/api/v1/public
Descriptions in the reference are currently in German.
Download the OpenAPI file Go to the guide
Setup
GET /cards
Aktive Kartenprogramme mit Prämien
Scope: setup:read
Response 200 · Card
Kartenprogramme
| Field | Type | Description |
|---|---|---|
datarequired | array<object> | |
data[]. | string | |
data[]. | string | |
data[]. | string | enum STAMP | POINTS | OFFERS | PACKAGE | MEMBERSHIP |
data[]. | integer | null | |
data[]. | array<object> | |
data[]. | string | |
data[]. | string | |
data[]. | integer | |
data[]. | integer | null | |
data[]. | integer | Wirksame Punktekosten (ohne eigenen Wert = threshold) |
data[]. | boolean | Wird automatisch als Gutschein ausgestellt (nicht über /redeem einlösbar) |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": [
{
"id": "string",
"name": "string",
"type": "STAMP",
"stampGoal": 0,
"rewards": [
{
"id": "string",
"title": "string",
"threshold": 0,
"valueCents": 0,
"pointsCost": 0,
"autoIssue": true
}
]
}
],
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (5)
| Status | Code |
|---|---|
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen |
GET /locations
Standorte (standortgebundene Keys: nur die eigenen)
Scope: setup:read
Response 200 · Location
Standorte
| Field | Type | Description |
|---|---|---|
datarequired | array<object> | |
data[]. | string | |
data[]. | string | |
data[]. | string | enum OPEN | CLOSED |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": [
{
"id": "string",
"name": "string",
"status": "OPEN"
}
],
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (5)
| Status | Code |
|---|---|
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen |
GET /employees
Aktive Mitarbeiter mit Rolle und Standorten
Beschäftigtendaten (Name, Rolle): nur Systemen geben, die sie brauchen.
Scope: setup:read
Response 200 · Employee
Mitarbeiter
| Field | Type | Description |
|---|---|---|
datarequired | array<object> | |
data[]. | string | |
data[]. | string | null | |
data[]. | string | enum OWNER | MANAGER | EMPLOYEE |
data[]. | array<string> | |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": [
{
"id": "string",
"name": "string",
"role": "OWNER",
"locationIds": [
"string"
]
}
],
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (5)
| Status | Code |
|---|---|
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen |
Cards
POST /passes
Anmeldelink für einen neuen Gast
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.
Scope: pass:write
Parameters
| Field | Type | Description |
|---|---|---|
Idempotency-Keyheader | string | 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. maxLength 255 · pattern ^[\x21-\x7E]+$ |
Request body · CreatePassLinkRequest
| Field | Type | Description |
|---|---|---|
cardIdrequired | string | Kartenprogramm (GET /cards)maxLength 64 |
employeeIdrequired | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdrequired | string | Standort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.maxLength 64 |
employeeRef | string | Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen). maxLength 120 |
Response 201 · PassLink
Anmeldelink
| Field | Type | Description |
|---|---|---|
datarequired | object | |
data.required | string | |
data.required | string (uri) | Anmeldelink (7 Tage gültig, mehrfach nutzbar, an keinen Gast gebunden). Bei einer idempotenten Wiederholung entsteht ein frischer Link. |
data.required | string (date-time) | |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"cardId": "string",
"addUrl": "string",
"expiresAt": "2026-11-07T10:00:00.000Z"
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (8)
| Status | Code |
|---|---|
| 400 | BAD_REQUEST (Validierung), LOCATION_WRONG_COMPANY, IDEMPOTENCY_KEY_INVALID |
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED, EMPLOYEE_NOT_AT_LOCATION, ACTOR_ROLE_NOT_ALLOWED |
| 404 | EMPLOYEE_NOT_FOUND, CARD_NOT_FOUND |
| 409 | CARD_ARCHIVED, CARD_NOT_AT_LOCATION (Karte an diesem Standort nicht ausgegeben), LOCATION_DEACTIVATED, IDEMPOTENCY_KEY_REUSED |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | REQUEST_IN_PROGRESS |
GET /passes/by-serial/{serial}
Pass über die Seriennummer aus dem Wallet-Barcode
Scope: pass:read
Parameters
| Field | Type | Description |
|---|---|---|
serialrequiredpath | string |
Response 200 · Pass
Pass
| Field | Type | Description |
|---|---|---|
datarequired | object | |
data.required | string | |
data.required | string | |
data.required | string | |
data.required | string | Seriennummer aus dem Wallet-Barcode |
data.required | integer | |
data.required | integer | |
data.required | string | null | Aktuelle Treuestufe oder null |
data.required | string (date-time) | null | |
data.required | string (date-time) | |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"id": "string",
"cardId": "string",
"customerId": "string",
"serialNumber": "string",
"stampCount": 0,
"pointsBalance": 0,
"tier": "string",
"lastStampAt": "2026-11-07T10:00:00.000Z",
"createdAt": "2026-11-07T10:00:00.000Z"
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (6)
| Status | Code |
|---|---|
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED |
| 404 | PASS_NOT_FOUND (auch storniert) |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen |
GET /passes/{id}
Aktueller Stand eines Passes
Scope: pass:read
Parameters
| Field | Type | Description |
|---|---|---|
idrequiredpath | string | maxLength 64 |
Response 200 · Pass
Pass
| Field | Type | Description |
|---|---|---|
datarequired | object | |
data.required | string | |
data.required | string | |
data.required | string | |
data.required | string | Seriennummer aus dem Wallet-Barcode |
data.required | integer | |
data.required | integer | |
data.required | string | null | Aktuelle Treuestufe oder null |
data.required | string (date-time) | null | |
data.required | string (date-time) | |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"id": "string",
"cardId": "string",
"customerId": "string",
"serialNumber": "string",
"stampCount": 0,
"pointsBalance": 0,
"tier": "string",
"lastStampAt": "2026-11-07T10:00:00.000Z",
"createdAt": "2026-11-07T10:00:00.000Z"
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (6)
| Status | Code |
|---|---|
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED |
| 404 | PASS_NOT_FOUND (auch storniert) |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen |
POST /passes/{id}/stamp
Stempel/Punkte buchen
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).
Scope: pass:write
Parameters
| Field | Type | Description |
|---|---|---|
idrequiredpath | string | maxLength 64 |
Idempotency-Keyheader | string | 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. maxLength 255 · pattern ^[\x21-\x7E]+$ |
Request body · StampRequest
Ohne Betrag ein Besuch; mit amountCents Umsatzpunkte; mit points direkte Punkte. Welcher Weg passt, entscheidet die Karte (sonst 400).
| Field | Type | Description |
|---|---|---|
employeeIdrequired | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdrequired | string | Standort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.maxLength 64 |
employeeRef | string | Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen). maxLength 120 |
amountCents | integer | minimum 1 · maximum 100000000 |
points | integer | minimum 1 · maximum 100000 |
Response 201 · PassState
Neuer Stand
| Field | Type | Description |
|---|---|---|
datarequired | object | Neuer Stand nach Stempeln/Einlösen. |
data. | string | |
data. | string | |
data. | string | |
data. | string | Seriennummer aus dem Wallet-Barcode |
data. | integer | |
data. | integer | |
data. | string | null | Aktuelle Treuestufe oder null |
data. | string (date-time) | null | |
data. | string (date-time) | |
data. | integer | Monotoner Gesamtfortschritt |
data. | integer | Laufende Runde der Stempelkarte |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"id": "string",
"cardId": "string",
"customerId": "string",
"serialNumber": "string",
"stampCount": 0,
"pointsBalance": 0,
"tier": "string",
"lastStampAt": "2026-11-07T10:00:00.000Z",
"createdAt": "2026-11-07T10:00:00.000Z",
"lifetimeProgress": 0,
"stampCycle": 0
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (8)
| Status | Code |
|---|---|
| 400 | 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 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | 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 | EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND |
| 409 | LOCATION_DEACTIVATED, PASS_VOIDED, IDEMPOTENCY_KEY_REUSED, REQUEST_ABANDONED (nur Besuch auf einer Angebotskarte: abgebrochene Erstanfrage wird nicht erneut ausgeführt) |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | REQUEST_IN_PROGRESS, RETRY |
POST /passes/{id}/redeem
Prämie einlösen
Manager-Eskalation ab Warenwert-Schwelle wie an der Theke (PIN_REQUIRED, wenn employeeId nicht MANAGER/OWNER ist).
Scope: pass:redeem
Parameters
| Field | Type | Description |
|---|---|---|
idrequiredpath | string | maxLength 64 |
Idempotency-Keyheader | string | 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. maxLength 255 · pattern ^[\x21-\x7E]+$ |
Request body · RedeemRequest
| Field | Type | Description |
|---|---|---|
rewardIdrequired | string | Prämie (GET /cards → rewards)maxLength 64 |
valueCents | integer | Warenwert für Mindestumsatz und Manager-Eskalation minimum 0 · maximum 100000000 |
employeeIdrequired | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdrequired | string | Standort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.maxLength 64 |
employeeRef | string | Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen). maxLength 120 |
Response 201 · PassState
Neuer Stand
| Field | Type | Description |
|---|---|---|
datarequired | object | Neuer Stand nach Stempeln/Einlösen. |
data. | string | |
data. | string | |
data. | string | |
data. | string | Seriennummer aus dem Wallet-Barcode |
data. | integer | |
data. | integer | |
data. | string | null | Aktuelle Treuestufe oder null |
data. | string (date-time) | null | |
data. | string (date-time) | |
data. | integer | Monotoner Gesamtfortschritt |
data. | integer | Laufende Runde der Stempelkarte |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"id": "string",
"cardId": "string",
"customerId": "string",
"serialNumber": "string",
"stampCount": 0,
"pointsBalance": 0,
"tier": "string",
"lastStampAt": "2026-11-07T10:00:00.000Z",
"createdAt": "2026-11-07T10:00:00.000Z",
"lifetimeProgress": 0,
"stampCycle": 0
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (8)
| Status | Code |
|---|---|
| 400 | BAD_REQUEST (Validierung), LOCATION_WRONG_COMPANY, IDEMPOTENCY_KEY_INVALID, REWARD_AUTO_ISSUED (wird automatisch als Gutschein ausgestellt), PACKAGE_USE_REQUIRED, MEMBERSHIP_ACTION_REQUIRED |
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | 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 | EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND, REWARD_NOT_FOUND |
| 409 | LOCATION_DEACTIVATED, PASS_VOIDED, IDEMPOTENCY_KEY_REUSED |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | REQUEST_IN_PROGRESS, RETRY |
POST /passes/{id}/cancel
Karte stornieren (MANAGER+)
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.
Scope: pass:cancel
Parameters
| Field | Type | Description |
|---|---|---|
idrequiredpath | string | maxLength 64 |
Idempotency-Keyheader | string | 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. maxLength 255 · pattern ^[\x21-\x7E]+$ |
Request body · CancelRequest
employeeId muss Rolle MANAGER oder OWNER haben (sonst ROLE_NOT_ALLOWED).
| Field | Type | Description |
|---|---|---|
employeeIdrequired | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdrequired | string | Standort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.maxLength 64 |
employeeRef | string | Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen). maxLength 120 |
Response 201
Storniert
| Field | Type | Description |
|---|---|---|
datarequired | object | |
data.required | string | |
data.required | true | |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"id": "string",
"cancelled": true
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (8)
| Status | Code |
|---|---|
| 400 | BAD_REQUEST (Validierung), LOCATION_WRONG_COMPANY, IDEMPOTENCY_KEY_INVALID |
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED, EMPLOYEE_NOT_AT_LOCATION, ACTOR_ROLE_NOT_ALLOWED, ROLE_NOT_ALLOWED |
| 404 | EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND |
| 409 | LOCATION_DEACTIVATED, PASS_VOIDED, IDEMPOTENCY_KEY_REUSED |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | REQUEST_IN_PROGRESS, RETRY |
Offers
GET /passes/{id}/offers
Angebote eines Passes (Angebotskarte)
Scope: offer:read
Parameters
| Field | Type | Description |
|---|---|---|
idrequiredpath | string | maxLength 64 |
Response 200 · OfferList
Angebote
| Field | Type | Description |
|---|---|---|
datarequired | object | |
data. | array<object> | |
data. | string | |
data. | string | |
data. | string | null | |
data. | object | null | Rohe Übersetzungen von title/description |
data. | boolean | |
data. | string | enum PERCENT | AMOUNT | BOGO | FREE_ITEM | FREE_FOR_GUEST | CUSTOM |
data. | integer | null | |
data. | integer | null | |
data. | string | null | |
data. | object | null | |
data. | string | enum available | used_up | cooldown | exhausted | not_started | expired | not_eligible | wrong_location |
data. | integer | |
data. | string (date-time) | null | |
data. | string (date-time) | null | |
data. | string (date-time) | null | |
data. | integer | |
data. | integer | |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"offers": [
{
"offerId": "string",
"title": "string",
"description": "string",
"translations": {},
"highlightToday": true,
"kind": "PERCENT",
"valuePercent": 0,
"valueCents": 0,
"taxRate": "string",
"valueSplit": {},
"status": "available",
"remaining": 0,
"validUntil": "2026-11-07T10:00:00.000Z",
"availableAgainAt": "2026-11-07T10:00:00.000Z",
"lastRedeemedAt": "2026-11-07T10:00:00.000Z",
"order": 0
}
],
"openCount": 0
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (6)
| Status | Code |
|---|---|
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED |
| 404 | PASS_NOT_FOUND, NOT_FOUND (Angebote nicht aktiviert) |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen |
POST /passes/{id}/redeem-offer
Angebot einlösen
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).
Scope: offer:redeem
Parameters
| Field | Type | Description |
|---|---|---|
idrequiredpath | string | maxLength 64 |
Idempotency-Keyheader | string | 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. maxLength 255 · pattern ^[\x21-\x7E]+$ |
Request body · RedeemOfferRequest
| Field | Type | Description |
|---|---|---|
offerIdrequired | string | Angebot (GET /passes/{id}/offers)maxLength 64 |
employeeIdrequired | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdrequired | string | Standort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.maxLength 64 |
employeeRef | string | Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen). maxLength 120 |
Response 201 · OfferRedemption
Einlösung
| Field | Type | Description |
|---|---|---|
datarequired | object | |
data. | string | |
data. | string | |
data. | integer | Wie oft der Gast das Angebot im Fenster noch einlösen kann |
data. | integer | |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"offerId": "string",
"title": "string",
"remaining": 0,
"openCount": 0
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (8)
| Status | Code |
|---|---|
| 400 | 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 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | 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 | EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND, OFFER_NOT_FOUND, NOT_FOUND (Angebote nicht aktiviert) |
| 409 | 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 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | REQUEST_IN_PROGRESS |
Guests
GET /customers
Gast über die E-Mail finden
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.
Scope: customer:read
Parameters
| Field | Type | Description |
|---|---|---|
emailrequiredquery | string (email) | maxLength 254 |
Response 200 · Customer
Gast
| Field | Type | Description |
|---|---|---|
datarequired | object | Minimale Gast-Sicht (kein Geburtstag, kein Besuchsverhalten). Jeder Abruf wird protokolliert. |
data. | string | |
data. | string | null | |
data. | string (email) | null | |
data. | string | |
data. | boolean | Werbe-Einwilligung. Werbe-E-Mails aus dem eigenen System nur, wenn true UND emailVerifiedAt gesetzt ist. |
data. | string (date-time) | null | |
data. | boolean | 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. |
data. | string (date-time) | |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"id": "string",
"name": "string",
"email": "string",
"customerNumberLabel": "string",
"marketingConsent": true,
"emailVerifiedAt": "2026-11-07T10:00:00.000Z",
"anonymous": true,
"createdAt": "2026-11-07T10:00:00.000Z"
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (7)
| Status | Code |
|---|---|
| 400 | BAD_REQUEST: email fehlt oder ist ungültig, unbekannte Query-Parameter |
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED |
| 404 | CUSTOMER_NOT_FOUND |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen |
GET /customers/deleted
Gelöschte Gäste seit einem Zeitpunkt
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.
Scope: customer:read
Parameters
| Field | Type | Description |
|---|---|---|
sincerequiredquery | string (date-time) | ISO-8601-Zeitpunkt; Löschungen ab einschließlich |
cursorquery | string | maxLength 64 |
limitquery | integer | minimum 1 · maximum 500 · default 100 |
Response 200 · DeletedCustomerPage
Lösch-Nachweise
| Field | Type | Description |
|---|---|---|
datarequired | object | |
data.required | array<object> | |
data.required | string | Eintrag (Cursor) |
data.required | string | |
data.required | array<string> | |
data.required | string (date-time) | |
data.required | string | null | Als cursor für die nächste Seite übergeben; null = Ende |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"items": [
{
"id": "string",
"customerId": "string",
"passIds": [
"string"
],
"deletedAt": "2026-11-07T10:00:00.000Z"
}
],
"nextCursor": "string"
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (6)
| Status | Code |
|---|---|
| 400 | BAD_REQUEST: since fehlt oder ist kein ISO-8601-Zeitpunkt, limit außerhalb 1 bis 500 |
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen |
GET /customers/{id}
Gast (minimale Sicht)
Nicht für standortgebundene Keys.
Scope: customer:read
Parameters
| Field | Type | Description |
|---|---|---|
idrequiredpath | string |
Response 200 · Customer
Gast
| Field | Type | Description |
|---|---|---|
datarequired | object | Minimale Gast-Sicht (kein Geburtstag, kein Besuchsverhalten). Jeder Abruf wird protokolliert. |
data. | string | |
data. | string | null | |
data. | string (email) | null | |
data. | string | |
data. | boolean | Werbe-Einwilligung. Werbe-E-Mails aus dem eigenen System nur, wenn true UND emailVerifiedAt gesetzt ist. |
data. | string (date-time) | null | |
data. | boolean | 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. |
data. | string (date-time) | |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"id": "string",
"name": "string",
"email": "string",
"customerNumberLabel": "string",
"marketingConsent": true,
"emailVerifiedAt": "2026-11-07T10:00:00.000Z",
"anonymous": true,
"createdAt": "2026-11-07T10:00:00.000Z"
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (6)
| Status | Code |
|---|---|
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED |
| 404 | CUSTOMER_NOT_FOUND |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen |
Messages
POST /notifications/push
Karten-Update an Gäste mit Werbe-Einwilligung
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).
Scope: notification:send
Parameters
| Field | Type | Description |
|---|---|---|
Idempotency-Keyheader | string | 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. maxLength 255 · pattern ^[\x21-\x7E]+$ |
Request body · PushRequest
| Field | Type | Description |
|---|---|---|
textrequired | string | Kartentext; nur bekannte Platzhalter wie {Kundenname}, {Betrieb} (sonst 400 PLACEHOLDER_UNKNOWN). Anstößige Inhalte lehnt die Moderation ab (422). minLength 1 · maxLength 240 |
cardId | string | Optional: nur Gäste dieses Kartenprogramms maxLength 64 |
Response 201
Versendet
| Field | Type | Description |
|---|---|---|
datarequired | object | |
data.required | integer | Zahl der erreichten Gäste |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"recipients": 0
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (9)
| Status | Code |
|---|---|
| 400 | BAD_REQUEST (Validierung), PLACEHOLDER_UNKNOWN (unbekannter Platzhalter), QUIET_HOURS (Plattform-Ruhezeit), IDEMPOTENCY_KEY_INVALID |
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED |
| 404 | CARD_NOT_FOUND (cardId gehört nicht zum Betrieb) |
| 409 | IDEMPOTENCY_KEY_REUSED, REQUEST_ABANDONED |
| 422 | UNPROCESSABLE (Text von der Moderation abgelehnt) |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | REQUEST_IN_PROGRESS |
Reports
GET /analytics
Übersicht: letzte 30 Tage und Bestand
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.
Scope: analytics:read
Response 200 · AnalyticsOverview
Übersicht
| Field | Type | Description |
|---|---|---|
datarequired | object | 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. |
data. | integer | Bestand: nicht archivierte Kartenprogramme des ganzen Betriebs (auch bei standortgebundenen Keys nicht nach Standort gefiltert) |
data. | integer | Ausgegebene Karten, letzte 30 Tage |
data. | integer | Stempel-/Punktebuchungen, letzte 30 Tage |
data. | integer | Einlösungen (Prämien und Angebote), letzte 30 Tage |
data. | integer | Bestand: nicht stornierte Gastkarten |
data. | integer | Bestand: Gäste |
data. | integer | Neue Gäste, letzte 30 Tage |
data. | object | Vergleich mit den 30 Tagen davor je Kennzahl (stampsAdded, redemptions, cardsIssued, newCustomers) |
timestamprequired | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"cardPrograms": 0,
"cardsIssued": 0,
"stampsAdded": 0,
"redemptions": 0,
"activeCards": 0,
"totalCustomers": 0,
"newCustomers": 0,
"deltas": {}
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Possible errors (5)
| Status | Code |
|---|---|
| 401 | UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen) |
| 403 | SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED |
| 429 | 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 | INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar) |
| 503 | SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen |
Webhook events
pass.created
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).
Fields in data
| Field | Type | Description |
|---|---|---|
passIdrequired | string | |
cardIdrequired | string | |
customerIdrequired | string | |
employeeIdrequired | string | null | |
locationIdrequired | string | null | |
channelrequired | string | null |
Envelope
| Field | Type | Description |
|---|---|---|
idrequired | string | evt_…, stabil über Wiederholungen (Dedupe) |
eventrequired | "pass.created" | |
timestamprequired | string (date-time) | Zeitpunkt des Ereignisses (UTC) |
test | true | Nur bei Tests aus „Test senden" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz. |
Headers
| Field | Type | Description |
|---|---|---|
X-tapja-Eventrequired | string | Name des Ereignisses |
X-tapja-Deliveryrequired | string | Kennung der Zustellung (= id im Body), stabil über Wiederholungen |
X-tapja-Timestamprequired | string | Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s) |
X-tapja-Signaturerequired | string | sha256=<hex>: HMAC-SHA256 mit dem Webhook-Secret über ${X-tapja-Timestamp}.${roher Body} |
X-tapja-Test | "1" | Nur bei Tests („Test senden"): 1. Fehlt bei echten Ereignissen. Erlaubt das Aussortieren vor dem Parsen. |
pass.stamped
Stempel/Punkte gebucht (Theke, App, Selbststempeln, API). timestamp = Gerätezeit bei offline nachgereichten Buchungen.
Fields in data
| Field | Type | Description |
|---|---|---|
passIdrequired | string | |
cardIdrequired | string | |
stampCountrequired | integer | |
pointsBalancerequired | integer | |
employeeIdrequired | string | null | |
locationIdrequired | string | null | |
channelrequired | string | null |
pass.redeemed
Prämie oder Gutschein eingelöst. timestamp = Gerätezeit bei offline nachgereichten Buchungen.
Fields in data
| Field | Type | Description |
|---|---|---|
passIdrequired | string | |
rewardId | string | |
locationId | string |
pass.cancelled
Karte storniert.
Fields in data
| Field | Type | Description |
|---|---|---|
passIdrequired | string | |
cardIdrequired | string |
pass.reactivated
Stornierte Karte nach nachgeholter E-Mail-Bestätigung wieder aktiv.
Fields in data
| Field | Type | Description |
|---|---|---|
passIdrequired | string | |
customerIdrequired | string |
pass.corrected
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.
Fields in data
| Field | Type | Description |
|---|---|---|
passIdrequired | string | |
fieldrequired | string | enum stampCount | pointsBalance |
valuerequired | integer | |
employeeId | string | |
locationId | string |
reward.ready
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.
Fields in data
| Field | Type | Description |
|---|---|---|
passIdrequired | string | |
cardIdrequired | string | |
rewardIdsrequired | array<string> |
offer.redeemed
Angebot eingelöst.
Fields in data
| Field | Type | Description |
|---|---|---|
passIdrequired | string | |
offerIdrequired | string | |
locationId | string |
package.used
Einheit(en) einer Paketkarte genutzt.
Fields in data
| Field | Type | Description |
|---|---|---|
passIdrequired | string | |
quantityrequired | integer | |
unitsrequired | integer | |
employeeIdrequired | string | |
locationId | string |
customer.created
Neuer Gast. Bei der Anmeldung (Selbstanmeldung, Anmeldelink) erst nach erfolgreicher Kartenausgabe und meist nach pass.created; beim Anlegen im Dashboard sofort, auch ohne Karte.
Fields in data
| Field | Type | Description |
|---|---|---|
customerIdrequired | string |
customer.deleted
Gast gelöscht (Art. 17): im eigenen System ebenfalls löschen.
Fields in data
| Field | Type | Description |
|---|---|---|
customerIdrequired | string | |
passIdsrequired | array<string> |
customer.consent_changed
Werbe-Einwilligung eines bestehenden Gastes geändert (nicht bei der Erstanmeldung).
Fields in data
| Field | Type | Description |
|---|---|---|
customerIdrequired | string | |
marketingConsentrequired | boolean |
campaign.sent
Kampagne versendet.
Fields in data
| Field | Type | Description |
|---|---|---|
campaignIdrequired | string | |
recipientsrequired | integer |
pingcannot be subscribed to
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.
Fields in data
| Field | Type | Description |
|---|---|---|
messagerequired | string |
Schemas
Error
| Field | Type | Description |
|---|---|---|
errorrequired | object | |
error.required | string | 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.e.g. COOLDOWN_ACTIVE, PASS_NOT_FOUND, SCOPE_MISSING |
error.required | string | Für Menschen; meist deutsch, bei Formfehlern (Validierung) teils englisch. |
Pass
| Field | Type | Description |
|---|---|---|
idrequired | string | |
cardIdrequired | string | |
customerIdrequired | string | |
serialNumberrequired | string | Seriennummer aus dem Wallet-Barcode |
stampCountrequired | integer | |
pointsBalancerequired | integer | |
tierrequired | string | null | Aktuelle Treuestufe oder null |
lastStampAtrequired | string (date-time) | null | |
createdAtrequired | string (date-time) |
PassState
Neuer Stand nach Stempeln/Einlösen.
| Field | Type | Description |
|---|---|---|
id | string | |
cardId | string | |
customerId | string | |
serialNumber | string | Seriennummer aus dem Wallet-Barcode |
stampCount | integer | |
pointsBalance | integer | |
tier | string | null | Aktuelle Treuestufe oder null |
lastStampAt | string (date-time) | null | |
createdAt | string (date-time) | |
lifetimeProgress | integer | Monotoner Gesamtfortschritt |
stampCycle | integer | Laufende Runde der Stempelkarte |
PassLink
| Field | Type | Description |
|---|---|---|
cardIdrequired | string | |
addUrlrequired | string (uri) | Anmeldelink (7 Tage gültig, mehrfach nutzbar, an keinen Gast gebunden). Bei einer idempotenten Wiederholung entsteht ein frischer Link. |
expiresAtrequired | string (date-time) |
Customer
Minimale Gast-Sicht (kein Geburtstag, kein Besuchsverhalten). Jeder Abruf wird protokolliert.
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | null | |
email | string (email) | null | |
customerNumberLabel | string | |
marketingConsent | boolean | Werbe-Einwilligung. Werbe-E-Mails aus dem eigenen System nur, wenn true UND emailVerifiedAt gesetzt ist. |
emailVerifiedAt | string (date-time) | null | |
anonymous | boolean | 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 | string (date-time) |
DeletedCustomer
Lösch-Nachweis: im eigenen System Gast und Karten ebenfalls löschen. Nur IDs, 30 Tage abrufbar.
| Field | Type | Description |
|---|---|---|
idrequired | string | Eintrag (Cursor) |
customerIdrequired | string | |
passIdsrequired | array<string> | |
deletedAtrequired | string (date-time) |
DeletedCustomerPage
| Field | Type | Description |
|---|---|---|
itemsrequired | array<object> | |
items[].required | string | Eintrag (Cursor) |
items[].required | string | |
items[].required | array<string> | |
items[].required | string (date-time) | |
nextCursorrequired | string | null | Als cursor für die nächste Seite übergeben; null = Ende |
Offer
| Field | Type | Description |
|---|---|---|
offerId | string | |
title | string | |
description | string | null | |
translations | object | null | Rohe Übersetzungen von title/description |
highlightToday | boolean | |
kind | string | enum PERCENT | AMOUNT | BOGO | FREE_ITEM | FREE_FOR_GUEST | CUSTOM |
valuePercent | integer | null | |
valueCents | integer | null | |
taxRate | string | null | |
valueSplit | object | null | |
status | string | enum available | used_up | cooldown | exhausted | not_started | expired | not_eligible | wrong_location |
remaining | integer | |
validUntil | string (date-time) | null | |
availableAgainAt | string (date-time) | null | |
lastRedeemedAt | string (date-time) | null | |
order | integer |
OfferList
| Field | Type | Description |
|---|---|---|
offers | array<object> | |
offers[]. | string | |
offers[]. | string | |
offers[]. | string | null | |
offers[]. | object | null | Rohe Übersetzungen von title/description |
offers[]. | boolean | |
offers[]. | string | enum PERCENT | AMOUNT | BOGO | FREE_ITEM | FREE_FOR_GUEST | CUSTOM |
offers[]. | integer | null | |
offers[]. | integer | null | |
offers[]. | string | null | |
offers[]. | object | null | |
offers[]. | string | enum available | used_up | cooldown | exhausted | not_started | expired | not_eligible | wrong_location |
offers[]. | integer | |
offers[]. | string (date-time) | null | |
offers[]. | string (date-time) | null | |
offers[]. | string (date-time) | null | |
offers[]. | integer | |
openCount | integer |
OfferRedemption
| Field | Type | Description |
|---|---|---|
offerId | string | |
title | string | |
remaining | integer | Wie oft der Gast das Angebot im Fenster noch einlösen kann |
openCount | integer |
Card
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | |
type | string | enum STAMP | POINTS | OFFERS | PACKAGE | MEMBERSHIP |
stampGoal | integer | null | |
rewards | array<object> | |
rewards[]. | string | |
rewards[]. | string | |
rewards[]. | integer | |
rewards[]. | integer | null | |
rewards[]. | integer | Wirksame Punktekosten (ohne eigenen Wert = threshold) |
rewards[]. | boolean | Wird automatisch als Gutschein ausgestellt (nicht über /redeem einlösbar) |
Location
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | |
status | string | enum OPEN | CLOSED |
Employee
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | null | |
role | string | enum OWNER | MANAGER | EMPLOYEE |
locationIds | array<string> |
AnalyticsOverview
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.
| Field | Type | Description |
|---|---|---|
cardPrograms | integer | Bestand: nicht archivierte Kartenprogramme des ganzen Betriebs (auch bei standortgebundenen Keys nicht nach Standort gefiltert) |
cardsIssued | integer | Ausgegebene Karten, letzte 30 Tage |
stampsAdded | integer | Stempel-/Punktebuchungen, letzte 30 Tage |
redemptions | integer | Einlösungen (Prämien und Angebote), letzte 30 Tage |
activeCards | integer | Bestand: nicht stornierte Gastkarten |
totalCustomers | integer | Bestand: Gäste |
newCustomers | integer | Neue Gäste, letzte 30 Tage |
deltas | object | Vergleich mit den 30 Tagen davor je Kennzahl (stampsAdded, redemptions, cardsIssued, newCustomers) |
CreatePassLinkRequest
| Field | Type | Description |
|---|---|---|
cardIdrequired | string | Kartenprogramm (GET /cards)maxLength 64 |
employeeIdrequired | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdrequired | string | Standort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.maxLength 64 |
employeeRef | string | Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen). maxLength 120 |
StampRequest
Ohne Betrag ein Besuch; mit amountCents Umsatzpunkte; mit points direkte Punkte. Welcher Weg passt, entscheidet die Karte (sonst 400).
| Field | Type | Description |
|---|---|---|
employeeIdrequired | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdrequired | string | Standort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.maxLength 64 |
employeeRef | string | Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen). maxLength 120 |
amountCents | integer | minimum 1 · maximum 100000000 |
points | integer | minimum 1 · maximum 100000 |
RedeemRequest
| Field | Type | Description |
|---|---|---|
rewardIdrequired | string | Prämie (GET /cards → rewards)maxLength 64 |
valueCents | integer | Warenwert für Mindestumsatz und Manager-Eskalation minimum 0 · maximum 100000000 |
employeeIdrequired | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdrequired | string | Standort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.maxLength 64 |
employeeRef | string | Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen). maxLength 120 |
RedeemOfferRequest
| Field | Type | Description |
|---|---|---|
offerIdrequired | string | Angebot (GET /passes/{id}/offers)maxLength 64 |
employeeIdrequired | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdrequired | string | Standort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.maxLength 64 |
employeeRef | string | Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen). maxLength 120 |
CancelRequest
employeeId muss Rolle MANAGER oder OWNER haben (sonst ROLE_NOT_ALLOWED).
| Field | Type | Description |
|---|---|---|
employeeIdrequired | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdrequired | string | Standort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.maxLength 64 |
employeeRef | string | Optionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen). maxLength 120 |
PushRequest
| Field | Type | Description |
|---|---|---|
textrequired | string | Kartentext; nur bekannte Platzhalter wie {Kundenname}, {Betrieb} (sonst 400 PLACEHOLDER_UNKNOWN). Anstößige Inhalte lehnt die Moderation ab (422). minLength 1 · maxLength 240 |
cardId | string | Optional: nur Gäste dieses Kartenprogramms maxLength 64 |
Error codes
| Code | Status | Endpoints | Note |
|---|---|---|---|
AMOUNT_BELOW_MINIMUM | 400 | ||
AMOUNT_REQUIRED | 400 | ||
AMOUNT_TOO_SMALL | 400 | ||
BAD_REQUEST | 400 | Validierung | |
CARD_HAS_NO_BALANCE | 400 | ||
COUPON_NOT_COMBINABLE | 400 | heute schon ein nicht kombinierbarer Gutschein eingelöst | |
IDEMPOTENCY_KEY_INVALID | 400 | ||
LOCATION_WRONG_COMPANY | 400 | ||
MEMBERSHIP_ACTION_REQUIRED | 400 | ||
OFFERS_NOT_ON_CARD | 400 | keine Angebotskarte | |
PACKAGE_USE_REQUIRED | 400 | ||
PLACEHOLDER_UNKNOWN | 400 | unbekannter Platzhalter | |
POINTS_BALANCE_LIMIT | 400 | ||
POINTS_REQUIRED | 400 | ||
QUIET_HOURS | 400 | Plattform-Ruhezeit | |
REWARD_AUTO_ISSUED | 400 | wird automatisch als Gutschein ausgestellt | |
STAMP_CAP_EXCEEDED | 400 | ||
STAMP_MODE_AMOUNT | 400 | ||
STAMP_MODE_VISIT | 400 | ||
UNAUTHORIZED | 401 | all endpoints | Key fehlt, ist ungültig, widerrufen oder abgelaufen |
ACTOR_ROLE_NOT_ALLOWED | 403 | ||
CARD_FULL | 403 | ||
COMPANY_SUSPENDED | 403 | all endpoints | |
COOLDOWN_ACTIVE | 403 | ||
EMPLOYEE_NOT_AT_LOCATION | 403 | ||
GUEST_EMAIL_UNVERIFIED | 403 | ||
LOCATION_NOT_ALLOWED | 403 | ||
NOT_ENOUGH_POINTS | 403 | ||
OFFER_COOLDOWN | 403 | ||
OFFER_EXHAUSTED | 403 | ||
OFFER_EXPIRED | 403 | ||
OFFER_NOT_ELIGIBLE | 403 | ||
OFFER_NOT_STARTED | 403 | ||
OFFER_WRONG_LOCATION | 403 | ||
PIN_REQUIRED | 403 | Manager-Eskalation | |
PLAN_FEATURE_REQUIRED | 403 | all endpoints | |
REDEEM_NOT_AT_LOCATION | 403 | ||
REWARD_ALREADY_REDEEMED | 403 | ||
REWARD_EXPIRED | 403 | ||
REWARD_LIMIT_REACHED | 403 | ||
REWARD_MEMBERSHIP_REQUIRED | 403 | ||
REWARD_MIN_PURCHASE | 403 | ||
REWARD_NOT_COMBINABLE | 403 | ||
REWARD_NOT_YET_VALID | 403 | ||
REWARD_QUOTA_EXHAUSTED | 403 | ||
REWARD_THRESHOLD_NOT_REACHED | 403 | ||
REWARD_TIER_REQUIRED | 403 | ||
REWARD_WRONG_LOCATION | 403 | ||
ROLE_NOT_ALLOWED | 403 | ||
SCOPE_MISSING | 403 | all endpoints | |
STAMP_LIMIT_REACHED | 403 | ||
CARD_NOT_FOUND | 404 | cardId gehört nicht zum Betrieb | |
CUSTOMER_NOT_FOUND | 404 | ||
EMPLOYEE_NOT_FOUND | 404 | ||
NOT_FOUND | 404 | Angebote nicht aktiviert | |
OFFER_NOT_FOUND | 404 | ||
PASS_NOT_FOUND | 404 | auch storniert | |
REWARD_NOT_FOUND | 404 | ||
CARD_ARCHIVED | 409 | ||
CARD_NOT_AT_LOCATION | 409 | Karte an diesem Standort nicht ausgegeben | |
IDEMPOTENCY_KEY_REUSED | 409 | ||
LOCATION_DEACTIVATED | 409 | ||
OFFER_ALREADY_REDEEMED | 409 | gleichzeitige Einlösung war schneller | |
OFFER_USED_UP | 409 | im Fenster schon eingelöst | |
PASS_VOIDED | 409 | ||
REQUEST_ABANDONED | 409 | nur Besuch auf einer Angebotskarte: abgebrochene Erstanfrage wird nicht erneut ausgeführt | |
UNPROCESSABLE | 422 | Text von der Moderation abgelehnt | |
RATE_LIMITED | 429 | all endpoints | Gesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After |
INTERNAL_ERROR | 500 | all endpoints | unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar |
REQUEST_IN_PROGRESS | 503 | all endpoints | Erstanfrage mit diesem Idempotency-Key läuft noch |
RETRY | 503 | ||
SERVICE_UNAVAILABLE | 503 | vorübergehend nicht verfügbar |