Réservation & Rendez-vous

Ajoutez la planification de rendez-vous et la fonctionnalité de réservation multi-jours à votre site Larapen. Gérez les services, prestataires, plannings hebdomadaires et un calendrier de réservation interactif, avec intégration de paiement optionnelle.

Cas d'utilisation

Mode Rendez-vous

• Salon ou Spa : Les clients choisissent un service (coupe de cheveux, massage), une date et un créneau horaire parmi les disponibilités.
• Cabinet de conseil : Les visiteurs réservent une consultation de 30 ou 60 minutes avec un conseiller spécifique.
• Cabinet médical : Les patients planifient des visites avec des praticiens. Les pauses et dates bloquées maintiennent le calendrier à jour.

Mode Réservation

• Hôtel / Chambre d'hôtes : Les clients sélectionnent les dates d'arrivée et de départ avec tarification par nuit et limites de capacité.
• Location de salle : Les organisateurs d'événements réservent un lieu pour plusieurs jours avec des contraintes de séjour minimum/maximum.
• Location d'équipement : Les clients réservent du matériel pour une plage de dates avec détection de chevauchement des réservations.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+

Installation

Étape 1 : Placer l'add-on

Copiez ou créez un lien symbolique du dossier booking dans le répertoire "extensions/addons" de votre Larapen :

Étape 2 : Activer l'add-on

Allez dans Admin → Add-ons → Add-ons installés et activez Réservation & Rendez-vous.

Étape 3 : Exécuter les migrations

Cela crée 6 tables : booking_services, booking_providers, booking_provider_schedules, booking_provider_service (pivot), booking_blocked_dates et booking_appointments.

Étape 4 : Définir les permissions

L'add-on enregistre 13 permissions (voir Permissions). Assignez-les aux rôles administrateurs via Admin → Utilisateurs → Rôles & Permissions.

Étape 5 : Configurer

Naviguez vers Admin → Réservation → Paramètres et configurez le type de réservation, les options de planification et les préférences de notification. Voir Configuration.

Étape 6 : Créer des services & prestataires

1. Allez dans Admin → Réservation → Services et créez au moins un service actif.
2. Allez dans Admin → Réservation → Prestataires et ajoutez des prestataires (membres du personnel). Le système initialise un planning par défaut Lun–Ven 9h00–17h00 pour chaque nouveau prestataire.
3. Assignez des services aux prestataires et personnalisez leurs plannings hebdomadaires.

Configuration

Tous les paramètres sont gérés dans Admin → Réservation → Paramètres (stockés dans la table settings, groupe booking). Les valeurs par défaut sont définies dans config/booking.php.

Paramètre	Description	Défaut
booking_type	Mode de réservation : appointment (créneau horaire) ou reservation (plage de dates).	appointment
booking_enabled	Afficher ou masquer la page de réservation sur le front-end.	true
booking_multi_provider	Permettre aux clients de choisir un prestataire spécifique lors de la réservation. Désactivé, le système assigne automatiquement un prestataire.	false
booking_pending_blocks_slot	Activé, les rendez-vous en attente bloquent également le créneau horaire. Désactivé, seuls les rendez-vous confirmés/terminés bloquent les créneaux.	true
booking_advance_days	Combien de jours à l'avance les clients peuvent réserver.	60
booking_min_advance_hours	Heures minimum avant qu'un rendez-vous puisse être réservé (empêche les réservations de dernière minute).	2
booking_slot_interval	Remplacer l'intervalle de créneau horaire en minutes. Laisser vide pour utiliser la durée du service.	(null : utilise la durée du service)
booking_notification_email	Adresse e-mail pour recevoir les notifications admin de réservation.	(vide)
booking_require_payment	Exiger le paiement avant la confirmation de réservation. S'applique uniquement aux services avec un prix > 0.	false
booking_cancellation_policy	Politique d'annulation en texte libre affichée sur la page de réservation.	(vide)
booking_captcha_enabled	Activer le défi CAPTCHA sur le formulaire de réservation.	false

Paramètres de notification

Paramètre	Description	Défaut
booking_notify_admin_on_new_booking	Envoyer un e-mail à l'adresse de notification lors de nouvelles réservations.	true
booking_notify_client_on_booking	Envoyer un e-mail de confirmation au client lors de la soumission de réservation.	true
booking_notify_client_on_status_change	Notifier le client lorsque le statut de la réservation change (confirmé, annulé, terminé).	true
booking_notify_provider_on_new_booking	Notifier le prestataire assigné lorsqu'il reçoit une nouvelle réservation.	true
booking_notify_provider_on_cancellation	Notifier le prestataire assigné lorsqu'une réservation est annulée.	true

Types de réservation

L'add-on supporte deux paradigmes de réservation fondamentalement différents. Le mode actif est contrôlé par le paramètre booking_type et affecte le formulaire front-end, les vues admin, la logique de génération de créneaux et les calculs de disponibilité.

Mode Rendez-vous

Réservations à date unique, basées sur des créneaux horaires. Exemples : coupe de cheveux à 15h, consultation à 10h, visite médicale à 14h30.

• Les services définissent une durée en minutes (ex. : 30, 60, 90).
• Le système génère les créneaux horaires disponibles à partir du planning hebdomadaire du prestataire, en excluant les pauses et les réservations existantes.
• Les clients choisissent une date dans le calendrier, puis sélectionnent un créneau horaire spécifique.
• Gestion de capacité : max_capacity permet plusieurs réservations simultanées par créneau (ex. : un cours de sport avec 10 places).
• Les champs start_time et end_time sont utilisés ; check_in_date / check_out_date sont null.

Mode Réservation

Réservations multi-jours, basées sur des plages de dates. Exemples : chambre d'hôtel pour 3 nuits, location de salle pour un week-end.

• Les services définissent un prix par nuit, un nombre min/max de nuits et un nombre max d'invités.
• Les clients sélectionnent les dates d'arrivée et de départ depuis un calendrier affichant la disponibilité jour par jour.
• Le prix total est calculé ainsi : prix_par_nuit × nombre de nuits.
• La détection de chevauchement empêche les doubles réservations : le système compte les réservations occupant chaque date et compare avec max_capacity.
• Les champs check_in_date, check_out_date et num_guests sont utilisés ; start_time / end_time sont null.

Admin : Services

La page Services (Réservation → Services) gère votre catalogue de services réservables.

Liste des services

Un tableau triable et paginé affichant :

• Nom (traduisible)
• Durée (formatée, ex. : « 1h 30min ») : mode rendez-vous
• Prix (formaté avec devise) : ou Prix par nuit en mode réservation
• Capacité max
• Nombre de rendez-vous
• Statut (badge actif/inactif)
• Position (ordre d'affichage)

Actions par ligne : Modifier, Supprimer.

Création & modification de services

Champs communs (les deux modes)

• Nom (traduisible, requis pour la langue par défaut)
• Slug (traduisible, généré automatiquement si vide)
• Description (traduisible)
• Prix (numérique, optionnel)
• Devise (requise, parmi les devises actives)
• Capacité max (entier, 1–100)
• Actif bascule
• Position (ordre d'affichage)

Champs du mode Rendez-vous

• Durée (minutes) : requis, 5–480 minutes. Détermine la longueur du créneau.

Champs du mode Réservation

• Durée (minutes) : optionnel (non utilisé pour la génération de créneaux en mode réservation).
• Prix par nuit : utilisé pour calculer le prix total.
• Nuits min / Nuits max : contraintes de durée de séjour.
• Invités max : limite d'invités par réservation.

Admin : Prestataires

Les prestataires représentent les membres du personnel, les salles ou les ressources qui fournissent vos services. Gérés dans Réservation → Prestataires.

Liste des prestataires

Un tableau paginé affichant :

• Avatar (ou initiales par défaut)
• Nom, E-mail, Téléphone
• Nombre de services assignés
• Nombre de rendez-vous
• Statut (actif/inactif)

Actions par ligne : Modifier, Supprimer.

Création d'un prestataire

• Nom, E-mail, Téléphone
• Bio : description textuelle
• Avatar : téléchargement d'image (stocké dans booking/providers/ sur le disque public)
• Compte utilisateur lié : clé étrangère optionnelle vers la table users
• Services assignés : sélection multiple parmi les services actifs
• Actif bascule, Position

Lorsqu'un prestataire est créé, un planning hebdomadaire par défaut est automatiquement initialisé : Lundi–Vendredi 09h00–17h00 avec une pause de 12h00–13h00. Samedi et Dimanche sont désactivés.

Planning hebdomadaire

L'éditeur de planning (Prestataires → {prestataire} → Modifier → Onglet Planning) permet de configurer chaque jour de la semaine :

• Disponible bascule (activé/désactivé)
• Heure de début et Heure de fin
• Début de pause et Fin de pause (période de déjeuner/repos optionnelle)

Les créneaux qui chevauchent la fenêtre de pause sont automatiquement exclus de la disponibilité.

Dates bloquées

Dates individuelles où un prestataire n'est pas disponible (jours fériés, congés maladie, vacances). Gérées depuis la page de modification du prestataire.

• Date (requise)
• Raison (optionnelle : ex. « Jour férié », « Vacances »)

Les dates bloquées peuvent également être globales (aucun prestataire assigné) pour bloquer tous les prestataires à cette date.

Admin : Rendez-vous

La page Rendez-vous (Réservation → Rendez-vous) affiche toutes les réservations dans un tableau paginé.

Liste des rendez-vous

Filtrable par statut. Les colonnes incluent :

• Nom & e-mail du client
• Nom du service
• Nom du prestataire
• Date & heure (ou arrivée/départ pour les réservations)
• Statut badge (en attente/confirmé/annulé/terminé)
• Statut du paiement (si le paiement est activé)

Des cartes de statistiques en haut affichent les totaux, le nombre en attente, les rendez-vous du jour, de la semaine et à venir. En mode réservation, des statistiques supplémentaires affichent les arrivées du jour, les départs du jour et les séjours actifs.

Détail du rendez-vous & gestion des statuts

La page de détail (Rendez-vous → {rendez-vous}) affiche :

• Informations client : nom, e-mail, téléphone, adresse IP, horodatage de réservation
• Informations de réservation : service, prestataire, date/heure (ou plage de dates), prix total
• Détails du paiement (le cas échéant) : statut, méthode, référence, horodatage de paiement
• Gestion des statuts : boutons pour changer le statut avec transitions :
  • En attente → Confirmé, Annulé
  • Confirmé → Terminé, Annulé, Revenir à En attente
  • Terminé → Revenir à Confirmé
  • Annulé → Réouvrir (retour à En attente)
• Raison d'annulation : affichée lors de l'annulation ; effacée lors de la réouverture
• Notes admin : notes internes non visibles par le client
• Notes client : notes soumises par le client lors de la réservation

Vue calendrier

La page Calendrier (Réservation → Rendez-vous → Calendrier) fournit une vue mensuelle visuelle :

• Les événements sont chargés via AJAX (GET admin/booking/appointments/calendar-events).
• Filtrer par prestataire via le menu déroulant.
• Les rendez-vous s'affichent comme des événements horaires ; les réservations s'affichent comme des étendues multi-jours.
• Code couleur par statut (warning=en attente, success=confirmé, danger=annulé, info=terminé).
• Cliquez sur un événement pour accéder à la page de détail du rendez-vous.

Admin : Paramètres

La page de paramètres (Réservation → Paramètres) est organisée en sections :

Paramètres généraux

• Type de réservation : sélecteur radio pour le mode Rendez-vous ou Réservation avec descriptions.
• Activer la réservation : bascule pour afficher/masquer la page de réservation front-end.
• Mode multi-prestataires : permettre aux clients de choisir leur prestataire.

Planification

• Les rendez-vous en attente bloquent les créneaux : bascule.
• Intervalle de créneau : remplacer la valeur par défaut (durée du service).
• Réservation à l'avance (jours) : jusqu'à combien de jours à l'avance les clients peuvent réserver.
• Délai minimum (heures) : empêche les réservations de dernière minute.
• Politique d'annulation : texte libre affiché sur la page de réservation.

Paiement

• Exiger le paiement : bascule. S'applique uniquement aux services avec un prix > 0.
• Un avertissement est affiché si aucun add-on de passerelle de paiement n'est actif.

Notifications

• E-mail de notification : adresse e-mail admin pour les alertes de réservation.
• Cinq bascules contrôlant quels e-mails sont envoyés (voir Notifications).

CAPTCHA

• Activer le CAPTCHA sur le formulaire de réservation : bascule. Nécessite qu'un fournisseur CAPTCHA soit configuré dans les paramètres principaux.

Front-end : Page de réservation

La page de réservation est disponible à /{locale}/booking et fournit un assistant étape par étape.

Routes

Méthode	URL	Nom de route	Description
GET	/{locale}/booking	booking.index.localized	Page de l'assistant de réservation
POST	/{locale}/booking	booking.store.localized	Soumettre une réservation
GET	/{locale}/booking/confirmation/{appointment}	booking.confirmation.localized	Page de confirmation
GET	/{locale}/booking/my-bookings	booking.my-bookings.localized	Historique des réservations de l'utilisateur (authentification requise)

Des variantes non localisées (sans {locale}) sont également enregistrées.

Étapes de l'assistant Rendez-vous

1. Sélectionner un service : grille de cartes des services actifs affichant le nom, la description, la durée et le prix.
2. Choisir un prestataire : affiché uniquement si le mode multi-prestataires est activé. Inclut une option « N'importe quel prestataire disponible ».
3. Choisir la date & l'heure : calendrier interactif affichant les jours disponibles/indisponibles. Sélectionner une date charge les créneaux horaires via AJAX.
4. Vos coordonnées : nom, e-mail, téléphone (optionnel), notes (optionnel). Pré-rempli pour les utilisateurs authentifiés.
5. Confirmer : carte récapitulative avec toutes les sélections. Le bouton de soumission déclenche la réservation.

Étapes de l'assistant Réservation

1. Sélectionner un service : grille de cartes affichant le nom, la description, le prix par nuit et les contraintes de durée de séjour.
2. Sélectionner les dates : calendrier interactif pour choisir les dates d'arrivée et de départ. Vérification de disponibilité en temps réel via AJAX.
3. Invités : saisie du nombre d'invités (si max_guests est configuré).
4. Vos coordonnées : formulaire d'informations client.
5. Confirmer : récapitulatif avec plage de dates, nombre de nuits, prix total. Le bouton de soumission déclenche la réservation.

API de créneaux & disponibilité

Trois endpoints JSON alimentent le calendrier front-end et la sélection de créneaux :

Logique de génération de créneaux

En mode rendez-vous, les créneaux horaires sont générés comme suit :

1. Charger le planning du prestataire pour le jour de la semaine demandé.
2. Vérifier les dates bloquées (spécifiques au prestataire et globales).
3. Générer les créneaux de start_time à end_time aux intervalles de slot_interval (ou durée du service).
4. Exclure les créneaux qui chevauchent la fenêtre de pause.
5. Exclure les créneaux avant le délai minimum de réservation.
6. Pour chaque créneau candidat, compter les rendez-vous bloquants existants (confirmés + terminés, et en attente si pending_blocks_slot est activé).
7. Inclure le créneau uniquement si le nombre de chevauchements est inférieur à max_capacity.

Lorsqu'aucun prestataire n'est spécifié, le système agrège les créneaux de tous les prestataires actifs pour le service. Si aucun prestataire n'existe, un planning par défaut intégré (Lun–Ven 09h00–17h00, pause 12h00–13h00) est utilisé comme solution de repli.

Page de confirmation

Après une réservation réussie (ou un paiement réussi), l'utilisateur est redirigé vers /{locale}/booking/confirmation/{appointment}.

• Affiche un message de succès avec les détails du rendez-vous/de la réservation.
• Affiche le nom du service, le prestataire, la date/heure (ou la plage de dates pour les réservations) et le prix total.
• Note de statut expliquant que la réservation est en attente de confirmation.
• Liens vers « Retour à l'accueil » et « Réserver à nouveau ».

Paiement

Lorsque booking_require_payment est activé et que le rendez-vous a un prix total > 0, le flux de réservation redirige vers une page de paiement au lieu de la page de confirmation.

Routes

Méthode	URL	Nom de route	Description
GET	/{locale}/booking/checkout/{appointment}	booking.checkout.localized	Page de paiement
POST	/{locale}/booking/checkout/{appointment}	booking.checkout.process.localized	Traiter le paiement

Interface Payable

Le modèle Appointment implémente l'interface App\Contracts\Payable, fournissant :

• getPayableAmount() : retourne le prix total
• getPayableCurrency() : depuis la devise du service ou la devise par défaut du site
• getPayableDescription() : ex. « Rendez-vous : Coupe de cheveux le 15 mars 2026 »
• getPayableCustomerEmail(), getPayableCustomerName()
• markAsPaid() : définit le statut à Confirmé, payment_status à « paid »
• markPaymentFailed() : définit payment_status à « failed »
• getPaymentSuccessUrl() : redirige vers la page de confirmation
• getPaymentCancelUrl() : redirige vers la page de paiement

Passerelles de paiement supportées

La page de paiement fonctionne avec tout add-on de passerelle de paiement actif :

• Stripe : Payment Intents côté client avec Stripe.js
• PayPal : paiement par redirection
• Paddle : superposition inline ou redirection
• MoMo : mobile money avec saisie du numéro de téléphone

Mes réservations

Les utilisateurs authentifiés peuvent consulter leur historique de réservations à /{locale}/booking/my-bookings.

• Correspond aux réservations par user_id ou client_email (couvre les réservations faites avant l'inscription).
• Liste paginée (15 par page) triée par date décroissante.
• Chaque entrée affiche : nom du service, prestataire, date/heure (ou plage de dates), badge de statut et statut du paiement.

Cette page est également accessible depuis le menu du compte utilisateur via le lien « Mes réservations » (enregistré dans addon.json sous provides.user_menu).

Notifications

L'add-on utilise le système de Notification de Laravel avec des destinataires de courrier à la demande. Toutes les notifications sont envoyées via le service BookingManager et capturent silencieusement toute erreur d'envoi.

Classe de notification	Destinataire	Déclencheur	Paramètre
BookingConfirmationNotification	Client	Réservation créée (après paiement, si requis)	notify_client_on_booking
NewBookingAdminNotification	Admin (notification_email)	Réservation créée	notify_admin_on_new_booking
NewBookingProviderNotification	Prestataire assigné	Réservation créée	notify_provider_on_new_booking
BookingStatusChangeNotification	Client	Statut changé en confirmé/annulé/terminé	notify_client_on_status_change
BookingCancellationProviderNotification	Prestataire assigné	Réservation annulée	notify_provider_on_cancellation

Chaque notification adapte son objet et son contenu en fonction du booking_type (rendez-vous vs. réservation), incluant les détails de date/heure ou de plage de dates appropriés.

Mise à jour

Étape 1 : Remplacer les fichiers

Remplacez le répertoire de l'add-on par la nouvelle version.

Étape 2 : Exécuter les migrations

Étape 3 : Reconstruire les assets

Requis si la mise à jour inclut des fichiers SCSS/JS de thème nouveaux ou modifiés.

Étape 4 : Vider les caches

Dépannage

Le calendrier n'affiche aucun jour disponible

• Assurez-vous qu'au moins un service actif existe.
• Si des prestataires sont configurés, vérifiez qu'au moins un prestataire a un planning actif pour le jour de la semaine concerné.
• Vérifiez que booking_advance_days est défini à une valeur supérieure à 0.
• Vérifiez qu'aucune date bloquée globale ne couvre la période visible entière.
• Si aucun prestataire n'existe, le système utilise un planning par défaut Lun–Ven : les week-ends s'afficheront comme indisponibles.

Aucun créneau horaire n'apparaît pour une date sélectionnée

• La date sélectionnée peut être dans le délai de booking_min_advance_hours (ex. : aujourd'hui avant la fenêtre de délai minimum).
• Tous les créneaux peuvent être réservés. Vérifiez si booking_pending_blocks_slot est activé : les rendez-vous en attente comptent pour la capacité.
• Le planning du prestataire peut être défini comme indisponible pour ce jour de la semaine.
• Une date bloquée peut exister pour le prestataire ou globalement.
• La durée du service peut dépasser la fenêtre de temps disponible (ex. : service de 3 heures mais seulement 2 heures disponibles après la pause).

La page de réservation retourne une erreur 404

• Assurez-vous que booking_enabled est défini sur true dans les paramètres. Le contrôleur retourne une 404 lorsque la réservation est désactivée.
• Vérifiez que l'add-on est activé dans Admin → Add-ons.

Mode réservation : « dates non disponibles » malgré un calendrier vide

• Vérifiez les dates bloquées sur toute la plage de dates (une seule date bloquée invalide la plage entière).
• Vérifiez les contraintes de nuits min/max sur le service. Un séjour de 2 nuits sur un service avec min_nights = 3 échouera.
• Assurez-vous que max_capacity est correctement défini. Une capacité de 1 signifie qu'une seule réservation peut occuper une date donnée.

Le client ne reçoit pas les e-mails de confirmation

• Vérifiez que booking_notify_client_on_booking est activé dans les paramètres.
• Vérifiez que votre configuration mail fonctionne (SMTP, Mailgun, etc.) dans Admin → Paramètres → Mail.
• Les échecs de notification sont capturés silencieusement : consultez storage/logs/laravel.log pour toute erreur.

La page de paiement n'affiche aucun moyen de paiement

• Assurez-vous qu'au moins un add-on de passerelle de paiement (Stripe, PayPal, Paddle ou MoMo) est installé et activé.
• Vérifiez que la passerelle est correctement configurée avec les clés API dans ses propres paramètres.
• PaymentService::getAvailableGateways() ne retourne que les passerelles entièrement configurées.

Le mode multi-prestataires n'affiche pas le sélecteur de prestataire

• Assurez-vous que booking_multi_provider est activé dans les paramètres.
• Vérifiez qu'au moins un prestataire actif existe et est assigné au service sélectionné.

Les notifications de changement de statut ne s'envoient pas

• L'AppointmentObserver gère les notifications de changement de statut. Assurez-vous qu'il est enregistré dans BookingServiceProvider::boot().
• Seules les transitions vers Confirmé, Annulé ou Terminé déclenchent les notifications client.
• Les notifications d'annulation au prestataire nécessitent que le prestataire ait une adresse e-mail définie.