API Fidel'me
Une API REST simple pour brancher votre caisse, votre site, ou tout outil externe sur vos données de fidélité — inscriptions, visites, récompenses, statistiques.
🔑 Authentification
Chaque requête doit porter votre clé API dans l'en-tête X-Api-Key (ou, à défaut, en paramètre d'URL ?api_key=…). Retrouvez votre clé dans votre espace commerçant, onglet API & Export — vous pouvez la régénérer à tout moment si elle a fuité.
curl -H "X-Api-Key: fmk_votre_cle" \ https://fidel-me.fr/api/v1/customers
⏱️ Limites de débit
180 requêtes par minute et par endpoint, par clé API. Au-delà, l'API répond 429 avec un en-tête Retry-After (en secondes). Largement suffisant pour une caisse qui encaisse un ticket à la fois — contactez-nous si votre usage est différent.
📖 Lecture
Réponse
{
"company": "Café Lumière",
"count": 312,
"customers": [
{ "id": 42, "name": "Camille Martin", "email": "camille@mail.fr",
"visits": 7, "total_spent": 84.5, "stamps": 7,
"token": "a1b2c3…", "segment": "Fidèle", "rfm_segment": "Champions" }
]
}
token (le même identifiant que celui encodé dans le QR code imprimé sur sa carte).Réponse — 404 si le jeton est inconnu
{ "id": 42, "name": "Camille Martin", "visits": 7, "stamps": 7,
"segment": "Fidèle", "rfm_segment": "Champions", "program_id": 3 }
program_id à passer lors d'une inscription.Réponse
{ "programs": [
{ "id": 3, "name": "Carte café", "type": "stamps", "stamps_required": 10, "reward": "Café offert" }
] }
Réponse
{ "company": "Café Lumière",
"kpis": { "clients": 312, "atRisk": 14, … },
"segments": { "Champion": 28, "Fidèle": 64, … } }
✍️ Écriture
Corps de la requête
| name | requis | Nom du client |
| optionnel | ||
| phone | optionnel | |
| program_id | optionnel | Sinon, la première carte active du commerce est utilisée |
curl -X POST -H "X-Api-Key: fmk_…" \ -H "Content-Type: application/json" \ -d '{"name":"Camille","email":"c@mail.fr"}' \ https://fidel-me.fr/api/v1/enroll
{ "token": "a1b2c3…",
"card_url": "https://fidel-me.fr/card.html?t=…" }
Corps de la requête
| token | requis | Jeton du client (QR code de sa carte) |
| amount | voir note | Montant du ticket, en euros |
| note | voir note | Commentaire libre |
Au moins amount ou note est requis, pour garder une trace de chaque visite.
curl -X POST -H "X-Api-Key: fmk_…" \ -H "Content-Type: application/json" \ -d '{"token":"a1b2c3…","amount":12.5}' \ https://fidel-me.fr/api/v1/scan
{ "ok": true, "stamps": 8, "reward": false,
"type": "stamps", "message": "Tampon ajouté !" }
Corps de la requête
| token | requis | Jeton du client |
curl -X POST -H "X-Api-Key: fmk_…" \ -H "Content-Type: application/json" \ -d '{"token":"a1b2c3…"}' \ https://fidel-me.fr/api/v1/redeem
{ "ok": true, "message": "Café offert" }
🪝 Webhooks
Recevez un POST JSON sur votre propre URL à chaque événement — pas besoin d'interroger l'API en boucle. Configurez l'URL de destination depuis l'onglet API & Export de votre espace commerçant.
Événements disponibles
Format de la charge utile
{
"event": "visit",
"company_id": 7,
"at": "2026-09-02T10:14:00.000Z",
"data": { "customer": "Camille Martin", "token": "a1b2c3…", "amount": 12.5 }
}
Vérifier la signature
Chaque envoi porte l'en-tête X-Fidelme-Signature: t=<horodatage>,v1=<signature>. La signature est un HMAC-SHA256 (hexadécimal) de la chaîne t + "." + corps brut de la requête, calculé avec le secret de signature affiché à côté de votre webhook dans l'onglet API & Export. Recalculez-la de votre côté, comparez, et refusez les appels dont l'horodatage a plus de 5 minutes.
const [t, v1] = header.split(',').map(p => p.split('=')[1]); const ok = crypto.createHmac('sha256', SECRET).update(t + '.' + rawBody).digest('hex') === v1;