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 /passesrenvoie 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_REQUIREDouMEMBERSHIP_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:writeetsetup:readsont présélectionnés. Sanssetup:read, votre système ne connaît niemployeeIdnilocationId. - Limitation à certains sites (facultatif) : la clé n’enregistre alors que sur ces sites. Les scopes
customer:read,pass:canceletnotification:sendsont 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
https://api.tapja.de/api/v1/public3. 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.
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.
curl https://api.tapja.de/api/v1/public/passes/by-serial/SN8F3K2 \
-H "Authorization: Bearer sk_live_…"{
"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.
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.
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" }'{
"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 } }.
{ "data": { "…": "…" }, "timestamp": "2026-11-07T10:00:00.000Z" }{ "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)
| Code | Statut | Endpoints |
|---|---|---|
AMOUNT_BELOW_MINIMUM | 400 | POST /passes/{id}/stamp |
AMOUNT_REQUIRED | 400 | POST /passes/{id}/stamp |
AMOUNT_TOO_SMALL | 400 | POST /passes/{id}/stamp |
BAD_REQUEST | 400 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancelGET /customersGET /customers/deletedPOST /notifications/push |
CARD_HAS_NO_BALANCE | 400 | POST /passes/{id}/stamp |
COUPON_NOT_COMBINABLE | 400 | POST /passes/{id}/redeem-offer |
IDEMPOTENCY_KEY_INVALID | 400 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancelPOST /notifications/push |
LOCATION_WRONG_COMPANY | 400 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
MEMBERSHIP_ACTION_REQUIRED | 400 | POST /passes/{id}/stampPOST /passes/{id}/redeem |
OFFERS_NOT_ON_CARD | 400 | POST /passes/{id}/redeem-offer |
PACKAGE_USE_REQUIRED | 400 | POST /passes/{id}/stampPOST /passes/{id}/redeem |
PLACEHOLDER_UNKNOWN | 400 | POST /notifications/push |
POINTS_BALANCE_LIMIT | 400 | POST /passes/{id}/stamp |
POINTS_REQUIRED | 400 | POST /passes/{id}/stamp |
QUIET_HOURS | 400 | POST /notifications/push |
REWARD_AUTO_ISSUED | 400 | POST /passes/{id}/redeem |
STAMP_CAP_EXCEEDED | 400 | POST /passes/{id}/stamp |
STAMP_MODE_AMOUNT | 400 | POST /passes/{id}/stamp |
STAMP_MODE_VISIT | 400 | POST /passes/{id}/stamp |
UNAUTHORIZED | 401 | tous les endpoints |
ACTOR_ROLE_NOT_ALLOWED | 403 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
CARD_FULL | 403 | POST /passes/{id}/stamp |
COMPANY_SUSPENDED | 403 | tous les endpoints |
COOLDOWN_ACTIVE | 403 | POST /passes/{id}/stamp |
EMPLOYEE_NOT_AT_LOCATION | 403 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
GUEST_EMAIL_UNVERIFIED | 403 | POST /passes/{id}/redeemPOST /passes/{id}/redeem-offer |
LOCATION_NOT_ALLOWED | 403 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancelPOST /notifications/push |
NOT_ENOUGH_POINTS | 403 | POST /passes/{id}/redeem |
OFFER_COOLDOWN | 403 | POST /passes/{id}/redeem-offer |
OFFER_EXHAUSTED | 403 | POST /passes/{id}/redeem-offer |
OFFER_EXPIRED | 403 | POST /passes/{id}/redeem-offer |
OFFER_NOT_ELIGIBLE | 403 | POST /passes/{id}/redeem-offer |
OFFER_NOT_STARTED | 403 | POST /passes/{id}/redeem-offer |
OFFER_WRONG_LOCATION | 403 | POST /passes/{id}/redeem-offer |
PIN_REQUIRED | 403 | POST /passes/{id}/redeemPOST /passes/{id}/redeem-offer |
PLAN_FEATURE_REQUIRED | 403 | tous les endpoints |
REDEEM_NOT_AT_LOCATION | 403 | POST /passes/{id}/redeem |
REWARD_ALREADY_REDEEMED | 403 | POST /passes/{id}/redeem |
REWARD_EXPIRED | 403 | POST /passes/{id}/redeem |
REWARD_LIMIT_REACHED | 403 | POST /passes/{id}/redeem |
REWARD_MEMBERSHIP_REQUIRED | 403 | POST /passes/{id}/redeem |
REWARD_MIN_PURCHASE | 403 | POST /passes/{id}/redeem |
REWARD_NOT_COMBINABLE | 403 | POST /passes/{id}/redeem |
REWARD_NOT_YET_VALID | 403 | POST /passes/{id}/redeem |
REWARD_QUOTA_EXHAUSTED | 403 | POST /passes/{id}/redeem |
REWARD_THRESHOLD_NOT_REACHED | 403 | POST /passes/{id}/redeem |
REWARD_TIER_REQUIRED | 403 | POST /passes/{id}/redeem |
REWARD_WRONG_LOCATION | 403 | POST /passes/{id}/redeem |
ROLE_NOT_ALLOWED | 403 | POST /passes/{id}/cancel |
SCOPE_MISSING | 403 | tous les endpoints |
STAMP_LIMIT_REACHED | 403 | POST /passes/{id}/stamp |
CARD_NOT_FOUND | 404 | POST /passesPOST /notifications/push |
CUSTOMER_NOT_FOUND | 404 | GET /customersGET /customers/{id} |
EMPLOYEE_NOT_FOUND | 404 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
NOT_FOUND | 404 | GET /passes/{id}/offersPOST /passes/{id}/redeem-offer |
OFFER_NOT_FOUND | 404 | POST /passes/{id}/redeem-offer |
PASS_NOT_FOUND | 404 | GET /passes/by-serial/{serial}GET /passes/{id}POST /passes/{id}/stampPOST /passes/{id}/redeemGET /passes/{id}/offersPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
REWARD_NOT_FOUND | 404 | POST /passes/{id}/redeem |
CARD_ARCHIVED | 409 | POST /passesPOST /passes/{id}/redeem-offer |
CARD_NOT_AT_LOCATION | 409 | POST /passes |
IDEMPOTENCY_KEY_REUSED | 409 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancelPOST /notifications/push |
LOCATION_DEACTIVATED | 409 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
OFFER_ALREADY_REDEEMED | 409 | POST /passes/{id}/redeem-offer |
OFFER_USED_UP | 409 | POST /passes/{id}/redeem-offer |
PASS_VOIDED | 409 | POST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
REQUEST_ABANDONED | 409 | POST /passes/{id}/stampPOST /passes/{id}/redeem-offerPOST /notifications/push |
UNPROCESSABLE | 422 | POST /notifications/push |
RATE_LIMITED | 429 | tous les endpoints |
INTERNAL_ERROR | 500 | tous les endpoints |
REQUEST_IN_PROGRESS | 503 | tous les endpoints |
RETRY | 503 | POST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/cancel |
SERVICE_UNAVAILABLE | 503 | GET /passes/by-serial/{serial}GET /passes/{id}GET /passes/{id}/offersGET /customersGET /customers/deletedGET /customers/{id}GET /analyticsGET /cardsGET /locationsGET /employees |
Attribution
- Chaque opération indique
employeeId(un employé actif de l’établissement, rattaché au site) etlocationId. - 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
MANAGERouOWNERet une clé dont le rôle d’acteur est au moinsMANAGER.
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.
| Scope | Libellé vu par le propriétaire | Endpoints |
|---|---|---|
pass:write | Émettre des cartes et tamponner | POST /passesPOST /passes/{id}/stamp |
pass:read | Voir les cartes | GET /passes/by-serial/{serial}GET /passes/{id} |
pass:redeem | Utiliser des récompenses | POST /passes/{id}/redeem |
offer:read | Voir les offres | GET /passes/{id}/offers |
offer:redeem | Utiliser des offres | POST /passes/{id}/redeem-offer |
pass:cancel | Annuler des cartes | POST /passes/{id}/cancel |
customer:read | Voir les clients | GET /customersGET /customers/deletedGET /customers/{id} |
notification:send | Envoyer des messages aux clients | POST /notifications/push |
analytics:read | Consulter les chiffres | GET /analytics |
setup:read | Consulter cartes, sites et équipe | GET /cardsGET /locationsGET /employees |
Idempotence
- Tous les endpoints
POSTacceptent l’en-têteIdempotency-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 recevez503 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_LIMITEDavec l’en-tête standardRetry-After(secondes) ainsi queRetry-After-apiouRetry-After-customerLookup. - De nombreuses clés incorrectes depuis une adresse entraînent un blocage temporaire de cette adresse, également
429avecRetry-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/pushpour 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énement | Libellé | Champs de data |
|---|---|---|
pass.created | Carte émise | passId cardId customerId employeeId locationId channel |
pass.stamped | Tampon ajouté | passId cardId stampCount pointsBalance employeeId locationId channel |
pass.redeemed | Récompense utilisée | passId rewardId (facultatif) locationId (facultatif) |
pass.cancelled | Carte annulée | passId cardId |
pass.reactivated | Carte de nouveau active | passId customerId |
pass.corrected | Enregistrement corrigé | passId field value employeeId (facultatif) locationId (facultatif) |
reward.ready | Récompense disponible | passId cardId rewardIds |
offer.redeemed | Offre utilisée | passId offerId locationId (facultatif) |
package.used | Unité de forfait utilisée | passId quantity units employeeId locationId (facultatif) |
customer.created | Client ajouté | customerId |
customer.deleted | Client supprimé | customerId passIds |
customer.consent_changed | Consentement marketing modifié | customerId marketingConsent |
campaign.sent | Message 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.
{
"id": "evt_3f2a…",
"event": "pass.redeemed",
"data": { "passId": "pass_123", "rewardId": "rw_1" },
"timestamp": "2026-11-07T10:00:00.000Z"
}X-tapja-Event: pass.redeemed
X-tapja-Delivery: evt_3f2a…
X-tapja-Timestamp: 1794045600
X-tapja-Signature: sha256=<hex>
User-Agent: tapja-webhooks/2Vé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.
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));
}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’
idreste 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": trueet l’en-têteX-tapja-Test: 1. Les vrais événements ne portent ni l’un ni l’autre. Tous les identifiants sont inventés et commencent partest_. - 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
testet ne les comptabilisez pas.
Suppressions et protection des données
customer.deletedindique 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.deletedn’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-mailGET /customersrenvoient 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: trueetemailVerifiedAtrenseigné. GET /employeesrenvoie les noms et rôles de l’équipe. Ne donnezsetup:readqu’aux systèmes qui en ont besoin.
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.