API Notificaciones Apple Wallet — Integración Google Wallet para Negocios

1

1. Autenticación

Todas las peticiones a la API deben incluir tu API Key en la cabecera de la petición.

Incluye esta cabecera en todas las peticiones a la API.

Cabecera

X-API-Key: your_api_key_here

Mantén tu API Key segura. No la expongas en código de frontend ni en repositorios públicos.

Inicia sesión en el panel de Elune y ve a Configuración → API. Allí encontrarás tu clave y podrás regenerarla si es necesario.

2

2. Registro de empresa

Registra una nueva empresa en el sistema. Este es el primer paso para comenzar a usar la API.

POST /register

Crea una nueva cuenta de empresa con los datos proporcionados.

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre de la empresa
`email`	string	Sí	Correo electrónico de contacto
`phone`	string	No	Teléfono de contacto
`address`	string	No	Dirección física

Ejemplo de petición

{
  "name": "Mi Empresa SL",
  "email": "info@miempresa.com",
  "phone": "+34 600 000 000"
}

Ejemplo de respuesta

{
  "id": "emp_a1b2c3d4",
  "api_key": "ek_live_xxxxxxxxxxxxxxxxxxxx",
  "created_at": "2025-01-15T10:30:00Z"
}

Guarda la API key devuelta — se muestra una sola vez y no puede recuperarse.

3

3. Configuración

Actualiza los ajustes visuales de tu empresa y los valores por defecto de las notificaciones.

PUT /company/config

Actualiza la configuración de la empresa. Se aceptan actualizaciones parciales.

Campo	Tipo	Obligatorio	Descripción
`color`	string	No	Color primario de marca (hex)
`textColor`	string	No	Color del texto (hex)
`notificationTitle`	string	No	Título de notificación por defecto
`pointsName`	string	No	Nombre personalizado para los puntos
`rewardsEnabled`	boolean	No	Activar/desactivar catálogo de recompensas

Los colores de marca se aplican a todas las tarjetas emitidas por tu empresa salvo que se sobreescriban a nivel de modelo.

4

4. Modelos de tarjeta

Los modelos de tarjeta definen la plantilla visual para un conjunto de tarjetas emitidas.

POST /refs

Crea un nuevo modelo de tarjeta con la configuración indicada.

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre del modelo
`description`	string	No	Descripción corta (visible en la tarjeta)
`color`	string	No	Color primario alternativo (hex)
`textColor`	string	No	Color del texto alternativo (hex)
`pointsEnabled`	boolean	No	Activar puntos de fidelidad para este modelo
`rewardsEnabled`	boolean	No	Activar catálogo de recompensas para este modelo

GET /refs

Devuelve todos los modelos de tarjeta de tu empresa.

PUT /refs/:refId

Actualiza un modelo de tarjeta específico. Se aceptan actualizaciones parciales.

DELETE /refs/:refId

Elimina un modelo de tarjeta. Las tarjetas ya emitidas no se ven afectadas.

5

5. Tarjetas emitidas

Las tarjetas emitidas son los passos digitales reales que los usuarios finales añaden a Apple Wallet o Google Wallet.

POST /cards

Crea una nueva tarjeta para un usuario final. Devuelve la URL del pase para compartir o incrustar en un QR.

Campo	Tipo	Obligatorio	Descripción
`refId`	string	Sí	ID del modelo de tarjeta
`userName`	string	Sí	Nombre completo del usuario
`userEmail`	string	No	Correo electrónico del usuario
`userPhone`	string	No	Teléfono del usuario
`customFields`	object	No	Objeto clave-valor con campos extra

Ejemplo de respuesta

{
  "cardId": "card_x9y8z7w6",
  "passUrl": "https://wallet.eluneconnections.com/pass/card_x9y8z7w6",
  "qrCode": "data:image/png;base64,..."
}

GET /cards/:cardId

Obtiene el estado actual de una tarjeta específica.

GET /cards

Lista todas las tarjetas emitidas por tu empresa o un modelo específico.

DELETE /cards/:cardId

Desactiva una tarjeta. El usuario dejará de recibir notificaciones.

6

6. Notificaciones

Envía notificaciones push directamente a la pantalla de bloqueo de los usuarios que tienen tu tarjeta.

POST /notifications/bulk

Envía una notificación a todas las tarjetas, o filtra por valores de campo.

Campo	Tipo	Obligatorio	Descripción
`title`	string	Sí	Título de la notificación (máx. 40 chars)
`body`	string	Sí	Cuerpo de la notificación (máx. 120 chars)
`filters`	array	No	Array de filtros para segmentar destinatarios

Cada objeto de filtro tiene tres claves: field (string), operator (eq / neq / contains / gt / lt) y value.

Ejemplo de petición

{
  "title": "¡Oferta especial!",
  "body": "2x1 en cafés hoy hasta las 18h ☕",
  "filters": [
    { "field": "city", "operator": "eq", "value": "Barcelona" }
  ]
}

POST /notifications/single

Envía una notificación a una tarjeta específica por su ID.

Campo	Tipo	Obligatorio	Descripción
`cardId`	string	Sí	ID de la tarjeta destinataria
`title`	string	Sí	Título de la notificación
`body`	string	Sí	Cuerpo de la notificación

7

7. Puntos y recompensas

Gestiona puntos de fidelidad y un catálogo de recompensas canjeables.

POST /points/add

Añade puntos a una o más tarjetas (masivo o individual).

Campo	Tipo	Obligatorio	Descripción
`points`	number	Sí	Número de puntos a añadir
`concept`	string	No	Etiqueta de transacción para el historial
`cardId`	string	No	ID de tarjeta (omitir para masivo con filtros)
`filters`	array	No	Filtros para seleccionar destinatarios

POST /points/subtract

Resta puntos de una o más tarjetas.

GET /points/balance/:cardId

Obtiene el saldo de puntos actual de una tarjeta.

GET /points/history/:cardId

Obtiene el historial completo de transacciones de una tarjeta.

POST /rewards/redeem

Canjea una recompensa para una tarjeta.

Campo	Tipo	Obligatorio	Descripción
`cardId`	string	Sí	ID de la tarjeta
`rewardId`	string	Sí	ID de la recompensa a canjear

GET /rewards

Lista todas las recompensas del catálogo de tu empresa.

8

8. Webhooks

Registra un endpoint HTTPS para recibir eventos en tiempo real de Elune.

POST /webhooks

Registra una URL de webhook para un tipo de evento específico.

Campo	Tipo	Obligatorio	Descripción
`url`	string	Sí	Tu URL de endpoint HTTPS
`event`	string	Sí	Tipo de evento al que suscribirse

Tipos de eventos disponibles

`card.added`	Se añadió una nueva tarjeta a un wallet
`card.deleted`	Se eliminó una tarjeta de un wallet
`points.added`	Se añadieron puntos a una tarjeta
`reward.redeemed`	Un usuario canjeó una recompensa

Los payloads de webhook están firmados con HMAC-SHA256. Verifica la cabecera X-Elune-Signature para garantizar la autenticidad.

Si tu endpoint devuelve un estado distinto de 2xx, Elune reintentará hasta 3 veces con retroceso exponencial.

GET /webhooks

Lista todos los webhooks registrados de tu empresa.

DELETE /webhooks/:webhookId

Elimina un registro de webhook.

9

9. Imágenes

Sube logotipos y banners para tu empresa o modelos de tarjeta específicos.

POST /images/logo

Por URL: Proporciona una URL de imagen accesible públicamente.

Por archivo: Sube el archivo de imagen directamente (multipart/form-data).

POST /images/banner

Proporciona una URL de imagen accesible públicamente o sube el archivo directamente.

Orden de resolución del banner:

Banner de la referencia
Banner de la empresa
Banner por defecto

Puedes fijar un banner a nivel de empresa como fallback y sobreescribirlo por modelo de tarjeta.

10

10. Gestión de errores

Todas las respuestas de error siguen un formato consistente.

Formato de error

{
  "error": "invalid_api_key",
  "message": "The provided API key is missing or invalid.",
  "statusCode": 401
}

Código HTTP	Descripción
`200`	Petición correcta
`201`	Recurso creado
`202`	Aceptado para procesamiento asíncrono
`400`	Petición inválida
`401`	API Key faltante o inválida
`403`	Cuota excedida
`404`	Recurso no encontrado
`500`	Error interno del servidor

⚡

Referencia rápida — Todos los endpoints

Método	Ruta	Auth	Descripción
POST	/register	Ninguna	Registrar empresa
PUT	/company/config	API Key	Actualizar configuración
POST	/images/banner	API Key	Subir banner
POST	/images/logo	API Key	Subir logo
POST	/refs	API Key	Crear modelo de tarjeta
GET	/refs	API Key	Listar modelos
PUT	/refs/:refId	API Key	Actualizar modelo
DELETE	/refs/:refId	API Key	Eliminar modelo
POST	/cards	API Key	Crear tarjeta
GET	/cards/:cardId	API Key	Estado de tarjeta
GET	/cards	API Key	Listar tarjetas
DELETE	/cards/:cardId	API Key	Desactivar tarjeta
POST	/notifications/bulk	API Key	Notificación masiva
POST	/notifications/single	API Key	Notificación individual
POST	/points/add	API Key	Añadir puntos
POST	/points/subtract	API Key	Restar puntos
GET	/points/balance/:id	API Key	Saldo
GET	/points/history/:id	API Key	Historial
POST	/rewards/redeem	API Key	Canjear
GET	/rewards	API Key	Recompensas
POST	/webhooks	API Key	Registrar webhook
GET	/webhooks	API Key	Listar webhooks
DELETE	/webhooks/:id	API Key	Eliminar webhook

POST/register

Registrar empresa

PUT/company/config

Actualizar configuración

POST/refs

Crear modelo

POST/cards

Crear tarjeta

POST/notifications/bulk

Notificación masiva

POST/notifications/single

Notificación individual

POST/points/add

Añadir puntos

POST/rewards/redeem

Canjear recompensa

Documentación de la Partner API