Pour les pros du golf

API de réservation du simulateur

Proposez le simulateur V-Box directement sur votre site : consultez les disponibilités, posez une réservation provisoire pendant le paiement de votre client, puis confirmez-la. Les mêmes règles que l'agenda s'appliquent (horaires, durées, quota hebdomadaire, horizon de réservation).

Description OpenAPI 3.1 : /api/v1/openapi.json · Client TypeScript typé : createVboxClient de @repo/shared/vbox-api.

Authentification

Chaque pro reçoit de l'accueil du golf une clé personnelle au format vbx_<préfixe>_<secret>, affichée une seule fois. Envoyez-la dans l'en-tête Authorization de chaque requête, uniquement depuis votre serveur (jamais dans le navigateur). Limite : 120 requêtes par minute et par clé.

Authorization: Bearer vbx_votreprefixe_votresecret

Dates : ISO 8601 avec fuseau (ex. 2026-11-20T15:00:00+01:00 ou …Z). Le golf applique ses horaires en heure de Paris ; les créneaux commencent à l'heure pile ou à la demie.

Points d'accès

GET`/api/v1/availability?from&to`

Plages libres (horaires − blocages − réservations), limitées à [maintenant, maintenant + maxDaysAhead], et votre quota pour chaque semaine touchée. Fenêtre de 62 jours maximum.

curl "https://vbox.thomasfanlogolf.fr/api/v1/availability?from=2026-11-20T00:00:00%2B01:00&to=2026-11-21T00:00:00%2B01:00" \
  -H "Authorization: Bearer vbx_votreprefixe_votresecret"

{"timezone":"Europe/Paris","slotMinutes":[30,60],"maxDaysAhead":30,
 "free":[{"start":"2026-11-20T07:00:00.000Z","end":"2026-11-20T19:00:00.000Z"}],
 "quotas":[{"weekStart":"2026-11-16","limitMin":600,"usedMin":60,"remainingMin":540}]}

POST`/api/v1/reservations`

Crée une réservation confirmée, ou provisoire avec hold: true (expire après holdMinutes, 5 à 60, 35 par défaut). L'en-tête Idempotency-Key évite les doublons en cas de nouvel essai : la même clé renvoie la même réservation (en-tête Idempotent-Replayed: true).

curl -X POST "https://vbox.thomasfanlogolf.fr/api/v1/reservations" \
  -H "Authorization: Bearer vbx_votreprefixe_votresecret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-1234" \
  -d '{"start":"2026-11-20T15:00:00+01:00","end":"2026-11-20T16:00:00+01:00",
       "hold":true,"clientName":"Léa Dupont","clientEmail":"lea@example.com",
       "externalRef":"commande-1234"}'

→ 201 {"id":"cm…","status":"HELD","holdExpiresAt":"2026-11-14T10:35:00.000Z", …}

clientEmail (facultatif) permet l'envoi d'une demande d'avis Google après la séance, avec lien de désinscription.

POST`/api/v1/reservations/{id}/confirm`

Confirme une réservation provisoire (paiement reçu). 409 HOLD_EXPIRED si elle a expiré. Sans effet si elle est déjà confirmée.

curl -X POST "https://vbox.thomasfanlogolf.fr/api/v1/reservations/cm…/confirm" -H "Authorization: Bearer vbx_votreprefixe_votresecret"

DELETE`/api/v1/reservations/{id}`

Annule une de vos réservations (idempotent) → 204. Impossible une fois la séance commencée.

curl -X DELETE "https://vbox.thomasfanlogolf.fr/api/v1/reservations/cm…" -H "Authorization: Bearer vbx_votreprefixe_votresecret"

GET`/api/v1/reservations?from&to`

Vos réservations (tous statuts : HELD, CONFIRMED, CANCELLED) qui chevauchent la fenêtre.

curl "https://vbox.thomasfanlogolf.fr/api/v1/reservations?from=2026-11-01T00:00:00Z&to=2026-12-01T00:00:00Z" \
  -H "Authorization: Bearer vbx_votreprefixe_votresecret"

Erreurs

Toutes les erreurs ont la forme {"error":{"code":"…","message":"…"}} (message en français, affichable à l'utilisateur).

Code	HTTP	Signification
UNAUTHORIZED	401	Clé absente, invalide, révoquée ou compte désactivé.
FORBIDDEN	403	Action non autorisée.
VALIDATION	400	Paramètres ou corps JSON invalides (dates ISO 8601, début aligné sur :00 ou :30…).
NOT_FOUND	404	Réservation inconnue ou appartenant à un autre pro.
SLOT_UNAVAILABLE	409	Créneau déjà pris, bloqué pour entretien, ou réservation annulée.
OUTSIDE_OPENING_HOURS	422	En dehors des horaires d'ouverture du simulateur.
INVALID_DURATION	422	Durée non autorisée (voir slotMinutes dans /availability).
TOO_FAR_AHEAD	422	Au-delà de l'horizon de réservation (maxDaysAhead).
IN_THE_PAST	422	Créneau passé, ou annulation d'une séance déjà commencée.
QUOTA_EXCEEDED	422	Quota hebdomadaire du pro atteint (semaine du lundi au dimanche, heure de Paris).
HOLD_EXPIRED	409	Réservation provisoire expirée : le créneau a été libéré.
RATE_LIMITED	429	Plus de 120 requêtes par minute avec la même clé (voir l'en-tête Retry-After).
INTERNAL	500	Erreur inattendue : réessayez, puis contactez l'accueil du golf.

Flux iCal

Chaque pro dispose aussi d'un lien iCal secret (page « Mon compte ») listant ses séances de −30 jours à +6 mois, à ajouter comme agenda par URL dans Google Agenda, Apple Calendrier ou Outlook.

API de réservation du simulateur

Authentification

Points d'accès

GET/api/v1/availability?from&to

POST/api/v1/reservations

POST/api/v1/reservations/{id}/confirm

DELETE/api/v1/reservations/{id}