Para desarrolladores
Conecta tapja con tu caja, tienda y CRM
API REST y webhooks para quienes desarrollan cajas, tiendas y CRM y conectan un negocio con el plan Cadena favorita.
Ir a la referencia de la API OpenAPI
Resumen
Con la interfaz, el sistema de un negocio habla directamente con tapja. La caja escanea el código de barras de la tarjeta, encuentra al cliente, añade sellos y canjea premios. Con los webhooks, tapja avisa en cuanto pasa algo.
Qué se puede hacer
- Encontrar una tarjeta por el número de serie de su código QR o de barras:
GET /passes/by-serial/{serial} - Leer el estado de una tarjeta y los datos mínimos del cliente:
GET /passes/{id},GET /customers/{id},GET /customers - Añadir sellos o puntos:
POST /passes/{id}/stamp - Canjear premios y ofertas, anular tarjetas:
POST /passes/{id}/redeem,POST /passes/{id}/redeem-offer,POST /passes/{id}/cancel - Obtener un enlace de registro para clientes nuevos:
POST /passes - Leer programas de tarjetas, ubicaciones, empleados y cifras:
GET /cards,GET /locations,GET /employees,GET /analytics - Enviar una notificación de tarjeta a clientes con consentimiento publicitario:
POST /notifications/push - Conciliar clientes eliminados:
GET /customers/deleted - Recibir webhooks de 13 eventos, como «Tarjeta emitida», «Sello añadido», «Premio disponible» y «Cliente eliminado»
Qué no se puede hacer, a propósito
- Emitir tarjetas sin el consentimiento del cliente.
POST /passesdevuelve un enlace de registro; la tarjeta la crea el propio cliente. - Crear clientes sin que se registren por ese enlace.
- Exportar clientes de forma masiva. Cada cliente se consulta por su identificador o por búsqueda de correo.
- Registrar tarjetas de paquete y de socio. La interfaz lo rechaza con
PACKAGE_USE_REQUIREDoMEMBERSHIP_ACTION_REQUIRED.
Requisitos
El negocio tiene el plan Cadena favorita. La clave de API la crea el propietario del negocio. No existe una conexión lista para usar con un sistema de caja concreto; la interfaz es el camino para construirla.
Inicio rápido en 5 pasos
1. Pide que creen una clave de API
El propietario crea la clave en la web en Gestión › Integraciones, en la app en Más › Configuración y gestión › Integraciones. tapja vuelve a pedirle la contraseña y todos los propietarios del negocio reciben un correo de seguridad. La clave se muestra una sola vez.
- Scopes: solo los que necesite tu sistema (consulta Scopes). Vienen marcados
pass:read,pass:writeysetup:read. Sinsetup:read, tu sistema no conoce niemployeeIdnilocationId. - Vinculación a ubicaciones (opcional): la clave solo registra en esas ubicaciones. Los scopes
customer:read,pass:cancelynotification:sendno son posibles en esas claves. - Rol máximo de actor («Puede actuar como» en la interfaz): tu sistema puede indicar empleados hasta ese rol. Por defecto es «Empleado».
2. URL base
https://api.tapja.de/api/v1/public3. Autenticación
Cada petición lleva la clave como token Bearer. La clave va solo en el servidor o en la caja, nunca en el navegador, en una app o en los registros.
Authorization: Bearer sk_live_…4. Primera llamada: leer una tarjeta
Lee la tarjeta por el número de serie de su código de barras.
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. Primer registro: sellar
Un registro siempre indica un empleado y una ubicación. GET /employees y GET /locations devuelven sus identificadores.
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_…"El Idempotency-Key es nuevo en cada operación, por ejemplo el número de ticket. El identificador de la tarjeta es el campo id del paso 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"
}Cada clave registra de verdad. Antes de la primera prueba, lee Sin modo de prueba.
Reglas básicas
Respuestas y errores
Las respuestas correctas llegan en { data, timestamp }, los errores en { error: { code, message } }.
{ "data": { "…": "…" }, "timestamp": "2026-11-07T10:00:00.000Z" }{ "error": { "code": "COOLDOWN_ACTIVE", "message": "Bereits kürzlich gestempelt." } }Bifurca solo por code, nunca por message. El texto es para personas, suele estar en alemán y puede cambiar. La interfaz rechaza con 400 los campos desconocidos del cuerpo de la petición.
Códigos de error (72)
| Código | Estado | 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 | todos los 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 | todos los 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 | todos los 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 | todos los 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 | todos los endpoints |
INTERNAL_ERROR | 500 | todos los endpoints |
REQUEST_IN_PROGRESS | 503 | todos los 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 |
Atribución
- Cada registro indica
employeeId(un empleado activo del negocio, asignado a la ubicación) ylocationId. - Tu sistema también puede enviar
employeeRef, la referencia del cajero. Usa números de caja o de personal, no nombres reales. - Si tu sistema indica un empleado con un rol superior al que permite la clave, la interfaz responde
403 ACTOR_ROLE_NOT_ALLOWED. - Anular necesita un empleado con rol
MANAGERuOWNERy una clave cuyo rol de actor sea al menosMANAGER.
Scopes
Se deniega por defecto: una clave solo puede hacer lo que permiten sus scopes. Si falta uno, llega 403 SCOPE_MISSING.
| Scope | Lo que ve el propietario | Endpoints |
|---|---|---|
pass:write | Emitir tarjetas y sellar | POST /passesPOST /passes/{id}/stamp |
pass:read | Ver tarjetas | GET /passes/by-serial/{serial}GET /passes/{id} |
pass:redeem | Canjear premios | POST /passes/{id}/redeem |
offer:read | Ver ofertas | GET /passes/{id}/offers |
offer:redeem | Canjear ofertas | POST /passes/{id}/redeem-offer |
pass:cancel | Anular tarjetas | POST /passes/{id}/cancel |
customer:read | Ver clientes | GET /customersGET /customers/deletedGET /customers/{id} |
notification:send | Enviar mensajes a clientes | POST /notifications/push |
analytics:read | Consultar cifras | GET /analytics |
setup:read | Consultar tarjetas, ubicaciones y equipo | GET /cardsGET /locationsGET /employees |
Idempotencia
- Todos los endpoints
POSTaceptan la cabeceraIdempotency-Key. Vale por clave de API, está ligada a método, ruta y contenido y tiene como máximo 255 caracteres ASCII visibles, por ejemplo el número de ticket. - La misma repetición devuelve la misma respuesta; en el enlace de registro, un enlace nuevo. Otro contenido con la misma clave da
409 IDEMPOTENCY_KEY_REUSED. Si la primera petición sigue en curso, llega503 REQUEST_IN_PROGRESS. - Solo se guarda una respuesta correcta, durante 7 días. Más allá de esos 7 días solo quedan protegidos sellar y canjear premios: la misma tarjeta con la misma clave no se registra dos veces, y otra tarjeta da
409 IDEMPOTENCY_KEY_REUSED.
Caso especial: tarjeta de ventajas. En una tarjeta de ventajas, la llamada registra una visita. Igual que canjear una oferta, solo está protegida 7 días por el Idempotency-Key. Si la primera petición se interrumpe a medias, nunca se vuelve a ejecutar (primero 503 REQUEST_IN_PROGRESS, luego 409 REQUEST_ABANDONED). Comprueba el estado con GET /passes/{id} y, si hace falta, registra de nuevo con un Idempotency-Key nuevo.
Identificadores
Los identificadores en las rutas tienen como máximo 64 caracteres; los más largos dan 400.
Límites de peticiones
- 300 peticiones por minuto y clave en todos los endpoints. Cabeceras:
X-RateLimit-Limit-api,X-RateLimit-Remaining-api,X-RateLimit-Reset-api. - La búsqueda por correo (
GET /customers) tiene además 60 por minuto y clave y 120 por minuto y negocio. Cabeceras:X-RateLimit-Limit-customerLookup,X-RateLimit-Remaining-customerLookup. - Por encima llega
429 RATE_LIMITEDcon la cabecera estándarRetry-After(segundos) yRetry-After-apioRetry-After-customerLookup. - Muchas claves incorrectas desde una dirección provocan un bloqueo temporal de esa dirección, también
429conRetry-After.
Sin modo de prueba
No hay entorno de pruebas ni claves de prueba. Cada clave registra de verdad: los registros aparecen en los análisis y en el registro de actividad, y los premios canjeados también en el justificante fiscal.
- Prueba con una tarjeta de prueba propia y una clave propia con pocos scopes, y revócala después.
- No uses
POST /notifications/pushpara hacer pruebas; los mensajes llegan a clientes reales. - Los webhooks se pueden probar sin riesgo, consulta Probar webhooks.
Versiones
La versión está en la ruta (/api/v1). En cualquier momento pueden aparecer campos nuevos en las respuestas y eventos nuevos, así que ignora los campos desconocidos. Los cambios incompatibles solo llegan con una versión nueva y con antelación.
Webhooks
Crear un webhook
El propietario crea el webhook en Integraciones: una dirección HTTPS accesible públicamente y los eventos elegidos. El secreto del webhook se muestra una vez. No es la clave de API: la clave da acceso a tapja, el secreto solo comprueba los mensajes que te llegan.
Eventos
| Evento | Nombre | Campos en data |
|---|---|---|
pass.created | Tarjeta emitida | passId cardId customerId employeeId locationId channel |
pass.stamped | Sello añadido | passId cardId stampCount pointsBalance employeeId locationId channel |
pass.redeemed | Premio canjeado | passId rewardId (opcional) locationId (opcional) |
pass.cancelled | Tarjeta anulada | passId cardId |
pass.reactivated | Tarjeta activa de nuevo | passId customerId |
pass.corrected | Registro corregido | passId field value employeeId (opcional) locationId (opcional) |
reward.ready | Premio disponible | passId cardId rewardIds |
offer.redeemed | Oferta canjeada | passId offerId locationId (opcional) |
package.used | Unidad del paquete usada | passId quantity units employeeId locationId (opcional) |
customer.created | Cliente añadido | customerId |
customer.deleted | Cliente eliminado | customerId passIds |
customer.consent_changed | Consentimiento publicitario cambiado | customerId marketingConsent |
campaign.sent | Mensaje enviado | campaignId recipients |
Además existe el evento de prueba ping con el campo message, al que no es posible suscribirse. Todas las descripciones están en la referencia.
Envoltorio y cabeceras
Cada mensaje tiene los campos id, event, data y timestamp. X-tapja-Delivery coincide con el 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/2Comprobar la firma
HMAC-SHA256 con el secreto del webhook sobre ${X-tapja-Timestamp}.${cuerpo sin procesar}, tolerancia de 300 segundos, comparación en tiempo constante. Lo que cuenta es el cuerpo sin procesar, antes de interpretar el 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)Entrega
- Responde rápido con un 2xx y haz el trabajo de forma asíncrona. A los 10 segundos, el intento se considera fallido.
- Si no llega un 2xx, siguen hasta 5 reintentos tras aproximadamente 1, 2, 4, 8 y 16 minutos, en total alrededor de media hora.
- El
idno cambia entre reintentos. Elimina duplicados con él. - Tras 30 intentos fallidos seguidos, el webhook se pausa y el propietario lo reactiva. Los eventos de la pausa no se entregan después.
Orden
El orden no está garantizado. pass.created puede llegar antes que customer.created, reward.ready antes que pass.stamped. Ordena los estados por timestamp o con GET /passes/{id}.
customer.deleted es una marca de borrado definitiva: descarta los eventos posteriores sobre ese cliente y no lo vuelvas a crear.
Los webhooks no son un registro sin huecos. Concilia con GET los estados críticos cuando haga falta.
Renovar el secreto
El nuevo secreto del webhook vale al instante, sin periodo de transición. Renuévalo en un momento tranquilo e introduce el secreto nuevo enseguida.
Probar webhooks
- «Enviar prueba» envía
ping, «Enviar evento de ejemplo» una muestra de un tipo suscrito. - Las pruebas llevan el campo
"test": truey la cabeceraX-tapja-Test: 1. Los eventos reales no llevan ninguno de los dos. Todos los identificadores son inventados y empiezan portest_. - Las pruebas no se repiten, llegan también a webhooks en pausa y nunca cuentan para la pausa. Como máximo 20 pruebas por hora y webhook.
- Reconoce las pruebas por el campo
testy no las registres.
Eliminaciones y privacidad
customer.deletedindica los identificadores del cliente y de sus tarjetas.- Las eliminaciones perdidas se obtienen con
GET /customers/deleted?since=…: los últimos 30 días, solo identificadores, por cursor. Lo mejor es conciliar a diario y eliminar también en tu propio sistema. - Si se elimina el negocio entero, no llega un
customer.deletedpor cliente. - Los webhooks solo contienen identificadores y contadores, ni nombres ni direcciones.
- El correo de un cliente solo lo devuelven
GET /customers/{id}y la búsqueda por correoGET /customers. Cada consulta queda registrada. - La publicidad desde tu propio sistema solo va a clientes con
marketingConsent: trueyemailVerifiedAtinformado. GET /employeesdevuelve los nombres y roles del equipo. Dasetup:readsolo a los sistemas que lo necesiten.
curl "https://api.tapja.de/api/v1/public/customers/deleted?since=2026-11-01T00:00:00.000Z" \
-H "Authorization: Bearer sk_live_…"Responsabilidad sobre los datos
El negocio es responsable de los datos de su propio sistema. Según cómo esté montado, necesita un contrato de encargo del tratamiento con el proveedor de ese sistema y lo menciona en su aviso de privacidad.
Contacto
Las preguntas sobre la integración y los hallazgos de seguridad van a hallo@tapja.de. Indica el endpoint, la hora (UTC) y el código de error. Nunca envíes la clave de API ni el secreto del webhook.