API de notifications Wallet | Elune Connections

1

1. Authentification

Toutes les requêtes à l'API doivent inclure votre API Key dans l'en-tête de la requête.

Incluez cet en-tête dans toutes les requêtes à l'API.

En-têtes

X-API-Key: your_api_key_here

Gardez votre API Key secrète. Ne l'exposez pas dans du code front-end ni dans des dépôts publics.

Comment obtenir votre API Key

Connectez-vous au tableau de bord Elune et allez dans Paramètres → API. Vous y trouverez votre clé et pourrez la régénérer si nécessaire.

2

2. Enregistrement d'entreprise

Enregistrez une nouvelle entreprise dans le système. C'est la première étape pour commencer à utiliser l'API.

POST /register

Crée un nouveau compte d'entreprise avec les informations fournies.

Champ	Type	Obligatoire	Description
`name`	string	Oui	Nom de l'entreprise
`email`	string	Oui	Adresse e-mail de contact
`phone`	string	Non	Numéro de téléphone de contact
`address`	string	Non	Adresse physique

Exemple de requête

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

Exemple de réponse

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

Sauvegardez l'API key renvoyée — elle n'est affichée qu'une seule fois et ne peut pas être récupérée.

3

3. Configuration

Mettez à jour les paramètres visuels de votre entreprise et les valeurs par défaut des notifications.

PUT /company/config

Met à jour la configuration de l'entreprise. Les mises à jour partielles sont acceptées — envoyez uniquement les champs à modifier.

Champ	Type	Obligatoire	Description
`color`	string	Non	Couleur principale de la marque (hex)
`textColor`	string	Non	Couleur du texte (hex)
`notificationTitle`	string	Non	Titre de notification par défaut
`pointsName`	string	Non	Nom personnalisé pour vos points (ex. Étoiles, Crédits)
`rewardsEnabled`	boolean	Non	Activer / désactiver le catalogue de récompenses

Les couleurs de marque s'appliquent à toutes les cartes émises par votre entreprise, sauf si elles sont remplacées au niveau du modèle de carte.

4

4. Modèles de carte (Referencias)

Les modèles de carte définissent le modèle visuel pour un ensemble de cartes émises. Vous pouvez avoir plusieurs modèles, chacun avec son propre design.

POST /refs

Crée un nouveau modèle de carte avec la configuration indiquée.

Champ	Type	Obligatoire	Description
`name`	string	Oui	Nom d'affichage du modèle
`description`	string	Non	Description courte (affichée sur la carte)
`color`	string	Non	Couleur principale alternative (hex)
`textColor`	string	Non	Couleur du texte alternative (hex)
`pointsEnabled`	boolean	Non	Activer les points de fidélité pour ce modèle
`rewardsEnabled`	boolean	Non	Activer le catalogue de récompenses pour ce modèle

GET /refs

Renvoie tous les modèles de carte de votre entreprise.

PUT /refs/:refId

Met à jour un modèle de carte spécifique. Mises à jour partielles acceptées.

DELETE /refs/:refId

Supprime un modèle de carte. Les cartes déjà émises ne sont pas affectées.

5

5. Cartes émises

Les cartes émises sont les passes numériques réels ajoutés à Apple Wallet ou Google Wallet par les utilisateurs finaux.

POST /cards

Crée une nouvelle carte pour un utilisateur final. Renvoie l'URL du pass à partager ou intégrer dans un QR code.

Champ	Type	Obligatoire	Description
`refId`	string	Oui	ID du modèle de carte
`userName`	string	Oui	Nom complet de l'utilisateur
`userEmail`	string	Non	Adresse e-mail de l'utilisateur
`userPhone`	string	Non	Numéro de téléphone de l'utilisateur
`customFields`	object	Non	Objet clé-valeur avec des champs utilisateur supplémentaires

Exemple de réponse

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

GET /cards/:cardId

Obtient l'état actuel d'une carte spécifique.

GET /cards

Liste toutes les cartes émises par votre entreprise ou un modèle spécifique.

DELETE /cards/:cardId

Désactive une carte. L'utilisateur ne recevra plus de notifications.

6

6. Notifications

Envoyez des notifications push directement sur l'écran verrouillé des utilisateurs qui ont votre carte.

POST /notifications/bulk

Envoie une notification à toutes les cartes, ou filtre par valeurs de champ.

Champ	Type	Obligatoire	Description
`title`	string	Oui	Titre de la notification (max 40 caractères)
`body`	string	Oui	Corps de la notification (max 120 caractères)
`filters`	array	Non	Tableau d'objets de filtre pour cibler un sous-ensemble de cartes

Chaque objet de filtre a trois clés : field (string), operator (eq / neq / contains / gt / lt) et value.

Exemple de requête

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

POST /notifications/single

Envoie une notification à une carte spécifique par son ID.

Champ	Type	Obligatoire	Description
`cardId`	string	Oui	ID de la carte destinataire
`title`	string	Oui	Titre de la notification (max 40 caractères)
`body`	string	Oui	Corps de la notification (max 120 caractères)

7

7. Points et récompenses

Gérez les points de fidélité et un catalogue de récompenses échangeables.

POST /points/add

Ajoute des points à une ou plusieurs cartes (en masse ou individuel).

Champ	Type	Obligatoire	Description
`points`	number	Oui	Nombre de points à ajouter ou retirer
`concept`	string	Non	Étiquette de transaction affichée dans l'historique
`cardId`	string	Non	ID de la carte destinataire
`filters`	array	Non	Tableau d'objets de filtre pour cibler un sous-ensemble de cartes

POST /points/subtract

Retire des points d'une ou plusieurs cartes.

GET /points/balance/:cardId

Obtient le solde de points actuel d'une carte.

GET /points/history/:cardId

Obtient l'historique complet des transactions d'une carte.

POST /rewards/redeem

Échange une récompense pour une carte.

Champ	Type	Obligatoire	Description
`cardId`	string	Oui	ID de la carte destinataire
`rewardId`	string	Oui	ID de la récompense à échanger

GET /rewards

Liste toutes les récompenses de votre catalogue.

8

8. Webhooks

Enregistrez un endpoint HTTPS pour recevoir des événements en temps réel d'Elune.

POST /webhooks

Enregistre une URL de webhook pour un type d'événement spécifique.

Champ	Type	Obligatoire	Description
`url`	string	Oui	Votre URL d'endpoint HTTPS
`event`	string	Oui	Type d'événement auquel s'abonner

Types d'événements disponibles

`card.added`	Une nouvelle carte a été ajoutée à un wallet
`card.deleted`	Une carte a été supprimée d'un wallet
`points.added`	Des points ont été ajoutés à une carte
`reward.redeemed`	Un utilisateur a échangé une récompense

Les payloads de webhook sont signés avec HMAC-SHA256. Vérifiez l'en-tête X-Elune-Signature pour garantir l'authenticité.

Si votre endpoint renvoie un statut non-2xx, Elune réessaiera jusqu'à 3 fois avec un délai exponentiel.

GET /webhooks

Liste tous les webhooks enregistrés pour votre entreprise.

DELETE /webhooks/:webhookId

Supprime un enregistrement de webhook.

9

9. Images

Téléchargez des logos et des bannières pour votre entreprise ou des modèles de carte spécifiques.

POST /images/logo

Téléchargement par URL Fournissez une URL d'image accèssible publiquement.

Téléchargement par fichier Téléchargez le fichier image directement.

POST /images/banner

Fournissez une URL d'image accèssible publiquement.

Ordre de résolution de la bannière

Bannière du modèle
Bannière de l'entreprise
Bannière par défaut

Définissez une bannière au niveau de l'entreprise comme fallback et remplacez-la par modèle de carte.

10

10. Gestion des erreurs

Toutes les réponses d'erreur suivent un format cohérent.

Exemple de réponse

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

Codes HTTP courants	Description
`200`	Requête réussie
`201`	Ressource créée
`202`	Accepté pour traitement asynchrone
`400`	Requête invalide
`401`	API Key absente ou invalide
`403`	Quota dépassé
`404`	Ressource introuvable
`500`	Erreur interne du serveur

11

Référence rapide — Tous les endpoints

Méthode	Chemin	Auth	Description
POST	/register	Aucune	Enregistrer entreprise
PUT	/company/config	API Key	Mettre à jour la configuration
POST	/images/banner	API Key	Télécharger bannière
POST	/images/logo	API Key	Télécharger logo
POST	/refs	API Key	Créer modèle de carte
GET	/refs	API Key	Lister les modèles
PUT	/refs/:refId	API Key	Mettre à jour le modèle
DELETE	/refs/:refId	API Key	Supprimer le modèle
POST	/cards	API Key	Créer une carte
GET	/cards/:cardId	API Key	Statut de la carte
GET	/cards	API Key	Lister les cartes
DELETE	/cards/:cardId	API Key	Désactiver la carte
POST	/notifications/bulk	API Key	Notification en masse
POST	/notifications/single	API Key	Notification individuelle
POST	/points/add	API Key	Ajouter des points
POST	/points/subtract	API Key	Retirer des points
GET	/points/balance/:id	API Key	Solde
GET	/points/history/:id	API Key	Historique
POST	/rewards/redeem	API Key	Échanger
GET	/rewards	API Key	Récompenses
POST	/webhooks	API Key	Enregistrer entreprise
GET	/webhooks	API Key	Lister les modèles
DELETE	/webhooks/:id	API Key	Supprimer le modèle

POST/register

Enregistrer entreprise

PUT/company/config

Mettre à jour la configuration

POST/refs

Créer modèle de carte

POST/cards

Créer une carte

POST/notifications/bulk

Notification en masse

POST/notifications/single

Notification individuelle

POST/points/add

Ajouter des points

POST/rewards/redeem

Échanger

Documentation de la Partner API

1. Authentification

2. Enregistrement d'entreprise

3. Configuration

4. Modèles de carte (Referencias)

5. Cartes émises

6. Notifications

7. Points et récompenses

8. Webhooks

9. Images

10. Gestion des erreurs

Référence rapide — Tous les endpoints