API pour les écoles de ski

Les clés appartiennent à l'école, pas à une personne, et seul le titulaire de l'école peut les créer ou les révoquer, depuis l'onglet Connexions du tableau de bord de l'école. Une clé n'est affichée qu'une fois, à sa création ; nous en conservons un hash et ne pouvons pas la réafficher. Une école peut détenir jusqu'à 5 clés réelles, de sorte qu'une nouvelle intégration reçoit la sienne et qu'une ancienne se révoque sans toucher aux autres. Les clés réelles commencent par ap_live_ ; celles de l'environnement de test commencent par ap_test_ et se comptent à part.

Une clé cesse de fonctionner dès qu'elle est révoquée, et toutes reçoivent un 403 school_not_active dès que l'école est fermée ou n'est pas approuvée. Une école seulement suspendue (masquée sur le site, sans sa page) garde ses clés : ses réservations continuent, et l'API avec elles. Les clés ne se gèrent pas depuis l'API elle-même. Pour en faire tourner une : créez la nouvelle, basculez votre système dessus, puis révoquez l'ancienne ; entre-temps, les deux sont valables. Le tableau de bord indique quand chaque clé a été utilisée pour la dernière fois, à 5 minutes près. Les clés sont faites pour des serveurs : n'en mettez jamais une dans un navigateur ni dans une application mobile.

Chaque requête porte la clé comme bearer token. L'URL de base est https://alpinepal.com/api/v1 ; les réponses sont en JSON, jamais mises en cache, et chacune porte un X-Request-Id que vous pouvez nous citer. Les heures de la journée sont à l'heure de la station au format HH:mm, les dates au format YYYY-MM-DD et les instants en ISO 8601 en UTC avec millisecondes.

Les corps de requête doivent être du JSON avec un en-tête Content-Type: application/json (415 sinon), de moins de 256 Ko (413), et sont vérifiés strictement : un champ inconnu est un 400 validation_error qui liste les chemins fautifs. Un corps vide se lit comme un objet vide. Une méthode que le chemin n'accepte pas est un 405 avec un en-tête Allow ; une barre oblique finale est un 404.

Il n'y a pas de CORS : l'API est de serveur à serveur, et une requête depuis un navigateur échouera. C'est voulu : une clé dans un navigateur est une clé que n'importe qui peut lire.

Par clé, en fenêtres fixes d'une minute : 600 lectures (GET) et 120 écritures (tout le reste, DELETE compris) par minute. Au-delà, la réponse est 429 rate_limited avec un en-tête Retry-After, en secondes. Une clé de test a son propre quota. Les échecs d'authentification sont limités par adresse IP, 20 en 10 minutes ; passé ce seuil, toute nouvelle tentative reçoit 429 avant même que la clé soit recherchée. Les tests et les renvois de webhooks partagent un quota à part de 10 en 10 minutes par clé, puisque chacun est une requête vers le serveur de quelqu'un d'autre.

Chaque erreur est la même enveloppe : un statut HTTP, un code stable sur lequel aiguiller votre logique, un message pour un humain et l'id de la requête. Cinq codes portent des details : validation_error liste les champs fautifs comme [{path, message}] (10 au plus) ; booking_state dit dans quel état se trouve maintenant la réservation ({bookingStatus}) ; booking_conflict nomme les heures qui gênent et, si cette réservation est payée, son id et sa référence ; rate_limited répète l'attente comme {retryAfterSeconds} ; inside_notice_window donne le délai de préavis du moniteur en heures ({hours}).

Ids. Les moniteurs portent l'id de leur compte (user_…), ou unclaimed_… tant que personne n'a réclamé un profil que votre école a ajouté sans compte ; le poste des cours sans moniteur attribué d'une école est pool_<schoolId> ; les moniteurs de l'environnement de test sont sandbox_ia_… et sandbox_ib_…. Les réservations sont b_…, les événements evt_…, les livraisons whd_…, les endpoints wh_…, les requêtes req_…. Les références sont AP-<année>-<5 chiffres> pour les réservations réelles et SB<6 hex> dans l'environnement de test.

Heures. date, startTime et endTime sont l'heure locale de resortTimeZone, jamais l'UTC ; les instants (createdAt, updatedAt, paidAt, instructorResponseDeadline…) sont en UTC. Un cours la nuit du changement d'heure se résout à la première occurrence d'une heure ambiguë, et une heure qui n'existe pas cette nuit-là est décalée vers l'avant. endTime peut valoir 24:00. Savoir si une heure est passée se juge à l'heure de la station.

Argent. subtotal = (hourlyPrice + extraStudentPrice × max(0, numberOfStudents − includedStudents)) × durationHours, arrondi à la devise ; c'est ce que paie le client. hourlyPrice est celui de la date du cours : celui d'une saison (seasonPrices) si la date y tombe, sinon celui du moniteur ou du poste ; includedStudents est le nombre d'élèves qu'il couvre, 1 sauf si l'école en fixe davantage. platformFee est notre commission : 10 %, ou la commission plus élevée que votre école a convenue par écrit avec nous ; chaque réservation garde le taux auquel elle a été vendue. netAmount est le reste, subtotal − platformFee, crédité sur le registre de votre école quand le cours se termine, quel que soit celui qui l'a donné et qui le gère, et annulé si la réservation est remboursée. Chaque moniteur de votre effectif facture dans la devise de votre école ; les prix horaires ont un plancher par devise (10 EUR, 11 USD, 10 CHF) et extraStudentPrice vaut 0 ou plus. Le matériel que le client loue à votre école avec le cours s'ajoute aussi à subtotal (equipment.amount) et compte comme le cours.

managedBy est la règle qui décide qui répond : quand il dit instructor, le calendrier et les demandes sont au moniteur et l'API peut lire mais pas écrire ; quand il dit school, l'école, et donc l'API, écrit le calendrier et répond aux demandes, et le moniteur regarde. Il se règle depuis l'effectif dans le tableau de bord, par une personne, et ne se change pas via l'API. Rendre son calendrier au moniteur supprime les blocs externes que votre système y avait écrits.

Quand un moniteur quitte l'école, ses réservations disparaissent de GET /bookings et ses événements s'arrêtent, tandis que ce qu'il a déjà gagné reste sur votre registre. Ni cela ni un changement de managedBy n'envoie d'événement : comparez GET /instructors à chaque synchronisation.

unclaimed signale un moniteur que l'école a ajouté dans son tableau de bord sans compte : personne ne se connecte à sa place, il est donc toujours managedBy school et l'école répond de lui en tout, messagerie comprise. Quand la personne réclame le profil avec son propre compte, unclaimed passe à false et l'id du moniteur change pour un id définitif : tous les chemins et le filtre instructorId continuent d'accepter l'ancien id, le moniteur le porte dans previousId et les événements suivants citent le nouveau. Aucun événement ne l'annonce : comparez GET /instructors à chaque synchronisation et rapprochez previousId.

Les disponibilités d'un moniteur sont une liste de blocs. Un bloc est available, blocked ou vacation, appartient à une station où le moniteur enseigne, va de startTime à endTime (endTime peut valoir 24:00), et est ancré soit à un jour de la semaine (dayOfWeek 0–6, dimanche en premier, avec éventuellement since et until comme première et dernière dates où il s'applique), soit à une date précise : exactement l'un des deux. Les nouvelles heures available doivent tomber entre 07:00 et 21:00, heure de la station (sinon 422 outside_ski_day) ; les blocs blocked et vacation peuvent couvrir n'importe quelle heure. Les clients ne peuvent réserver qu'à l'intérieur de blocs available que rien d'autre ne recouvre.

PUT /instructors/{id}/availability remplace tout l'horaire, chaque station et chaque bloc, jusqu'à 400, par ce que vous envoyez, exactement comme enregistrer le calendrier dans le tableau de bord. Les ids sont facultatifs : le serveur en attribue un à un bloc qui n'en a pas, conserve ceux que vous envoyez, et refuse les doublons ou le préfixe xb_ des blocs externes. Les blocs externes (ci-dessous) ne sont jamais touchés par le PUT et ne doivent pas y figurer. Un bloc malformé, une station inconnue, les deux ancrages à la fois ou un since postérieur à l'until du bloc sont un 422 invalid_availability. Les blocs qui ne peuvent plus s'appliquer (une date passée, un bloc hebdomadaire au-delà de son until) sont écartés : le PUT ne les enregistre pas et le GET ne les renvoie pas. Une date est passée quand elle l'est partout, à 12:00 UTC le lendemain.

GET …/availability/expanded fait le calcul pour vous : pour une station et jusqu'à 62 jours, il renvoie, par jour, les plages libres qu'un client pourrait réserver et les plages occupées, chacune de celles-ci étiquetée booking (un cours confirmé), pending (une demande payée en attente de réponse) ou external (un bloc venu de l'API). Il applique la marge entre les cours et le délai de préavis fixés par le moniteur ; il n'écarte pas les trous plus courts que sa durée minimale de cours, si bien qu'un trou de trente minutes apparaît comme libre.

Un cours que vous avez vendu en dehors d'Alpine Pal occupe le moniteur. Enregistrez-le comme bloc externe et le créneau disparaît de la recherche, dans toutes les stations où le moniteur enseigne : une personne ne peut pas être dans deux vallées à la fois. Les blocs exigent que l'école gère le moniteur (managedBy = school).

Chaque bloc porte votre propre externalRef. Renvoyer la même référence avec la même date et les mêmes heures est idempotent et renvoie 200 avec le bloc enregistré, quel que soit le resortId passé ; la même référence avec d'autres heures est un 409 external_ref_exists : supprimez et recréez. Un bloc qui chevauche une réservation active est un 409 booking_conflict avec les heures qui gênent et, si cette réservation est payée, son id et sa référence : ce cours est déjà vendu de notre côté.

Un moniteur peut avoir au plus 400 blocs externes à partir d'aujourd'hui ; un de plus est un 422 limit_reached. Un bloc dont la date est passée (à 12:00 UTC le lendemain) s'en va de lui-même : GET /blocks ne le liste plus, un DELETE sur lui est un 404 et il cesse de compter dans les 400.

Accepter une demande de réservation revérifie le créneau : un bloc externe sur ses heures, comme une réservation active ou un cours collectif, donne un 409 slot_conflict, et l'école doit refuser la demande ou proposer un autre horaire. Sur le poste sans moniteur, accepter ne revérifie rien : ses places ont été comptées quand le client a payé. Dès que votre bloc reçoit un 201, l'heure est à vous : un paiement déjà en cours sur ce créneau est remboursé quand il tente d'aboutir, et vous parvient comme booking.expired.

Une école peut vendre des heures sans dire qui les donnera : le client réserve et paie, et l'école attribue un moniteur quand elle le souhaite, via l'API, depuis le tableau de bord ou au point de rendez-vous avec qui est libre. Dans l'API, c'est le poste propre de l'école : il a un calendrier, un prix et un interrupteur de confirmation immédiate à lui, il ne figure pas dans /instructors, et ses réservations arrivent avec unassigned: true et instructorId égal au poste (pool_…). Il vend autant de cours à la fois que son calendrier a de places : un bloc available peut porter capacity (jusqu'à 50 ; 1 s'il n'en porte pas), comptées dans la station du bloc minute par minute : les blocs propres à un jour remplacent les blocs hebdomadaires sur les minutes qu'ils couvrent, et à l'intérieur de chacun, les blocs qui se chevauchent s'additionnent. Un cours a besoin d'une place sur toute sa durée. Les cours collectifs du poste n'occupent pas de places : ils ont lieu en même temps que les cours particuliers et que d'autres cours.

GET /unassigned affiche les réglages ; PATCH /unassigned fixe n'importe lequel de hourlyPrice, extraStudentPrice (0 ou plus ; négatif, il donne un 422 invalid_price), extraStudentPer, durationPrices, seasonPrices, includedStudents, autoAcceptBookings et maximumStudents. Le premier PATCH crée le poste, et jusque-là ses endpoints de calendrier et de blocs renvoient 404. Il n'y a pas d'interrupteur : active indique si le poste est en vente, ce qu'il est dès que son prix horaire dépasse le plancher (ou, s'il vend des formules, dès que ses formules et ses saisons sont complètes) ; il vend sur les heures qu'ouvre son calendrier, donc une école qui ne veut pas de ces cours n'en ouvre aucune. Un active dans un PATCH est ignoré. Pour le reste, le calendrier du poste fonctionne comme celui d'un moniteur, dans les stations de l'école.

Formules fixes. Au lieu de l'heure, une école peut vendre les cours particuliers de son poste en formules fixes, réglées dans le tableau de bord : jusqu'à 6 (matin, après-midi, journée complète ou autre, chacune avec son début et sa fin) et des saisons, des périodes avec un prix par formule, par cours pour tout le groupe. saleMode dans GET /unassigned indique laquelle des deux, et lessonFormats liste les formules et les saisons (en lecture seule dans l'API). Tant que le poste vend des formules, chacun de ses cours particuliers en est une : une formule sans prix dans la saison d'une date n'est pas vendue ce jour-là, et une date hors de toute saison ne vend rien. Une formule a besoin d'une place libre pendant tout son horaire, comme tout cours du poste, et n'a pas la limite de 6 heures des cours à l'heure. Un tel poste est en vente dès que ses formules et ses saisons sont complètes, quel que soit son prix horaire. Ses réservations portent format (id et type), subtotal est le prix de cette formule ce jour-là, et propose-time ne la déplace qu'au même horaire, un jour qui vend sa formule au prix payé (sinon 409 format_fixed_time ou format_price_differs). Dans l'environnement de test, POST /sandbox/bookings sur le poste accepte formatId et utilise les formules de votre école.

Tant que le cours n'est pas attribué, l'école en est le côté moniteur : elle répond à la demande, discute avec le client par la messagerie et convient du point de rendez-vous. Une fois attribué, la réservation est celle du moniteur comme n'importe quelle autre, et ce que l'école peut encore en faire suit managedBy.

Un cours collectif est un événement avec des places que des clients indépendants achètent séparément : ponctuel (date) ou série hebdomadaire (dayOfWeek, avec since et until en option), avec une capacité, un prix par place pour tout le cours, un niveau, à qui il s'adresse (audience : tous, enfants ou adultes ; un cours enfants peut indiquer minAge et maxAge, et chaque élève qui réserve une place doit y correspondre), un point de rendez-vous fixe et un minimum de participants pour avoir lieu. Les cours d'un moniteur prennent leur prix par place dans les réglages du moniteur lui-même (groupClassesEnabled et groupPricePerStudent, modifiables via PATCH /instructors/{id}) ; seul le poste sans moniteur le fixe à la création, et un changement de prix réécrit les cours actifs. Les cours se publient, se confient à un moniteur et s'annulent depuis le panneau — sur l'API ils sont en lecture seule en v1 — et vivent sur un moniteur de l'effectif ou sur le poste sans moniteur attribué.

GET /instructors/{id}/classes (et GET /unassigned/classes) listent les cours actifs. GET …/classes/expanded?from&to les résout en dates concrètes avec leurs places prises, paiements en cours dans leurs 10 minutes de réservation compris — au plus 62 jours par appel. Sur le calendrier d'un moniteur, les heures d'un cours apparaissent aussi comme occupées dans la vue étendue des disponibilités, et un bloc externe sur elles est refusé avec un 409 booking_conflict : ces heures ne sont pas à vous pour être vendues ailleurs. Le poste sans moniteur attribué est une équipe : ses cours ne prennent rien à ses places particulières, ont lieu en même temps qu'elles et que d'autres cours, et un bloc externe n'entre jamais en conflit avec eux.

Chaque place vendue arrive par /bookings comme une réservation ordinaire avec son groupClassId, confirmée dès qu'elle est payée (acceptedVia auto). propose-time et assign la refusent — l'horaire appartient au cours et à tous ses participants, et un cours passe à un moniteur en entier, depuis le panneau. Annuler un cours (ou un jour de la série) rembourse chaque place intégralement et envoie un booking.cancelled par place ; un cours encore sous son minStudents 24 heures avant le début est annulé de la même façon, avec cancelledBy platform.

Seules les réservations payées atteignent l'API : une réservation existe pour vous dès l'instant où son paiement aboutit (paidAt), et une réservation remboursée reste listée avec son paymentStatus. Un client choisit un moniteur et un créneau, paie, et la demande arrive chez le moniteur ou chez l'école. À partir de là, soit elle reçoit une réponse, soit elle expire sans réponse et le client est remboursé.

L'horloge : le délai de réponse est de 48 heures à compter du paiement, jamais au-delà du début du cours ; une proposition ou son refus le remet à zéro (jamais au-delà du plus tôt des deux débuts, l'original et le proposé) ; un balayage horaire fait expirer ce qui est en retard, si bien que l'expiration peut arriver jusqu'à une heure plus tard. Un cours confirmé passe à upcoming 24 heures avant son début et à in_progress pendant qu'il a lieu. Il est marqué terminé quand le client le confirme, ou de lui-même 48 heures après sa fin ; la clôture libère votre part. Le client peut annuler sans frais jusqu'à freeCancellationHours heures avant le début : le délai propre à la réservation, celui qu'avait la politique d'annulation de votre école au moment où elle a été faite (48 par défaut), et qu'elle garde quoi que devienne la politique ensuite.

Du client, vous recevez un nom court (prénom et initiale), sa langue préférée et son message : de quoi donner le cours, et ce que notre politique de confidentialité lui promet. L'e-mail, le téléphone et tout identifiant de compte ne sont jamais envoyés ; la conversation avec le client reste dans la messagerie d'Alpine Pal, là où se trouve le moniteur.

GET /bookings liste les réservations payées de vos moniteurs, de la modification la plus ancienne à la plus récente, avec des filtres sur status (liste séparée par des virgules), instructorId, from et to (dates du cours) et updatedSince (n'importe quel instant ISO 8601 ; inclusif). Les pages sont paginées par curseur sur (updatedAt, id) : suivez nextCursor jusqu'à ce qu'il soit null. Le curseur est opaque et n'expire jamais, mais il appartient aux filtres avec lesquels il a été créé : changez-les et repartez du début ; un curseur inventé est un 400.

Le schéma d'une synchronisation nocturne ou horaire est toujours le même : retenez l'updatedAt le plus récent que vous avez vu et demandez tout depuis là, exactement tel que vous l'avez reçu. Les webhooks vous préviennent à l'instant où quelque chose change ; cet endpoint est la façon de vous rattraper après une interruption. updatedAt bouge aussi pour des changements qui n'envoient aucun événement (le cours qui passe à upcoming ou in_progress, un rappel envoyé), si bien qu'une ligne peut apparaître dans une synchronisation sans rien de visiblement différent.

Les actions sont ouvertes à l'école sur les moniteurs qu'elle gère et sur son propre poste de cours sans moniteur attribué ; sur un moniteur qui se gère lui-même, la réponse est 403 not_managed_by_school. Chaque action est une mise à jour conditionnelle : si la réservation n'est plus dans l'état que l'action attend, la réponse est 409 booking_state avec l'état actuel dans details, et rien ne change. Répéter une action est donc sans risque, et la façon de confirmer ce qui s'est passé est GET /bookings/{id}.

Deux choses manquent ici à dessein : marquer une absence et déclarer un cours terminé. Toutes deux font bouger de l'argent d'après ce qui s'est passé sur la piste, et toutes deux restent un acte humain dans le tableau de bord.

Enregistrez une URL https et nous y faisons un POST de chaque événement de réservation : le même JSON que renvoient les endpoints de réservations, enveloppé dans un événement. Jusqu'à 10 endpoints par école, chacun abonné à certains événements ou à tous avec "*". Enregistrez-les depuis le tableau de bord ou via l'API ; le tableau de bord montre le journal des livraisons dans les deux cas. L'URL doit être en https, avec un nom d'hôte comportant un point, sans identifiants de connexion ni fragment, et ni une adresse privée ni la nôtre.

Événements. booking.requested : une demande payée est arrivée. booking.confirmed : acceptée par le moniteur ou par l'école, confirmée automatiquement, ou le client a accepté un horaire proposé ; acceptedVia dit lequel, et previousStatus vaut change_proposed dans le dernier cas. booking.time_proposed : un autre horaire a été proposé au client. booking.rejected. booking.cancelled : cancelledBy vaut customer, instructor, school ou platform (le compte derrière la réservation a été supprimé, ou un cours collectif a été annulé faute d'atteindre son minimum). booking.expired : personne n'a répondu à temps. booking.completed : le cours est terminé, absences comprises. booking.updated : tout le reste qui mérite d'être signalé, avec data.reason : proposal_declined, meeting_point_proposed, meeting_point_confirmed, dispute_opened, dispute_resolved, refund_settled (l'argent est revenu au client), refund_issued (par nous) ou instructor_assigned (previousInstructorId nomme le poste sur lequel était le cours). ping est l'événement de test, avec un data vide ; ce n'est pas un type auquel on s'abonne. Aucun événement n'est émis pour upcoming, in_progress, ni pour les changements d'effectif ou de managedBy.

À quoi s'attendre. La livraison est au moins une fois : une réponse qui arrive après notre délai de 10 secondes compte comme un échec et l'événement revient, donc traitez l'id de l'événement comme clé et ignorez les répétitions. L'ordre n'est pas garanti, les nouvelles tentatives et le balayage réordonnent les événements, donc triez par data.booking.updatedAt. Une réservation ne commence pas toujours par booking.requested : celle d'un moniteur dont la confirmation immédiate est activée (autoAcceptBookings) arrive directement comme booking.confirmed, avec previousStatus pending_instructor_approval. Créez donc la réservation dans votre système dès le premier événement reçu pour son id, quel que soit son type. Le payload est figé à la création de l'événement ; une nouvelle tentative porte ce qui était vrai alors, et un événement ultérieur, l'état plus récent. Un événement peut se perdre si notre tentative de l'enregistrer échoue ; GET /bookings?updatedSince est le filet de sécurité. Chaque événement porte sandbox: true ou false. Le journal conserve les livraisons 30 jours ; un renvoi envoie à nouveau une livraison passée.

Chaque livraison est signée avec le secret de l'endpoint : l'en-tête X-AlpinePal-Signature porte un horodatage et un HMAC-SHA256 de l'horodatage, d'un point et du corps brut. Vérifiez-la avant de faire confiance à quoi que ce soit, comparez en temps constant, et rejetez les horodatages à plus de 5 minutes de votre horloge. Le secret est renvoyé à la création de l'endpoint et par GET /webhooks, et peut être renouvelé depuis le tableau de bord ou avec POST /webhooks/{id}/rotate-secret ; l'ancien meurt aussitôt.

Répondez avec n'importe quel 2xx en moins de 10 secondes. Tout le reste, un 3xx compris puisque nous ne suivons pas les redirections, est un échec : nous réessayons après 5 minutes, 15 minutes, 1 heure, 4 heures, 12 heures et 24 heures, environ 42 heures en tout, chaque fois avec le même id d'événement pour que vous puissiez dédupliquer. Un endpoint n'est désactivé, et les gestionnaires de l'école prévenus, que lorsqu'une livraison a épuisé toutes ses tentatives sans qu'aucune autre livraison n'aboutisse entre-temps ; une courte panne ne le désactive pas, même avec de nombreux événements en cours. Tant qu'il est désactivé, les nouveaux événements ne sont pas mis en file pour lui (GET /bookings?updatedSince vous permet de rattraper), et une livraison en attente dont la tentative arrive à échéance pendant ce temps passe en échec sans être envoyée ; les nouvelles tentatives qui arrivent à échéance après sa réactivation partent normalement. Renvoyez celles qui ont échoué. POST /webhooks/{id}/test met un ping en file comme une livraison ordinaire, le tente tout de suite et indique comment s'est passée cette tentative : un ping en échec est réessayé de la même façon, compte comme n'importe quelle livraison pour la désactivation de l'endpoint et, sur un endpoint désactivé, passe en échec sans être envoyé. GET /webhooks/{id}/deliveries montre les livraisons les plus récentes d'abord, 50 par défaut et jusqu'à 100 avec ?limit=, avec leur nombre de tentatives et sans leurs corps : chaque événement a une livraison par endpoint, plus une par renvoi, avec le même id d'événement.

Chaque école dispose d'une jumelle de test dès que son titulaire crée une clé de test depuis le tableau de bord (Connexions → Environnement de test) : une copie de l'école avec deux moniteurs fictifs, sandbox_ia_…, qui répond aux demandes à la main, et sandbox_ib_…, avec la confirmation immédiate activée, et le poste des cours sans moniteur attribué, chacun avec un calendrier 09:00–17:00 tous les jours dans les stations de l'école, de 1 à 6 heures par cours, jusqu'à 6 élèves, sans marge ni préavis. Les clés de test commencent par ap_test_ et n'atteignent que la jumelle ; les clés réelles jamais. Tout le reste est la même API : lister les moniteurs de la jumelle, écrire leurs calendriers, enregistrer des webhooks, répondre aux demandes, attribuer des cours.

Ce qu'un client fait sur le site, POST /sandbox/bookings le fait pour vous : il crée une réservation payée pour le moniteur que vous nommez, avec les mêmes vérifications qu'une vraie, disponibilités publiées et aucun chevauchement, et sans argent en jeu. À partir de là, la vraie machinerie tourne, et les actions ci-dessous tiennent lieu de client et d'horloge, si bien que chaque événement peut être observé en quelques minutes. Aucun e-mail ne sort de l'environnement de test, et rien de ce qu'il contient n'est jamais public ; chaque événement qu'il envoie porte sandbox: true, tout comme GET /me. POST /sandbox/reset le vide pour qu'une suite de tests parte de zéro.

Restent hors de portée dans l'environnement de test : les litiges, les absences, un remboursement émis par nous, une annulation avec cancelledBy platform, et le point de rendez-vous (ses événements viennent du site). Les réservations de l'environnement de test portent un studentLevels vide et un client nommé Sandbox C. qui lit le site en anglais.

La description lisible par une machine vit à https://alpinepal.com/api/v1/openapi.json : chaque chemin, méthode, paramètre et schéma ci-dessus, en OpenAPI 3.1. Pointez-y un générateur pour obtenir un client typé, ou importez-la dans votre outil HTTP pour la parcourir. Elle est servie sans authentification et mise en cache pendant une heure.

Ceci est la v1. À l'intérieur, nous ne faisons qu'ajouter : de nouveaux champs, de nouveaux paramètres facultatifs, de nouveaux types d'événements, de nouveaux endpoints. Votre intégration doit ignorer les champs et les événements qu'elle ne connaît pas. Tout ce qui casserait un client existant ira dans une v2 à une nouvelle URL de base, la v1 restant en service pendant que vous migrez.