Guide du module Réservation & Rendez-vous pour Larapen

Ajoutez la réservation multi-jours à votre site Larapen. Gérez des services réservables avec tarification par nuit, traitez les réservations des clients avec dates d’arrivée et de départ, et visualisez l’ensemble sur un calendrier interactif, avec intégration de paiement optionnelle.

Cas d’utilisation

Le système de réservation est conçu pour toute activité qui accepte des réservations multi-jours :

• Hôtels & chambres d’hôtes : Réservations de chambres avec tarifs par nuit, exigences de séjour minimum et limites de personnes.
• Location de salle : Espaces événementiels, salles de conférence ou salles des fêtes réservés à la journée, avec contrôle de la capacité.
• Location d’équipement : Location multi-jours de véhicules, d’outils ou d’autre matériel avec sélection d’une plage de dates.
• Propriétés de vacances : Maisons ou appartements de vacances avec tarification saisonnière et règles de nuits minimum.
• Campings & aires de camping-car : Réservations d’emplacement de camping ou de camping-car avec nombre maximum de personnes.

Prérequis

Installation

Étape 1 : Téléverser l’add-on

Dans le panneau d’administration, allez dans Admin → Extensions → Add-ons et cliquez sur le bouton Télécharger un add-on. Sélectionnez le fichier ZIP de l’add-on : le système le décompresse automatiquement et l’add-on apparaît dans la liste des add-ons installés.

Étape 2 : Activer l’add-on

Repérez Réservation dans la liste et cliquez sur Activer. Ses migrations, ses seeders (le cas échéant) et ses permissions sont mis en place automatiquement.

Étape 3 : Configurer

Naviguez vers Admin → Réservation → Paramètres pour configurer les services réservables, les horaires d’ouverture, les règles de réservation et les notifications. Voir Configuration.

Code d’achat (clé de licence)

Réservation est vendu comme un produit séparé, il possède donc son propre code d’achat (clé de licence), distinct du code d’achat de l’application principale et de celui de chaque autre add-on. Il vous est demandé lorsque vous activez Réservation dans Panneau d’administration → Add-ons.

Nos produits sont vendus sur trois plateformes. La façon dont vous recevez un code d’achat dépend de l’endroit où vous avez acheté le produit.

1. Boutique bedigit.com (achat sur le site)

• Dès que le statut de paiement de la commande devient Payée, une clé de licence est générée automatiquement pour chaque article sous licence de la commande (une clé par unité achetée : acheter 3 unités donne 3 clés distinctes).
• Elle est envoyée par e-mail à l’adresse utilisée pour la commande, soit dans un e-mail de licence dédié, soit dans l’e-mail de confirmation de commande. Vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• La clé reste disponible dans votre compte sous Mon compte → Mes licences. Les clés sont masquées dans la liste ; ouvrez la page de détail de la licence pour afficher et copier la clé complète, voir les domaines sur lesquels elle est activée, et désactiver un domaine pour libérer un emplacement d’activation.
• La facture correspondante se trouve sous Mon compte → Mes commandes.

2. Gumroad

• Un achat sur Gumroad produit deux e-mails distincts : le reçu Gumroad (envoyé par Gumroad, donnant accès aux fichiers) et un e-mail de clé de licence (envoyé par bedigit.com) qui contient votre code d’achat.
• L’e-mail de clé de licence est généré dès que Gumroad nous notifie la vente, il arrive donc normalement quelques secondes après le paiement. Ici aussi, vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• Lorsque le produit Gumroad utilise la fonctionnalité de clés de licence propre à Gumroad, la même clé apparaît aussi dans votre reçu Gumroad et sous Bibliothèque → votre achat sur gumroad.com.
• Utilisez la même adresse e-mail sur bedigit.com que sur Gumroad : vos clés sont alors liées automatiquement à votre compte et listées sous Mon compte → Mes licences, même si vous vous inscrivez après l’achat. Vous pouvez aussi ajouter une clé Gumroad manuellement depuis Mon compte → Mes licences Gumroad.

3. Envato Market (CodeCanyon)

• Les codes d’achat Envato sont délivrés et fournis par Envato Market, jamais envoyés par e-mail par nous, il n’y a donc rien à chercher dans votre dossier de spam : vous récupérez le code depuis votre compte Envato.
• Connectez-vous à votre compte Envato / CodeCanyon, ouvrez la page Downloads, trouvez l’article et choisissez License certificate & purchase code dans le menu déroulant Download. Le code est inscrit dans ce certificat.
• Un code d’achat Envato ressemble à 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 caractères). Il ne change jamais, et le renouvellement du support de l’article n’en délivre pas de nouveau.
• Article officiel Envato : Where Is My Purchase Code?

Configuration

Tous les paramètres sont gérés depuis /admin/booking/settings.

Paramètres généraux

Paramètres de notification

Les bascules de notification sont gérées depuis la page centralisée des paramètres de notification, à /admin/settings/notifications. L’add-on de réservation enregistre 3 types de notification :

Admin : Services

Gérez les services réservables à /admin/booking/services. La vue liste affiche les services dans un tableau triable avec les colonnes suivantes :

Création & modification

Le formulaire de service comprend les champs suivants :

Images du service

Lorsque booking_service_images_enabled est activé, chaque service prend en charge la gestion des images via le trait HasMedia et le sélecteur de médias de l’administration :

• Image principale : L’image principale affichée dans les cartes de service sur la page de réservation et en haut du détail du service.
• Images de la galerie : Images supplémentaires affichées dans une galerie lightbox sur la vue de détail du service.

Admin : Réservations

Gérez toutes les réservations à /admin/booking/reservations. La vue liste comprend des onglets de filtrage par statut et des cartes de statistiques récapitulatives :

• Total des réservations : Nombre de réservations depuis toujours.
• Réservations actives : Réservations actuellement confirmées et en cours.
• Arrivées aujourd’hui : Réservations dont la date d’arrivée est celle du jour.
• Départs aujourd’hui : Réservations dont la date de départ est celle du jour.

Les réservations peuvent être filtrées par statut grâce à l’énumération ReservationStatus :

Détail & statut

La vue de détail de la réservation affiche :

• Informations client : Nom, e-mail, numéro de téléphone, nombre de personnes et notes éventuelles.
• Dates de la réservation : Date d’arrivée, date de départ et nombre total de nuits.
• Détails du service : Nom du service sélectionné, prix par nuit et prix total.
• Informations de paiement : Statut du paiement, passerelle utilisée et référence de transaction (lorsque le paiement est requis).
• Notes administratives : Champ de notes internes réservé au personnel.
• Gestion des statuts : Menu déroulant pour changer le statut de la réservation. Un changement de statut déclenche un e-mail de notification au client (si activé).

Vue calendrier

Accédez au calendrier à /admin/booking/reservations/calendar. Les réservations sont affichées comme des étendues horizontales multi-jours sur une grille de calendrier, chaque réservation étant en code couleur selon son statut. Le calendrier récupère ses données depuis l’endpoint calendar-events et prend en charge la navigation par mois.

Admin : Paramètres

Configurez le système de réservation à /admin/booking/settings. Les paramètres sont organisés dans les groupes suivants :

Général

• Activer les réservations (booking_enabled) : Bascule principale d’activation/désactivation du système de réservation.
• Services par ligne (booking_services_per_row) : Colonnes de la grille sur la page de réservation.

Paramètres d’affichage

• Images du service (booking_service_images_enabled) : Active ou désactive les téléversements d’images et les galeries pour les services.
• Titre de l’étape service (booking_service_step_title) : Titre traduisible personnalisé de l’étape de sélection du service dans l’assistant de réservation.

Paiement

• Exiger le paiement (booking_require_payment) : Lorsque ce paramètre est activé, les réservations doivent être payées au moment du règlement pour être confirmées. Nécessite au moins un add-on de passerelle de paiement (Stripe, PayPal, Paddle ou MoMo).

Planification

• Réservation à l’avance (jours) (booking_advance_days) : Jusqu’à quand dans le futur les clients peuvent réserver.
• Délai minimum (heures) (booking_min_advance_hours) : Combien d’heures avant l’arrivée une réservation peut être effectuée.

Politique d’annulation

• Texte de la politique (booking_cancellation_policy) : Texte traduisible affiché aux clients pendant le processus de réservation. Prend en charge un contenu distinct par langue.

Notifications

Les bascules de notification sont gérées de manière centralisée à /admin/settings/notifications. Voir la section Configuration pour les 3 types de notification enregistrés par cet add-on.

CAPTCHA

• Activer le CAPTCHA (booking_captcha_enabled) : Ajoute une vérification CAPTCHA au formulaire de réservation pour empêcher les soumissions de spam automatisées.

Côté visiteur : Page de réservation

Routes

Assistant de réservation

La page de réservation côté visiteur utilise un assistant en plusieurs étapes :

1. Étape 1 : Choisir un service : Parcourez les services disponibles, affichés sous forme de cartes dans une grille (nombre de colonnes configurable via booking_services_per_row). Chaque carte affiche l’image principale (si elle est activée), le nom du service, le prix par nuit et la capacité en personnes. Cliquer sur une carte sélectionne le service et passe à l’étape suivante.
2. Étape 2 : Choisir les dates : Un calendrier interactif pour choisir les dates d’arrivée et de départ. Le calendrier applique les règles de nuits minimum et maximum du service, les limites de réservation à l’avance et la disponibilité selon la capacité restante. Les dates indisponibles sont grisées.
3. Étape 3 : Vos coordonnées, Un formulaire qui recueille les informations du client :
   • Nom complet (requis)
   • Adresse e-mail (requise)
   • Numéro de téléphone
   • Nombre de personnes
   • Demandes particulières / notes
   La politique d’annulation est affichée ici si elle est configurée. Le CAPTCHA est affiché s’il est activé.

Côté visiteur : API de disponibilité

Deux endpoints GET fournissent les données de disponibilité utilisées par le calendrier de l’assistant de réservation :

Côté visiteur : Confirmation

Après la soumission réussie d’une réservation, le client est redirigé vers /booking/confirmation/{reservation}. Cette page affiche un récapitulatif de la réservation comprenant le nom du service, les dates, le nombre de nuits, le prix total et une référence de confirmation. Si le paiement est requis et n’a pas encore été effectué, un lien vers la page de paiement est affiché.

Côté visiteur : Paiement

Lorsque booking_require_payment est activé, les clients sont dirigés vers /booking/checkout/{reservation} pour effectuer leur paiement. La page de paiement affiche le récapitulatif de la réservation et un sélecteur de passerelle présentant toutes les passerelles de paiement actives (Stripe, PayPal, Paddle, MoMo) installées sur le site.

Le modèle Reservation implémente l’interface Payable, ce qui lui permet de fonctionner avec n’importe quel add-on de passerelle de paiement. Après un paiement réussi, le statut de la réservation passe automatiquement à Confirmé.

Côté visiteur : Mes réservations

Les utilisateurs authentifiés peuvent consulter leur historique de réservations à /booking/my-reservations. Cette page est accessible depuis le menu utilisateur sous « Mes réservations » et affiche la liste des réservations passées et à venir de l’utilisateur avec le statut, les dates et les détails du service.

Notifications

L’add-on de réservation définit 3 types de notification, gérés via le système de notification centralisé :

Activez ou désactivez chaque notification à /admin/settings/notifications. Les utilisateurs peuvent aussi gérer leurs préférences de notification depuis les paramètres de leur compte.

Mise à jour

1. Sauvegarder : Sauvegardez votre base de données et le répertoire extensions/addons/booking avant la mise à jour.
2. Remplacer les fichiers : Écrasez le répertoire extensions/addons/booking avec la nouvelle version.
3. Exécuter les migrations : Exécutez php artisan migrate pour appliquer les éventuelles nouvelles modifications de la base de données.
4. Vider les caches : Lancez php artisan optimize:clear pour vider tous les caches de l’application.

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez Booking (Reservations) et cliquez sur Désactiver.

• Ses routes, ses vues, ses entrées de menu d’administration et ses permissions cessent d’être enregistrées, et ses pages publiques ne répondent plus.
• Ses tables de base de données et toutes les données qu’elles contiennent sont conservées, et ses fichiers restent dans extensions/addons/booking/. Rien n’est supprimé.
• Le code d’achat enregistré lors de l’activation est conservé lui aussi : réactiver l’add-on ne le redemande pas.
• La désactivation est refusée tant qu’un autre add-on actif dépend de celui-ci : désactivez d’abord cet add-on.

Cliquez sur Activer sur la même carte pour le rallumer. Les migrations en attente sont rejouées, les assets republiés, et l’add-on reprend exactement là où il s’était arrêté.

Suppression

La suppression est définitive et détruit les données de l’add-on. Le bouton Supprimer n’apparaît que sur un add-on désactivé : la suppression se fait donc toujours en deux temps :

1. Désactivez Booking (Reservations) (voir Désinstallation).
2. Cliquez sur Supprimer sur sa carte et confirmez la demande.

Le panneau d’administration, en une seule passe :

• exécute le hook de désinstallation de l’add-on, s’il en fournit un, tant que son code est encore sur le disque ;
• révoque les permissions déclarées dans son addon.json ;
• annule ses migrations, ce qui supprime ses tables de base de données et toutes les lignes qu’elles contiennent, et purge ses entrées de la table migrations, afin qu’une réinstallation ultérieure reparte de zéro ;
• supprime ses assets publiés : public/addons/booking/, public/vendor/booking/ et storage/app/public/addons/booking/ ;
• supprime le dossier de l’add-on extensions/addons/booking/ ;
• supprime sa ligne dans la table addons (le code d’achat enregistré disparaît avec elle) et vide le cache de l’application.

La suppression est refusée, avec un message explicatif et avant toute destruction, lorsque l’add-on est encore actif, lorsqu’un autre add-on actif en dépend, ou lorsque l’utilisateur du serveur web (PHP) ne peut pas supprimer extensions/addons/booking/. Dans ce dernier cas, donnez à cet utilisateur le droit d’écriture sur le dossier et sur son parent, puis réessayez.

Supprimer le dossier en FTP ou en SSH n’est pas équivalent : les tables de l’add-on, ses entrées dans la table migrations et sa ligne addons restent en place, et sa carte reste dans la liste. Utilisez plutôt Supprimer dans le panneau d’administration.

Dépannage

Aucune disponibilité ne s’affiche dans le calendrier

• Vérifiez que le service a is_active défini sur true.
• Vérifiez que max_capacity est supérieur à zéro.
• Assurez-vous que booking_advance_days couvre les dates que vous essayez de réserver.
• Vérifiez que booking_min_advance_hours n’empêche pas les dates d’arrivée proches.

Le calendrier ne se charge pas dans l’administration

• Videz le cache du navigateur et vérifiez la console du navigateur pour repérer d’éventuelles erreurs JavaScript.
• Vérifiez que l’endpoint calendar-events retourne un JSON valide en visitant directement /admin/booking/reservations/calendar-events.
• Assurez-vous que l’utilisateur admin possède la permission booking.reservations.view.

Erreurs de paiement lors du règlement

• Vérifiez qu’au moins un add-on de passerelle de paiement est installé et activé.
• Vérifiez que les clés API de la passerelle de paiement sont correctement configurées dans les paramètres de la passerelle.
• Consultez les journaux Laravel dans storage/logs/laravel.log pour des messages d’erreur détaillés.
• Assurez-vous que les méthodes de l’interface Payable du modèle Reservation retournent les bonnes valeurs (montant, devise, description).

Le CAPTCHA ne s’affiche pas

• Assurez-vous que booking_captcha_enabled est défini sur true dans les paramètres de réservation.
• Vérifiez que le pilote CAPTCHA global et les clés API sont configurés dans /admin/settings/security.

Les images du service ne s’affichent pas

• Vérifiez que booking_service_images_enabled est défini sur true.
• Vérifiez que les images ont bien été téléversées via le sélecteur de médias de l’administration.
• Vérifiez que le lien symbolique storage existe (php artisan storage:link).