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

Pour les développeurs

Connecter tapja à votre caisse, boutique et CRM

API REST et webhooks pour les développeurs de caisses, de boutiques et de CRM qui connectent un établissement avec la formule Enseigne préférée.

Aller à la référence de l’API OpenAPI

Vue d’ensemble

Grâce à l’interface, le système d’un établissement communique directement avec tapja. La caisse scanne le code-barres de la carte, trouve le client, ajoute des tampons et utilise des récompenses. Avec les webhooks, tapja prévient dès qu’il se passe quelque chose.

Ce qui est possible

  • Trouver une carte grâce au numéro de série de son QR code ou code-barres : GET /passes/by-serial/{serial}
  • Lire l’état d’une carte et les données minimales du client : GET /passes/{id}, GET /customers/{id}, GET /customers
  • Ajouter des tampons ou des points : POST /passes/{id}/stamp
  • Utiliser des récompenses et des offres, annuler des cartes : POST /passes/{id}/redeem, POST /passes/{id}/redeem-offer, POST /passes/{id}/cancel
  • Obtenir un lien d’inscription pour les nouveaux clients : POST /passes
  • Lire les programmes de cartes, les sites, les employés et les chiffres : GET /cards, GET /locations, GET /employees, GET /analytics
  • Envoyer une notification de carte aux clients ayant donné leur consentement marketing : POST /notifications/push
  • Rapprocher les clients supprimés : GET /customers/deleted
  • Recevoir des webhooks pour 13 événements, comme « Carte émise », « Tampon ajouté », « Récompense disponible » et « Client supprimé »

Ce qui est volontairement impossible

  • Émettre des cartes sans le consentement du client. POST /passes renvoie un lien d’inscription ; le client crée lui-même sa carte.
  • Créer des clients sans qu’ils s’inscrivent par ce lien.
  • Exporter les clients en masse. Chaque client se consulte par son identifiant ou par recherche d’e-mail.
  • Enregistrer des cartes forfait et de membre. L’interface le refuse avec PACKAGE_USE_REQUIRED ou MEMBERSHIP_ACTION_REQUIRED.

Conditions

L’établissement dispose de la formule Enseigne préférée. La clé API est créée par le propriétaire de l’établissement. Il n’existe pas de connexion prête à l’emploi pour un système de caisse donné ; l’interface permet d’en construire une.

Démarrage rapide en 5 étapes

1. Faites créer une clé API

Le propriétaire crée la clé sur le web dans Gestion › Intégrations, dans l’app sous Plus › Configuration et gestion › Intégrations. tapja redemande son mot de passe, et tous les propriétaires de l’établissement reçoivent un e-mail de sécurité. La clé n’est affichée qu’une seule fois.

  • Scopes : uniquement ceux dont votre système a besoin (voir Scopes). pass:read, pass:write et setup:read sont présélectionnés. Sans setup:read, votre système ne connaît ni employeeId ni locationId.
  • Limitation à certains sites (facultatif) : la clé n’enregistre alors que sur ces sites. Les scopes customer:read, pass:cancel et notification:send sont impossibles pour de telles clés.
  • Rôle d’acteur maximal (« Peut agir en tant que » dans l’interface) : votre système peut indiquer des employés jusqu’à ce rôle. Par défaut, c’est « Employé ».

2. URL de base

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

3. Authentification

Chaque requête porte la clé sous forme de jeton Bearer. La clé ne doit se trouver que sur le serveur ou dans la caisse, jamais dans un navigateur, une app ou des journaux.

http
Authorization: Bearer sk_live_…

4. Premier appel : lire une carte

Lisez la carte grâce au numéro de série de son code-barres.

bash
curl https://api.tapja.de/api/v1/public/passes/by-serial/SN8F3K2 \
  -H "Authorization: Bearer sk_live_…"
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"
}

5. Première opération : tamponner

Une opération indique toujours un employé et un site. GET /employees et GET /locations renvoient leurs identifiants.

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_…"

Le Idempotency-Key est nouveau pour chaque opération, par exemple le numéro de ticket. L’identifiant de la carte est le champ id de l’étape 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" }'
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"
}

Chaque clé enregistre pour de vrai. Avant votre premier test, lisez Pas de mode test.

Règles de base

Réponses et erreurs

Les réponses réussies arrivent dans { data, timestamp }, les erreurs dans { error: { code, message } }.

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

Basez vos traitements uniquement sur code, jamais sur message. Le texte s’adresse aux humains, il est le plus souvent en allemand et peut changer. L’interface refuse avec 400 les champs inconnus du corps de la requête.

Codes d’erreur (72)
CodeStatutEndpoints
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
UNAUTHORIZED401tous les 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_SUSPENDED403tous les 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_REQUIRED403tous les 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_MISSING403tous les 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_LIMITED429tous les endpoints
INTERNAL_ERROR500tous les endpoints
REQUEST_IN_PROGRESS503tous les 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

  • Chaque opération indique employeeId (un employé actif de l’établissement, rattaché au site) et locationId.
  • Votre système peut aussi envoyer employeeRef, la référence du caissier. Utilisez des numéros de caisse ou de personnel, pas de vrais noms.
  • Si votre système indique un employé dont le rôle dépasse ce que la clé autorise, l’interface répond 403 ACTOR_ROLE_NOT_ALLOWED.
  • Annuler nécessite un employé au rôle MANAGER ou OWNER et une clé dont le rôle d’acteur est au moins MANAGER.

Scopes

Tout est refusé par défaut : une clé ne peut faire que ce que ses scopes autorisent. S’il en manque un, vous recevez 403 SCOPE_MISSING.

ScopeLibellé vu par le propriétaireEndpoints
pass:writeÉmettre des cartes et tamponner
POST /passes
POST /passes/{id}/stamp
pass:readVoir les cartes
GET /passes/by-serial/{serial}
GET /passes/{id}
pass:redeemUtiliser des récompenses
POST /passes/{id}/redeem
offer:readVoir les offres
GET /passes/{id}/offers
offer:redeemUtiliser des offres
POST /passes/{id}/redeem-offer
pass:cancelAnnuler des cartes
POST /passes/{id}/cancel
customer:readVoir les clients
GET /customers
GET /customers/deleted
GET /customers/{id}
notification:sendEnvoyer des messages aux clients
POST /notifications/push
analytics:readConsulter les chiffres
GET /analytics
setup:readConsulter cartes, sites et équipe
GET /cards
GET /locations
GET /employees

Idempotence

  • Tous les endpoints POST acceptent l’en-tête Idempotency-Key. Il vaut par clé API, est lié à la méthode, au chemin et au contenu et compte au plus 255 caractères ASCII visibles, par exemple le numéro de ticket.
  • Une répétition identique renvoie la même réponse ; pour le lien d’inscription, un nouveau lien. Un autre contenu avec la même clé donne 409 IDEMPOTENCY_KEY_REUSED. Si la première requête est encore en cours, vous recevez 503 REQUEST_IN_PROGRESS.
  • Seule une réponse réussie est conservée, pendant 7 jours. Au-delà de ces 7 jours, seuls l’ajout de tampons et l’utilisation de récompenses restent protégés : la même carte avec la même clé n’est pas enregistrée deux fois, une autre carte donne 409 IDEMPOTENCY_KEY_REUSED.

Cas particulier : carte d’avantages. Sur une carte d’avantages, l’appel enregistre une visite. Comme l’utilisation d’une offre, il n’est protégé que 7 jours par le Idempotency-Key. Si la première requête s’interrompt en cours de route, elle n’est jamais réexécutée (d’abord 503 REQUEST_IN_PROGRESS, puis 409 REQUEST_ABANDONED). Vérifiez l’état avec GET /passes/{id} et, si nécessaire, enregistrez à nouveau avec un nouveau Idempotency-Key.

Identifiants

Les identifiants dans les chemins comptent au plus 64 caractères ; au-delà, vous recevez 400.

Limites de débit

  • 300 requêtes par minute et par clé, tous endpoints confondus. En-têtes : X-RateLimit-Limit-api, X-RateLimit-Remaining-api, X-RateLimit-Reset-api.
  • Recherche d’e-mail (GET /customers) : en plus, 60 par minute et par clé et 120 par minute et par établissement. En-têtes : X-RateLimit-Limit-customerLookup, X-RateLimit-Remaining-customerLookup.
  • Au-delà, vous recevez 429 RATE_LIMITED avec l’en-tête standard Retry-After (secondes) ainsi que Retry-After-api ou Retry-After-customerLookup.
  • De nombreuses clés incorrectes depuis une adresse entraînent un blocage temporaire de cette adresse, également 429 avec Retry-After.

Pas de mode test

Il n’y a ni environnement de test ni clé de test. Chaque clé enregistre pour de vrai : les opérations apparaissent dans les analyses et le journal d’activité, et les récompenses utilisées aussi dans le justificatif fiscal.

  • Testez avec une carte de test à part et une clé à part ayant peu de scopes, puis révoquez-la.
  • N’utilisez pas POST /notifications/push pour tester ; les messages arrivent chez de vrais clients.
  • Les webhooks se testent sans risque, voir Tester les webhooks.

Versions

La version figure dans le chemin (/api/v1). De nouveaux champs de réponse et de nouveaux événements peuvent apparaître à tout moment, ignorez donc les champs inconnus. Les changements incompatibles n’arrivent qu’avec une nouvelle version et un préavis.

Webhooks

Création

Le propriétaire crée le webhook dans Intégrations : une adresse HTTPS accessible publiquement et les événements choisis. Le secret de webhook n’est affiché qu’une fois. Ce n’est pas la clé API : la clé ouvre l’accès à tapja, le secret sert seulement à vérifier les messages qui vous arrivent.

Événements

ÉvénementLibelléChamps de data
pass.createdCarte émisepassId cardId customerId employeeId locationId channel
pass.stampedTampon ajoutépassId cardId stampCount pointsBalance employeeId locationId channel
pass.redeemedRécompense utiliséepassId rewardId (facultatif) locationId (facultatif)
pass.cancelledCarte annuléepassId cardId
pass.reactivatedCarte de nouveau activepassId customerId
pass.correctedEnregistrement corrigépassId field value employeeId (facultatif) locationId (facultatif)
reward.readyRécompense disponiblepassId cardId rewardIds
offer.redeemedOffre utiliséepassId offerId locationId (facultatif)
package.usedUnité de forfait utiliséepassId quantity units employeeId locationId (facultatif)
customer.createdClient ajoutécustomerId
customer.deletedClient supprimécustomerId passIds
customer.consent_changedConsentement marketing modifiécustomerId marketingConsent
campaign.sentMessage envoyécampaignId recipients

Il existe aussi l’événement de test ping avec le champ message, auquel on ne peut pas s’abonner. Toutes les descriptions se trouvent dans la référence.

Enveloppe et en-têtes

Chaque message comporte les champs id, event, data et timestamp. X-tapja-Delivery correspond à l’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

Vérifier la signature

HMAC-SHA256 avec le secret de webhook sur ${X-tapja-Timestamp}.${corps brut}, tolérance de 300 secondes, comparaison à temps constant. Ce qui compte est le corps brut, avant toute analyse JSON.

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)

Livraison

  • Répondez vite avec un 2xx et faites le travail de façon asynchrone. Après 10 secondes, la tentative est considérée comme échouée.
  • Sans 2xx, jusqu’à 5 nouvelles tentatives suivent après environ 1, 2, 4, 8 et 16 minutes, soit une demi-heure environ au total.
  • L’id reste identique d’une tentative à l’autre. Dédupliquez avec lui.
  • Après 30 échecs consécutifs, le webhook se met en pause et le propriétaire le réactive. Les événements de la pause ne sont pas livrés ensuite.

Ordre

L’ordre n’est pas garanti. pass.created peut arriver avant customer.created, reward.ready avant pass.stamped. Ordonnez les états avec timestamp ou GET /passes/{id}.

customer.deleted est une marque de suppression définitive : ignorez les événements arrivant ensuite pour ce client et ne le recréez pas.

Les webhooks ne sont pas un journal sans lacune. Rapprochez les états critiques avec GET si nécessaire.

Renouveler le secret

Le nouveau secret de webhook s’applique immédiatement, sans période de transition. Renouvelez-le à un moment calme et enregistrez aussitôt le nouveau secret.

Tester les webhooks

  • « Envoyer un test » envoie ping, « Envoyer un événement d’exemple » un exemple d’un type abonné.
  • Les tests portent le champ "test": true et l’en-tête X-tapja-Test: 1. Les vrais événements ne portent ni l’un ni l’autre. Tous les identifiants sont inventés et commencent par test_.
  • Les tests ne sont pas répétés, arrivent aussi aux webhooks en pause et ne comptent jamais pour la pause. Au plus 20 tests par heure et par webhook.
  • Reconnaissez les tests au champ test et ne les comptabilisez pas.

Suppressions et protection des données

  • customer.deleted indique les identifiants du client et de ses cartes.
  • Récupérez les suppressions manquées avec GET /customers/deleted?since=… : les 30 derniers jours, identifiants seulement, par curseur. Idéalement, rapprochez chaque jour et supprimez aussi dans votre propre système.
  • Si l’établissement entier est supprimé, aucun customer.deleted n’est envoyé par client.
  • Les webhooks ne contiennent que des identifiants et des compteurs, ni noms ni adresses.
  • Seuls GET /customers/{id} et la recherche d’e-mail GET /customers renvoient l’adresse e-mail d’un client. Chaque consultation est journalisée.
  • La publicité depuis votre propre système ne s’adresse qu’aux clients avec marketingConsent: true et emailVerifiedAt renseigné.
  • GET /employees renvoie les noms et rôles de l’équipe. Ne donnez setup:read qu’aux systèmes qui en ont besoin.
bash
curl "https://api.tapja.de/api/v1/public/customers/deleted?since=2026-11-01T00:00:00.000Z" \
  -H "Authorization: Bearer sk_live_…"

Responsabilité des données

L’établissement est responsable des données de son propre système. Selon son installation, il lui faut un contrat de sous-traitance avec le fournisseur de ce système, et il mentionne ce système dans sa politique de confidentialité.

Contact

Les questions d’intégration et les signalements de sécurité vont à hallo@tapja.de. Indiquez l’endpoint, l’heure (UTC) et le code d’erreur. N’envoyez jamais la clé API ni le secret de webhook.