Saltar al contenido

Diese Seite gibt es auch auf Deutsch. Auf Deutsch ansehen

This page is also available in English. Switch to English

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

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

Mostrada en el idioma que elegiste. Auf Deutsch ansehenSwitch to EnglishBekijk in het NederlandsVoir en français

tapja

Referencia de la API

Endpoints, webhooks, códigos de error

Generada a partir de la descripción OpenAPI de la interfaz. URL base: https://api.tapja.de/api/v1/public

Las descripciones de la referencia están por ahora en alemán.

Descargar el archivo OpenAPI Ir a la guía

Configuración

GET /cards

Aktive Kartenprogramme mit Prämien

Scope: setup:read

Respuesta 200 · Card

Kartenprogramme

CampoTipoDescripción
dataobligatorioarray<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)
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "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"
}
Errores posibles (5)
EstadoCódigo
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

Respuesta 200 · Location

Standorte

CampoTipoDescripción
dataobligatorioarray<object>
data[].idstring
data[].namestring
data[].statusstring
enum OPEN | CLOSED
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "status": "OPEN"
    }
  ],
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Errores posibles (5)
EstadoCódigo
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

Respuesta 200 · Employee

Mitarbeiter

CampoTipoDescripción
dataobligatorioarray<object>
data[].idstring
data[].namestring | null
data[].rolestring
enum OWNER | MANAGER | EMPLOYEE
data[].locationIdsarray<string>
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "role": "OWNER",
      "locationIds": [
        "string"
      ]
    }
  ],
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Errores posibles (5)
EstadoCódigo
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

Tarjetas

GET /passes/by-serial/{serial}

Pass über die Seriennummer aus dem Wallet-Barcode

Scope: pass:read

Parámetros

CampoTipoDescripción
serialobligatorio
path
string

Respuesta 200 · Pass

Pass

CampoTipoDescripción
dataobligatorioobject
data.idobligatoriostring
data.cardIdobligatoriostring
data.customerIdobligatoriostring
data.serialNumberobligatoriostringSeriennummer aus dem Wallet-Barcode
data.stampCountobligatoriointeger
data.pointsBalanceobligatoriointeger
data.tierobligatoriostring | nullAktuelle Treuestufe oder null
data.lastStampAtobligatoriostring (date-time) | null
data.createdAtobligatoriostring (date-time)
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "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"
}
Errores posibles (6)
EstadoCódigo
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

Parámetros

CampoTipoDescripción
idobligatorio
path
string
maxLength 64

Respuesta 200 · Pass

Pass

CampoTipoDescripción
dataobligatorioobject
data.idobligatoriostring
data.cardIdobligatoriostring
data.customerIdobligatoriostring
data.serialNumberobligatoriostringSeriennummer aus dem Wallet-Barcode
data.stampCountobligatoriointeger
data.pointsBalanceobligatoriointeger
data.tierobligatoriostring | nullAktuelle Treuestufe oder null
data.lastStampAtobligatoriostring (date-time) | null
data.createdAtobligatoriostring (date-time)
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "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"
}
Errores posibles (6)
EstadoCódigo
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

Parámetros

CampoTipoDescripción
idobligatorio
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]+$

Cuerpo de la petición · StampRequest

Ohne Betrag ein Besuch; mit amountCents Umsatzpunkte; mit points direkte Punkte. Welcher Weg passt, entscheidet die Karte (sonst 400).

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

Respuesta 201 · PassState

Neuer Stand

CampoTipoDescripción
dataobligatorioobjectNeuer 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
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "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"
}
Errores posibles (8)
EstadoCódigo
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

Parámetros

CampoTipoDescripción
idobligatorio
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]+$

Cuerpo de la petición · RedeemRequest

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

Respuesta 201 · PassState

Neuer Stand

CampoTipoDescripción
dataobligatorioobjectNeuer 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
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "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"
}
Errores posibles (8)
EstadoCódigo
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

Parámetros

CampoTipoDescripción
idobligatorio
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]+$

Cuerpo de la petición · CancelRequest

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

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

Respuesta 201

Storniert

CampoTipoDescripción
dataobligatorioobject
data.idobligatoriostring
data.cancelledobligatoriotrue
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "data": {
    "id": "string",
    "cancelled": true
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Errores posibles (8)
EstadoCódigo
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

Ofertas

GET /passes/{id}/offers

Angebote eines Passes (Angebotskarte)

Scope: offer:read

Parámetros

CampoTipoDescripción
idobligatorio
path
string
maxLength 64

Respuesta 200 · OfferList

Angebote

CampoTipoDescripción
dataobligatorioobject
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
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "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"
}
Errores posibles (6)
EstadoCódigo
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

Parámetros

CampoTipoDescripción
idobligatorio
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]+$

Cuerpo de la petición · RedeemOfferRequest

CampoTipoDescripción
offerIdobligatoriostringAngebot (GET /passes/{id}/offers)
maxLength 64
employeeIdobligatoriostringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoriostringStandort 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

Respuesta 201 · OfferRedemption

Einlösung

CampoTipoDescripción
dataobligatorioobject
data.offerIdstring
data.titlestring
data.remainingintegerWie oft der Gast das Angebot im Fenster noch einlösen kann
data.openCountinteger
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "data": {
    "offerId": "string",
    "title": "string",
    "remaining": 0,
    "openCount": 0
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Errores posibles (8)
EstadoCódigo
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

Clientes

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

Parámetros

CampoTipoDescripción
emailobligatorio
query
string (email)
maxLength 254

Respuesta 200 · Customer

Gast

CampoTipoDescripción
dataobligatorioobjectMinimale 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)
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "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"
}
Errores posibles (7)
EstadoCódigo
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

Parámetros

CampoTipoDescripción
sinceobligatorio
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

Respuesta 200 · DeletedCustomerPage

Lösch-Nachweise

CampoTipoDescripción
dataobligatorioobject
data.itemsobligatorioarray<object>
data.items[].idobligatoriostringEintrag (Cursor)
data.items[].customerIdobligatoriostring
data.items[].passIdsobligatorioarray<string>
data.items[].deletedAtobligatoriostring (date-time)
data.nextCursorobligatoriostring | nullAls cursor für die nächste Seite übergeben; null = Ende
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "data": {
    "items": [
      {
        "id": "string",
        "customerId": "string",
        "passIds": [
          "string"
        ],
        "deletedAt": "2026-11-07T10:00:00.000Z"
      }
    ],
    "nextCursor": "string"
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Errores posibles (6)
EstadoCódigo
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

Parámetros

CampoTipoDescripción
idobligatorio
path
string

Respuesta 200 · Customer

Gast

CampoTipoDescripción
dataobligatorioobjectMinimale 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)
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "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"
}
Errores posibles (6)
EstadoCódigo
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

Mensajes

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

Parámetros

CampoTipoDescripción
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]+$

Cuerpo de la petición · PushRequest

CampoTipoDescripción
textobligatoriostringKartentext; 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

Respuesta 201

Versendet

CampoTipoDescripción
dataobligatorioobject
data.recipientsobligatoriointegerZahl der erreichten Gäste
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "data": {
    "recipients": 0
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Errores posibles (9)
EstadoCódigo
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

Análisis

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

Respuesta 200 · AnalyticsOverview

Übersicht

CampoTipoDescripción
dataobligatorioobjectZeitraum-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)
timestampobligatoriostring (date-time)Zeitpunkt der Antwort (UTC)
Forma de la respuesta
{
  "data": {
    "cardPrograms": 0,
    "cardsIssued": 0,
    "stampsAdded": 0,
    "redemptions": 0,
    "activeCards": 0,
    "totalCustomers": 0,
    "newCustomers": 0,
    "deltas": {}
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
Errores posibles (5)
EstadoCódigo
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

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

Campos en data

CampoTipoDescripción
passIdobligatoriostring
cardIdobligatoriostring
customerIdobligatoriostring
employeeIdobligatoriostring | null
locationIdobligatoriostring | null
channelobligatoriostring | null

Envoltorio

CampoTipoDescripción
idobligatoriostringevt_…, stabil über Wiederholungen (Dedupe)
eventobligatorio"pass.created"
timestampobligatoriostring (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.

Cabeceras

CampoTipoDescripción
X-tapja-EventobligatoriostringName des Ereignisses
X-tapja-DeliveryobligatoriostringKennung der Zustellung (= id im Body), stabil über Wiederholungen
X-tapja-TimestampobligatoriostringUnix-Sekunden des Zustellversuchs (Toleranz beim Empfänger: 300 s)
X-tapja-Signatureobligatoriostringsha256=<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.

Campos en data

CampoTipoDescripción
passIdobligatoriostring
cardIdobligatoriostring
stampCountobligatoriointeger
pointsBalanceobligatoriointeger
employeeIdobligatoriostring | null
locationIdobligatoriostring | null
channelobligatoriostring | null

pass.redeemed

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

Campos en data

CampoTipoDescripción
passIdobligatoriostring
rewardIdstring
locationIdstring

pass.cancelled

Karte storniert.

Campos en data

CampoTipoDescripción
passIdobligatoriostring
cardIdobligatoriostring

pass.reactivated

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

Campos en data

CampoTipoDescripción
passIdobligatoriostring
customerIdobligatoriostring

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.

Campos en data

CampoTipoDescripción
passIdobligatoriostring
fieldobligatoriostring
enum stampCount | pointsBalance
valueobligatoriointeger
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.

Campos en data

CampoTipoDescripción
passIdobligatoriostring
cardIdobligatoriostring
rewardIdsobligatorioarray<string>

offer.redeemed

Angebot eingelöst.

Campos en data

CampoTipoDescripción
passIdobligatoriostring
offerIdobligatoriostring
locationIdstring

package.used

Einheit(en) einer Paketkarte genutzt.

Campos en data

CampoTipoDescripción
passIdobligatoriostring
quantityobligatoriointeger
unitsobligatoriointeger
employeeIdobligatoriostring
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.

Campos en data

CampoTipoDescripción
customerIdobligatoriostring

customer.deleted

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

Campos en data

CampoTipoDescripción
customerIdobligatoriostring
passIdsobligatorioarray<string>

campaign.sent

Kampagne versendet.

Campos en data

CampoTipoDescripción
campaignIdobligatoriostring
recipientsobligatoriointeger

pingno se puede suscribir

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.

Campos en data

CampoTipoDescripción
messageobligatoriostring

Esquemas

Error

CampoTipoDescripción
errorobligatorioobject
error.codeobligatoriostringStabiler, 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.messageobligatoriostringFür Menschen; meist deutsch, bei Formfehlern (Validierung) teils englisch.

Pass

CampoTipoDescripción
idobligatoriostring
cardIdobligatoriostring
customerIdobligatoriostring
serialNumberobligatoriostringSeriennummer aus dem Wallet-Barcode
stampCountobligatoriointeger
pointsBalanceobligatoriointeger
tierobligatoriostring | nullAktuelle Treuestufe oder null
lastStampAtobligatoriostring (date-time) | null
createdAtobligatoriostring (date-time)

PassState

Neuer Stand nach Stempeln/Einlösen.

CampoTipoDescripción
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.

CampoTipoDescripción
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.

CampoTipoDescripción
idobligatoriostringEintrag (Cursor)
customerIdobligatoriostring
passIdsobligatorioarray<string>
deletedAtobligatoriostring (date-time)

DeletedCustomerPage

CampoTipoDescripción
itemsobligatorioarray<object>
items[].idobligatoriostringEintrag (Cursor)
items[].customerIdobligatoriostring
items[].passIdsobligatorioarray<string>
items[].deletedAtobligatoriostring (date-time)
nextCursorobligatoriostring | nullAls cursor für die nächste Seite übergeben; null = Ende

Offer

CampoTipoDescripción
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

CampoTipoDescripción
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

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

Card

CampoTipoDescripción
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

CampoTipoDescripción
idstring
namestring
statusstring
enum OPEN | CLOSED

Employee

CampoTipoDescripción
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.

CampoTipoDescripción
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

CampoTipoDescripción
cardIdobligatoriostringKartenprogramm (GET /cards)
maxLength 64
employeeIdobligatoriostringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoriostringStandort 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).

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

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

CampoTipoDescripción
offerIdobligatoriostringAngebot (GET /passes/{id}/offers)
maxLength 64
employeeIdobligatoriostringAktiver Mitarbeiter des Betriebs, dem Standort zugeordnet (GET /employees). Seine Rolle darf die Akteursgrenze des Keys nicht übersteigen.
maxLength 64
locationIdobligatoriostringStandort 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).

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

CampoTipoDescripción
textobligatoriostringKartentext; 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

Códigos de error

CódigoEstadoEndpointsNota
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
UNAUTHORIZED401todos los endpointsKey fehlt, ist ungültig, widerrufen oder abgelaufen
ACTOR_ROLE_NOT_ALLOWED403
CARD_FULL403
COMPANY_SUSPENDED403todos los 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_REQUIRED403todos los 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_MISSING403todos los 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_LIMITED429todos los 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_ERROR500todos los endpointsunerwarteter Fehler; ohne Details, mit demselben Idempotency-Key wiederholbar
REQUEST_IN_PROGRESS503todos los endpointsErstanfrage mit diesem Idempotency-Key läuft noch
RETRY503
SERVICE_UNAVAILABLE503vorübergehend nicht verfügbar