Aller au contenu

API et webhooks

Connectez Izzy Book à un logiciel comptable, un PMS, un CRM ou un outil d'automatisation. API REST en JSON, webhooks signés, description OpenAPI.

Télécharger la description OpenAPI (Postman, Make, Zapier…)

Authentification

L'établissement crée une clé dans Réglages › API et webhooks : en lecture seule, ou en lecture et écriture. La clé s'envoie dans l'en-tête Authorization. Elle donne accès aux seules données de son établissement. Ne l'utilisez jamais dans un navigateur ou une application mobile.

curl https://izzybook.fr/api/v1/bookings?from=2026-12-01T00:00:00Z \
  -H "Authorization: Bearer hbs_live_…"

Limite : 120 requêtes par minute et par clé. Montants en centimes TTC, dates ISO 8601 en UTC.

Points d'accès

Base : https://izzybook.fr/api/v1

  • GET/establishmentreadÉtablissement de la clé.
  • GET/servicesreadSoins (prix TTC en centimes, TVA en points de base) et compléments.
  • GET/availability?service_id=…&from=…&to=…readCréneaux libres d'un soin, 14 jours au plus. gender=f|m pour une praticienne ou un praticien ; partner_service_id pour un duo à la carte (un soin par personne, en cabine duo).
  • GET/bookings?from=…&to=…&status=…&updated_since=…readRéservations, paginées. updated_since sert à synchroniser un PMS ou un CRM.
  • GET/bookings/{reference}readUne réservation (référence HS-… ou id).
  • POST/bookingswriteCréer une réservation, avec les mêmes règles que le module en ligne (y compris duo à la carte : partner_service_id).
  • POST/bookings/{reference}/statuswriteArrivée, terminé, absence ou annulation (avec remboursement de l'acompte).
  • GET/customers?updated_since=…&segment=…&tag=…&marketing=truereadClients : consentement, étiquettes, statistiques de visite et segments du moment.
  • GET/customers/{id}readUn client.
  • PATCH/customers/{id}writeConsentement aux offres (désinscription depuis votre outil) et étiquettes.
  • GET/segmentsreadSegments (nouveaux, fidèles, meilleurs clients, à relancer…) avec leurs effectifs.
  • GET/vouchers?code=…&status=…readBons cadeaux.
  • GET/payments?from=…&to=…readPaiements en ligne (Stripe) : acomptes, prépaiements, ventes de bons, remboursements.
  • GET/events?type=…readÉvénements des 30 derniers jours, du plus récent au plus ancien : échantillon et mode interrogation (Make, n8n, Zapier).
  • GET/subscriptionsreadAbonnements REST de l'établissement.
  • POST/subscriptionsreadS'abonner à un événement (REST hook) : target_url et event. Le secret de signature n'est renvoyé qu'une fois.
  • DELETE/subscriptions/{id}readSupprimer un abonnement.

Pagination : limit (1 à 100) et starting_after (id du dernier élément reçu) ; la réponse indique has_more et next_starting_after.

Créer une réservation

curl -X POST https://izzybook.fr/api/v1/bookings \
  -H "Authorization: Bearer hbs_live_…" -H "Content-Type: application/json" \
  -d '{
    "service_id": "…",
    "starts_at": "2026-12-04T14:00:00+01:00",
    "customer": { "first_name": "Léa", "last_name": "Martin", "email": "lea@exemple.fr", "phone": "0612345678" },
    "customer_type": "hotel_guest", "room_number": "204"
  }'

Réponse 201 avec la réservation. Si l'établissement demande un acompte, la réservation attend le paiement et payment_url est à transmettre au client. Un créneau pris entre-temps renvoie 409 slot_unavailable.

La création passe par les mêmes contrôles que le module en ligne : disponibilités, horaires, délai minimal, contrainte anti-chevauchement de la base, acompte. Ajoutez l'en-tête Idempotency-Key (une valeur unique par réservation) : si la requête est rejouée dans les 24 heures avec le même corps, la réponse enregistrée est renvoyée avec Idempotent-Replayed: true et rien n'est créé en double. Même clé avec un autre corps : 422 ; requête encore en cours : 409.

Synchroniser les contacts (TriggerFlow, CRM, e-mailing)

  1. Import initial : parcourez GET /customers page par page. Chaque client porte marketing_consent, tags, stats (visites, dépense, dernière visite, prochain rendez-vous) et segments.
  2. Au fil de l'eau : abonnez-vous à customer.created, customer.updated et customer.deleted.
  3. Les segments évoluent avec le temps (un client devient « à relancer » sans rien modifier) : relisez GET /customers une fois par jour, ou GET /customers?segment=inactive avant une campagne.
  4. Désinscription dans votre outil : envoyez PATCH /customers/{id} avec {"marketing_consent": false}. Le client ne reçoit plus aucune offre, ici non plus. N'envoyez true que si votre outil a recueilli son accord.
curl -X PATCH https://izzybook.fr/api/v1/customers/6f1c… \
  -H "Authorization: Bearer hbs_live_…" -H "Content-Type: application/json" \
  -d '{"marketing_consent": false}'

Webhooks

Izzy Book envoie un POST JSON à votre adresse à chaque événement du catalogue ci-dessous. Répondez par un code 2xx en moins de 10 secondes ; sinon, nouvel essai après 1 min, 5 min, 30 min, 2 h, 6 h, 12 h puis 24 h. Aucune redirection n'est suivie.

  • booking.createdRéservation confirmée
  • booking.updatedRéservation modifiée (statut, horaire)
  • booking.cancelledRéservation annulée
  • booking.arrivedArrivée du client enregistrée
  • booking.completedSoin terminé
  • booking.no_showAbsence
  • booking.reminderRappel avant le soin (SMS, WhatsApp)
  • booking.followupRelance après la visite
  • customer.createdNouveau client
  • customer.updatedClient modifié (consentement, étiquettes)
  • customer.deletedClient effacé (RGPD)
  • payment.succeededPaiement encaissé
  • payment.refundedPaiement remboursé (cumul)
  • refund.createdRemboursement (montant de ce remboursement)
  • voucher.createdBon cadeau créé
  • voucher.redeemedBon cadeau utilisé
  • package.soldForfait vendu
  • package.session_usedSéance de forfait utilisée
  • review.submittedQuestionnaire de satisfaction rempli
  • waitlist.slot_availablePlace libérée pour un inscrit en liste d'attente
  • accounting.entry.createdPièce comptable (encaissement ou remboursement)

customer.created, customer.updated (identité, consentement, étiquettes) et customer.deleted (effacement RGPD : supprimez le contact de votre côté) gardent un outil marketing synchronisé.

booking.reminder part au moment du rappel avant le soin (délai réglé par l'établissement) et booking.followup au moment de la relance après la visite (clients ayant accepté les offres). Leur data est la réservation complète, téléphone du client compris : de quoi envoyer un SMS ou un message WhatsApp depuis votre outil.

{
  "id": "6f1c…",
  "type": "booking.created",
  "created_at": "2026-11-11T09:12:00Z",
  "data": { "reference": "HS-1A2B3C", "status": "confirmed", "starts_at": "…", "customer": { … } }
}

Vérifiez la signature avec le secret affiché à la création du webhook. L'en-tête Izzy-Signature (aussi envoyé sous son ancien nom Hibook-Signature) vaut t=<horodatage>,v1=<signature>, où la signature est le HMAC-SHA256 hexadécimal de <t>.<corps brut>.

import crypto from "node:crypto";

function verify(secret, rawBody, header) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(v1, "hex"));
}

Connecteurs : Zapier, Make, n8n et vos outils

Sans développement, l'établissement ajoute des destinations dans Réglages › Connecteurs : adresse https, événements, authentification (en-tête de clé, Basic, Bearer ou OAuth2 client credentials), objet complet ou seulement les champs choisis, journal des envois et bouton d'essai. Les textes libres (note du client, commentaire d'avis) ne partent que sur choix explicite.

Les outils d'automatisation s'abonnent eux-mêmes (REST hooks) avec la clé d'API de l'établissement, puis se désabonnent quand le scénario est arrêté :

curl -X POST https://izzybook.fr/api/v1/subscriptions \
  -H "Authorization: Bearer hbs_live_…" -H "Content-Type: application/json" \
  -d '{"target_url": "https://hooks.zapier.com/…", "event": "booking.created"}'

curl -X DELETE https://izzybook.fr/api/v1/subscriptions/<id> -H "Authorization: Bearer hbs_live_…"

Corps envoyé : { id, type, api_version: "v1", created_at, establishment_id, data }. En-têtes : Izzy-Event, Izzy-Event-Id (stable d'un essai à l'autre : dédoublonnez dessus), Izzy-Delivery, Izzy-Timestamp et Izzy-Signature (même vérification que ci-dessus). Une réponse 410 Gone supprime l'abonnement. Pour un outil qui interroge plutôt qu'il ne reçoit, lisez GET /events?type=booking.created et dédoublonnez sur id.

Adresses acceptées : publiques, en https, port 443 ou 8443. Les adresses internes (réseau privé, boucle locale, métadonnées du cloud) sont refusées à la saisie et revérifiées à chaque envoi.

Erreurs

{ "error": { "code": "invalid_request", "message": "service_id : …" } }

400 requête invalide ; 401 clé absente ou révoquée ; 403 droit « write » manquant ; 404 introuvable ; 409 créneau indisponible, statut impossible ou Idempotency-Key en cours ; 422 Idempotency-Key déjà utilisée pour une autre requête ; 429 trop de requêtes ; 500 erreur interne.