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

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 /passes devuelve 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_REQUIRED o MEMBERSHIP_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:write y setup:read. Sin setup:read, tu sistema no conoce ni employeeId ni locationId.
  • Vinculación a ubicaciones (opcional): la clave solo registra en esas ubicaciones. Los scopes customer:read, pass:cancel y notification:send no 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

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

3. 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.

http
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.

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

5. Primer registro: sellar

Un registro siempre indica un empleado y una ubicación. GET /employees y GET /locations devuelven sus identificadores.

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

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.

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" }'
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"
}

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 } }.

json
{ "data": { "…": "…" }, "timestamp": "2026-11-07T10:00:00.000Z" }
json
{ "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ódigoEstadoEndpoints
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
UNAUTHORIZED401todos los 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_SUSPENDED403todos los 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_REQUIRED403todos los 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_MISSING403todos los 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_LIMITED429todos los endpoints
INTERNAL_ERROR500todos los endpoints
REQUEST_IN_PROGRESS503todos los 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

Atribución

  • Cada registro indica employeeId (un empleado activo del negocio, asignado a la ubicación) y locationId.
  • 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 MANAGER u OWNER y una clave cuyo rol de actor sea al menos MANAGER.

Scopes

Se deniega por defecto: una clave solo puede hacer lo que permiten sus scopes. Si falta uno, llega 403 SCOPE_MISSING.

ScopeLo que ve el propietarioEndpoints
pass:writeEmitir tarjetas y sellar
POST /passes
POST /passes/{id}/stamp
pass:readVer tarjetas
GET /passes/by-serial/{serial}
GET /passes/{id}
pass:redeemCanjear premios
POST /passes/{id}/redeem
offer:readVer ofertas
GET /passes/{id}/offers
offer:redeemCanjear ofertas
POST /passes/{id}/redeem-offer
pass:cancelAnular tarjetas
POST /passes/{id}/cancel
customer:readVer clientes
GET /customers
GET /customers/deleted
GET /customers/{id}
notification:sendEnviar mensajes a clientes
POST /notifications/push
analytics:readConsultar cifras
GET /analytics
setup:readConsultar tarjetas, ubicaciones y equipo
GET /cards
GET /locations
GET /employees

Idempotencia

  • Todos los endpoints POST aceptan la cabecera Idempotency-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, llega 503 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_LIMITED con la cabecera estándar Retry-After (segundos) y Retry-After-api o Retry-After-customerLookup.
  • Muchas claves incorrectas desde una dirección provocan un bloqueo temporal de esa dirección, también 429 con Retry-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/push para 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

EventoNombreCampos en data
pass.createdTarjeta emitidapassId cardId customerId employeeId locationId channel
pass.stampedSello añadidopassId cardId stampCount pointsBalance employeeId locationId channel
pass.redeemedPremio canjeadopassId rewardId (opcional) locationId (opcional)
pass.cancelledTarjeta anuladapassId cardId
pass.reactivatedTarjeta activa de nuevopassId customerId
pass.correctedRegistro corregidopassId field value employeeId (opcional) locationId (opcional)
reward.readyPremio disponiblepassId cardId rewardIds
offer.redeemedOferta canjeadapassId offerId locationId (opcional)
package.usedUnidad del paquete usadapassId quantity units employeeId locationId (opcional)
customer.createdCliente añadidocustomerId
customer.deletedCliente eliminadocustomerId passIds
customer.consent_changedConsentimiento publicitario cambiadocustomerId marketingConsent
campaign.sentMensaje enviadocampaignId 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.

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

Comprobar 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.

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)

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 id no 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": true y la cabecera X-tapja-Test: 1. Los eventos reales no llevan ninguno de los dos. Todos los identificadores son inventados y empiezan por test_.
  • 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 test y no las registres.

Eliminaciones y privacidad

  • customer.deleted indica 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.deleted por 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 correo GET /customers. Cada consulta queda registrada.
  • La publicidad desde tu propio sistema solo va a clientes con marketingConsent: true y emailVerifiedAt informado.
  • GET /employees devuelve los nombres y roles del equipo. Da setup:read solo a los sistemas que lo necesiten.
bash
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.