API REMYZ

Reliez un logiciel de caisse ou un site e-commerce au programme de fidélité : retrouver un client (nom, téléphone, carte QR), lire son solde, enregistrer un achat qui crédite les points, rembourser, utiliser une récompense — et être prévenu de chaque événement par webhook.

Spécification machine : OpenAPI 3.1 · URL de base : https://remyz.fr/api/v1

Démarrer

1. Un propriétaire ou administrateur du commerce crée une clé dans Paramètres › API & webhooks (lecture seule, ou lecture et écriture). La clé n'est affichée qu'une fois.
2. Votre logiciel l'envoie à chaque appel ; la clé désigne le commerce : aucun identifiant d'organisation n'est à fournir.
3. Pour être prévenu des achats, remboursements, etc. faits en boutique, ajoutez un webhook (adresse HTTPS).

curl "https://remyz.fr/api/v1/customers?q=06%2096%2012%2034%2056" \
  -H "Authorization: Bearer rmz_k7f3q9xz_…"

Authentification et limites

En-tête Authorization: Bearer <clé> sur chaque requête, en HTTPS. Une clé révoquée est refusée immédiatement (401 api_key_revoked). Portées :

• lecture : clients, soldes et historiques, achats, récompenses, établissements ;
• écriture (inclut la lecture) : créer un client, enregistrer un achat, rembourser, utiliser une récompense. Une clé en lecture seule reçoit 403 insufficient_scope sur une écriture.

Appelez l'API depuis votre serveur : une clé ne doit jamais figurer dans le code d'une page web ou d'une application mobile (l'API n'autorise pas les appels directs des navigateurs).

Limite : 120 requêtes par minute et par clé. Au-delà : 429 rate_limited avec l'en-tête Retry-After (secondes). Les opérations faites par l'API apparaissent dans le journal d'activité du commerce avec le nom de la clé.

Conventions

Chaque réponse authentifiée réussie inclut unit : points ou tampons, selon le programme du commerce. Les noms existants (pointsBalance, pointsEarned, pointsCost, missingPoints…) restent inchangés ; leurs nombres utilisent cette unité. Les webhooks conservent leur format actuel.

• JSON en entrée et en sortie ; montants en centimes entiers (5250 = 52,50 €) ; dates ISO 8601 (UTC).
• Les champs inconnus sont refusés (une faute de frappe ne passe pas inaperçue).
• Listes paginées par curseur : ?limit=25 (100 au plus), réponse { "data": [...], "hasMore": true, "nextCursor": "…" }, page suivante avec ?cursor=<nextCursor>. Tri : plus récent d'abord.
• Chaque réponse porte un en-tête X-Request-Id à communiquer au support.

Idempotence

Les écritures d'argent ou de points (POST /purchases, POST /purchases/{id}/refunds, POST /rewards/{id}/redemptions) exigent un en-tête Idempotency-Key : 8 à 100 caractères (lettres, chiffres, _ . : -), unique par opération — par exemple le numéro de ticket. En cas de coupure réseau, renvoyez exactement la même requête avec la même clé : l'opération n'est faite qu'une fois et la réponse initiale revient (200 et Idempotent-Replayed: true). La même clé avec un contenu différent donne 409 idempotency_conflict.

Erreurs

Format unique, message en français lisible par un humain, détail par champ pour la validation :

HTTP/1.1 400 Bad Request
{
  "error": {
    "code": "validation_error",
    "message": "Certains paramètres sont invalides.",
    "details": [{ "path": "amountCents", "message": "Le montant : nombre entier de centimes attendu" }],
    "requestId": "req_Xb2…"
  }
}

Un identifiant appartenant à un autre commerce répond 404, exactement comme un identifiant inexistant.

Clients

curl -X POST https://remyz.fr/api/v1/customers \
  -H "Authorization: Bearer rmz_k7f3q9xz_…" -H "Content-Type: application/json" \
  -d '{ "firstName": "Hélène", "lastName": "Joseph", "phone": "0696 12 34 56" }'

Achats et remboursements

curl -X POST https://remyz.fr/api/v1/purchases \
  -H "Authorization: Bearer rmz_k7f3q9xz_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-2026-000123" \
  -d '{ "customerId": "4f0c…", "amountCents": 5200, "reference": "T-000123" }'

HTTP/1.1 201 Created
{ "purchase": { "id": "…", "amountCents": 5200, "pointsEarned": 52, "status": "COMPLETED", … },
  "customer": { "id": "4f0c…", "pointsBalance": 214 }, "belowMinimum": false, "referral": { "qualified": false } }

curl -X POST https://remyz.fr/api/v1/purchases/9a1e…/refunds \
  -H "Authorization: Bearer rmz_k7f3q9xz_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: avoir-2026-000045" \
  -d '{ "amountCents": 1500, "reason": "Article retourné" }'

Récompenses et établissements

Webhooks

Pour chaque événement choisi, REMYZ envoie un POST JSON à votre adresse HTTPS. L'événement est enregistré dans la même transaction que l'opération : il n'existe que si elle a réussi.

POST /votre/adresse HTTP/1.1
Content-Type: application/json; charset=utf-8
Remyz-Signature: t=1792072800,v1=5f2b…
Remyz-Event-Id: 0b6f…
Remyz-Event-Type: transaction.created
Remyz-Delivery-Id: 77c1…

{ "id": "0b6f…", "type": "transaction.created", "apiVersion": "v1", "createdAt": "2026-10-15T14:00:00.000Z",
  "organizationId": "…",
  "data": { "purchase": { "id": "…", "reference": "T-000123", "amountCents": 5200, "pointsEarned": 52, … },
            "customer": { "id": "4f0c…", "pointsBalance": 214 } } }

• Aucune donnée personnelle (nom, e-mail, téléphone, motif) dans les événements : relisez la fiche avec GET /customers/{id} si besoin.
• Répondez 2xx en moins de 10 s (traitez ensuite en arrière-plan). Toute autre réponse, une redirection ou un délai dépassé déclenche une reprise : 30 s, 1,5 min, 4,5 min, 13,5 min, 40,5 min, 2 h, 6 h — puis abandon après 8 essais. L'historique et le bouton « Renvoyer » sont dans Paramètres › API & webhooks.
• Livraison « au moins une fois », ordre non garanti : dédupliquez avec Remyz-Event-Id (identique à chaque reprise et à chaque renvoi).
• Sécurité : adresses HTTPS uniquement, sans identifiants dans l'URL ; les adresses qui désignent ou résolvent vers un réseau privé ou local (127.0.0.1, 10.x, 192.168.x, 169.254.x, fc00::/7…) sont refusées, à l'enregistrement comme à chaque envoi.

Vérifier la signature

Remyz-Signature: t=<horodatage>,v1=<signature> où la signature est le HMAC-SHA256 (hexadécimal) de la chaîne <t>.<corps brut>, avec pour clé le secret du webhook (whsec_…, affiché à sa création). Calculez-la sur le corps brut reçu (avant toute analyse JSON), comparez en temps constant et refusez un horodatage de plus de 5 minutes (rejeu).

// Node.js (Express : app.post("/remyz", express.raw({ type: "application/json" }), handler))
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyRemyz(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const received = Buffer.from(parts.v1 ?? "", "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

# PHP
[$t, $v1] = [null, null];
foreach (explode(',', $_SERVER['HTTP_REMYZ_SIGNATURE']) as $p) { [$k, $v] = explode('=', $p, 2); if ($k === 't') $t = $v; if ($k === 'v1') $v1 = $v; }
$ok = abs(time() - (int)$t) <= 300
   && hash_equals(hash_hmac('sha256', $t . '.' . file_get_contents('php://input'), $secret), $v1);

Une question d'intégration ? Écrivez-nous en indiquant l'en-tête X-Request-Id de la réponse concernée.