API REST et webhooks | Krealo Wallet

Authentification

Créez une clé dans le panneau (API et webhooks). Chaque clé donne accès à une seule entreprise. Envoyez-la dans l’en-tête Authorization.

Authorization: Bearer kw_live_…

Erreurs et limites

Une erreur répond { "error": { "code", "message" } } avec le code HTTP correspondant (400, 401, 402 abonnement inactif, 403 forfait sans API, 404, 429). Limites : 300 requêtes par minute et par clé, et un quota par jour selon le forfait (essai 500, Pro 10 000, Entreprise 100 000). Chaque réponse indique X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; un 429 ajoute Retry-After (secondes).

Idempotence

Les opérations qui émettent ou font bouger un solde acceptent l’en-tête Idempotency-Key : la même clé pendant 24 h renvoie la même réponse sans refaire l’opération (en-tête Idempotent-Replayed: true).

Points d’accès

Toutes les routes, générées depuis notre contrat OpenAPI 3.1. Ouvrez une route pour voir un exemple curl.

https://wallet.krealomedia.com/api/v1/openapi.json

Postman → Import → collez l’URL du contrat OpenAPI. Insomnia, Bruno et les générateurs de SDK l’acceptent aussi.

Importer dans Postman

Modèles de carte

Company

Clients

Cartes émises

Mouvements

Notifications

Webhooks

Exemple : émettre une carte et ajouter un tampon

curl -X POST https://wallet.krealomedia.com/api/v1/passes \
  -H "Authorization: Bearer kw_live_…" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"TEMPLATE_ID","customer":{"name":"Demo Customer","email":"demo@example.com"}}'

curl -X POST https://wallet.krealomedia.com/api/v1/passes/PASS_ID/stamps \
  -H "Authorization: Bearer kw_live_…" \
  -H "Content-Type: application/json" -d '{"count":1}'

Webhooks

Nous envoyons un POST JSON à votre URL HTTPS pour chaque événement. Répondez 2xx en moins de 10 s ; sinon nous réessayons après 1 min, 5 min, 30 min, 2 h et 12 h. Vérifiez la signature avec le secret reçu à la création.

customer.created (client créé, quelle que soit l’origine), pass.voided (carte annulée), pass.expired (carte arrivée à échéance, une fois), reward.ready (le client atteint une récompense, une fois par seuil). Dans le panneau, « Envoyer un événement test » envoie un événement ping signé ; une livraison en échec peut être renvoyée. Après 3 événements non livrés de suite, le webhook est désactivé et les administrateurs reçoivent un courriel.

pass.issuedpass.installedpass.removedpoints.changedreward.redeemedbalance.changedcustomer.createdpass.voidedpass.expiredreward.ready

POST https://your-server.example/hook
Krealo-Event: points.changed
Krealo-Signature: t=1760300000,v1=5f2b…

{ "id": "evt_…", "type": "points.changed", "created": "2026-10-12T20:00:00.000Z",
  "data": { "pass": { "id": "…", "stamps": 4, … }, "movement": { "operation": "sumar", "before": 3, "after": 4 } } }

Vérifier la signature (Node.js)

import crypto from 'node:crypto';

// header = req.headers['krealo-signature'], body = le corps BRUT (texte, avant JSON.parse)
export function verify(header, body, secret) {
  if (typeof header !== 'string') return false;
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? '')) return false;
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(parts.v1, 'hex'), Buffer.from(expected, 'hex'));
}

Shopify

Installez l’application Krealo Wallet dans votre boutique, puis reliez-la à votre entreprise depuis le panneau (Intégrations → Shopify). Chaque commande payée ajoute des tampons ou des points sur la carte choisie, et chaque nouveau client reçoit sa carte de bienvenue ; son lien d’installation est enregistré dans le métachamp client krealo_wallet.install_url. Inclus dans tous les forfaits.

Sans attendre l’application : le guide Shopify Flow

Shopify Flow → Krealo Wallet (sans application)

Chaque commande payée ajoute un tampon, des points ou de la remise en argent sur la carte du client, et crée la carte s’il n’en a pas encore. Il faut le forfait Pro ou Entreprise de Krealo Wallet, et une boutique Shopify Grow, Advanced ou Plus (l’action « Send HTTP request » de Flow n’existe pas en Basic). Comptez 10 minutes.

Dans Krealo Wallet, ouvrez Intégrations → API et clés et créez une clé. Copiez-la tout de suite (elle commence par kw_live_ et ne s’affiche qu’une fois).
Toujours dans Krealo Wallet, ouvrez Cartes puis la carte fidélité à utiliser (elle doit être publiée). Son identifiant est la fin de l’adresse dans le navigateur, après /plantillas/ : copiez-le.
Dans Shopify, installez l’application gratuite Shopify Flow depuis le Shopify App Store, puis ouvrez-la et créez un flux de travail.
Choisissez le déclencheur « Order paid ».
Ajoutez l’action « Send HTTP request ». HTTP method : POST. URL : https://wallet.krealomedia.com/api/v1/purchases
Headers : ajoutez Key « Authorization » avec Value « Bearer » suivi d’un espace et de votre clé ; puis Key « Content-Type » avec Value « application/json ». Conseil : enregistrez la clé avec « Add secret » pour qu’elle n’apparaisse jamais en clair.
Body : collez le texte ci-dessous et remplacez TEMPLATE_ID par l’identifiant copié à l’étape 2. Les {{…}} sont remplis par Shopify à chaque commande : ne les modifiez pas.
Pour les réponses 4XX choisissez « Fail » ; pour 5XX/429 laissez « Retry ». Rien ne compte en double : la même commande envoyée deux fois n’est ajoutée qu’une fois.
Activez le flux de travail (Turn on workflow).

Body à coller :

{
  "template_id": "TEMPLATE_ID",
  "email": "{{order.email}}",
  "phone": "{{order.phone}}",
  "name": "{{order.customer.displayName}}",
  "amount": "{{order.totalPriceSet.shopMoney.amount}}",
  "order_id": "{{order.id}}",
  "source": "shopify-flow"
}

Tester : passez une commande de test avec un courriel à vous et capturez le paiement. Dans Shopify Flow, l’onglet de l’historique des exécutions montre la réponse (200 = c’est bon). Dans Krealo Wallet, ouvrez Clients : le client apparaît avec sa carte et le mouvement dans son historique. À la première commande, la réponse contient install_links : le lien pour ajouter la carte à Apple Wallet ou Google Wallet.

Quand une carte est créée par POST /purchases (Shopify Flow), le client la reçoit par courriel s’il a une adresse. Avec Twilio connecté, il la reçoit aussi par texto s’il a un téléphone : un message court, dans sa langue (FR, EN, ES), avec le nom de votre entreprise et le lien d’installation (raccourci avec Krealo QR s’il est connecté). Les clients qui répondent STOP ne reçoivent plus de textos. Carte envoyée par courriel et par texto (Twilio)

Problèmes fréquents

401 : la clé est absente ou mal copiée. Vérifiez « Bearer » + espace + la clé complète, ou créez-en une nouvelle.
403 : votre forfait Krealo Wallet n’inclut pas l’API. Passez au forfait Pro ou Entreprise.
400 « email or phone is required » : la commande n’a ni courriel ni téléphone (vente sans client). Rien n’est ajouté ; c’est normal.
400 sur template_id ou 404 : l’identifiant de la carte est mal copié, ou ce n’est pas une carte fidélité (tampons, points ou remise en argent).

Carte envoyée par courriel et par texto (Twilio)

Quand une carte est créée par POST /purchases (Shopify Flow), le client la reçoit par courriel s’il a une adresse. Avec Twilio connecté, il la reçoit aussi par texto s’il a un téléphone : un message court, dans sa langue (FR, EN, ES), avec le nom de votre entreprise et le lien d’installation (raccourci avec Krealo QR s’il est connecté). Les clients qui répondent STOP ne reçoivent plus de textos.

Dans Krealo Wallet, ouvrez Intégrations → Twilio (SMS) (forfait Pro ou Entreprise).
Collez l’Account SID et l’Auth Token de votre console Twilio (Account Info), ou une clé API (SK… + secret).
Expéditeur : votre numéro Twilio (+15145550000) ou un Messaging Service SID (MG…). Cliquez Connecter Twilio : les identifiants sont vérifiés auprès de Twilio puis chiffrés.
Envoyez un SMS de test à votre numéro. La carte indique Connectée.

Dans l’API : send_email et send_sms (vrai par défaut dans /purchases quand la carte est créée) ; dans POST /passes et l’outil MCP issue_pass, enviarCorreo et send_sms sont optionnels. La réponse contient email_sent et sms_sent {sent, error}. Sans Twilio, sms_sent.error vaut twilio_not_configured et le courriel part comme d’habitude.

Serveur MCP (Claude et autres agents)

Gérez vos cartes depuis Claude : ajoutez un connecteur personnalisé avec l’URL ci-dessous. La connexion se fait avec votre compte (OAuth) et vous choisissez l’entreprise ; un agent qui ne gère pas OAuth peut utiliser une clé d’API.

https://wallet.krealomedia.com/mcp

Zapier

Reliez Krealo Wallet à plus de 7 000 applications sans écrire de code. Déclencheurs : carte émise, récompense utilisée, client créé. Actions : créer un client, émettre une carte (avec son lien d’installation), ajouter des tampons.

L’application Zapier est en accès sur invitation : ouvrez le lien ci-dessous (ou demandez-le à Krealo) et acceptez l’invitation.
Dans Zapier, créez un Zap et cherchez « Krealo Wallet ».
À la connexion, collez une clé d’API (voir Authentification) ; la connexion prend le nom de votre entreprise.

Accepter l’invitation Zapier

Bouton « Ajouter à mon Wallet »

Ajoutez sur votre site un bouton qui ouvre l’inscription à votre carte fidélité ou à votre coupon. Le code de chaque carte est dans le panneau (Lien et QR d’inscription) : collez-le là où le bouton doit apparaître.

<script src="https://wallet.krealomedia.com/embed.js" data-carte="/u/ORG_ID/CARD_ID" data-lang="fr" async></script>

data-carte accepte le chemin /u/… ou l’URL complète de l’inscription. Sans data-lang, le bouton prend la langue de la page (fr, en ou es). Il fonctionne avec une CSP stricte : ajoutez seulement https://wallet.krealomedia.com à script-src.

API Krealo Wallet

Authentification

Erreurs et limites

Idempotence

Points d’accès

Modèles de carte

GET /templatesLister les modèles

POST /templatesCréer un modèle

GET /templates/{id}Lire un modèle

PATCH /templates/{id}Modifier un modèle (seulement les champs envoyés)

POST /templates/{id}/imageUpload the logo or icon of a template (PNG by https URL or base64), resized like the panel does

Company

GET /companyGet the company profile (shown on the back of every pass)

PATCH /companyUpdate the company profile (only the fields sent; branches replaces the list). Passes update.

PUT /company/logoUpload the company logo (PNG by https URL or base64)

POST /company/branchesAdd a branch

PATCH /company/branches/{index}Edit a branch (index from 0; only the fields sent)

DELETE /company/branches/{index}Remove a branch (index from 0)

Clients

GET /customersLister ou chercher des clients

POST /customersCréer un client

GET /customers/{id}Lire un client

PATCH /customers/{id}Modifier un client

DELETE /customers/{id}Supprimer un client ; ses cartes sont annulées et anonymisées

Cartes émises

GET /passesLister les cartes émises

POST /passesÉmettre une carte (renvoie les liens d’installation)

GET /passes/lookupTrouver une carte par le code scanné au comptoir (série ou id)

GET /passes/{id}Lire une carte

POST /passes/{id}/stampsAjouter des tampons

POST /passes/{id}/pointsAjouter des points

POST /passes/{id}/purchaseEnregistrer un achat (tampon, points ou remise en argent)

POST /purchasesEnregistrer un achat par courriel ou téléphone : trouve ou crée le client, émet la carte au besoin (Shopify Flow, caisse). Idempotent par order_id

POST /passes/{id}/redeemUtiliser une récompense, un coupon ou un montant du solde

POST /passes/{id}/balanceSolde de carte-cadeau : charger, débiter ou fixer

POST /passes/{id}/voidAnnuler une carte

Mouvements

GET /passes/{id}/movementsHistorique d’une carte, du plus récent au plus ancien

GET /movementsTous les mouvements depuis une date, du plus ancien au plus récent (synchroniser une caisse ou un CRM)

Notifications

GET /notificationsLes 50 dernières notifications

POST /notificationsEnvoyer une notification sur l’écran verrouillé

Webhooks

GET /webhooksLister les webhooks

POST /webhooksCréer un webhook (le secret n’est renvoyé qu’une fois)

DELETE /webhooks/{id}Supprimer un webhook

GET /webhooks/{id}/deliveriesLes 50 dernières livraisons d’un webhook

Exemple : émettre une carte et ajouter un tampon

Webhooks

Vérifier la signature (Node.js)

Shopify

Shopify Flow → Krealo Wallet (sans application)

Problèmes fréquents

Carte envoyée par courriel et par texto (Twilio)

Serveur MCP (Claude et autres agents)

Zapier

Bouton « Ajouter à mon Wallet »