Skip to content

Diese Seite gibt es auch auf Deutsch. Auf Deutsch ansehen

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

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

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

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

tapja

For developers

Connect tapja to your POS, shop and CRM

REST API and webhooks for developers of POS systems, shops and CRMs who connect a business on the Favourite Chain plan.

Go to the API reference OpenAPI

Overview

Through the interface, a business’s own system talks directly to tapja. The POS scans the barcode on the card, finds the guest, adds stamps and redeems rewards. With webhooks, tapja reports back as soon as something happens.

What you can do

  • Find a card by the serial number in its QR code or barcode: GET /passes/by-serial/{serial}
  • Read a card’s state and minimal guest data: GET /passes/{id}, GET /customers/{id}, GET /customers
  • Add stamps or points: POST /passes/{id}/stamp
  • Redeem rewards and offers, cancel cards: POST /passes/{id}/redeem, POST /passes/{id}/redeem-offer, POST /passes/{id}/cancel
  • Get a sign-up link for new guests: POST /passes
  • Read card programmes, locations, employees and figures: GET /cards, GET /locations, GET /employees, GET /analytics
  • Send a card notification to guests with marketing consent: POST /notifications/push
  • Reconcile deleted guests: GET /customers/deleted
  • Receive webhooks for 13 events, such as “Card issued”, “Stamp added”, “Reward ready” and “Guest deleted”

What is deliberately not possible

  • Issuing cards without the guest’s consent. POST /passes returns a sign-up link; the guest creates the card themselves.
  • Creating guests without them signing up through that link.
  • Bulk-exporting guests. Individual guests are available by ID or by email search.
  • Booking package and membership cards. The interface rejects this with PACKAGE_USE_REQUIRED or MEMBERSHIP_ACTION_REQUIRED.

Requirements

The business is on the Favourite Chain plan. The owner of the business creates the API key. There is no ready-made connector for any specific POS system; the interface is the way to build one.

Quickstart in 5 steps

1. Have an API key created

The owner creates the key on the web under Administration › Integrations, in the app under More › Setup & management › Integrations. tapja asks for their password again, and every owner of the business gets a security email. The key is shown exactly once.

  • Scopes: only the ones your system needs (see Scopes). pass:read, pass:write and setup:read are preselected. Without setup:read, your system knows neither employeeId nor locationId.
  • Location binding (optional): the key then only books at these locations. The scopes customer:read, pass:cancel and notification:send are not possible for such keys.
  • Highest actor role (“May act as” in the interface): your system may name employees up to this role. The default is “Employee”.

2. Base URL

text
https://api.tapja.de/api/v1/public

3. Authenticate

Every request carries the key as a bearer token. The key belongs on the server or in the POS only, never in a browser, an app or logs.

http
Authorization: Bearer sk_live_…

4. First call: read a card

Read the card by the serial number from its barcode.

bash
curl https://api.tapja.de/api/v1/public/passes/by-serial/SN8F3K2 \
  -H "Authorization: Bearer sk_live_…"
Response shape
{
  "data": {
    "id": "string",
    "cardId": "string",
    "customerId": "string",
    "serialNumber": "string",
    "stampCount": 0,
    "pointsBalance": 0,
    "tier": "string",
    "lastStampAt": "2026-11-07T10:00:00.000Z",
    "createdAt": "2026-11-07T10:00:00.000Z"
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}

5. First booking: add a stamp

A booking always names an employee and a location. GET /employees and GET /locations return their IDs.

bash
curl https://api.tapja.de/api/v1/public/employees -H "Authorization: Bearer sk_live_…"
curl https://api.tapja.de/api/v1/public/locations -H "Authorization: Bearer sk_live_…"

The Idempotency-Key is new for every transaction, for example the receipt number. The card’s ID is the id field from step 4.

bash
curl -X POST https://api.tapja.de/api/v1/public/passes/pass_123/stamp \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: kasse-3-bon-4711" \
  -H "Content-Type: application/json" \
  -d '{ "employeeId": "emp_42", "locationId": "loc_mitte", "employeeRef": "Kasse 3" }'
Response shape
{
  "data": {
    "id": "string",
    "cardId": "string",
    "customerId": "string",
    "serialNumber": "string",
    "stampCount": 0,
    "pointsBalance": 0,
    "tier": "string",
    "lastStampAt": "2026-11-07T10:00:00.000Z",
    "createdAt": "2026-11-07T10:00:00.000Z",
    "lifetimeProgress": 0,
    "stampCycle": 0
  },
  "timestamp": "2026-11-07T10:00:00.000Z"
}

Every key books for real. Read No test mode before your first test.

Ground rules

Responses and errors

Successful responses come in { data, timestamp }, errors in { error: { code, message } }.

json
{ "data": { "…": "…" }, "timestamp": "2026-11-07T10:00:00.000Z" }
json
{ "error": { "code": "COOLDOWN_ACTIVE", "message": "Bereits kürzlich gestempelt." } }

Branch on code only, never on message. The text is for humans, mostly German, and can change. The interface rejects unknown fields in the request body with 400.

Error codes (72)
CodeStatusEndpoints
AMOUNT_BELOW_MINIMUM400
POST /passes/{id}/stamp
AMOUNT_REQUIRED400
POST /passes/{id}/stamp
AMOUNT_TOO_SMALL400
POST /passes/{id}/stamp
BAD_REQUEST400
POST /passes
POST /passes/{id}/stamp
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
POST /passes/{id}/cancel
GET /customers
GET /customers/deleted
POST /notifications/push
CARD_HAS_NO_BALANCE400
POST /passes/{id}/stamp
COUPON_NOT_COMBINABLE400
POST /passes/{id}/redeem-offer
IDEMPOTENCY_KEY_INVALID400
POST /passes
POST /passes/{id}/stamp
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
POST /passes/{id}/cancel
POST /notifications/push
LOCATION_WRONG_COMPANY400
POST /passes
POST /passes/{id}/stamp
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
POST /passes/{id}/cancel
MEMBERSHIP_ACTION_REQUIRED400
POST /passes/{id}/stamp
POST /passes/{id}/redeem
OFFERS_NOT_ON_CARD400
POST /passes/{id}/redeem-offer
PACKAGE_USE_REQUIRED400
POST /passes/{id}/stamp
POST /passes/{id}/redeem
PLACEHOLDER_UNKNOWN400
POST /notifications/push
POINTS_BALANCE_LIMIT400
POST /passes/{id}/stamp
POINTS_REQUIRED400
POST /passes/{id}/stamp
QUIET_HOURS400
POST /notifications/push
REWARD_AUTO_ISSUED400
POST /passes/{id}/redeem
STAMP_CAP_EXCEEDED400
POST /passes/{id}/stamp
STAMP_MODE_AMOUNT400
POST /passes/{id}/stamp
STAMP_MODE_VISIT400
POST /passes/{id}/stamp
UNAUTHORIZED401all endpoints
ACTOR_ROLE_NOT_ALLOWED403
POST /passes
POST /passes/{id}/stamp
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
POST /passes/{id}/cancel
CARD_FULL403
POST /passes/{id}/stamp
COMPANY_SUSPENDED403all endpoints
COOLDOWN_ACTIVE403
POST /passes/{id}/stamp
EMPLOYEE_NOT_AT_LOCATION403
POST /passes
POST /passes/{id}/stamp
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
POST /passes/{id}/cancel
GUEST_EMAIL_UNVERIFIED403
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
LOCATION_NOT_ALLOWED403
POST /passes
POST /passes/{id}/stamp
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
POST /passes/{id}/cancel
POST /notifications/push
NOT_ENOUGH_POINTS403
POST /passes/{id}/redeem
OFFER_COOLDOWN403
POST /passes/{id}/redeem-offer
OFFER_EXHAUSTED403
POST /passes/{id}/redeem-offer
OFFER_EXPIRED403
POST /passes/{id}/redeem-offer
OFFER_NOT_ELIGIBLE403
POST /passes/{id}/redeem-offer
OFFER_NOT_STARTED403
POST /passes/{id}/redeem-offer
OFFER_WRONG_LOCATION403
POST /passes/{id}/redeem-offer
PIN_REQUIRED403
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
PLAN_FEATURE_REQUIRED403all endpoints
REDEEM_NOT_AT_LOCATION403
POST /passes/{id}/redeem
REWARD_ALREADY_REDEEMED403
POST /passes/{id}/redeem
REWARD_EXPIRED403
POST /passes/{id}/redeem
REWARD_LIMIT_REACHED403
POST /passes/{id}/redeem
REWARD_MEMBERSHIP_REQUIRED403
POST /passes/{id}/redeem
REWARD_MIN_PURCHASE403
POST /passes/{id}/redeem
REWARD_NOT_COMBINABLE403
POST /passes/{id}/redeem
REWARD_NOT_YET_VALID403
POST /passes/{id}/redeem
REWARD_QUOTA_EXHAUSTED403
POST /passes/{id}/redeem
REWARD_THRESHOLD_NOT_REACHED403
POST /passes/{id}/redeem
REWARD_TIER_REQUIRED403
POST /passes/{id}/redeem
REWARD_WRONG_LOCATION403
POST /passes/{id}/redeem
ROLE_NOT_ALLOWED403
POST /passes/{id}/cancel
SCOPE_MISSING403all endpoints
STAMP_LIMIT_REACHED403
POST /passes/{id}/stamp
CARD_NOT_FOUND404
POST /passes
POST /notifications/push
CUSTOMER_NOT_FOUND404
GET /customers
GET /customers/{id}
EMPLOYEE_NOT_FOUND404
POST /passes
POST /passes/{id}/stamp
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
POST /passes/{id}/cancel
NOT_FOUND404
GET /passes/{id}/offers
POST /passes/{id}/redeem-offer
OFFER_NOT_FOUND404
POST /passes/{id}/redeem-offer
PASS_NOT_FOUND404
GET /passes/by-serial/{serial}
GET /passes/{id}
POST /passes/{id}/stamp
POST /passes/{id}/redeem
GET /passes/{id}/offers
POST /passes/{id}/redeem-offer
POST /passes/{id}/cancel
REWARD_NOT_FOUND404
POST /passes/{id}/redeem
CARD_ARCHIVED409
POST /passes
POST /passes/{id}/redeem-offer
CARD_NOT_AT_LOCATION409
POST /passes
IDEMPOTENCY_KEY_REUSED409
POST /passes
POST /passes/{id}/stamp
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
POST /passes/{id}/cancel
POST /notifications/push
LOCATION_DEACTIVATED409
POST /passes
POST /passes/{id}/stamp
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
POST /passes/{id}/cancel
OFFER_ALREADY_REDEEMED409
POST /passes/{id}/redeem-offer
OFFER_USED_UP409
POST /passes/{id}/redeem-offer
PASS_VOIDED409
POST /passes/{id}/stamp
POST /passes/{id}/redeem
POST /passes/{id}/redeem-offer
POST /passes/{id}/cancel
REQUEST_ABANDONED409
POST /passes/{id}/stamp
POST /passes/{id}/redeem-offer
POST /notifications/push
UNPROCESSABLE422
POST /notifications/push
RATE_LIMITED429all endpoints
INTERNAL_ERROR500all endpoints
REQUEST_IN_PROGRESS503all endpoints
RETRY503
POST /passes/{id}/stamp
POST /passes/{id}/redeem
POST /passes/{id}/cancel
SERVICE_UNAVAILABLE503
GET /passes/by-serial/{serial}
GET /passes/{id}
GET /passes/{id}/offers
GET /customers
GET /customers/deleted
GET /customers/{id}
GET /analytics
GET /cards
GET /locations
GET /employees

Attribution

  • Every booking names employeeId (an active employee of the business, assigned to the location) and locationId.
  • Your system can also send employeeRef, the cashier’s reference. Use till or staff numbers, not real names.
  • If your system names an employee with a higher role than the key allows, the interface answers 403 ACTOR_ROLE_NOT_ALLOWED.
  • Cancelling needs an employee with the role MANAGER or OWNER and a key whose actor role is at least MANAGER.

Scopes

Deny by default: a key can only do what its scopes allow. If one is missing, you get 403 SCOPE_MISSING.

ScopeLabel the owner seesEndpoints
pass:writeIssue cards and add stamps
POST /passes
POST /passes/{id}/stamp
pass:readView cards
GET /passes/by-serial/{serial}
GET /passes/{id}
pass:redeemRedeem rewards
POST /passes/{id}/redeem
offer:readView offers
GET /passes/{id}/offers
offer:redeemRedeem offers
POST /passes/{id}/redeem-offer
pass:cancelCancel cards
POST /passes/{id}/cancel
customer:readView guests
GET /customers
GET /customers/deleted
GET /customers/{id}
notification:sendSend messages to guests
POST /notifications/push
analytics:readFetch figures
GET /analytics
setup:readFetch cards, locations and team
GET /cards
GET /locations
GET /employees

Idempotency

  • All POST endpoints accept the Idempotency-Key header. It applies per API key, is bound to method, path and body, and has at most 255 visible ASCII characters, for example the receipt number.
  • An identical repeat returns the same response; for the sign-up link, a fresh link. Different content with the same key returns 409 IDEMPOTENCY_KEY_REUSED. While the first request is still running, you get 503 REQUEST_IN_PROGRESS.
  • Only a successful response is stored, for 7 days. Only stamping and redeeming rewards stay protected beyond those 7 days: the same pass with the same key is not booked twice, and a different pass returns 409 IDEMPOTENCY_KEY_REUSED.

Special case: offer cards. On an offer card, the call books a visit. Like redeeming an offer, it is only protected for 7 days through the Idempotency-Key. If the first request breaks off midway, it is never executed again (first 503 REQUEST_IN_PROGRESS, then 409 REQUEST_ABANDONED). Check the state with GET /passes/{id} and, if needed, book again with a new Idempotency-Key.

IDs

IDs in paths have at most 64 characters; longer ones return 400.

Rate limits

  • 300 requests per minute per key across all endpoints. Headers: X-RateLimit-Limit-api, X-RateLimit-Remaining-api, X-RateLimit-Reset-api.
  • Email search (GET /customers) additionally 60 per minute per key and 120 per minute per business. Headers: X-RateLimit-Limit-customerLookup, X-RateLimit-Remaining-customerLookup.
  • Above that you get 429 RATE_LIMITED with the standard Retry-After header (seconds) plus Retry-After-api or Retry-After-customerLookup.
  • Many invalid keys from one address lead to a temporary block of that address, also 429 with Retry-After.

No test mode

There is no sandbox and there are no test keys. Every key books for real: bookings appear in reports and the activity log, and redeemed rewards also in the tax report.

  • Test with a separate test card and a separate key with few scopes, and revoke it afterwards.
  • Do not use POST /notifications/push for testing; the messages go to real guests.
  • Webhooks can be tested safely, see Testing webhooks.

Versioning

The version is part of the path (/api/v1). New response fields and new events can appear at any time, so skip unknown fields. Breaking changes only come with a new version and advance notice.

Webhooks

Creating a webhook

The owner creates the webhook under Integrations: a publicly reachable HTTPS address and the selected events. The webhook secret is shown once. It is not the API key: the key opens access to tapja, the secret only verifies the messages that reach you.

Events

EventLabelFields in data
pass.createdCard issuedpassId cardId customerId employeeId locationId channel
pass.stampedStamp addedpassId cardId stampCount pointsBalance employeeId locationId channel
pass.redeemedReward redeemedpassId rewardId (optional) locationId (optional)
pass.cancelledCard cancelledpassId cardId
pass.reactivatedCard active againpassId customerId
pass.correctedBooking correctedpassId field value employeeId (optional) locationId (optional)
reward.readyReward readypassId cardId rewardIds
offer.redeemedOffer redeemedpassId offerId locationId (optional)
package.usedPackage unit usedpassId quantity units employeeId locationId (optional)
customer.createdGuest addedcustomerId
customer.deletedGuest deletedcustomerId passIds
customer.consent_changedMarketing consent changedcustomerId marketingConsent
campaign.sentMessage sentcampaignId recipients

There is also the test event ping with the field message, which cannot be subscribed to. All descriptions are in the reference.

Envelope and headers

Every message has the fields id, event, data and timestamp. X-tapja-Delivery equals the id.

json
{
  "id": "evt_3f2a…",
  "event": "pass.redeemed",
  "data": { "passId": "pass_123", "rewardId": "rw_1" },
  "timestamp": "2026-11-07T10:00:00.000Z"
}
http
X-tapja-Event: pass.redeemed
X-tapja-Delivery: evt_3f2a…
X-tapja-Timestamp: 1794045600
X-tapja-Signature: sha256=<hex>
User-Agent: tapja-webhooks/2

Verifying the signature

HMAC-SHA256 with the webhook secret over ${X-tapja-Timestamp}.${raw body}, tolerance 300 seconds, constant-time comparison. What counts is the raw body, before any JSON parsing.

Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(rawBody, headers, secret) {
  const ts = headers['x-tapja-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const given = String(headers['x-tapja-signature'] ?? '');
  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
Python
import hmac, hashlib, time
def verify(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers['X-tapja-Timestamp']
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = 'sha256=' + hmac.new(secret.encode(), f'{ts}.'.encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(headers.get('X-tapja-Signature', ''), expected)

Delivery

  • Answer quickly with a 2xx and do the work asynchronously. After 10 seconds an attempt counts as failed.
  • On a non-2xx, up to 5 retries follow after about 1, 2, 4, 8 and 16 minutes, roughly half an hour in total.
  • The id stays the same across retries. Deduplicate on it.
  • After 30 failed attempts in a row the webhook pauses, and the owner reactivates it. Events from the pause are not delivered afterwards.

Order

Order is not guaranteed. pass.created can arrive before customer.created, reward.ready before pass.stamped. Order states by timestamp or GET /passes/{id}.

customer.deleted is a final deletion marker: discard later events about this guest and do not recreate them.

Webhooks are not a gapless log. Reconcile critical states with GET where needed.

Renewing the secret

The new webhook secret applies immediately, with no transition period. Renew it at a quiet time and enter the new secret right away.

Testing webhooks

  • “Send test” sends ping, “Send sample event” a sample of a subscribed type.
  • Tests carry the envelope field "test": true and the header X-tapja-Test: 1. Real events carry neither. All IDs are made up and start with test_.
  • Tests are not retried, also reach paused webhooks and never count towards the pause. At most 20 tests per hour per webhook.
  • Detect tests by the test field and do not book them.

Deletions and privacy

  • customer.deleted names the IDs of the guest and their cards.
  • Fetch missed deletions with GET /customers/deleted?since=…: the last 30 days, IDs only, cursor-based. Ideally reconcile daily and delete in your own system too.
  • If the whole business is deleted, no customer.deleted is sent per guest.
  • Webhooks contain only IDs and counters, no names or addresses.
  • Only GET /customers/{id} and the email search GET /customers return a guest’s email address. Every retrieval is logged.
  • Marketing from your own system only goes to guests with marketingConsent: true and emailVerifiedAt set.
  • GET /employees returns the team’s names and roles. Only give setup:read to systems that need it.
bash
curl "https://api.tapja.de/api/v1/public/customers/deleted?since=2026-11-01T00:00:00.000Z" \
  -H "Authorization: Bearer sk_live_…"

Responsibility for data

The business is responsible for the data in its own system. Depending on the setup, it needs a data processing agreement with the provider of that system and names the system in its privacy notice.

Contact

Questions about the integration and security findings go to hallo@tapja.de. Include the endpoint, time (UTC) and error code. Never send the API key or the webhook secret.