Créditer une commande en ligne sur la carte de fidélité

Créditez les points de fidélité des commandes passées sur votre site selon leur montant, sans geste de l'équipe : membre, crédit, renvoi sans doublon.

Documentation de l'APIGuides · Commandes en ligne et fidélité

Ce que fait l'intégration

Votre site de commande en ligne ou votre caisse envoie chaque commande validée à Ma Belle Note. La carte de fidélité de l'acheteur est créditée selon le montant, exactement comme un crédit fait au comptoir par l'équipe : mêmes tranches de dépense, mêmes plafonds, mêmes récompenses. L'équipe n'a rien à faire. Elle remet la récompense sur place, avec l'écran habituel, quand le client vient chercher sa commande.

Deux opérations, en version bêta :

OpérationRôle
GET /v1/loyalty/membersSavoir si un email appartient à un membre du programme.
POST /v1/loyalty/creditsCréditer une commande sur la carte du membre.

Avant de commencer

  1. Un programme de fidélité actif sur l'établissement. En mode « Selon le montant dépensé », les points suivent les tranches du programme. En mode « À chaque passage », chaque commande rapporte les points par défaut du programme.
  2. Une clé API avec le droit loyalty:credit, présenté dans l'application sous le nom « Créditer les cartes de fidélité ». Elle se crée dans Réglages › Intégration, API & webhooks. L'API est incluse dans le plan Pro et dans l'essai gratuit.
  3. Des appels depuis votre serveur, jamais depuis le navigateur : la clé ne doit pas être visible des clients.

Comment le client devient membre

Le client s'inscrit lui-même au programme, par l'adresse ou le QR code d'inscription du programme, et confirme son email. Mettez cette adresse en évidence sur votre site, par exemple dans la page de confirmation de commande. Seuls les membres confirmés sont crédités, et le client doit commander avec l'email de son inscription. Une commande passée avant l'inscription n'est pas créditée après coup.

Rédigez les règles du programme dans l'application (Fidélité, votre programme, Modifier, champ « Règles du programme ») : elles s'affichent sur la page d'inscription. Par exemple : « Les commandes en ligne passées avec l'email de votre inscription sont créditées automatiquement. Les commandes passées avant l'inscription ne le sont pas. » Ma Belle Note n'ajoute aucune mention de lui-même.

1. Vérifier que l'acheteur est membre (facultatif)

Pour afficher « Vous gagnerez des points » ou « Inscrivez-vous pour gagner des points » au moment de la commande :

curl -G https://api.mabellenote.com/v1/loyalty/members \
  -H "Authorization: Bearer $MBN_API_KEY" \
  --data-urlencode "establishmentId=kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p" \
  --data-urlencode "[email protected]"
{
  "object": "loyalty_member",
  "id": "lm5n8q1t4w7z0c3f6i9l2o5r8u1x4a7d",
  "establishmentId": "kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p",
  "programId": "lp7r0u3x6a9d2g5j8m1p4s7v0y3b6e9h",
  "contactId": "ct9x2b5d8f1h4j7l0n3p6r9t2v5x8z1b",
  "contactExternalId": null,
  "balance": 12,
  "nextReward": { "label": "Un dessert offert", "pointsRequired": 15, "pointsRemaining": 3 },
  "joinedAt": "2026-11-02T18:40:00.000Z"
}

Un email inconnu, une inscription pas encore confirmée ou un membre d'un autre programme répondent tous 404 member_not_found.

2. Créditer la commande validée

Appelez l'opération dès que la commande est validée, avec le montant TTC en centimes et la référence de la commande dans votre système :

curl https://api.mabellenote.com/v1/loyalty/credits \
  -H "Authorization: Bearer $MBN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "establishmentId": "kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p",
    "email": "[email protected]",
    "amountCents": 3450,
    "orderReference": "CMD-2026-11-17-0042",
    "orderedAt": "2026-11-17T11:30:00.000Z"
  }'
ChampRôle
establishmentIdÉtablissement où la commande est passée. Il désigne le programme, même si ce programme couvre plusieurs établissements.
emailEmail de l'acheteur, celui de son inscription au programme.
amountCentsMontant TTC de la commande, en centimes, entier positif.
orderReferenceRéférence unique et stable de la commande, de 1 à 128 caractères. Elle empêche tout double crédit.
orderedAtDate de la commande, facultative, conservée à titre d'information. Elle ne peut pas être dans le futur.

Avec les tranches 1 € : 1 point, 10 € : 3 points, 30 € : 5 points, une commande de 34,50 € rapporte 5 points :

{
  "object": "loyalty_order_credit",
  "alreadyRecorded": false,
  "credit": {
    "object": "loyalty_points_credit",
    "id": "mv2c5f8i1l4o7r0u3x6a9d2g5j8m1p4s",
    "memberId": "lm5n8q1t4w7z0c3f6i9l2o5r8u1x4a7d",
    "establishmentId": "kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p",
    "programId": "lp7r0u3x6a9d2g5j8m1p4s7v0y3b6e9h",
    "contactId": "ct9x2b5d8f1h4j7l0n3p6r9t2v5x8z1b",
    "contactExternalId": null,
    "points": 5,
    "amountCents": 3450,
    "orderReference": "CMD-2026-11-17-0042",
    "source": "api",
    "balance": 17,
    "creditedAt": "2026-11-17T11:32:08.000Z"
  },
  "rewards": [
    {
      "object": "loyalty_reward",
      "id": "gn8k1n4q7t0w3z6c9f2i5l8o1r4u7x0a",
      "memberId": "lm5n8q1t4w7z0c3f6i9l2o5r8u1x4a7d",
      "establishmentId": "kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p",
      "programId": "lp7r0u3x6a9d2g5j8m1p4s7v0y3b6e9h",
      "contactId": "ct9x2b5d8f1h4j7l0n3p6r9t2v5x8z1b",
      "contactExternalId": null,
      "tierRank": 2,
      "label": "Un dessert offert",
      "issuedAt": "2026-11-17T11:32:08.000Z",
      "usableFrom": "2026-11-17T11:32:08.000Z",
      "expiresAt": "2026-12-17T11:32:08.000Z"
    }
  ]
}

rewards liste les récompenses débloquées par ce crédit : vous pouvez annoncer au client qu'une récompense l'attend au retrait. Le crédit met à jour sa carte, y compris dans son Wallet, et produit les événements loyalty_points.credited, d'origine api, et loyalty_reward.issued, livrés à vos webhooks. Dans l'application, l'historique de la carte affiche le crédit avec le badge « via API », le numéro de commande et le nom de la clé.

Les mêmes règles qu'au comptoir

  • Un passage du jour : chaque crédit compte comme un passage, et la limite de passages par jour du programme est partagée avec le comptoir. Au-delà, l'API répond 409 daily_credit_limit_reached.
  • Montant sous la première tranche : le passage est compté, avec 0 point.
  • Date du crédit : le crédit est daté de sa réception. Une commande renvoyée le lendemain compte pour le lendemain.
  • Gros montant : au-delà de 500 €, l'application demande une confirmation à l'équipe. Par l'API, le montant venant de votre système de commande, il est accepté sans confirmation.
  • Commande annulée : rien ne s'annule par l'API. Le commerçant corrige le solde dans l'application, avec un motif.

Renvoyer sans risque

Une commande se crédite une seule fois par membre, quel que soit le nombre d'envois. Si la même orderReference revient, rien n'est crédité de nouveau : la réponse est 200 au lieu de 201, avec alreadyRecorded: true et le crédit d'origine. Vous pouvez donc renvoyer une commande après une coupure réseau ou une réponse 5xx sans risque de doublon. L'en-tête Idempotency-Key est accepté mais n'est pas nécessaire : la référence de commande joue ce rôle.

Ne faites jamais dépendre la commande de cet appel. Si Ma Belle Note ne répond pas, validez la commande, puis renvoyez le crédit plus tard depuis une file d'attente.

Exemple côté serveur

const API = "https://api.mabellenote.com/v1";

export async function creditOnlineOrder(order) {
  const response = await fetch(`${API}/loyalty/credits`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MBN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      establishmentId: order.establishmentId,
      email: order.customerEmail,
      amountCents: order.totalCents,
      orderReference: order.reference,
      orderedAt: order.validatedAt,
    }),
  });

  if (response.ok) {
    const result = await response.json();
    return { status: "credited", points: result.credit.points, rewards: result.rewards };
  }

  const problem = await response.json();
  switch (problem.code) {
    case "member_not_found":
      return { status: "not_a_member" };
    case "daily_credit_limit_reached":
    case "loyalty_program_paused":
    case "loyalty_program_not_active":
      return { status: "not_credited", reason: problem.code };
    case "rate_limited":
      return { status: "retry", afterSeconds: Number(response.headers.get("Retry-After")) };
    default:
      if (response.status >= 500) return { status: "retry", afterSeconds: 60 };
      throw new Error(`Loyalty credit failed: ${problem.code} (${problem.requestId})`);
  }
}

not_a_member et not_credited sont des issues normales : enregistrez-les sans renvoyer. Seuls retry et les erreurs de configuration demandent une action.

Erreurs à traiter

RéponseCauseQue faire
400 invalid_requestChamp manquant ou invalide, ou orderedAt dans le futurCorriger la requête.
403 insufficient_scopeLa clé ne porte pas loyalty:creditCréer une clé avec ce droit.
403 tenant_read_onlyLe compte est en lecture seuleRétablir l'abonnement.
404 not_foundÉtablissement inconnu ou d'un autre compteVérifier establishmentId.
404 member_not_foundL'acheteur n'est pas membre confirmé du programmeNe rien renvoyer. Lui proposer de s'inscrire.
409 loyalty_program_pausedProgramme en pauseNe rien renvoyer.
409 loyalty_program_not_activeProgramme en brouillon ou terminéNe rien renvoyer.
409 daily_credit_limit_reachedCarte déjà créditée le nombre de fois permis aujourd'huiNe rien renvoyer.
422 unprocessableMontant invalideEnvoyer un montant entier positif, en centimes.
429 rate_limitedPlus de 120 appels par minute avec la cléAttendre Retry-After, puis renvoyer la même commande.

Le guide des erreurs décrit le format commun de ces réponses.

Mis à jour le 18 novembre 2026