Brancher une caisse, une borne ou un scanner

Premier crédit en trente minutes

1. 1 · Obtenir un jeton

   Deux chemins, selon ce que vous branchez. Une borne ou une tablette s'appaire avec le code à six chiffres de l'établissement, comme le ferait un employé. Un système déjà en place — caisse, CRM — utilise une clé d'organisation, créée par le commerçant dans Paramètres → Développeurs.

   curl -X POST https://fidapp.fr/api/v1/devices/pair \
     -H 'content-type: application/json' \
     -d '{"accessCode":"482913","deviceName":"Borne entrée"}'
   
   # → { "deviceToken": "fid_dev_…", "expiresAt": "…", "scopes": [...] }

2. 2 · Vérifier qui parle

   Premier réflexe de toute intégration. La réponse dit l'enseigne, l'établissement, les droits et le débit accordé — de quoi savoir tout de suite si vous tenez la bonne clé.

   curl https://fidapp.fr/api/v1/me \
     -H 'authorization: Bearer fid_dev_…'

3. 3 · Identifier le client

   Par le QR de sa carte, par son identifiant dicté au comptoir (K7QM-3XA9), ou par son téléphone. Le téléphone et l'email passent par POST : un numéro dans une URL finit dans les journaux d'accès de chaque intermédiaire, et s'y conserve des mois.

   curl "https://fidapp.fr/api/v1/members/lookup?qr=${QR}" \
     -H "authorization: Bearer ${TOKEN}"

4. 4 · Créditer le passage

   La clé d'idempotence se génère avant l'envoi et se réutilise telle quelle à chaque réessai. C'est elle qui transforme une reprise réseau en non-événement plutôt qu'en double crédit. La réponse contient le nouveau solde, la promotion appliquée et la récompense éventuellement débloquée : rien d'autre à demander pour afficher l'écran de confirmation.

   curl -X POST https://fidapp.fr/api/v1/members/${ID}/earn \
     -H "authorization: Bearer ${TOKEN}" \
     -H "idempotency-key: $(uuidgen)" \
     -H 'content-type: application/json' \
     -d '{"amountCents": 1250}'

Trois règles qui décident de la qualité d'une intégration

Les 14 routes

Générées depuis la spécification, elle-même tirée des schémas qui valident les requêtes. Cette liste ne peut pas être en retard sur le serveur.

Droits

Une clé porte les droits qu'on lui donne, et rien de plus. Une borne posée en salle reçoit les trois premiers : elle doit pouvoir créditer, pas reconfigurer le programme.

pos:read

Identifier un client et lire son solde

pos:write

Créditer un passage et utiliser une récompense

members:read

Lire la base clients

members:write

Inscrire et modifier des clients

programs:read

Lire les programmes, récompenses et paliers

programs:write

Configurer les programmes

analytics:read

Lire les analyses et exporter

webhooks:manage

Gérer les notifications sortantes

Erreurs

Branchez votre logique sur code, jamais sur message : le premier est stable pour toute la durée de la version, le second est du français destiné à un écran, que nous nous réservons de réécrire. Chaque réponse porte un requestId — c'est ce que le support vous demandera.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Solde insuffisant : 3 tampons sur les 10 requis.",
    "details": { "required": 10, "available": 3 },
    "requestId": "01J9X2K…"
  }
}

Notifications sortantes

Pour la caisse, la réponse de earn suffit : elle contient déjà le nouveau solde et la récompense débloquée. Les notifications servent au reste — tenir votre propre fichier client à jour, réagir à une montée de palier survenue entre deux visites, sans nous interroger en boucle. Le commerçant déclare son adresse dans Paramètres → Développeurs.

member.joined

Un client s'inscrit à un programme

transaction.created

Un passage est crédité

transaction.cancelled

Une opération est annulée

reward.earned

Une récompense est débloquée

reward.redeemed

Une récompense est utilisée

tier.upgraded

Un client atteint un palier supérieur

membership.updated

Le solde ou l'état d'une adhésion change

Livraison au moins une fois. En cas de doute — un délai d'attente sur une requête qui a peut-être abouti — nous réessayons. Dédupliquez sur id, qui identifie le fait et non la livraison. L'ordre n'est pas garanti.

Réessais après 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h, 24 h. Au-delà, la livraison est abandonnée — mais votre adresse continue de recevoir les événements suivants, jusqu'à trois jours d'échecs consécutifs. Un serveur réparé le mardi soir reprend donc le fil tout seul.

POST /votre-adresse
content-type:    application/json
fid-signature:   t=1758724800,v1=<hex>
fid-event-id:    01J9X2K…       ← dédupliquez là-dessus
fid-event-type:  transaction.created
fid-attempt:     1

Vérifiez la signature. Sans cette étape, n'importe qui connaissant votre adresse peut vous faire croire à un passage. L'horodatage fait partie de ce qui est signé : une requête interceptée cesse d'être valable au bout de cinq minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.trim().split("=")),
  );

  // Fenêtre anti-rejeu.
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

Le corps doit être lu brut, avant tout analyseur JSON : une re-sérialisation change les espaces et l'ordre des clés, et l'empreinte ne correspond plus.

Il n'existe pas d'événement de descente de palier, et il n'en existera pas. Une montée se célèbre, une descente se constate en silence : prévenir quelqu'un qu'il perd son statut ne le fait pas revenir, ça lui fait désinstaller sa carte.

Débit et offres

L'accès par clé fait partie des offres Pro et Business. Les appareils appairés, eux, fonctionnent sur toutes les offres — c'est la console caisse, elle est incluse partout.

Un forfait épuisé n'arrête jamais le comptoir. Créditer un passage et utiliser une récompense passent quoi qu'il arrive : le client d'un commerçant n'a pas à payer un différend d'abonnement entre ce commerçant et nous. Ce sont les lectures qui ralentissent.