Entwickler · Version 2026-09-01
Fidélitas API und Integrationen
Senden Sie Verkäufe aus einer Kasse, erkennen Sie Kunden, buchen Sie ihre Punkte und empfangen Sie Fidélitas-Ereignisse in Echtzeit. Eine REST-API mit JSON, signierte Webhooks und ein einheitliches Ereignisformat – ganz gleich, aus welcher Software die Daten kommen.
Erste Schritte
- Der Händler erstellt unter Integrationen › API und Webhooks einen Schlüssel und wählt dessen Berechtigungen (Voreinstellung „Kasse“ empfohlen).
- Jede Anfrage enthält den Header
Authorization: Bearer fidk_…. Der Schlüssel bezeichnet das Geschäft: Es ist keine Geschäfts-ID zu übergeben. - Basisadresse:
https://fidelitas.fr/api/v1. Antworten in JSON, Datumsangaben nach ISO 8601, Beträge in Cent.
Berechtigungen eines Schlüssels
customers:readKunden und ihre Punkte lesencustomers:writeKunden anlegentransactions:writeVerkäufe und Rückerstattungen sendenloyalty:writeBesuche erfassen und Punkte anpassenrewards:readPrämien und Treueprogramm lesenrewards:writePrämien einlösenactions:runKassencodes auslösen (Prämie, Punkte, Nachricht)campaigns:sendKampagnen startenwebhooks:manageWebhooks verwalten
Endpunkte
| Methode und Pfad | Funktion | Berechtigung |
|---|---|---|
GET/customers | Kunden auflisten / suchen (q, filter, page) | customers:read |
POST/customers | Einen Kunden anlegen (ausdrückliche Einwilligung)· Idempotency-Key | customers:write |
GET/customers/{id} | Datensatz eines Kunden | customers:read |
GET/customers/{id}/points | Punktestand, nächste Prämie, verfügbare Prämien | customers:read |
POST/customers/{id}/visits | Einen Besuch erfassen· Idempotency-Key | loyalty:write |
GET/customers/by-token/{cardToken} | Einen Kunden über den QR-Code seiner Karte finden | customers:read |
POST/transactions | Einen Verkauf senden (Punkte, Besuch, Zuordnung zum Scan); Prefer: respond-async → 202 ohne die Verarbeitung abzuwarten· Idempotency-Key | transactions:write |
POST/transactions/{saleId}/refunds | Einen Verkauf rückerstatten (Punkte werden abgezogen)· Idempotency-Key | transactions:write |
POST/loyalty/events | Besuch ohne Verkauf oder Punktekorrektur· Idempotency-Key | loyalty:write |
GET/rewards | Stufen des Programms und Prämien eines Kunden (customerId) | rewards:read |
POST/rewards/redeem | Eine Prämie einlösen (Code)· Idempotency-Key | rewards:write |
GET/program | Regeln des Programms (Stempel / Punkte, Stufen) | rewards:read |
GET/pos/actions | Vom Geschäft eingerichtete Kassencodes | actions:run |
POST/pos/actions/{code} | Einen Kassencode für einen Kunden auslösen (Prämie, Punkte, Kampagne, Etikett)· Idempotency-Key | actions:run |
GET/campaigns | Versandbereite Kampagnen (Entwürfe) | campaigns:send |
POST/campaigns/{id}/send | Eine Kampagne starten (ganze Gruppe) oder an einen einzelnen Kunden senden (customer)· Idempotency-Key | campaigns:send |
GET/webhooks | Webhook-Adressen | webhooks:manage |
POST/webhooks | Eine Adresse hinzufügen (Secret wird nur einmal zurückgegeben)· Idempotency-Key | webhooks:manage |
DELETE/webhooks/{id} | Eine Adresse löschen | webhooks:manage |
Verkauf senden
Der Kunde wird über seine Fidélitas-ID, das Token seiner Karte (an der Kasse gescannter QR-Code), seine E-Mail-Adresse oder seine Telefonnummer bestimmt. Ein unbekannter Kunde mit E-Mail-Adresse oder Telefonnummer wird angelegt (ohne Marketing-Einwilligung). Derselbe Verkauf zweimal gesendet zählt nur einmal.
curl https://fidelitas.fr/api/v1/transactions \
-H "Authorization: Bearer fidk_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ticket-2026-000123" \
-d '{
"id": "ticket-2026-000123",
"amountCents": 2450,
"currency": "EUR",
"customer": { "cardToken": "ckx…", "email": "lea@exemple.fr" },
"items": [{ "name": "Coupe", "quantity": 1, "unitCents": 2450 }]
}'{
"eventId": "cm…",
"duplicate": false,
"status": "PROCESSED",
"outcome": "visit_created",
"outcomeLabel": "Visite enregistrée",
"customerId": "cm…",
"visitId": "cm…",
"transactionId": "cm…",
"points": 1,
"error": null
}Kiosk oder Kasse im Stossbetrieb: Warten Sie nie auf Fidélitas. Fügen Sie den Header Prefer: respond-async hinzu: Der Verkauf wird mit 202 sofort bei Eingang bestätigt (Status RECEIVED) und unmittelbar danach verarbeitet. Senden Sie ihn, ohne den Zahlvorgang zu blockieren, mit einem Timeout von 2 Sekunden und bei einem Fehlschlag einem erneuten Versuch mit demselben Idempotency-Key – niemals doppelt. Das Ergebnis kommt über den Webhook transaction.created und erscheint unter Integrationen › Journal. Geben Sie terminalId an (den Namen der Station, wie in der Kasse oder in Comptoir angezeigt), damit ein Verkauf ohne Kunden nur der an dieser Station gescannten Karte zugeordnet wird.
Rückerstattung: POST /transactions/ticket-2026-000123/refunds mit { "refundId": "r-1", "amountCents": 2450 }. Die entsprechenden Punkte werden abgezogen (nie unter null).
Angewendete Treueregeln
- Wurde die Karte des Kunden kurz davor gescannt (innerhalb von 30 Minuten), wird der Betrag diesem Besuch zugeordnet: keine Doppelzählung.
- Mehrere Einkäufe am selben Tag: nur ein Besuch (Stempelkarte: nur ein Stempel; Punktekarte: die Punkte summieren sich).
- Verkauf ohne Kunden: der einzigen Karte zugeordnet, die in den Minuten davor an derselben Station gescannt wurde (
terminalId), sonst ohne Punkte erfasst (der Umsatz ist dennoch bekannt). Der Kunde kann seinen Beleg auch selbst über seine Karte zuordnen, mit der Bestellnummer (iddes Verkaufs). - Die Wallet-Karte wird aktualisiert und die Automatisierungen des Händlers werden ausgelöst wie bei einem an der Kasse erfassten Besuch.
Webhook „Andere Kasse“
Für eine Kasse, die eine Webadresse aufrufen kann (oder über Zapier / Make): Der Händler erstellt eine Verbindung „Andere Kasse“ und übermittelt Ihnen eine Adresse und ein Secret. Senden Sie ein Ereignis (oder { "events": [ … ] }, höchstens 100), signiert.
Ereignistypen
sale.completedVerkaufsale.refundedRückerstattungcustomer.upsertedKunde angelegt oder geändertcustomer.visitBesuchloyalty.adjustedPunkte angepasst
{
"id": "evt-000123",
"type": "sale.completed",
"occurredAt": "2026-09-23T10:42:00Z",
"data": {
"saleId": "ticket-000123",
"amountCents": 1250,
"currency": "EUR",
"customer": { "externalId": "C-981", "phone": "+33612345678", "firstName": "Léa" },
"locationExternalId": "boutique-1"
}
}import crypto from "node:crypto";
const body = JSON.stringify(event);
const t = Math.floor(Date.now() / 1000);
const v1 = crypto.createHmac("sha256", SECRET).update(`${t}.${body}`).digest("hex");
await fetch(WEBHOOK_URL, {
method: "POST",
headers: { "Content-Type": "application/json", "Fidelitas-Signature": `t=${t},v1=${v1}` },
body,
});Antwort 202 mit der Anzahl akzeptierter Ereignisse und ignorierter Duplikate. Fehlende, falsche oder mehr als 5 Minuten alte Signatur: 401. Ungültiges Format: 422 mit dem betroffenen Feld. Das Ergebnis jedes Ereignisses sieht der Händler in seinem Journal.
Ausgehende Webhooks
Fidélitas ruft Ihre (https-)Adressen bei jedem Ereignis auf. Bei einem Fehlschlag (eine andere Antwort als 2xx oder keine Antwort innerhalb von 10 Sekunden) folgt ein neuer Versuch nach 1 Min., 5 Min., 30 Min., 2 Std., 6 Std., 12 Std. und dann 24 Std. Eine Adresse, die 50 Mal hintereinander fehlschlägt, wird pausiert.
customer.createdNeuer Kundecustomer.updatedKunde geändertvisit.createdBesuch erfassttransaction.createdVerkauf von einer Kasse erhaltenpoints.addedPunkte hinzugefügtreward.unlockedPrämie freigeschaltetreward.redeemedPrämie eingelöstwallet.updatedWallet-Karte hinzugefügtautomation.triggeredAutomatische Nachricht gesendet
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex"));
const received = Buffer.from(parts.v1 ?? "");
return received.length === expected.length && crypto.timingSafeEqual(expected, received);
}Header: Fidelitas-Signature, Fidelitas-Event-Id (bei jedem neuen Versuch identisch: damit entduplizieren), Fidelitas-Event-Type.
Fehler, Limits, Idempotenz
- Fehler im Format
{ "error": "message lisible", "code": "VALIDATION_ERROR", "details": [ … ] }– 400 unlesbare Anfrage, 401 ungültiger Schlüssel, 403 fehlende Berechtigung (INSUFFICIENT_SCOPE), 402 inaktives Abonnement, 404 nicht gefunden, 409 Konflikt, 422 ungültige Daten, 429 Limit erreicht. - 600 Anfragen pro Minute und Geschäft über alle Adressen hinweg; das Anlegen eines Kunden (120), die Kassencodes (300), der Kampagnenversand und das Hinzufügen eines Webhooks (30) haben zusätzlich ihre eigene Ratenbegrenzung. Header
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-ResetundRetry-After. Idempotency-Keybei Schreibvorgängen: Derselbe Schlüssel mit derselben Anfrage liefert 24 Stunden lang dieselbe Antwort (HeaderIdempotent-Replayed: true), ohne doppelte Wirkung; mit einer anderen Anfrage: 422.- Jede Antwort enthält
Fidelitas-Api-VersionundX-Request-Id(beim Support angeben). Inkompatible Änderungen erscheinen in einer neuen Version, die vorab angekündigt wird.
Angebundene Kassen
Verbindung aus dem Händlerbereich, ohne Entwicklung. Jede andere Kasse wird über die API oben angebunden, oder individuell, auf Anfrage (Pro-Paket). Heute verfügbare Kassen:
- Hiboutik VerfügbarEchtzeit · Kunde übermittelt
Sie sind Kassenhersteller und an einem nativen Konnektor interessiert? Schreiben Sie uns.