API de notificacions Wallet | Elune Connections

1

1. Autenticació

Totes les peticions a l'API han d'incloure la teva API Key a la capçalera de la petició.

Inclou aquesta capçalera a totes les peticions a l'API.

Capçaleres

X-API-Key: your_api_key_here

Mantén la teva API Key segura. No l'exposis en codi de frontend ni en repositoris públics.

Com obtenir la teva API Key

Inicia sessió al panell d'Elune i ves a Configuració → API. Allà trobaràs la teva clau i podràs regenerar-la si cal.

2

2. Registre d'empresa

Registra una nova empresa al sistema. Aquest és el primer pas per començar a usar l'API.

POST /register

Crea un nou compte d'empresa amb les dades proporcionades.

Camp	Tipus	Obligatori	Descripció
`name`	string	Sí	Nom de l'empresa
`email`	string	Sí	Correu electrònic de contacte
`phone`	string	No	Telèfon de contacte
`address`	string	No	Adreça física

Exemple de petició

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

Exemple de resposta

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

Desa la API key retornada — es mostra una sola vegada i no es pot recuperar.

3

3. Configuració

Actualitza la configuració visual de la teva empresa i els valors per defecte de les notificacions.

PUT /company/config

Actualitza la configuració de l'empresa. S'accepten actualitzacions parcials — envia només els camps que vols canviar.

Camp	Tipus	Obligatori	Descripció
`color`	string	No	Color primari de marca (hex)
`textColor`	string	No	Color del text (hex)
`notificationTitle`	string	No	Títol de notificació per defecte
`pointsName`	string	No	Nom personalitzat per als teus punts (p. ex. Estrelles, Crèdits)
`rewardsEnabled`	boolean	No	Activa / desactiva el catàleg de recompenses

Els colors de marca s'apliquen a totes les targetes emeses per la teva empresa llevat que es sobreescriguin a nivell de model de targeta.

4

4. Models de targeta (Referencias)

Els models de targeta defineixen la plantilla visual per a un conjunt de targetes emeses. Pots tenir múltiples models, cadascun amb el seu propi disseny.

POST /refs

Crea un nou model de targeta amb la configuració indicada.

Camp	Tipus	Obligatori	Descripció
`name`	string	Sí	Nom del model
`description`	string	No	Descripció curta (visible a la targeta)
`color`	string	No	Color primari alternatiu (hex)
`textColor`	string	No	Color del text alternatiu (hex)
`pointsEnabled`	boolean	No	Activa punts de fidelitat per a aquest model
`rewardsEnabled`	boolean	No	Activa el catàleg de recompenses per a aquest model

GET /refs

Retorna tots els models de targeta de la teva empresa.

PUT /refs/:refId

Actualitza un model de targeta específic. S'accepten actualitzacions parcials.

DELETE /refs/:refId

Elimina un model de targeta. Les targetes ja emeses no es veuen afectades.

5

5. Targetes emeses

Les targetes emeses són els passis digitals reals que els usuaris finals afegeixen a Apple Wallet o Google Wallet.

POST /cards

Crea una nova targeta per a un usuari final. Retorna la URL del passi per compartir o incrustar en un codi QR.

Camp	Tipus	Obligatori	Descripció
`refId`	string	Sí	ID del model de targeta
`userName`	string	Sí	Nom complet de l'usuari
`userEmail`	string	No	Correu electrònic de l'usuari
`userPhone`	string	No	Telèfon de l'usuari
`customFields`	object	No	Objecte clau-valor amb camps addicionals de l'usuari

Exemple de resposta

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

GET /cards/:cardId

Obté l'estat actual d'una targeta específica.

GET /cards

Llista totes les targetes emeses per la teva empresa o un model específic.

DELETE /cards/:cardId

Desactiva una targeta. L'usuari deixarà de rebre notificacions.

6

6. Notificacions

Envia notificacions push directament a la pantalla de bloqueig dels usuaris que tenen la teva targeta.

POST /notifications/bulk

Envia una notificació a totes les targetes, o filtra per valors de camp.

Camp	Tipus	Obligatori	Descripció
`title`	string	Sí	Títol de la notificació (màx. 40 caràcters)
`body`	string	Sí	Cos de la notificació (màx. 120 caràcters)
`filters`	array	No	Array d'objectes de filtre per arribar a un subconjunt de targetes

Cada objecte de filtre té tres claus: field (string), operator (eq / neq / contains / gt / lt) i value.

Exemple de petició

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

POST /notifications/single

Envia una notificació a una targeta específica pel seu ID.

Camp	Tipus	Obligatori	Descripció
`cardId`	string	Sí	ID de la targeta destinatària
`title`	string	Sí	Títol de la notificació (màx. 40 caràcters)
`body`	string	Sí	Cos de la notificació (màx. 120 caràcters)

7

7. Punts i recompenses

Gestiona els punts de fidelitat i un catàleg de recompenses canviables.

POST /points/add

Afegeix punts a una o més targetes (massiu o individual).

Camp	Tipus	Obligatori	Descripció
`points`	number	Sí	Nombre de punts a afegir o restar
`concept`	string	No	Etiqueta de transacció visible a l'historial
`cardId`	string	No	ID de la targeta destinatària
`filters`	array	No	Array d'objectes de filtre per arribar a un subconjunt de targetes

POST /points/subtract

Resta punts d'una o més targetes.

GET /points/balance/:cardId

Obté el saldo de punts actual d'una targeta.

GET /points/history/:cardId

Obté l'historial complet de transaccions d'una targeta.

POST /rewards/redeem

Canvia una recompensa per a una targeta.

Camp	Tipus	Obligatori	Descripció
`cardId`	string	Sí	ID de la targeta destinatària
`rewardId`	string	Sí	ID de la recompensa a canviar

GET /rewards

Llista totes les recompenses del teu catàleg.

8

8. Webhooks

Registra un endpoint HTTPS per rebre esdeveniments en temps real d'Elune.

POST /webhooks

Registra una URL de webhook per a un tipus d'esdeveniment específic.

Camp	Tipus	Obligatori	Descripció
`url`	string	Sí	La teva URL d'endpoint HTTPS
`event`	string	Sí	Tipus d'esdeveniment al qual subscriure's

Tipus d'esdeveniments disponibles

`card.added`	S'ha afegit una nova targeta a un wallet
`card.deleted`	S'ha eliminat una targeta d'un wallet
`points.added`	S'han afegit punts a una targeta
`reward.redeemed`	Un usuari ha canviat una recompensa

Els payloads de webhook estan signats amb HMAC-SHA256. Verifica la capçalera X-Elune-Signature per garantir l'autenticitat.

Si el teu endpoint retorna un estat diferent de 2xx, Elune ho reintentarà fins a 3 vegades amb retard exponencial.

GET /webhooks

Llista tots els webhooks registrats per a la teva empresa.

DELETE /webhooks/:webhookId

Elimina un registre de webhook.

9

9. Imatges

Puja logotips i banners per a la teva empresa o models de targeta específics.

POST /images/logo

Puja per URL Proporciona una URL d'imatge accessible públicament.

Puja per fitxer Puja el fitxer d'imatge directament.

POST /images/banner

Proporciona una URL d'imatge accessible públicament.

Ordre de resolució del banner

Banner del model
Banner de l'empresa
Banner per defecte

Pots fixar un banner a nivell d'empresa com a fallback i sobreescriure'l per model de targeta.

10

10. Gestió d'errors

Totes les respostes d'error segueixen un format consistent.

Exemple de resposta

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

Codis HTTP habituals	Descripció
`200`	Petició correcta
`201`	Recurs creat
`202`	Acceptat per a processament asíncron
`400`	Petició invàlida
`401`	API Key absent o invàlida
`403`	Quota superada
`404`	Recurs no trobat
`500`	Error intern del servidor

11

Referència ràpida — Tots els endpoints

Mètode	Ruta	Auth	Descripció
POST	/register	Cap	Registrar empresa
PUT	/company/config	API Key	Actualitzar configuració
POST	/images/banner	API Key	Pujar banner
POST	/images/logo	API Key	Pujar logotip
POST	/refs	API Key	Crear model de targeta
GET	/refs	API Key	Llistar models
PUT	/refs/:refId	API Key	Actualitzar model
DELETE	/refs/:refId	API Key	Eliminar model
POST	/cards	API Key	Crear targeta
GET	/cards/:cardId	API Key	Estat de targeta
GET	/cards	API Key	Llistar targetes
DELETE	/cards/:cardId	API Key	Desactivar targeta
POST	/notifications/bulk	API Key	Notificació massiva
POST	/notifications/single	API Key	Notificació individual
POST	/points/add	API Key	Afegir punts
POST	/points/subtract	API Key	Restar punts
GET	/points/balance/:id	API Key	Saldo
GET	/points/history/:id	API Key	Historial
POST	/rewards/redeem	API Key	Canviar
GET	/rewards	API Key	Recompenses
POST	/webhooks	API Key	Registrar empresa
GET	/webhooks	API Key	Llistar models
DELETE	/webhooks/:id	API Key	Eliminar model

POST/register

Registrar empresa

PUT/company/config

Actualitzar configuració

POST/refs

Crear model de targeta

POST/cards

Crear targeta

POST/notifications/bulk

Notificació massiva

POST/notifications/single

Notificació individual

POST/points/add

Afegir punts

POST/rewards/redeem

Canviar

Documentació de la Partner API

1. Autenticació

2. Registre d'empresa

3. Configuració

4. Models de targeta (Referencias)

5. Targetes emeses

6. Notificacions

7. Punts i recompenses

8. Webhooks

9. Imatges

10. Gestió d'errors

Referència ràpida — Tots els endpoints