Wallet-Benachrichtigungs-API | Elune Connections

1

1. Authentifizierung

Alle API-Anfragen müssen Ihren API-Schlüssel im Anfrage-Header enthälten.

Fügen Sie diesen Header jeder API-Anfrage hinzu.

Header

X-API-Key: your_api_key_here

Halten Sie Ihren API-Schlüssel sicher. Exponieren Sie ihn nicht in Frontend-Code oder öffentlichen Repositories.

Wie Sie Ihren API-Schlüssel erhälten

Melden Sie sich im Elune-Dashboard an und gehen Sie zu Einstellungen → API. Dort finden Sie Ihren Schlüssel und können ihn bei Bedarf neu generieren.

2

2. Unternehmensregistrierung

Registrieren Sie ein neues Unternehmen im System. Dies ist der erste Schritt zur Nutzung der API.

POST /register

Erstellt ein neues Unternehmenskonto mit den angegebenen Daten.

Feld	Typ	Pflichtfeld	Beschreibung
`name`	string	Ja	Unternehmensname
`email`	string	Ja	Kontakt-E-Mail-Adresse
`phone`	string	Nein	Kontakttelefonnummer
`address`	string	Nein	Physische Adresse

Beispielanfrage

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

Beispielantwort

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

Speichern Sie den zurückgegebenen API-Schlüssel — er wird nur einmal angezeigt und kann nicht wiederhergestellt werden.

3

3. Konfiguration

Aktualisieren Sie die visuellen Einstellungen Ihres Unternehmens und die Standardwerte für Benachrichtigungen.

PUT /company/config

Aktualisiert die Unternehmenskonfiguration. Teilaktualisierungen werden unterstützt — senden Sie nur die zu ändernden Felder.

Feld	Typ	Pflichtfeld	Beschreibung
`color`	string	Nein	Primärfarbe der Marke (hex)
`textColor`	string	Nein	Textfarbe (hex)
`notificationTitle`	string	Nein	Standard-Benachrichtigungstitel
`pointsName`	string	Nein	Benutzerdefinierter Name für Ihre Punkte (z. B. Sterne, Credits)
`rewardsEnabled`	boolean	Nein	Prämienkatalog aktivieren / deaktivieren

Markenfarben werden auf alle vom Unternehmen ausgestellten Karten angewendet, sofern sie nicht auf Kartenmodellebene überschrieben werden.

4

4. Kartenmodelle (Referencias)

Kartenmodelle definieren die visuelle Vorlage für eine Reihe von ausgestellten Karten. Sie können mehrere Modelle haben, jedes mit eigenem Design.

POST /refs

Erstellt ein neues Kartenmodell mit der angegebenen Konfiguration.

Feld	Typ	Pflichtfeld	Beschreibung
`name`	string	Ja	Anzeigename des Modells
`description`	string	Nein	Kurze Beschreibung (auf der Karte angezeigt)
`color`	string	Nein	Alternative Primärfarbe (hex)
`textColor`	string	Nein	Alternative Textfarbe (hex)
`pointsEnabled`	boolean	Nein	Treuepunkte für dieses Modell aktivieren
`rewardsEnabled`	boolean	Nein	Prämienkatalog für dieses Modell aktivieren

GET /refs

Gibt alle Kartenmodelle Ihres Unternehmens zurück.

PUT /refs/:refId

Aktualisiert ein bestimmtes Kartenmodell. Teilaktualisierungen werden unterstützt.

DELETE /refs/:refId

Löscht ein Kartenmodell. Bereits ausgestellte Karten sind nicht betroffen.

5

5. Ausgestellte Karten

Ausgestellte Karten sind die eigentlichen digitalen Pässe, die Endnutzer zu Apple Wallet oder Google Wallet hinzufügen.

POST /cards

Erstellt eine neue Karte für einen Endnutzer. Gibt die Pass-URL zurück, die geteilt oder in einen QR-Code eingebettet werden kann.

Feld	Typ	Pflichtfeld	Beschreibung
`refId`	string	Ja	ID des Kartenmodells
`userName`	string	Ja	Vollständiger Name des Nutzers
`userEmail`	string	Nein	E-Mail-Adresse des Nutzers
`userPhone`	string	Nein	Telefonnummer des Nutzers
`customFields`	object	Nein	Schlüssel-Wert-Objekt mit zusätzlichen Nutzerfeldern

Beispielantwort

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

GET /cards/:cardId

Ruft den aktuellen Status einer bestimmten Karte ab.

GET /cards

Listet alle vom Unternehmen oder einem bestimmten Modell ausgestellten Karten auf.

DELETE /cards/:cardId

Deaktiviert eine Karte. Der Nutzer erhält keine Benachrichtigungen mehr.

6

6. Benachrichtigungen

Senden Sie Push-Benachrichtigungen direkt auf den Sperrbildschirm der Nutzer, die Ihre Karte haben.

POST /notifications/bulk

Sendet eine Benachrichtigung an alle Karten oder filtert nach Feldwerten.

Feld	Typ	Pflichtfeld	Beschreibung
`title`	string	Ja	Benachrichtigungstitel (max. 40 Zeichen)
`body`	string	Ja	Benachrichtigungstext (max. 120 Zeichen)
`filters`	array	Nein	Array von Filterobjekten zur Zielgruppenauswahl

Jedes Filterobjekt hat drei Schlüssel: field (string), operator (eq / neq / contains / gt / lt) und value.

Beispielanfrage

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

POST /notifications/single

Sendet eine Benachrichtigung an eine bestimmte Karte anhand ihrer ID.

Feld	Typ	Pflichtfeld	Beschreibung
`cardId`	string	Ja	ID der Zielkarte
`title`	string	Ja	Benachrichtigungstitel (max. 40 Zeichen)
`body`	string	Ja	Benachrichtigungstext (max. 120 Zeichen)

7

7. Punkte & Prämien

Verwalten Sie Treuepunkte und einen einlösbaren Prämienkatalog.

POST /points/add

Fügt einer oder mehreren Karten Punkte hinzu (Massen- oder Einzelaktion).

Feld	Typ	Pflichtfeld	Beschreibung
`points`	number	Ja	Anzahl der hinzuzufügenden oder abzuziehenden Punkte
`concept`	string	Nein	Transaktionsbezeichnung im Verlauf
`cardId`	string	Nein	ID der Zielkarte
`filters`	array	Nein	Array von Filterobjekten zur Zielgruppenauswahl

POST /points/subtract

Zieht Punkte von einer oder mehreren Karten ab.

GET /points/balance/:cardId

Ruft das aktuelle Punkteguthaben einer Karte ab.

GET /points/history/:cardId

Ruft den vollständigen Transaktionsverlauf einer Karte ab.

POST /rewards/redeem

Löst eine Prämie für eine Karte ein.

Feld	Typ	Pflichtfeld	Beschreibung
`cardId`	string	Ja	ID der Zielkarte
`rewardId`	string	Ja	ID der einzulösenden Prämie

GET /rewards

Listet alle Prämien in Ihrem Katalog auf.

8

8. Webhooks

Registrieren Sie einen HTTPS-Endpunkt, um Echtzeit-Ereignisse von Elune zu empfangen.

POST /webhooks

Registriert eine Webhook-URL für einen bestimmten Ereignistyp.

Feld	Typ	Pflichtfeld	Beschreibung
`url`	string	Ja	Ihre HTTPS-Endpunkt-URL
`event`	string	Ja	Ereignistyp, den Sie abonnieren möchten

Verfügbare Ereignistypen

`card.added`	Eine neue Karte wurde zu einem Wallet hinzugefügt
`card.deleted`	Eine Karte wurde aus einem Wallet gelöscht
`points.added`	Punkte wurden einer Karte hinzugefügt
`reward.redeemed`	Ein Nutzer hat eine Prämie eingelöst

Webhook-Payloads sind mit HMAC-SHA256 signiert. Überprüfen Sie den X-Elune-Signature-Header, um die Authentizität sicherzustellen.

Wenn Ihr Endpunkt einen Nicht-2xx-Status zurückgibt, versucht Elune es bis zu 3 Mal mit exponentiellem Backoff erneut.

GET /webhooks

Listet alle registrierten Webhooks Ihres Unternehmens auf.

DELETE /webhooks/:webhookId

Löscht eine Webhook-Registrierung.

9

9. Bilder

Laden Sie Logos und Banner für Ihr Unternehmen oder bestimmte Kartenmodelle hoch.

POST /images/logo

Upload per URL Geben Sie eine öffentlich zugängliche Bild-URL an.

Upload per Datei Laden Sie die Bilddatei direkt hoch.

POST /images/banner

Geben Sie eine öffentlich zugängliche Bild-URL an.

Banner-Auflösungsreihenfolge

Modell-Banner
Unternehmens-Banner
Standard-Banner

Legen Sie ein Banner auf Unternehmensebene als Fallback fest und überschreiben Sie es pro Kartenmodell.

10

10. Fehlerbehandlung

Alle Fehlerantworten folgen einem einheitlichen Format.

Beispielantwort

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

Häufige HTTP-Statuscodes	Beschreibung
`200`	Anfrage erfolgreich
`201`	Ressource erstellt
`202`	Für asynchrone Verarbeitung akzeptiert
`400`	Ungültige Anfrage
`401`	Fehlender oder ungültiger API-Schlüssel
`403`	Kontingent überschritten
`404`	Ressource nicht gefunden
`500`	Interner Serverfehler

11

Schnellreferenz — Alle Endpunkte

Methode	Pfad	Auth	Beschreibung
POST	/register	Keine	Unternehmen registrieren
PUT	/company/config	API Key	Konfiguration aktualisieren
POST	/images/banner	API Key	Banner hochladen
POST	/images/logo	API Key	Logo hochladen
POST	/refs	API Key	Kartenmodell erstellen
GET	/refs	API Key	Modelle auflisten
PUT	/refs/:refId	API Key	Modell aktualisieren
DELETE	/refs/:refId	API Key	Modell löschen
POST	/cards	API Key	Karte erstellen
GET	/cards/:cardId	API Key	Kartenstatus
GET	/cards	API Key	Karten auflisten
DELETE	/cards/:cardId	API Key	Karte deaktivieren
POST	/notifications/bulk	API Key	Massenbenachrichtigung
POST	/notifications/single	API Key	Einzelbenachrichtigung
POST	/points/add	API Key	Punkte hinzufügen
POST	/points/subtract	API Key	Punkte abziehen
GET	/points/balance/:id	API Key	Guthaben
GET	/points/history/:id	API Key	Verlauf
POST	/rewards/redeem	API Key	Einlösen
GET	/rewards	API Key	Prämien
POST	/webhooks	API Key	Unternehmen registrieren
GET	/webhooks	API Key	Modelle auflisten
DELETE	/webhooks/:id	API Key	Modell löschen

POST/register

Unternehmen registrieren

PUT/company/config

Konfiguration aktualisieren

POST/refs

Kartenmodell erstellen

POST/cards

Karte erstellen

POST/notifications/bulk

Massenbenachrichtigung

POST/notifications/single

Einzelbenachrichtigung

POST/points/add

Punkte hinzufügen

POST/rewards/redeem

Einlösen

Partner-API-Dokumentation

1. Authentifizierung

2. Unternehmensregistrierung

3. Konfiguration

4. Kartenmodelle (Referencias)

5. Ausgestellte Karten

6. Benachrichtigungen

7. Punkte & Prämien

8. Webhooks

9. Bilder

10. Fehlerbehandlung

Schnellreferenz — Alle Endpunkte