Réservation API

Réservations et réservations publiques

Gérer les calendriers de réservation, créer des réservations et exposer les liens de réservation publics

Cette page regroupe l'espace de réservation non administrateur : administration des réservations-calendrier, interne de réservation CRUD et les points de terminaison de réservation publics qui fonctionnent avec les jetons de ressources publiés.

JWT ou clé utilisateur APILa réservation publique n'est pas authentifiéeCalendriers de réservation basés sur les rôlesGardien d'accès aux réservations

Authentification et autorisations

• Les itinéraires de calendrier de réservation nécessitent une authentification et des vérifications de rôle.
• Le CRUD de réservation interne nécessite JwtAuthGuard plus ReservationAccessGuard.
• Les itinéraires de réservation publics ne sont pas authentifiés et utilisent le jeton dans l'URL.

Remarque importante sur la source :

Référence du point de terminaison

Administration du calendrier de réservation

Méthode	Chemin	Objectif	Demande ou requête	Authentification
POST	/api/organisations/:id/reservation-calendars	Créez un calendrier de réservation pour une organisation.	Chemin : id, corps : charge utile du calendrier	Clé JWT ou utilisateur API
GET	/api/organisations/:id/reservation-calendars	Répertoriez les calendriers de réservation d’une organisation.	Chemin : id	Clé JWT ou utilisateur API
POST	/api/reservation-calendars/:id/roles	Attribuez un rôle de calendrier de réservation à un utilisateur.	Chemin : id, corps : userId,role	Clé JWT ou utilisateur API
DELETE	/api/reservation-calendars/:id/roles/:userId	Supprimez un rôle de calendrier de réservation.	Chemin : id,userId	Clé JWT ou utilisateur API
GET	/api/reservation-calendars/:id/roles	Répertoriez les attributions de rôles.	Chemin : id	Clé JWT ou utilisateur API
GET	/api/users/reservation-calendars	Répertoriez les calendriers de réservation accessibles à l'utilisateur actuel.	Aucun	Clé JWT ou utilisateur API
GET	/api/reservation-calendars/:id/my-role	Obtenez le rôle de l'utilisateur actuel.	Chemin : id	Clé JWT ou utilisateur API
GET	/api/reservation-calendars/:id/has-role/:role	Testez si l'utilisateur actuel a un rôle.	Chemin : id,role	Clé JWT ou utilisateur API
POST	/api/reservation-calendars/:id/reservations	Exemple d'action de réservation réservée à l'éditeur.	Chemin : id	Clé JWT ou utilisateur API
GET	/api/reservation-calendars/:id/reservations	Exemple d'action sur la liste de réservation d'un éditeur ou d'un réviseur.	Chemin : id	Clé JWT ou utilisateur API
POST	/api/reservation-calendars/:id/reservations/:reservationId/approve	Exemple d'action d'approbation.	Chemin : id,reservationId	Clé JWT ou utilisateur API

Réservations internes

Méthode	Chemin	Objectif	Demande ou requête	Authentification
POST	/api/reservations	Créez une réservation.	Corps : champs de réservation	Clé JWT ou utilisateur API
GET	/api/reservations	Liste des réservations.	Requête : resourceId	Clé JWT ou utilisateur API
GET	/api/reservations/:id	Obtenez une réservation.	Chemin : id	Clé JWT ou utilisateur API
PATCH	/api/reservations/:id	Mettez à jour une réservation.	Chemin : id, corps : champs de réservation partielle	Clé JWT ou utilisateur API
DELETE	/api/reservations/:id	Supprimez une réservation.	Chemin : id	Clé JWT ou utilisateur API

Réservation publique

Méthode	Chemin	Objectif	Demande ou requête	Authentification
GET	/api/public/booking/:token	Résolvez les métadonnées de réservation publiques.	Chemin : token	Publique
GET	/api/public/booking/:token/availability	Lisez les créneaux disponibles pour une journée.	Chemin : token, requête : date	Publique
POST	/api/public/booking/:token/reserve	Créez une réservation publique.	Chemin : token, corps : champs de réservation	Publique

Demander des formes

Calendriers de réservation

CreateReservationCalendarDto

• name : obligatoire, 1..100 caractères
• description : facultatif, maximum 500 caractères
• color : couleur hexadécimale facultative
• reservationRules : objet facultatif
• editorUserIds : tableau d'entiers positifs uniques en option
• reviewerUserIds : tableau d'entiers positifs uniques en option

AssignRoleDto

• userId : nombre positif requis
• role : énumération requise ReservationCalendarRoleType

Réservations internes

CreateReservationDto et UpdateReservationDto

• startTime : requis à la création, date-heure ISO
• endTime : requis à la création, date-heure ISO, doit être postérieur à startTime
• quantity : entier facultatif, minimum 1
• customerInfo : objet facultatif
• notes : chaîne nettoyée facultative, maximum 2 048 caractères
• resourceId : requis à la création, minimum 1
• status : énumération de mise à jour uniquement pending|confirmed|completed|cancelled|waitlist

Requête :

• ListReservationsQueryDto.resourceId : entier facultatif >= 1

Réservation publique

CreatePublicBookingDto

• startTime : date-heure ISO requise
• endTime : date-heure ISO requise
• quantity : entier requis, minimum 1
• customerName : chaîne obligatoire
• customerEmail : email requis
• customerPhone : chaîne obligatoire
• notes : chaîne facultative

Requête de disponibilité :

• date : chaîne de date ISO requise

Exemples d'appels

Créer un calendrier de réservation

curl -X POST "$PRIMECAL_API/api/organisations/12/reservation-calendars" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Family bookings",
    "color": "#14b8a6",
    "editorUserIds": [18],
    "reviewerUserIds": [19]
  }'

Créer une réservation

curl -X POST "$PRIMECAL_API/api/reservations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2026-04-01T08:00:00.000Z",
    "endTime": "2026-04-01T09:00:00.000Z",
    "resourceId": 21,
    "quantity": 1
  }'

Créer une réservation publique

curl -X POST "$PRIMECAL_API/api/public/booking/$PUBLIC_TOKEN/reserve" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2026-04-01T08:00:00.000Z",
    "endTime": "2026-04-01T09:00:00.000Z",
    "quantity": 1,
    "customerName": "Alex Example",
    "customerEmail": "alex@example.com",
    "customerPhone": "+36301112222"
  }'

Notes de réponse et de comportement

• Les réservations internes sont protégées par ReservationAccessGuard.
• Les exemples de points de terminaison de calendrier de réservation sont limités aux rôles mais sont actuellement mis en œuvre au niveau de l'échafaudage.
• Les points de terminaison de réservation publics utilisent uniquement le jeton publié ; ils ne nécessitent pas d'authentification.

Meilleures pratiques

• Utilisez des calendriers de réservation pour les flux de travail sensibles aux rôles et /api/reservations pour le CRUD de réservation interne réel.
• Validez la date de commande côté client avant de soumettre les écritures de réservation.
• Traitez les jetons de réservation publics comme des secrets. Régénérez-les en cas de fuite de liens ou de changements de personnel.
• Ajoutez une limitation de tarif ou une protection anti-bot devant les formulaires de réservation publics.