Aller au contenu

Diese Seite gibt es auch auf Deutsch. Auf Deutsch ansehen

This page is also available in English. Switch to English

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

Affiché dans la langue que vous avez choisie. Auf Deutsch ansehenSwitch to EnglishVer en españolBekijk in het Nederlands

tapja

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

ChampTypeDescription
dataobligatoirearray<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)
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "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)
StatutCode
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

Réponse 200 · Location

Standorte

ChampTypeDescription
dataobligatoirearray<object>
data[].idstring
data[].namestring
data[].statusstring
enum OPEN | CLOSED
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "status": "OPEN"
    }
  ],
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Erreurs possibles (5)
StatutCode
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

Réponse 200 · Employee

Mitarbeiter

ChampTypeDescription
dataobligatoirearray<object>
data[].idstring
data[].namestring | null
data[].rolestring
enum OWNER | MANAGER | EMPLOYEE
data[].locationIdsarray<string>
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "role": "OWNER",
      "locationIds": [
        "string"
      ]
    }
  ],
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Erreurs possibles (5)
StatutCode
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

Cartes

GET /passes/by-serial/{serial}

Pass über die Seriennummer aus dem Wallet-Barcode

Scope: pass:read

Paramètres

ChampTypeDescription
serialobligatoire
path
string

Réponse 200 · Pass

Pass

ChampTypeDescription
dataobligatoireobject
data.idobligatoirestring
data.cardIdobligatoirestring
data.customerIdobligatoirestring
data.serialNumberobligatoirestringSeriennummer aus dem Wallet-Barcode
data.stampCountobligatoireinteger
data.pointsBalanceobligatoireinteger
data.tierobligatoirestring | nullAktuelle Treuestufe oder null
data.lastStampAtobligatoirestring (date-time) | null
data.createdAtobligatoirestring (date-time)
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "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)
StatutCode
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

Paramètres

ChampTypeDescription
idobligatoire
path
string
maxLength 64

Réponse 200 · Pass

Pass

ChampTypeDescription
dataobligatoireobject
data.idobligatoirestring
data.cardIdobligatoirestring
data.customerIdobligatoirestring
data.serialNumberobligatoirestringSeriennummer aus dem Wallet-Barcode
data.stampCountobligatoireinteger
data.pointsBalanceobligatoireinteger
data.tierobligatoirestring | nullAktuelle Treuestufe oder null
data.lastStampAtobligatoirestring (date-time) | null
data.createdAtobligatoirestring (date-time)
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "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)
StatutCode
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

Paramètres

ChampTypeDescription
idobligatoire
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]+$

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).

ChampTypeDescription
employeeIdobligatoirestringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoirestringStandort 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

Réponse 201 · PassState

Neuer Stand

ChampTypeDescription
dataobligatoireobjectNeuer 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
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "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)
StatutCode
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

Paramètres

ChampTypeDescription
idobligatoire
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]+$

Corps de la requête · RedeemRequest

ChampTypeDescription
rewardIdobligatoirestringPrämie (GET /cards → rewards)
maxLength 64
valueCentsintegerWarenwert für Mindestumsatz und Manager-Eskalation
minimum 0 · maximum 100000000
employeeIdobligatoirestringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoirestringStandort 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

Réponse 201 · PassState

Neuer Stand

ChampTypeDescription
dataobligatoireobjectNeuer 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
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "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)
StatutCode
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

Paramètres

ChampTypeDescription
idobligatoire
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]+$

Corps de la requête · CancelRequest

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

ChampTypeDescription
employeeIdobligatoirestringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoirestringStandort 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

Réponse 201

Storniert

ChampTypeDescription
dataobligatoireobject
data.idobligatoirestring
data.cancelledobligatoiretrue
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "data": {
    "id": "string",
    "cancelled": true
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Erreurs possibles (8)
StatutCode
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

Offres

GET /passes/{id}/offers

Angebote eines Passes (Angebotskarte)

Scope: offer:read

Paramètres

ChampTypeDescription
idobligatoire
path
string
maxLength 64

Réponse 200 · OfferList

Angebote

ChampTypeDescription
dataobligatoireobject
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
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "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)
StatutCode
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

Paramètres

ChampTypeDescription
idobligatoire
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]+$

Corps de la requête · RedeemOfferRequest

ChampTypeDescription
offerIdobligatoirestringAngebot (GET /passes/{id}/offers)
maxLength 64
employeeIdobligatoirestringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoirestringStandort 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

Réponse 201 · OfferRedemption

Einlösung

ChampTypeDescription
dataobligatoireobject
data.offerIdstring
data.titlestring
data.remainingintegerWie oft der Gast das Angebot im Fenster noch einlösen kann
data.openCountinteger
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "data": {
    "offerId": "string",
    "title": "string",
    "remaining": 0,
    "openCount": 0
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Erreurs possibles (8)
StatutCode
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

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

ChampTypeDescription
emailobligatoire
query
string (email)
maxLength 254

Réponse 200 · Customer

Gast

ChampTypeDescription
dataobligatoireobjectMinimale 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)
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "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)
StatutCode
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

Paramètres

ChampTypeDescription
sinceobligatoire
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

Réponse 200 · DeletedCustomerPage

Lösch-Nachweise

ChampTypeDescription
dataobligatoireobject
data.itemsobligatoirearray<object>
data.items[].idobligatoirestringEintrag (Cursor)
data.items[].customerIdobligatoirestring
data.items[].passIdsobligatoirearray<string>
data.items[].deletedAtobligatoirestring (date-time)
data.nextCursorobligatoirestring | nullAls cursor für die nächste Seite übergeben; null = Ende
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "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)
StatutCode
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

Paramètres

ChampTypeDescription
idobligatoire
path
string

Réponse 200 · Customer

Gast

ChampTypeDescription
dataobligatoireobjectMinimale 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)
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "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)
StatutCode
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

Paramètres

ChampTypeDescription
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]+$

Corps de la requête · PushRequest

ChampTypeDescription
textobligatoirestringKartentext; 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

Réponse 201

Versendet

ChampTypeDescription
dataobligatoireobject
data.recipientsobligatoireintegerZahl der erreichten Gäste
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "data": {
    "recipients": 0
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Erreurs possibles (9)
StatutCode
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

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

ChampTypeDescription
dataobligatoireobjectZeitraum-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)
timestampobligatoirestring (date-time)Zeitpunkt der Antwort (UTC)
Forme de la réponse
{
  "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)
StatutCode
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

É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

ChampTypeDescription
passIdobligatoirestring
cardIdobligatoirestring
customerIdobligatoirestring
employeeIdobligatoirestring | null
locationIdobligatoirestring | null
channelobligatoirestring | null

Enveloppe

ChampTypeDescription
idobligatoirestringevt_…, stabil über Wiederholungen (Dedupe)
eventobligatoire"pass.created"
timestampobligatoirestring (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.

En-têtes

ChampTypeDescription
X-tapja-EventobligatoirestringName des Ereignisses
X-tapja-DeliveryobligatoirestringKennung der Zustellung (= id im Body), stabil über Wiederholungen
X-tapja-TimestampobligatoirestringUnix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)
X-tapja-Signatureobligatoirestringsha256=<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

ChampTypeDescription
passIdobligatoirestring
cardIdobligatoirestring
stampCountobligatoireinteger
pointsBalanceobligatoireinteger
employeeIdobligatoirestring | null
locationIdobligatoirestring | null
channelobligatoirestring | null

pass.redeemed

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

Champs de data

ChampTypeDescription
passIdobligatoirestring
rewardIdstring
locationIdstring

pass.cancelled

Karte storniert.

Champs de data

ChampTypeDescription
passIdobligatoirestring
cardIdobligatoirestring

pass.reactivated

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

Champs de data

ChampTypeDescription
passIdobligatoirestring
customerIdobligatoirestring

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

ChampTypeDescription
passIdobligatoirestring
fieldobligatoirestring
enum stampCount | pointsBalance
valueobligatoireinteger
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.

Champs de data

ChampTypeDescription
passIdobligatoirestring
cardIdobligatoirestring
rewardIdsobligatoirearray<string>

offer.redeemed

Angebot eingelöst.

Champs de data

ChampTypeDescription
passIdobligatoirestring
offerIdobligatoirestring
locationIdstring

package.used

Einheit(en) einer Paketkarte genutzt.

Champs de data

ChampTypeDescription
passIdobligatoirestring
quantityobligatoireinteger
unitsobligatoireinteger
employeeIdobligatoirestring
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.

Champs de data

ChampTypeDescription
customerIdobligatoirestring

customer.deleted

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

Champs de data

ChampTypeDescription
customerIdobligatoirestring
passIdsobligatoirearray<string>

campaign.sent

Kampagne versendet.

Champs de data

ChampTypeDescription
campaignIdobligatoirestring
recipientsobligatoireinteger

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

ChampTypeDescription
messageobligatoirestring

Schémas

Error

ChampTypeDescription
errorobligatoireobject
error.codeobligatoirestringStabiler, 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.messageobligatoirestringFür Menschen; meist deutsch, bei Formfehlern (Validierung) teils englisch.

Pass

ChampTypeDescription
idobligatoirestring
cardIdobligatoirestring
customerIdobligatoirestring
serialNumberobligatoirestringSeriennummer aus dem Wallet-Barcode
stampCountobligatoireinteger
pointsBalanceobligatoireinteger
tierobligatoirestring | nullAktuelle Treuestufe oder null
lastStampAtobligatoirestring (date-time) | null
createdAtobligatoirestring (date-time)

PassState

Neuer Stand nach Stempeln/Einlösen.

ChampTypeDescription
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.

ChampTypeDescription
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.

ChampTypeDescription
idobligatoirestringEintrag (Cursor)
customerIdobligatoirestring
passIdsobligatoirearray<string>
deletedAtobligatoirestring (date-time)

DeletedCustomerPage

ChampTypeDescription
itemsobligatoirearray<object>
items[].idobligatoirestringEintrag (Cursor)
items[].customerIdobligatoirestring
items[].passIdsobligatoirearray<string>
items[].deletedAtobligatoirestring (date-time)
nextCursorobligatoirestring | nullAls cursor für die nächste Seite übergeben; null = Ende

Offer

ChampTypeDescription
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

ChampTypeDescription
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

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

Card

ChampTypeDescription
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

ChampTypeDescription
idstring
namestring
statusstring
enum OPEN | CLOSED

Employee

ChampTypeDescription
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.

ChampTypeDescription
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

ChampTypeDescription
cardIdobligatoirestringKartenprogramm (GET /cards)
maxLength 64
employeeIdobligatoirestringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoirestringStandort 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).

ChampTypeDescription
employeeIdobligatoirestringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoirestringStandort 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

ChampTypeDescription
rewardIdobligatoirestringPrämie (GET /cards → rewards)
maxLength 64
valueCentsintegerWarenwert für Mindestumsatz und Manager-Eskalation
minimum 0 · maximum 100000000
employeeIdobligatoirestringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoirestringStandort 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

ChampTypeDescription
offerIdobligatoirestringAngebot (GET /passes/{id}/offers)
maxLength 64
employeeIdobligatoirestringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoirestringStandort 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).

ChampTypeDescription
employeeIdobligatoirestringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoirestringStandort 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

ChampTypeDescription
textobligatoirestringKartentext; 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

Codes d’erreur

CodeStatutEndpointsRemarque
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
UNAUTHORIZED401tous les endpointsKey fehlt, ist ungültig, widerrufen oder abgelaufen
ACTOR_ROLE_NOT_ALLOWED403
CARD_FULL403
COMPANY_SUSPENDED403tous les 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_REQUIRED403tous les 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_MISSING403tous les 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_LIMITED429tous les 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_ERROR500tous les endpointsunerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar
REQUEST_IN_PROGRESS503tous les endpointsErstanfrage mit diesem Idempotency-Key läuft noch
RETRY503
SERVICE_UNAVAILABLE503vorübergehend nicht verfügbar