Documentation · API publique

Connecte ta caisse à Walliko.

Crée la carte de fidélité d’un client et ajoute ses visites automatiquement, depuis ton logiciel de caisse, ton outil de réservation ou ton site. Trois routes, une clé, et c’est branché.

https://api.walliko.fr/public/v1JSON · HTTPS · clé Bearer

Introduction

À quoi ça sert

L’API permet à un autre logiciel de faire, tout seul, ce que ton équipe fait au comptoir avec Walliko Pro : créer la carte d’un client et lui ajouter un tampon (ou des points) à chaque passage. La carte se met à jour aussitôt dans son Apple Wallet ou son Google Wallet.

Ta caisse

À chaque ticket encaissé, la caisse ajoute la visite. Plus besoin de scanner la carte.

Ta réservation

Quand un rendez-vous est honoré, ton outil de réservation compte la visite tout seul.

Ton site

Ton formulaire d’inscription crée la carte et affiche le bouton « Ajouter au Wallet ».

Inclus dans l’offre Pro et Multi-salons

L’API publique fait partie des offres Pro et Multi-salons. Avec l’offre Starter, les appels sont refusés (erreur 402).

Démarrage

Démarrage en 3 étapes

  1. 1

    Crée ta clé API

    Dans ton espace Walliko, va dans Paramètres › Clés API, donne un nom à la clé (par exemple « Caisse du salon ») puis clique sur Créer une clé. Elle commence par psk_live_.

    Elle ne s’affiche qu’une seule fois

    Copie-la tout de suite et range-la dans ton logiciel (ou donne-la à ton prestataire). Si tu la perds, révoque-la et crées-en une nouvelle.
  2. 2

    Récupère tes identifiants

    Deux identifiants servent dans les appels. Tu les copies en un clic dans ton espace :

    • ID du programme : page Programme, choisis le programme puis clique sur Copier l’ID. Obligatoire pour créer une carte.
    • ID de l’établissement : page Établissements, bouton Copier l’ID sur la fiche du salon. Facultatif, sauf si ta carte n’est valable que dans certains salons.
  3. 3

    Fais ton premier appel

    Remplace la clé et l’ID du programme par les tiens, puis lance cette commande depuis un terminal :

    curl -X POST https://api.walliko.fr/public/v1/cards \
      -H "Authorization: Bearer psk_live_ta_cle_secrete" \
      -H "Content-Type: application/json" \
      -d '{
        "programId": "3f6c1a2e-8b4d-4e7a-9c11-2d5f0b7e9a41",
        "firstName": "Inès",
        "phone": "+33611223344"
      }'

    Tu reçois la carte d’Inès, avec ses liens Apple Wallet et Google Wallet. C’est branché.

Sécurité

Authentification

Chaque appel envoie ta clé dans l’en-tête Authorization, précédée de Bearer. Le corps des requêtes et des réponses est en JSON. La clé identifie ton commerce : tu n’as jamais à préciser lequel.

Authorization: Bearer psk_live_ta_cle_secrete
Content-Type: application/json

Une clé révoquée ou inconnue renvoie aussi 401 avec le message « Clé API invalide ou révoquée. ».

Route 1

Créer (ou retrouver) une carte

POST/public/v1/cards

Crée la carte de fidélité d’un client dans un programme. Si un client avec le même téléphone ou le même e-mail existe déjà, Walliko le retrouve au lieu d’en créer un deuxième, et renvoie sa carte. Tu peux donc appeler cette route sans risque à chaque inscription.

  • programIduuidObligatoire

    ID du programme (page Programme › Copier l’ID).

  • firstNametexteObligatoire

    Prénom du client, 1 à 40 caractères. Il s’affiche sur la carte.

  • phonetexteUn des deux

    Téléphone au format international, par exemple +33611223344.

  • emaile-mailUn des deux

    Adresse e-mail du client.

Téléphone : toujours au format +33

Walliko retrouve les clients par numéro exact. Envoie toujours le même format (+33611223344, sans espaces), sinon le même client peut être créé deux fois.
curl -X POST https://api.walliko.fr/public/v1/cards \
  -H "Authorization: Bearer psk_live_ta_cle_secrete" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "3f6c1a2e-8b4d-4e7a-9c11-2d5f0b7e9a41",
    "firstName": "Inès",
    "phone": "+33611223344"
  }'

Selon ton programme, un tampon de bienvenue peut être ajouté à la création (ici stamps: 1). Les liens links permettent au client d’ouvrir sa carte ou de l’ajouter à son Wallet.

Route 2

Ajouter une visite

POST/public/v1/visits

Compte un passage : un tampon pour un programme à tampons, des points pour un programme à points. La carte du client se met à jour dans son Wallet dans les secondes qui suivent. Identifie le client par un de ces trois champs : serial, phone ou email.

  • serialtexteUn des trois

    Identifiant de la carte, renvoyé par la route Créer une carte.

  • phonetexteUn des trois

    Téléphone du client, au même format qu’à la création (+33…).

  • emaile-mailUn des trois

    E-mail du client.

  • programIduuidFacultatif

    À préciser si le client a des cartes dans plusieurs programmes. Sinon, sa plus ancienne carte est utilisée.

  • establishmentIduuidFacultatif

    Salon où a lieu la visite. Obligatoire si la carte n’est valable que dans certains salons.

  • amountCentsentierFacultatif

    Montant du ticket en centimes (4500 pour 45 €). Utilisé par les programmes à points selon le montant, ignoré sinon.

  • idempotencyKeytexte, 64 maxFacultatif

    Identifiant unique du passage (numéro de ticket, ID du rendez-vous). Un même identifiant n’est jamais compté deux fois.

curl -X POST https://api.walliko.fr/public/v1/visits \
  -H "Authorization: Bearer psk_live_ta_cle_secrete" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+33611223344",
    "establishmentId": "9a0d7c55-1e3b-4f62-8a7d-6b4c2e1f0d93",
    "amountCents": 2500,
    "idempotencyKey": "ticket-000184"
  }'

La réponse contient la carte à jour et la liste unlocked des récompenses que cette visite vient de débloquer (vide la plupart du temps). Tu peux l’utiliser pour afficher « Coupe offerte débloquée » sur l’écran de la caisse.

Anti-fraude : une visite par client et par période

Ton programme fixe un délai minimum entre deux visites d’un même client (4 heures par défaut, réglable dans Programme). Une deuxième visite trop rapprochée est refusée avec une erreur 429 qui indique quand réessayer. C’est voulu : ne renvoie pas l’appel en boucle.

Route 3

Lire une carte

GET/public/v1/cards/{serial}

Renvoie l’état actuel d’une carte à partir de son serial (et non du code court imprimé sur la carte). Pratique pour afficher la progression du client sur ton écran de caisse ou dans ton espace client.

curl https://api.walliko.fr/public/v1/cards/k1Q52ystKd1elHNvgVdp-w \
  -H "Authorization: Bearer psk_live_ta_cle_secrete"

Référence

L’objet carte

Les trois routes renvoient la même description de carte :

  • serialtexteToujours

    Identifiant unique et stable de la carte. À stocker dans ton logiciel pour les appels suivants.

  • shortCodetexteToujours

    Code court imprimé sous le QR de la carte (par exemple WLK-23938-MW).

  • stampsentierToujours

    Tampons sur la carte en cours (programme à tampons).

  • pointsentierToujours

    Solde de points (programme à points).

  • lifetimeVisitsentierToujours

    Nombre total de visites depuis la création de la carte.

  • progressobjetToujours

    value (où en est le client), target (objectif de la prochaine récompense) et ratio (de 0 à 1).

  • availableRewardslisteToujours

    Récompenses prêtes à être offertes : id, title, threshold.

  • linksobjetToujours

    card (page de la carte), appleWallet et googleWallet (ajout au Wallet). Liens signés, à partager tels quels.

  • unlockedlisteRoute 2 seulement

    Récompenses débloquées par la visite qui vient d’être ajoutée.

Référence

Erreurs

Une erreur renvoie toujours un code HTTP et un objet error avec un code stable (à tester dans ton logiciel) et un message en français (à afficher tel quel si besoin).

Format
{
  "error": {
    "code": "anti_fraud",
    "message": "Visite déjà enregistrée récemment. Réessaie dans 3 h 57."
  }
}
  • 400validationChamp manquant ou invalide

    Ex. ni téléphone ni e-mail, UUID mal formé. Corrige la requête, ne réessaie pas telle quelle.

  • 401unauthorizedClé absente, inconnue ou révoquée

    Vérifie l’en-tête Authorization et la clé dans Paramètres.

  • 402plan_requiredOffre sans API

    Passe à l’offre Pro ou Multi-salons.

  • 404not_foundProgramme, client ou carte introuvable

    Ex. visite pour un téléphone inconnu : crée d’abord la carte (route 1).

  • 409wrong_establishmentCarte non valable dans ce salon

    Le programme est limité à certains salons : vérifie establishmentId.

  • 429anti_fraudVisite trop rapprochée

    Délai anti-fraude du programme. Le message indique quand réessayer.

  • 500internalErreur de notre côté

    Réessaie plus tard avec la même idempotencyKey.

Exemples complets

Recettes concrètes

À chaque ticket de caisse

La caisse connaît le téléphone du client et le numéro du ticket. On ajoute la visite ; si le client n’a pas encore de carte, on la crée puis on compte la visite. Le numéro de ticket sert d’idempotencyKey : même si la caisse renvoie l’appel, la visite n’est comptée qu’une fois.

const API = 'https://api.walliko.fr/public/v1'
const headers = {
  Authorization: `Bearer ${process.env.WALLIKO_API_KEY}`,
  'Content-Type': 'application/json',
}

export async function fideliteApresTicket(ticket) {
  const visite = {
    phone: ticket.telephoneClient,        // "+33611223344"
    amountCents: ticket.totalCentimes,    // utile pour un programme à points
    establishmentId: process.env.WALLIKO_SALON_ID,
    idempotencyKey: `ticket-${ticket.numero}`,
  }

  let res = await fetch(`${API}/visits`, { method: 'POST', headers, body: JSON.stringify(visite) })

  if (res.status === 404) {
    // Premier passage : on crée la carte, puis on compte la visite
    await fetch(`${API}/cards`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ programId: process.env.WALLIKO_PROGRAMME_ID, firstName: ticket.prenomClient, phone: visite.phone }),
    })
    res = await fetch(`${API}/visits`, { method: 'POST', headers, body: JSON.stringify(visite) })
  }

  if (res.status === 429) return { ok: false, raison: 'déjà compté récemment' }
  if (!res.ok) throw new Error((await res.json()).error.message)

  const carte = await res.json()
  return { ok: true, progression: carte.progress, recompense: carte.unlocked[0]?.title ?? null }
}

À chaque rendez-vous honoré

Ton logiciel de réservation sait quand un rendez-vous est terminé. Il appelle la route 2 avec l’e-mail (ou le téléphone) du client et l’ID du rendez-vous comme idempotencyKey. Un rendez-vous annulé ou non honoré ne doit simplement pas déclencher d’appel.

curl -X POST https://api.walliko.fr/public/v1/visits \
  -H "Authorization: Bearer psk_live_ta_cle_secrete" \
  -H "Content-Type: application/json" \
  -d '{"email":"ines@exemple.fr","idempotencyKey":"rdv-58213"}'

Afficher le lien de la carte au client

Après la route 1, envoie links.card par SMS ou par e-mail, ou affiche les boutons d’ajout au Wallet sur ta page de confirmation. Le client n’a rien à installer.

<!-- après POST /cards, avec la réponse "carte" -->
<a href="{{ carte.links.appleWallet }}">Ajouter à Apple Wallet</a>
<a href="{{ carte.links.googleWallet }}">Ajouter à Google Wallet</a>
<p>Ou ouvre ta carte : <a href="{{ carte.links.card }}">{{ carte.links.card }}</a></p>

Avant la mise en ligne

Bonnes pratiques

  • La clé reste côté serveurNe la mets jamais dans une page web, une app mobile ou un e-mail : quelqu’un pourrait ajouter des visites à ta place.
  • Une clé par logicielUne pour la caisse, une pour la réservation. Tu vois quand chacune a servi pour la dernière fois dans Paramètres.
  • Révoque en un clicClé perdue ou prestataire changé : Paramètres › Clés API › Révoquer. Les appels avec cette clé sont refusés immédiatement.
  • Toujours une idempotencyKeyNuméro de ticket ou de rendez-vous : un appel renvoyé après une coupure réseau ne compte jamais deux visites.
  • Un seul format de téléphoneToujours +33 sans espaces, à la création comme aux visites.
  • Ne réessaie pas les 4xxLes erreurs 400 à 429 demandent une correction. Seules les erreurs 500 se réessaient, avec la même idempotencyKey.

Spécification

Pour les développeurs

La spécification OpenAPI 3.1 complète est générée à partir du code de l’API : importe-la dans Postman, Insomnia ou ton générateur de client.