Référence de l’API
Endpoints, webhooks, codes d’erreur
Générée à partir de la description OpenAPI de l’interface. URL de base : https://api.tapja.de/api/v1/public
Les descriptions de la référence sont pour l’instant en allemand.
Télécharger le fichier OpenAPI Aller au guide
Configuration
GET /cards
Aktive Kartenprogramme mit Prämien
Scope: setup:read
Réponse 200 · Card
Kartenprogramme
| Champ | Type | Description |
|---|---|---|
dataobligatoire | 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) |
timestampobligatoire | 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"
}Erreurs possibles (5)
| Statut | 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
Réponse 200 · Location
Standorte
| Champ | Type | Description |
|---|---|---|
dataobligatoire | array<object> | |
data[]. | string | |
data[]. | string | |
data[]. | string | enum OPEN | CLOSED |
timestampobligatoire | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": [
{
"id": "string",
"name": "string",
"status": "OPEN"
}
],
"timestamp": "2026-11-07T10:00:00.000Z"
}Erreurs possibles (5)
| Statut | 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
Réponse 200 · Employee
Mitarbeiter
| Champ | Type | Description |
|---|---|---|
dataobligatoire | array<object> | |
data[]. | string | |
data[]. | string | null | |
data[]. | string | enum OWNER | MANAGER | EMPLOYEE |
data[]. | array<string> | |
timestampobligatoire | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": [
{
"id": "string",
"name": "string",
"role": "OWNER",
"locationIds": [
"string"
]
}
],
"timestamp": "2026-11-07T10:00:00.000Z"
}Erreurs possibles (5)
| Statut | 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 |
Cartes
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
Paramètres
| Champ | 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]+$ |
Corps de la requête · CreatePassLinkRequest
| Champ | Type | Description |
|---|---|---|
cardIdobligatoire | string | Kartenprogramm (GET /cards)maxLength 64 |
employeeIdobligatoire | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdobligatoire | 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 |
Réponse 201 · PassLink
Anmeldelink
| Champ | Type | Description |
|---|---|---|
dataobligatoire | object | |
data.obligatoire | string | |
data.obligatoire | string (uri) | Anmeldelink (7 Tage gültig, mehrfach nutzbar, an keinen Gast gebunden). Bei einer idempotenten Wiederholung entsteht ein frischer Link. |
data.obligatoire | string (date-time) | |
timestampobligatoire | 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"
}Erreurs possibles (8)
| Statut | 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
Paramètres
| Champ | Type | Description |
|---|---|---|
serialobligatoirepath | string |
Réponse 200 · Pass
Pass
| Champ | Type | Description |
|---|---|---|
dataobligatoire | object | |
data.obligatoire | string | |
data.obligatoire | string | |
data.obligatoire | string | |
data.obligatoire | string | Seriennummer aus dem Wallet-Barcode |
data.obligatoire | integer | |
data.obligatoire | integer | |
data.obligatoire | string | null | Aktuelle Treuestufe oder null |
data.obligatoire | string (date-time) | null | |
data.obligatoire | string (date-time) | |
timestampobligatoire | 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"
}Erreurs possibles (6)
| Statut | 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
Paramètres
| Champ | Type | Description |
|---|---|---|
idobligatoirepath | string | maxLength 64 |
Réponse 200 · Pass
Pass
| Champ | Type | Description |
|---|---|---|
dataobligatoire | object | |
data.obligatoire | string | |
data.obligatoire | string | |
data.obligatoire | string | |
data.obligatoire | string | Seriennummer aus dem Wallet-Barcode |
data.obligatoire | integer | |
data.obligatoire | integer | |
data.obligatoire | string | null | Aktuelle Treuestufe oder null |
data.obligatoire | string (date-time) | null | |
data.obligatoire | string (date-time) | |
timestampobligatoire | 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"
}Erreurs possibles (6)
| Statut | 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
Paramètres
| Champ | Type | Description |
|---|---|---|
idobligatoirepath | 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]+$ |
Corps de la requête · StampRequest
Ohne Betrag ein Besuch; mit amountCents Umsatzpunkte; mit points direkte Punkte. Welcher Weg passt, entscheidet die Karte (sonst 400).
| Champ | Type | Description |
|---|---|---|
employeeIdobligatoire | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdobligatoire | 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 |
Réponse 201 · PassState
Neuer Stand
| Champ | Type | Description |
|---|---|---|
dataobligatoire | 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 |
timestampobligatoire | 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"
}Erreurs possibles (8)
| Statut | 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
Paramètres
| Champ | Type | Description |
|---|---|---|
idobligatoirepath | 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]+$ |
Corps de la requête · RedeemRequest
| Champ | Type | Description |
|---|---|---|
rewardIdobligatoire | string | Prämie (GET /cards → rewards)maxLength 64 |
valueCents | integer | Warenwert für Mindestumsatz und Manager-Eskalation minimum 0 · maximum 100000000 |
employeeIdobligatoire | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdobligatoire | 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 |
Réponse 201 · PassState
Neuer Stand
| Champ | Type | Description |
|---|---|---|
dataobligatoire | 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 |
timestampobligatoire | 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"
}Erreurs possibles (8)
| Statut | 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
Paramètres
| Champ | Type | Description |
|---|---|---|
idobligatoirepath | 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]+$ |
Corps de la requête · CancelRequest
employeeId muss Rolle MANAGER oder OWNER haben (sonst ROLE_NOT_ALLOWED).
| Champ | Type | Description |
|---|---|---|
employeeIdobligatoire | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdobligatoire | 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 |
Réponse 201
Storniert
| Champ | Type | Description |
|---|---|---|
dataobligatoire | object | |
data.obligatoire | string | |
data.obligatoire | true | |
timestampobligatoire | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"id": "string",
"cancelled": true
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Erreurs possibles (8)
| Statut | 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 |
Offres
GET /passes/{id}/offers
Angebote eines Passes (Angebotskarte)
Scope: offer:read
Paramètres
| Champ | Type | Description |
|---|---|---|
idobligatoirepath | string | maxLength 64 |
Réponse 200 · OfferList
Angebote
| Champ | Type | Description |
|---|---|---|
dataobligatoire | 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 | |
timestampobligatoire | 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"
}Erreurs possibles (6)
| Statut | 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
Paramètres
| Champ | Type | Description |
|---|---|---|
idobligatoirepath | 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]+$ |
Corps de la requête · RedeemOfferRequest
| Champ | Type | Description |
|---|---|---|
offerIdobligatoire | string | Angebot (GET /passes/{id}/offers)maxLength 64 |
employeeIdobligatoire | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdobligatoire | 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 |
Réponse 201 · OfferRedemption
Einlösung
| Champ | Type | Description |
|---|---|---|
dataobligatoire | object | |
data. | string | |
data. | string | |
data. | integer | Wie oft der Gast das Angebot im Fenster noch einlösen kann |
data. | integer | |
timestampobligatoire | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"offerId": "string",
"title": "string",
"remaining": 0,
"openCount": 0
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Erreurs possibles (8)
| Statut | 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 |
Clients
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
Paramètres
| Champ | Type | Description |
|---|---|---|
emailobligatoirequery | string (email) | maxLength 254 |
Réponse 200 · Customer
Gast
| Champ | Type | Description |
|---|---|---|
dataobligatoire | 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) | |
timestampobligatoire | 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"
}Erreurs possibles (7)
| Statut | 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
Paramètres
| Champ | Type | Description |
|---|---|---|
sinceobligatoirequery | string (date-time) | ISO-8601-Zeitpunkt; Löschungen ab einschließlich |
cursorquery | string | maxLength 64 |
limitquery | integer | minimum 1 · maximum 500 · default 100 |
Réponse 200 · DeletedCustomerPage
Lösch-Nachweise
| Champ | Type | Description |
|---|---|---|
dataobligatoire | object | |
data.obligatoire | array<object> | |
data.obligatoire | string | Eintrag (Cursor) |
data.obligatoire | string | |
data.obligatoire | array<string> | |
data.obligatoire | string (date-time) | |
data.obligatoire | string | null | Als cursor für die nächste Seite übergeben; null = Ende |
timestampobligatoire | 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"
}Erreurs possibles (6)
| Statut | 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
Paramètres
| Champ | Type | Description |
|---|---|---|
idobligatoirepath | string |
Réponse 200 · Customer
Gast
| Champ | Type | Description |
|---|---|---|
dataobligatoire | 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) | |
timestampobligatoire | 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"
}Erreurs possibles (6)
| Statut | 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
Paramètres
| Champ | 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]+$ |
Corps de la requête · PushRequest
| Champ | Type | Description |
|---|---|---|
textobligatoire | 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 |
Réponse 201
Versendet
| Champ | Type | Description |
|---|---|---|
dataobligatoire | object | |
data.obligatoire | integer | Zahl der erreichten Gäste |
timestampobligatoire | string (date-time) | Zeitpunkt der Antwort (UTC) |
{
"data": {
"recipients": 0
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Erreurs possibles (9)
| Statut | 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 |
Analyses
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
Réponse 200 · AnalyticsOverview
Übersicht
| Champ | Type | Description |
|---|---|---|
dataobligatoire | 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) |
timestampobligatoire | 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"
}Erreurs possibles (5)
| Statut | 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 |
Événements webhook
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).
Champs de data
| Champ | Type | Description |
|---|---|---|
passIdobligatoire | string | |
cardIdobligatoire | string | |
customerIdobligatoire | string | |
employeeIdobligatoire | string | null | |
locationIdobligatoire | string | null | |
channelobligatoire | string | null |
Enveloppe
| Champ | Type | Description |
|---|---|---|
idobligatoire | string | evt_…, stabil über Wiederholungen (Dedupe) |
eventobligatoire | "pass.created" | |
timestampobligatoire | 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. |
En-têtes
| Champ | Type | Description |
|---|---|---|
X-tapja-Eventobligatoire | string | Name des Ereignisses |
X-tapja-Deliveryobligatoire | string | Kennung der Zustellung (= id im Body), stabil über Wiederholungen |
X-tapja-Timestampobligatoire | string | Unix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s) |
X-tapja-Signatureobligatoire | 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.
Champs de data
| Champ | Type | Description |
|---|---|---|
passIdobligatoire | string | |
cardIdobligatoire | string | |
stampCountobligatoire | integer | |
pointsBalanceobligatoire | integer | |
employeeIdobligatoire | string | null | |
locationIdobligatoire | string | null | |
channelobligatoire | string | null |
pass.redeemed
Prämie oder Gutschein eingelöst. timestamp = Gerätezeit bei offline nachgereichten Buchungen.
Champs de data
| Champ | Type | Description |
|---|---|---|
passIdobligatoire | string | |
rewardId | string | |
locationId | string |
pass.cancelled
Karte storniert.
Champs de data
| Champ | Type | Description |
|---|---|---|
passIdobligatoire | string | |
cardIdobligatoire | string |
pass.reactivated
Stornierte Karte nach nachgeholter E-Mail-Bestätigung wieder aktiv.
Champs de data
| Champ | Type | Description |
|---|---|---|
passIdobligatoire | string | |
customerIdobligatoire | 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.
Champs de data
| Champ | Type | Description |
|---|---|---|
passIdobligatoire | string | |
fieldobligatoire | string | enum stampCount | pointsBalance |
valueobligatoire | 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.
Champs de data
| Champ | Type | Description |
|---|---|---|
passIdobligatoire | string | |
cardIdobligatoire | string | |
rewardIdsobligatoire | array<string> |
offer.redeemed
Angebot eingelöst.
Champs de data
| Champ | Type | Description |
|---|---|---|
passIdobligatoire | string | |
offerIdobligatoire | string | |
locationId | string |
package.used
Einheit(en) einer Paketkarte genutzt.
Champs de data
| Champ | Type | Description |
|---|---|---|
passIdobligatoire | string | |
quantityobligatoire | integer | |
unitsobligatoire | integer | |
employeeIdobligatoire | 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.
Champs de data
| Champ | Type | Description |
|---|---|---|
customerIdobligatoire | string |
customer.deleted
Gast gelöscht (Art. 17): im eigenen System ebenfalls löschen.
Champs de data
| Champ | Type | Description |
|---|---|---|
customerIdobligatoire | string | |
passIdsobligatoire | array<string> |
customer.consent_changed
Werbe-Einwilligung eines bestehenden Gastes geändert (nicht bei der Erstanmeldung).
Champs de data
| Champ | Type | Description |
|---|---|---|
customerIdobligatoire | string | |
marketingConsentobligatoire | boolean |
campaign.sent
Kampagne versendet.
Champs de data
| Champ | Type | Description |
|---|---|---|
campaignIdobligatoire | string | |
recipientsobligatoire | integer |
pingabonnement impossible
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.
Champs de data
| Champ | Type | Description |
|---|---|---|
messageobligatoire | string |
Schémas
Error
| Champ | Type | Description |
|---|---|---|
errorobligatoire | object | |
error.obligatoire | 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.obligatoire | string | Für Menschen; meist deutsch, bei Formfehlern (Validierung) teils englisch. |
Pass
| Champ | Type | Description |
|---|---|---|
idobligatoire | string | |
cardIdobligatoire | string | |
customerIdobligatoire | string | |
serialNumberobligatoire | string | Seriennummer aus dem Wallet-Barcode |
stampCountobligatoire | integer | |
pointsBalanceobligatoire | integer | |
tierobligatoire | string | null | Aktuelle Treuestufe oder null |
lastStampAtobligatoire | string (date-time) | null | |
createdAtobligatoire | string (date-time) |
PassState
Neuer Stand nach Stempeln/Einlösen.
| Champ | 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
| Champ | Type | Description |
|---|---|---|
cardIdobligatoire | string | |
addUrlobligatoire | string (uri) | Anmeldelink (7 Tage gültig, mehrfach nutzbar, an keinen Gast gebunden). Bei einer idempotenten Wiederholung entsteht ein frischer Link. |
expiresAtobligatoire | string (date-time) |
Customer
Minimale Gast-Sicht (kein Geburtstag, kein Besuchsverhalten). Jeder Abruf wird protokolliert.
| Champ | 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.
| Champ | Type | Description |
|---|---|---|
idobligatoire | string | Eintrag (Cursor) |
customerIdobligatoire | string | |
passIdsobligatoire | array<string> | |
deletedAtobligatoire | string (date-time) |
DeletedCustomerPage
| Champ | Type | Description |
|---|---|---|
itemsobligatoire | array<object> | |
items[].obligatoire | string | Eintrag (Cursor) |
items[].obligatoire | string | |
items[].obligatoire | array<string> | |
items[].obligatoire | string (date-time) | |
nextCursorobligatoire | string | null | Als cursor für die nächste Seite übergeben; null = Ende |
Offer
| Champ | 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
| Champ | 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
| Champ | Type | Description |
|---|---|---|
offerId | string | |
title | string | |
remaining | integer | Wie oft der Gast das Angebot im Fenster noch einlösen kann |
openCount | integer |
Card
| Champ | 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
| Champ | Type | Description |
|---|---|---|
id | string | |
name | string | |
status | string | enum OPEN | CLOSED |
Employee
| Champ | 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.
| Champ | 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
| Champ | Type | Description |
|---|---|---|
cardIdobligatoire | string | Kartenprogramm (GET /cards)maxLength 64 |
employeeIdobligatoire | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdobligatoire | 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).
| Champ | Type | Description |
|---|---|---|
employeeIdobligatoire | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdobligatoire | 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
| Champ | Type | Description |
|---|---|---|
rewardIdobligatoire | string | Prämie (GET /cards → rewards)maxLength 64 |
valueCents | integer | Warenwert für Mindestumsatz und Manager-Eskalation minimum 0 · maximum 100000000 |
employeeIdobligatoire | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdobligatoire | 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
| Champ | Type | Description |
|---|---|---|
offerIdobligatoire | string | Angebot (GET /passes/{id}/offers)maxLength 64 |
employeeIdobligatoire | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdobligatoire | 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).
| Champ | Type | Description |
|---|---|---|
employeeIdobligatoire | string | Aktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.maxLength 64 |
locationIdobligatoire | 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
| Champ | Type | Description |
|---|---|---|
textobligatoire | 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 |
Codes d’erreur
| Code | Statut | Endpoints | Remarque |
|---|---|---|---|
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 | tous les endpoints | Key fehlt, ist ungültig, widerrufen oder abgelaufen |
ACTOR_ROLE_NOT_ALLOWED | 403 | ||
CARD_FULL | 403 | ||
COMPANY_SUSPENDED | 403 | tous les 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 | tous les 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 | tous les 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 | tous les 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 | tous les endpoints | unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar |
REQUEST_IN_PROGRESS | 503 | tous les endpoints | Erstanfrage mit diesem Idempotency-Key läuft noch |
RETRY | 503 | ||
SERVICE_UNAVAILABLE | 503 | vorübergehend nicht verfügbar |