Skip to content

Diese Seite gibt es auch auf Deutsch. Auf Deutsch ansehen

Esta página también está disponible en español. Ver en español

Deze pagina is er ook in het Nederlands. Bekijk in het Nederlands

Cette page existe aussi en français. Voir en français

Shown in the language you chose. Auf Deutsch ansehenVer en españolBekijk in het NederlandsVoir en français

tapja

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

FieldTypeDescription
datarequiredarray<object>
data[].idstring
data[].namestring
data[].typestring
enum STAMP | POINTS | OFFERS | PACKAGE | MEMBERSHIP
data[].stampGoalinteger | null
data[].rewardsarray<object>
data[].rewards[].idstring
data[].rewards[].titlestring
data[].rewards[].thresholdinteger
data[].rewards[].valueCentsinteger | null
data[].rewards[].pointsCostintegerWirksame Punktekosten (ohne eigenen Wert = threshold)
data[].rewards[].autoIssuebooleanWird automatisch als Gutschein ausgestellt (nicht über /redeem einlösbar)
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "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)
StatusCode
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503SERVICE_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

FieldTypeDescription
datarequiredarray<object>
data[].idstring
data[].namestring
data[].statusstring
enum OPEN | CLOSED
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "status": "OPEN"
    }
  ],
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Possible errors (5)
StatusCode
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503SERVICE_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

FieldTypeDescription
datarequiredarray<object>
data[].idstring
data[].namestring | null
data[].rolestring
enum OWNER | MANAGER | EMPLOYEE
data[].locationIdsarray<string>
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "role": "OWNER",
      "locationIds": [
        "string"
      ]
    }
  ],
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Possible errors (5)
StatusCode
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503SERVICE_UNAVAILABLE (vorübergehend nicht verfügbar) bzw. REQUEST_IN_PROGRESS (Erstanfrage mit diesem Idempotency-Key läuft noch); später wiederholen

Cards

GET /passes/by-serial/{serial}

Pass über die Seriennummer aus dem Wallet-Barcode

Scope: pass:read

Parameters

FieldTypeDescription
serialrequired
path
string

Response 200 · Pass

Pass

FieldTypeDescription
datarequiredobject
data.idrequiredstring
data.cardIdrequiredstring
data.customerIdrequiredstring
data.serialNumberrequiredstringSeriennummer aus dem Wallet-Barcode
data.stampCountrequiredinteger
data.pointsBalancerequiredinteger
data.tierrequiredstring | nullAktuelle Treuestufe oder null
data.lastStampAtrequiredstring (date-time) | null
data.createdAtrequiredstring (date-time)
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "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)
StatusCode
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED
404PASS_NOT_FOUND (auch storniert)
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503SERVICE_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

FieldTypeDescription
idrequired
path
string
maxLength 64

Response 200 · Pass

Pass

FieldTypeDescription
datarequiredobject
data.idrequiredstring
data.cardIdrequiredstring
data.customerIdrequiredstring
data.serialNumberrequiredstringSeriennummer aus dem Wallet-Barcode
data.stampCountrequiredinteger
data.pointsBalancerequiredinteger
data.tierrequiredstring | nullAktuelle Treuestufe oder null
data.lastStampAtrequiredstring (date-time) | null
data.createdAtrequiredstring (date-time)
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "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)
StatusCode
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED
404PASS_NOT_FOUND (auch storniert)
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503SERVICE_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

FieldTypeDescription
idrequired
path
string
maxLength 64
Idempotency-Key
header
stringJe 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).

FieldTypeDescription
employeeIdrequiredstringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdrequiredstringStandort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.
maxLength 64
employeeRefstringOptionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen).
maxLength 120
amountCentsinteger
minimum 1 · maximum 100000000
pointsinteger
minimum 1 · maximum 100000

Response 201 · PassState

Neuer Stand

FieldTypeDescription
datarequiredobjectNeuer Stand nach Stempeln/Einlösen.
data.idstring
data.cardIdstring
data.customerIdstring
data.serialNumberstringSeriennummer aus dem Wallet-Barcode
data.stampCountinteger
data.pointsBalanceinteger
data.tierstring | nullAktuelle Treuestufe oder null
data.lastStampAtstring (date-time) | null
data.createdAtstring (date-time)
data.lifetimeProgressintegerMonotoner Gesamtfortschritt
data.stampCycleintegerLaufende Runde der Stempelkarte
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "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)
StatusCode
400BAD_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
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED, EMPLOYEE_NOT_AT_LOCATION, ACTOR_ROLE_NOT_ALLOWED, COOLDOWN_ACTIVE, STAMP_LIMIT_REACHED, CARD_FULL
404EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND
409LOCATION_DEACTIVATED, PASS_VOIDED, IDEMPOTENCY_KEY_REUSED, REQUEST_ABANDONED (nur Besuch auf einer Angebotskarte: abgebrochene Erstanfrage wird nicht erneut ausgeführt)
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503REQUEST_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

FieldTypeDescription
idrequired
path
string
maxLength 64
Idempotency-Key
header
stringJe 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

FieldTypeDescription
rewardIdrequiredstringPrämie (GET /cards → rewards)
maxLength 64
valueCentsintegerWarenwert für Mindestumsatz und Manager-Eskalation
minimum 0 · maximum 100000000
employeeIdrequiredstringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdrequiredstringStandort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.
maxLength 64
employeeRefstringOptionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen).
maxLength 120

Response 201 · PassState

Neuer Stand

FieldTypeDescription
datarequiredobjectNeuer Stand nach Stempeln/Einlösen.
data.idstring
data.cardIdstring
data.customerIdstring
data.serialNumberstringSeriennummer aus dem Wallet-Barcode
data.stampCountinteger
data.pointsBalanceinteger
data.tierstring | nullAktuelle Treuestufe oder null
data.lastStampAtstring (date-time) | null
data.createdAtstring (date-time)
data.lifetimeProgressintegerMonotoner Gesamtfortschritt
data.stampCycleintegerLaufende Runde der Stempelkarte
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "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)
StatusCode
400BAD_REQUEST (Validierung), LOCATION_WRONG_COMPANY, IDEMPOTENCY_KEY_INVALID, REWARD_AUTO_ISSUED (wird automatisch als Gutschein ausgestellt), PACKAGE_USE_REQUIRED, MEMBERSHIP_ACTION_REQUIRED
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_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
404EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND, REWARD_NOT_FOUND
409LOCATION_DEACTIVATED, PASS_VOIDED, IDEMPOTENCY_KEY_REUSED
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503REQUEST_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

FieldTypeDescription
idrequired
path
string
maxLength 64
Idempotency-Key
header
stringJe 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).

FieldTypeDescription
employeeIdrequiredstringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdrequiredstringStandort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.
maxLength 64
employeeRefstringOptionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen).
maxLength 120

Response 201

Storniert

FieldTypeDescription
datarequiredobject
data.idrequiredstring
data.cancelledrequiredtrue
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "data": {
    "id": "string",
    "cancelled": true
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Possible errors (8)
StatusCode
400BAD_REQUEST (Validierung), LOCATION_WRONG_COMPANY, IDEMPOTENCY_KEY_INVALID
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED, EMPLOYEE_NOT_AT_LOCATION, ACTOR_ROLE_NOT_ALLOWED, ROLE_NOT_ALLOWED
404EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND
409LOCATION_DEACTIVATED, PASS_VOIDED, IDEMPOTENCY_KEY_REUSED
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503REQUEST_IN_PROGRESS, RETRY

Offers

GET /passes/{id}/offers

Angebote eines Passes (Angebotskarte)

Scope: offer:read

Parameters

FieldTypeDescription
idrequired
path
string
maxLength 64

Response 200 · OfferList

Angebote

FieldTypeDescription
datarequiredobject
data.offersarray<object>
data.offers[].offerIdstring
data.offers[].titlestring
data.offers[].descriptionstring | null
data.offers[].translationsobject | nullRohe Übersetzungen von title/description
data.offers[].highlightTodayboolean
data.offers[].kindstring
enum PERCENT | AMOUNT | BOGO | FREE_ITEM | FREE_FOR_GUEST | CUSTOM
data.offers[].valuePercentinteger | null
data.offers[].valueCentsinteger | null
data.offers[].taxRatestring | null
data.offers[].valueSplitobject | null
data.offers[].statusstring
enum available | used_up | cooldown | exhausted | not_started | expired | not_eligible | wrong_location
data.offers[].remaininginteger
data.offers[].validUntilstring (date-time) | null
data.offers[].availableAgainAtstring (date-time) | null
data.offers[].lastRedeemedAtstring (date-time) | null
data.offers[].orderinteger
data.openCountinteger
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "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)
StatusCode
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED
404PASS_NOT_FOUND, NOT_FOUND (Angebote nicht aktiviert)
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503SERVICE_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

FieldTypeDescription
idrequired
path
string
maxLength 64
Idempotency-Key
header
stringJe 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

FieldTypeDescription
offerIdrequiredstringAngebot (GET /passes/{id}/offers)
maxLength 64
employeeIdrequiredstringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdrequiredstringStandort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.
maxLength 64
employeeRefstringOptionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen).
maxLength 120

Response 201 · OfferRedemption

Einlösung

FieldTypeDescription
datarequiredobject
data.offerIdstring
data.titlestring
data.remainingintegerWie oft der Gast das Angebot im Fenster noch einlösen kann
data.openCountinteger
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "data": {
    "offerId": "string",
    "title": "string",
    "remaining": 0,
    "openCount": 0
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Possible errors (8)
StatusCode
400BAD_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)
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_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
404EMPLOYEE_NOT_FOUND, PASS_NOT_FOUND, OFFER_NOT_FOUND, NOT_FOUND (Angebote nicht aktiviert)
409LOCATION_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
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503REQUEST_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

FieldTypeDescription
emailrequired
query
string (email)
maxLength 254

Response 200 · Customer

Gast

FieldTypeDescription
datarequiredobjectMinimale Gast-Sicht (kein Geburtstag, kein Besuchsverhalten). Jeder Abruf wird protokolliert.
data.idstring
data.namestring | null
data.emailstring (email) | null
data.customerNumberLabelstring
data.marketingConsentbooleanWerbe-Einwilligung. Werbe-E-Mails aus dem eigenen System nur, wenn true UND emailVerifiedAt gesetzt ist.
data.emailVerifiedAtstring (date-time) | null
data.anonymousbooleantrue = 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.createdAtstring (date-time)
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "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)
StatusCode
400BAD_REQUEST: email fehlt oder ist ungültig, unbekannte Query-Parameter
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED
404CUSTOMER_NOT_FOUND
429RATE_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
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503SERVICE_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

FieldTypeDescription
sincerequired
query
string (date-time)ISO-8601-Zeitpunkt; Löschungen ab einschließlich
cursor
query
string
maxLength 64
limit
query
integer
minimum 1 · maximum 500 · default 100

Response 200 · DeletedCustomerPage

Lösch-Nachweise

FieldTypeDescription
datarequiredobject
data.itemsrequiredarray<object>
data.items[].idrequiredstringEintrag (Cursor)
data.items[].customerIdrequiredstring
data.items[].passIdsrequiredarray<string>
data.items[].deletedAtrequiredstring (date-time)
data.nextCursorrequiredstring | nullAls cursor für die nächste Seite übergeben; null = Ende
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "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)
StatusCode
400BAD_REQUEST: since fehlt oder ist kein ISO-8601-Zeitpunkt, limit außerhalb 1 bis 500
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503SERVICE_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

FieldTypeDescription
idrequired
path
string

Response 200 · Customer

Gast

FieldTypeDescription
datarequiredobjectMinimale Gast-Sicht (kein Geburtstag, kein Besuchsverhalten). Jeder Abruf wird protokolliert.
data.idstring
data.namestring | null
data.emailstring (email) | null
data.customerNumberLabelstring
data.marketingConsentbooleanWerbe-Einwilligung. Werbe-E-Mails aus dem eigenen System nur, wenn true UND emailVerifiedAt gesetzt ist.
data.emailVerifiedAtstring (date-time) | null
data.anonymousbooleantrue = 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.createdAtstring (date-time)
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "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)
StatusCode
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED
404CUSTOMER_NOT_FOUND
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503SERVICE_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

FieldTypeDescription
Idempotency-Key
header
stringJe 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

FieldTypeDescription
textrequiredstringKartentext; nur bekannte Platzhalter wie {Kundenname}, {Betrieb} (sonst 400 PLACEHOLDER_UNKNOWN). Anstößige Inhalte lehnt die Moderation ab (422).
minLength 1 · maxLength 240
cardIdstringOptional: nur Gäste dieses Kartenprogramms
maxLength 64

Response 201

Versendet

FieldTypeDescription
datarequiredobject
data.recipientsrequiredintegerZahl der erreichten Gäste
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "data": {
    "recipients": 0
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Possible errors (9)
StatusCode
400BAD_REQUEST (Validierung), PLACEHOLDER_UNKNOWN (unbekannter Platzhalter), QUIET_HOURS (Plattform-Ruhezeit), IDEMPOTENCY_KEY_INVALID
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED, LOCATION_NOT_ALLOWED
404CARD_NOT_FOUND (cardId gehört nicht zum Betrieb)
409IDEMPOTENCY_KEY_REUSED, REQUEST_ABANDONED
422UNPROCESSABLE (Text von der Moderation abgelehnt)
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503REQUEST_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

FieldTypeDescription
datarequiredobjectZeitraum-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.cardProgramsintegerBestand: nicht archivierte Kartenprogramme des ganzen Betriebs (auch bei standortgebundenen Keys nicht nach Standort gefiltert)
data.cardsIssuedintegerAusgegebene Karten, letzte 30 Tage
data.stampsAddedintegerStempel-/Punktebuchungen, letzte 30 Tage
data.redemptionsintegerEinlösungen (Prämien und Angebote), letzte 30 Tage
data.activeCardsintegerBestand: nicht stornierte Gastkarten
data.totalCustomersintegerBestand: Gäste
data.newCustomersintegerNeue Gäste, letzte 30 Tage
data.deltasobjectVergleich mit den 30 Tagen davor je Kennzahl (stampsAdded, redemptions, cardsIssued, newCustomers)
timestamprequiredstring (date-time)Zeitpunkt der Antwort (UTC)
Response shape
{
  "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)
StatusCode
401UNAUTHORIZED (Key fehlt, ist ungültig, widerrufen oder abgelaufen)
403SCOPE_MISSING, PLAN_FEATURE_REQUIRED, COMPANY_SUSPENDED
429RATE_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)
500INTERNAL_ERROR (unerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar)
503SERVICE_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

FieldTypeDescription
passIdrequiredstring
cardIdrequiredstring
customerIdrequiredstring
employeeIdrequiredstring | null
locationIdrequiredstring | null
channelrequiredstring | null

Envelope

FieldTypeDescription
idrequiredstringevt_…, stabil über Wiederholungen (Dedupe)
eventrequired"pass.created"
timestamprequiredstring (date-time)Zeitpunkt des Ereignisses (UTC)
testtrueNur bei Tests aus „Test senden" (Ping oder Beispiel-Ereignis, alle Kennungen erfunden mit Präfix test_, keine Wiederholungen). Fehlt bei echten Ereignissen ganz.

Headers

FieldTypeDescription
X-tapja-EventrequiredstringName des Ereignisses
X-tapja-DeliveryrequiredstringKennung der Zustellung (= id im Body), stabil über Wiederholungen
X-tapja-TimestamprequiredstringUnix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)
X-tapja-Signaturerequiredstringsha256=<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

FieldTypeDescription
passIdrequiredstring
cardIdrequiredstring
stampCountrequiredinteger
pointsBalancerequiredinteger
employeeIdrequiredstring | null
locationIdrequiredstring | null
channelrequiredstring | null

pass.redeemed

Prämie oder Gutschein eingelöst. timestamp = Gerätezeit bei offline nachgereichten Buchungen.

Fields in data

FieldTypeDescription
passIdrequiredstring
rewardIdstring
locationIdstring

pass.cancelled

Karte storniert.

Fields in data

FieldTypeDescription
passIdrequiredstring
cardIdrequiredstring

pass.reactivated

Stornierte Karte nach nachgeholter E-Mail-Bestätigung wieder aktiv.

Fields in data

FieldTypeDescription
passIdrequiredstring
customerIdrequiredstring

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

FieldTypeDescription
passIdrequiredstring
fieldrequiredstring
enum stampCount | pointsBalance
valuerequiredinteger
employeeIdstring
locationIdstring

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

FieldTypeDescription
passIdrequiredstring
cardIdrequiredstring
rewardIdsrequiredarray<string>

offer.redeemed

Angebot eingelöst.

Fields in data

FieldTypeDescription
passIdrequiredstring
offerIdrequiredstring
locationIdstring

package.used

Einheit(en) einer Paketkarte genutzt.

Fields in data

FieldTypeDescription
passIdrequiredstring
quantityrequiredinteger
unitsrequiredinteger
employeeIdrequiredstring
locationIdstring

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

FieldTypeDescription
customerIdrequiredstring

customer.deleted

Gast gelöscht (Art. 17): im eigenen System ebenfalls löschen.

Fields in data

FieldTypeDescription
customerIdrequiredstring
passIdsrequiredarray<string>

campaign.sent

Kampagne versendet.

Fields in data

FieldTypeDescription
campaignIdrequiredstring
recipientsrequiredinteger

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

FieldTypeDescription
messagerequiredstring

Schemas

Error

FieldTypeDescription
errorrequiredobject
error.coderequiredstringStabiler, 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.messagerequiredstringFür Menschen; meist deutsch, bei Formfehlern (Validierung) teils englisch.

Pass

FieldTypeDescription
idrequiredstring
cardIdrequiredstring
customerIdrequiredstring
serialNumberrequiredstringSeriennummer aus dem Wallet-Barcode
stampCountrequiredinteger
pointsBalancerequiredinteger
tierrequiredstring | nullAktuelle Treuestufe oder null
lastStampAtrequiredstring (date-time) | null
createdAtrequiredstring (date-time)

PassState

Neuer Stand nach Stempeln/Einlösen.

FieldTypeDescription
idstring
cardIdstring
customerIdstring
serialNumberstringSeriennummer aus dem Wallet-Barcode
stampCountinteger
pointsBalanceinteger
tierstring | nullAktuelle Treuestufe oder null
lastStampAtstring (date-time) | null
createdAtstring (date-time)
lifetimeProgressintegerMonotoner Gesamtfortschritt
stampCycleintegerLaufende Runde der Stempelkarte

Customer

Minimale Gast-Sicht (kein Geburtstag, kein Besuchsverhalten). Jeder Abruf wird protokolliert.

FieldTypeDescription
idstring
namestring | null
emailstring (email) | null
customerNumberLabelstring
marketingConsentbooleanWerbe-Einwilligung. Werbe-E-Mails aus dem eigenen System nur, wenn true UND emailVerifiedAt gesetzt ist.
emailVerifiedAtstring (date-time) | null
anonymousbooleantrue = 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.
createdAtstring (date-time)

DeletedCustomer

Lösch-Nachweis: im eigenen System Gast und Karten ebenfalls löschen. Nur IDs, 30 Tage abrufbar.

FieldTypeDescription
idrequiredstringEintrag (Cursor)
customerIdrequiredstring
passIdsrequiredarray<string>
deletedAtrequiredstring (date-time)

DeletedCustomerPage

FieldTypeDescription
itemsrequiredarray<object>
items[].idrequiredstringEintrag (Cursor)
items[].customerIdrequiredstring
items[].passIdsrequiredarray<string>
items[].deletedAtrequiredstring (date-time)
nextCursorrequiredstring | nullAls cursor für die nächste Seite übergeben; null = Ende

Offer

FieldTypeDescription
offerIdstring
titlestring
descriptionstring | null
translationsobject | nullRohe Übersetzungen von title/description
highlightTodayboolean
kindstring
enum PERCENT | AMOUNT | BOGO | FREE_ITEM | FREE_FOR_GUEST | CUSTOM
valuePercentinteger | null
valueCentsinteger | null
taxRatestring | null
valueSplitobject | null
statusstring
enum available | used_up | cooldown | exhausted | not_started | expired | not_eligible | wrong_location
remaininginteger
validUntilstring (date-time) | null
availableAgainAtstring (date-time) | null
lastRedeemedAtstring (date-time) | null
orderinteger

OfferList

FieldTypeDescription
offersarray<object>
offers[].offerIdstring
offers[].titlestring
offers[].descriptionstring | null
offers[].translationsobject | nullRohe Übersetzungen von title/description
offers[].highlightTodayboolean
offers[].kindstring
enum PERCENT | AMOUNT | BOGO | FREE_ITEM | FREE_FOR_GUEST | CUSTOM
offers[].valuePercentinteger | null
offers[].valueCentsinteger | null
offers[].taxRatestring | null
offers[].valueSplitobject | null
offers[].statusstring
enum available | used_up | cooldown | exhausted | not_started | expired | not_eligible | wrong_location
offers[].remaininginteger
offers[].validUntilstring (date-time) | null
offers[].availableAgainAtstring (date-time) | null
offers[].lastRedeemedAtstring (date-time) | null
offers[].orderinteger
openCountinteger

OfferRedemption

FieldTypeDescription
offerIdstring
titlestring
remainingintegerWie oft der Gast das Angebot im Fenster noch einlösen kann
openCountinteger

Card

FieldTypeDescription
idstring
namestring
typestring
enum STAMP | POINTS | OFFERS | PACKAGE | MEMBERSHIP
stampGoalinteger | null
rewardsarray<object>
rewards[].idstring
rewards[].titlestring
rewards[].thresholdinteger
rewards[].valueCentsinteger | null
rewards[].pointsCostintegerWirksame Punktekosten (ohne eigenen Wert = threshold)
rewards[].autoIssuebooleanWird automatisch als Gutschein ausgestellt (nicht über /redeem einlösbar)

Location

FieldTypeDescription
idstring
namestring
statusstring
enum OPEN | CLOSED

Employee

FieldTypeDescription
idstring
namestring | null
rolestring
enum OWNER | MANAGER | EMPLOYEE
locationIdsarray<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.

FieldTypeDescription
cardProgramsintegerBestand: nicht archivierte Kartenprogramme des ganzen Betriebs (auch bei standortgebundenen Keys nicht nach Standort gefiltert)
cardsIssuedintegerAusgegebene Karten, letzte 30 Tage
stampsAddedintegerStempel-/Punktebuchungen, letzte 30 Tage
redemptionsintegerEinlösungen (Prämien und Angebote), letzte 30 Tage
activeCardsintegerBestand: nicht stornierte Gastkarten
totalCustomersintegerBestand: Gäste
newCustomersintegerNeue Gäste, letzte 30 Tage
deltasobjectVergleich mit den 30 Tagen davor je Kennzahl (stampsAdded, redemptions, cardsIssued, newCustomers)

CreatePassLinkRequest

FieldTypeDescription
cardIdrequiredstringKartenprogramm (GET /cards)
maxLength 64
employeeIdrequiredstringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdrequiredstringStandort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.
maxLength 64
employeeRefstringOptionale 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).

FieldTypeDescription
employeeIdrequiredstringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdrequiredstringStandort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.
maxLength 64
employeeRefstringOptionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen).
maxLength 120
amountCentsinteger
minimum 1 · maximum 100000000
pointsinteger
minimum 1 · maximum 100000

RedeemRequest

FieldTypeDescription
rewardIdrequiredstringPrämie (GET /cards → rewards)
maxLength 64
valueCentsintegerWarenwert für Mindestumsatz und Manager-Eskalation
minimum 0 · maximum 100000000
employeeIdrequiredstringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdrequiredstringStandort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.
maxLength 64
employeeRefstringOptionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen).
maxLength 120

RedeemOfferRequest

FieldTypeDescription
offerIdrequiredstringAngebot (GET /passes/{id}/offers)
maxLength 64
employeeIdrequiredstringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdrequiredstringStandort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.
maxLength 64
employeeRefstringOptionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen).
maxLength 120

CancelRequest

employeeId muss Rolle MANAGER oder OWNER haben (sonst ROLE_NOT_ALLOWED).

FieldTypeDescription
employeeIdrequiredstringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdrequiredstringStandort der Buchung (GET /locations); bei standortgebundenen Keys einer der freigegebenen.
maxLength 64
employeeRefstringOptionale Kennung des Kassierers fürs Protokoll (Kassen-/Personalnummer, keine Klarnamen).
maxLength 120

PushRequest

FieldTypeDescription
textrequiredstringKartentext; nur bekannte Platzhalter wie {Kundenname}, {Betrieb} (sonst 400 PLACEHOLDER_UNKNOWN). Anstößige Inhalte lehnt die Moderation ab (422).
minLength 1 · maxLength 240
cardIdstringOptional: nur Gäste dieses Kartenprogramms
maxLength 64

Error codes

CodeStatusEndpointsNote
AMOUNT_BELOW_MINIMUM400
AMOUNT_REQUIRED400
AMOUNT_TOO_SMALL400
BAD_REQUEST400Validierung
CARD_HAS_NO_BALANCE400
COUPON_NOT_COMBINABLE400heute schon ein nicht kombinierbarer Gutschein eingelöst
IDEMPOTENCY_KEY_INVALID400
LOCATION_WRONG_COMPANY400
MEMBERSHIP_ACTION_REQUIRED400
OFFERS_NOT_ON_CARD400keine Angebotskarte
PACKAGE_USE_REQUIRED400
PLACEHOLDER_UNKNOWN400unbekannter Platzhalter
POINTS_BALANCE_LIMIT400
POINTS_REQUIRED400
QUIET_HOURS400Plattform-Ruhezeit
REWARD_AUTO_ISSUED400wird automatisch als Gutschein ausgestellt
STAMP_CAP_EXCEEDED400
STAMP_MODE_AMOUNT400
STAMP_MODE_VISIT400
UNAUTHORIZED401all endpointsKey fehlt, ist ungültig, widerrufen oder abgelaufen
ACTOR_ROLE_NOT_ALLOWED403
CARD_FULL403
COMPANY_SUSPENDED403all endpoints
COOLDOWN_ACTIVE403
EMPLOYEE_NOT_AT_LOCATION403
GUEST_EMAIL_UNVERIFIED403
LOCATION_NOT_ALLOWED403
NOT_ENOUGH_POINTS403
OFFER_COOLDOWN403
OFFER_EXHAUSTED403
OFFER_EXPIRED403
OFFER_NOT_ELIGIBLE403
OFFER_NOT_STARTED403
OFFER_WRONG_LOCATION403
PIN_REQUIRED403Manager-Eskalation
PLAN_FEATURE_REQUIRED403all endpoints
REDEEM_NOT_AT_LOCATION403
REWARD_ALREADY_REDEEMED403
REWARD_EXPIRED403
REWARD_LIMIT_REACHED403
REWARD_MEMBERSHIP_REQUIRED403
REWARD_MIN_PURCHASE403
REWARD_NOT_COMBINABLE403
REWARD_NOT_YET_VALID403
REWARD_QUOTA_EXHAUSTED403
REWARD_THRESHOLD_NOT_REACHED403
REWARD_TIER_REQUIRED403
REWARD_WRONG_LOCATION403
ROLE_NOT_ALLOWED403
SCOPE_MISSING403all endpoints
STAMP_LIMIT_REACHED403
CARD_NOT_FOUND404cardId gehört nicht zum Betrieb
CUSTOMER_NOT_FOUND404
EMPLOYEE_NOT_FOUND404
NOT_FOUND404Angebote nicht aktiviert
OFFER_NOT_FOUND404
PASS_NOT_FOUND404auch storniert
REWARD_NOT_FOUND404
CARD_ARCHIVED409
CARD_NOT_AT_LOCATION409Karte an diesem Standort nicht ausgegeben
IDEMPOTENCY_KEY_REUSED409
LOCATION_DEACTIVATED409
OFFER_ALREADY_REDEEMED409gleichzeitige Einlösung war schneller
OFFER_USED_UP409im Fenster schon eingelöst
PASS_VOIDED409
REQUEST_ABANDONED409nur Besuch auf einer Angebotskarte: abgebrochene Erstanfrage wird nicht erneut ausgeführt
UNPROCESSABLE422Text von der Moderation abgelehnt
RATE_LIMITED429all endpointsGesamt-Limit je Key, Header Retry-After und Retry-After-api; oder zu viele ungültige Keys von dieser IP, dann nur Retry-After
INTERNAL_ERROR500all endpointsunerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar
REQUEST_IN_PROGRESS503all endpointsErstanfrage mit diesem Idempotency-Key läuft noch
RETRY503
SERVICE_UNAVAILABLE503vorübergehend nicht verfügbar