Webhooks et REST API

HiLucy expose une REST API complète sous le namespace hilucy/v1. Cette API alimente à la fois les applications frontend et les intégrations tierces. Si vous développez des intégrations personnalisées ou connectez des systèmes externes, ce guide couvre les principaux groupes d'endpoints, les méthodes d'authentification et les patterns webhook.

Groupes d'Endpoints de l'API

L'API est organisée en groupes fonctionnels, chacun gérant un domaine spécifique :

Demandes de Service et Opérations

Le plus grand groupe d'endpoints gère les opérations quotidiennes -- demandes de service, contacts, annonces, réservations, clients et gestion de l'inventaire. Plus de 30 routes couvrent les opérations CRUD pour toutes les données opérationnelles.

Arrivées

Endpoints pour le flux de check-in client : résolution de tokens, correspondance de réservations, mises à jour des informations client et l'action d'arrivée idempotente qui fait passer une réservation au statut en séjour.

Clients de la Réservation

CRUD des clients au sein d'une réservation, flux d'invitation et de réclamation des accompagnants et endpoints de signature des conditions. Ceux-ci alimentent le check-in en ligne et les flux de réclamation des accompagnants.

Paiement et Finance

• Autorité de Paiement -- Configuration multi-payeurs : créer des setup intents, confirmer les moyens de paiement, révoquer des autorités et initialiser des folios par payeur
• Finance -- Requêtes du grand livre, recherches de solde, gestion des règles de commission et rapports financiers

Chat

Endpoint de streaming Server-Sent Events (SSE) qui fait proxy des conversations vers l'assistant LucyAI. Utilisé par l'interface de chat du portail client pour des réponses IA en temps réel.

Authentification

Connexion sociale (Google, Apple), rafraîchissement de tokens JWT, génération de liens magiques et vérification de liens magiques. Voir la section Authentification ci-dessous pour les détails.

Connecteurs et Versements

Endpoints d'intégration unifiés pour gérer les connexions tierces, plus les flux de génération, approbation et traitement des versements pour les propriétaires.

Portail WiFi

Endpoints du portail captif pour le WiFi client : gestion de sessions, identification des clients, autorisation et suivi des appareils.

Webhooks (Entrants)

HiLucy reçoit des webhooks de plusieurs services externes :

• Cloudbeds -- Événements de création/mise à jour/annulation de réservations qui synchronisent les réservations dans HiLucy
• Stripe -- Confirmations de paiement, litiges et événements de versement
• Acuity Scheduling -- Réservations et annulations de rendez-vous
• WhatsApp (Meta) -- Mises à jour de statut de livraison des messages
• Monday.com -- Événements de création et changement de statut de tâches

Chaque endpoint webhook entrant valide la signature de la requête avant traitement.

Authentification

L'API prend en charge plusieurs modes d'authentification selon l'endpoint :

• JWT Bearer Token -- Méthode principale pour les requêtes authentifiées. Obtenez un token via les endpoints d'auth (connexion sociale ou lien magique), puis incluez-le comme Authorization: Bearer <token> dans les requêtes suivantes.
• Token de Session d'Arrivée -- Auth par token pour le flux de check-in. Aucun compte utilisateur requis ; le token lui-même accorde un accès limité à une réservation spécifique.
• Session WordPress -- Auth standard par cookie WordPress pour les requêtes en contexte administrateur depuis le tableau de bord.
• Public -- Certains endpoints (comme l'identification du portail WiFi) sont accessibles publiquement sans authentification.

Patterns d'Intégration Webhook

Si vous développez un système qui envoie des webhooks à HiLucy ou consomme des données d'événements HiLucy :

• Les webhooks entrants sont configurés par intégration dans Paramètres > Intégrations. Chaque intégration fournit son URL webhook et les clés secrètes requises.
• Idempotence -- Les endpoints clés (comme l'action d'arrivée) sont idempotents, ce qui signifie que les livraisons webhook en double ne créeront pas de changements d'état en double.
• Validation de signature -- Tous les webhooks entrants sont vérifiés par signatures HMAC ou validation spécifique à la plateforme (ex : signatures webhook Stripe, tokens de vérification Meta).

Limites de Débit et Bonnes Pratiques

• Les endpoints authentifiés sont limités en débit par token utilisateur. Évitez le polling ; utilisez les webhooks pour les mises à jour en temps réel quand possible.
• Incluez toujours un traitement d'erreur approprié pour les réponses 401 (token expiré), 403 (permissions insuffisantes) et 429 (limite de débit dépassée).
• Pour les opérations en masse, regroupez les requêtes là où l'API le supporte plutôt que de faire des appels individuels par enregistrement.

Conseils

• Utilisez l'endpoint de rafraîchissement JWT pour renouveler les tokens avant qu'ils n'expirent plutôt que de vous ré-authentifier de zéro
• Testez les intégrations webhook contre l'environnement de développement (dev.hilucy.com) avant de les pointer vers la production
• Vérifiez les indicateurs de statut d'intégration dans Paramètres si les événements webhook semblent cesser d'arriver