API voor skischolen

Sleutels horen bij de skischool, niet bij een persoon, en alleen de eigenaar van de skischool kan ze aanmaken of intrekken, via het tabblad Koppelingen in het dashboard van de skischool. Een sleutel wordt één keer getoond, bij het aanmaken; wij bewaren een hash en kunnen hem niet opnieuw tonen. Een skischool kan tot 5 live sleutels hebben, zodat een nieuwe koppeling een eigen sleutel krijgt en een oude kan worden ingetrokken zonder aan de rest te komen. Live sleutels beginnen met ap_live_; de sleutels van de sandbox beginnen met ap_test_ en tellen apart.

Een sleutel werkt niet meer vanaf het moment dat hij wordt ingetrokken, en alle sleutels krijgen een 403 school_not_active zodra de skischool is gesloten of niet is goedgekeurd. Een skischool die alleen is geschorst (verborgen op de site, zonder eigen pagina) houdt haar sleutels: haar boekingen lopen door, en de API ook. Sleutels kun je niet via de API zelf beheren. Om een sleutel te vervangen: maak de nieuwe sleutel aan, zet je systeem erop over en trek daarna de oude in – in de tussentijd zijn ze allebei geldig. Het dashboard toont wanneer elke sleutel voor het laatst is gebruikt, tot op 5 minuten nauwkeurig. Sleutels zijn voor servers: zet er nooit een in een browser of een mobiele app.

Elk verzoek stuurt de sleutel mee als bearer-token. De basis-URL is https://alpinepal.com/api/v1; antwoorden zijn JSON, worden nooit gecachet en hebben elk een X-Request-Id die je ons kunt doorgeven. Tijdstippen op de dag volgen de klok van het skigebied, als HH:mm; datums zijn YYYY-MM-DD, en tijdstempels zijn ISO 8601 in UTC met milliseconden.

De body van een verzoek moet JSON zijn, met een header Content-Type: application/json (anders 415), kleiner dan 256 KB (413), en wordt streng gecontroleerd: een onbekend veld geeft een 400 validation_error met de paden die niet kloppen. Een lege body geldt als een leeg object. Een methode die het pad niet ondersteunt, geeft een 405 met een Allow-header; een schuine streep aan het eind geeft een 404.

Er is geen CORS: de API werkt van server tot server, en een verzoek vanuit een browser mislukt. Dat is met opzet, want een sleutel in een browser is een sleutel die iedereen kan lezen.

Per sleutel, in vaste vensters van een minuut: 600 leesverzoeken (GET) en 120 schrijfverzoeken (al het andere, DELETE inbegrepen) per minuut. Daarboven is het antwoord 429 rate_limited met een Retry-After-header, in seconden. Een testsleutel heeft een eigen tegoed. Mislukte authenticatie is per IP-adres beperkt, 20 in 10 minuten; daarna krijgt elke volgende poging een 429, nog voordat de sleutel zelfs maar wordt opgezocht. Webhooktests en replays delen een apart tegoed van 10 in 10 minuten per sleutel, want elk daarvan is een verzoek aan de server van iemand anders.

Elke fout heeft dezelfde vorm: een HTTP-status, een vaste code om op te vertakken, een bericht voor mensen en de request-id. Vijf codes hebben details: validation_error noemt de foute velden als [{path, message}] (maximaal 10); booking_state zegt in welke status de boeking nu is ({bookingStatus}); booking_conflict noemt de uren die in de weg zitten en, als die boeking betaald is, de id en referentie ervan; rate_limited herhaalt de wachttijd als {retryAfterSeconds}; inside_notice_window geeft de minimale boekingstermijn van de skileraar in uren ({hours}).

Id's. Skileraren hebben de id van hun account (user_…), of unclaimed_… zolang een profiel dat je skischool zonder account heeft aangemaakt nog niet is overgenomen; de plek van een skischool voor lessen zonder toegewezen skileraar is pool_<schoolId>; de skileraren van de sandbox zijn sandbox_ia_… en sandbox_ib_…. Boekingen zijn b_…, events evt_…, bezorgingen whd_…, endpoints wh_…, verzoeken req_…. Referenties zijn AP-<jaar>-<5 cijfers> voor echte boekingen en SB<6 hex> in de sandbox.

Tijden. date, startTime en endTime zijn de lokale tijd van resortTimeZone, nooit UTC; de tijdstempels (createdAt, updatedAt, paidAt, instructorResponseDeadline…) zijn UTC. Valt een les in de nacht waarin de klok wordt verzet op een uur dat twee keer voorkomt, dan geldt het eerste; een uur dat die nacht niet bestaat, schuift naar voren. endTime mag 24:00 zijn. Of een tijdstip in het verleden ligt, wordt beoordeeld op de klok van het skigebied.

Geld. subtotal = (hourlyPrice + extraStudentPrice × max(0, numberOfStudents − includedStudents)) × durationHours, afgerond op de valuta; dat is wat de klant betaalt. hourlyPrice is die van de lesdatum: die van een seizoen (seasonPrices) als de datum erin valt, anders die van de skileraar of de plek zelf; includedStudents is hoeveel leerlingen die prijs dekt, 1 tenzij de skischool meer instelt. platformFee is onze commissie: 10%, of de hogere die je skischool schriftelijk met ons heeft afgesproken; elke boeking houdt het percentage waartegen ze is verkocht. netAmount is de rest, subtotal − platformFee, die op het saldo van je skischool wordt bijgeschreven als de les is afgerond, wie hem ook gaf en wie die skileraar ook beheert – en die vervalt als de boeking wordt terugbetaald. Elke skileraar in je team rekent af in de valuta van je skischool; uurprijzen hebben een minimum per valuta (10 EUR, 11 USD, 10 CHF) en extraStudentPrice is 0 of meer. Materiaal dat de klant met de les bij je skischool huurt, telt ook mee in subtotal (equipment.amount) en wordt behandeld als de les.

managedBy is de regel die bepaalt wie antwoordt: staat er instructor, dan zijn de agenda en de aanvragen van de skileraar en kan de API lezen maar niet schrijven; staat er school, dan schrijft de skischool – en dus de API – de agenda en beantwoordt zij de aanvragen, en kijkt de skileraar mee. Het wordt ingesteld vanuit het team in het dashboard, door een persoon, en kan niet via de API worden gewijzigd. Geef je een agenda terug aan de skileraar, dan worden de externe blokken verwijderd die je systeem erin heeft gezet.

Als een skileraar de skischool verlaat, verdwijnen de boekingen van die skileraar uit GET /bookings en stoppen de events, terwijl wat al is verdiend op je saldo blijft. Daarvoor en voor een wijziging van managedBy komt er geen event: vergelijk GET /instructors bij elke synchronisatie.

unclaimed markeert een skileraar die de skischool zonder account in het dashboard heeft toegevoegd: niemand logt in als die skileraar, dus het profiel staat altijd op managedBy school en de skischool handelt alles af, ook de chat. Als de persoon het profiel overneemt met een eigen account, wordt unclaimed false en verandert de id van de skileraar in een definitieve: alle paden en het filter instructorId blijven de oude id accepteren, de skileraar draagt die als previousId, en events noemen vanaf dan de nieuwe. Geen enkel event meldt dit: vergelijk GET /instructors bij elke synchronisatie en koppel op previousId.

De beschikbaarheid van een skileraar is een lijst met blokken. Een blok is available, blocked of vacation, hoort bij een skigebied waar de skileraar lesgeeft, loopt van startTime tot endTime (endTime mag 24:00 zijn) en is gekoppeld aan een dag van de week (dayOfWeek 0–6, zondag eerst, eventueel met since en until als eerste en laatste datum waarop het geldt) of aan één datum – precies een van de twee. Nieuwe available-uren moeten tussen 07:00 en 21:00 uur vallen, lokale tijd van het skigebied (anders een 422 outside_ski_day); blocked- en vacation-blokken mogen elk tijdstip beslaan. Klanten kunnen alleen boeken binnen available-blokken die door niets anders worden overlapt.

PUT /instructors/{id}/availability vervangt het hele rooster – elk skigebied, elk blok, tot 400 – door wat je stuurt, precies zoals het opslaan van de agenda in het dashboard. Id's zijn optioneel: de server geeft een id aan een blok zonder id, behoudt de id's die je meestuurt en weigert duplicaten of het voorvoegsel xb_ van externe blokken. Externe blokken (zie hieronder) worden door PUT nooit aangeraakt en mogen er niet in voorkomen. Een ongeldig blok, een onbekend skigebied, beide ankers tegelijk of een since na de until van het blok geeft een 422 invalid_availability. Blokken die niet meer kunnen gelden (een datum die voorbij is, een weekblok na zijn until), vallen weg: PUT slaat ze niet op en GET geeft ze niet terug. Een datum is voorbij als hij overal voorbij is, om 12:00 UTC de volgende dag.

GET …/availability/expanded doet het rekenwerk voor je: voor één skigebied en tot 62 dagen geeft het per dag de vrije periodes die een klant zou kunnen boeken en de bezette, elke bezette periode gelabeld als booking (een bevestigde les), pending (een betaalde aanvraag die op antwoord wacht) of external (een blok uit de API). Het houdt rekening met de buffer tussen lessen en de minimale boekingstermijn die de skileraar heeft ingesteld; gaten die korter zijn dan de minimale lesduur laat het niet weg, dus een gat van dertig minuten staat als vrij.

Een les die je buiten Alpine Pal hebt verkocht, houdt de skileraar bezet. Leg hem vast als extern blok en het tijdslot verdwijnt uit de zoekresultaten, in elk skigebied waar de skileraar lesgeeft – iemand kan niet in twee dalen tegelijk zijn. Voor blokken moet de skischool de skileraar beheren (managedBy = school).

Elk blok heeft je eigen externalRef. Dezelfde referentie nog eens sturen met dezelfde datum en uren is idempotent en geeft 200 met het opgeslagen blok, welke resortId je ook meegeeft; dezelfde referentie met andere uren geeft een 409 external_ref_exists – verwijder het blok en maak het opnieuw aan. Een blok dat overlapt met een actieve boeking geeft een 409 booking_conflict met de uren die in de weg zitten en, als die boeking betaald is, de id en referentie ervan: die les is bij ons al verkocht.

Een skileraar heeft vanaf vandaag maximaal 400 externe blokken; nog één erbij geeft een 422 limit_reached. Een blok waarvan de datum voorbij is (om 12:00 UTC de volgende dag), verdwijnt vanzelf: GET /blocks toont het niet meer, een DELETE erop geeft een 404 en het telt niet meer mee voor de 400.

Bij het accepteren van een boekingsaanvraag wordt het tijdslot opnieuw gecontroleerd: een extern blok op die uren geeft, net als een actieve boeking of een groepsles, een 409 slot_conflict, en dan moet de skischool de aanvraag afwijzen of een ander tijdstip voorstellen. Op de plek zonder toegewezen skileraar wordt bij het accepteren niets opnieuw gecontroleerd: de plaatsen ervan zijn geteld toen de klant betaalde. Zodra je blok met 201 is beantwoord, is het uur van jou: een betaling die er al voor bezig was, wordt terugbetaald zodra die betaling binnenkomt, en bereikt je als booking.expired.

Een skischool kan uren verkopen zonder te zeggen wie ze gaat geven: de klant boekt en betaalt, en de skischool wijst een skileraar toe wanneer ze wil – via de API, vanuit het dashboard, of op het ontmoetingspunt met wie er vrij is. In de API is dit de eigen plek van de skischool: die heeft een eigen agenda, een eigen prijs en een eigen schakelaar voor directe bevestiging, staat niet bij /instructors, en de boekingen ervan komen binnen met unassigned: true en instructorId gelijk aan de plek (pool_…). De plek verkoopt zoveel lessen tegelijk als de agenda plaatsen heeft: een available-blok kan een capacity hebben (tot 50; 1 als die ontbreekt), geteld in het skigebied van het blok, minuut voor minuut – de eigen blokken van een dag vervangen de wekelijkse voor de minuten die ze beslaan, en binnen elk van beide tellen overlappende blokken op. Een les heeft een plaats nodig voor de hele duur. De groepslessen van de plek nemen geen plaatsen in: ze lopen naast de privélessen en naast elkaar.

GET /unassigned toont de instellingen; PATCH /unassigned stelt een of meer van hourlyPrice, extraStudentPrice (0 of meer; een negatieve geeft een 422 invalid_price), extraStudentPer, durationPrices, seasonPrices, includedStudents, autoAcceptBookings en maximumStudents in. De eerste PATCH maakt de plek aan; tot dan geven de agenda- en blok-endpoints ervan een 404. Er is geen schakelaar: active zegt of de plek te koop is, en dat is ze zodra de uurprijs boven het minimum ligt (of, als ze formules verkoopt, zodra de formules en seizoenen compleet zijn); ze verkoopt in de uren die de agenda openzet, dus een skischool die deze lessen niet wil, zet er geen open. Een active in een PATCH wordt genegeerd. Verder werkt de agenda van de plek zoals die van een skileraar, in de skigebieden van de skischool.

Vaste formules. In plaats van per uur kan een skischool de privélessen van haar plek verkopen in vaste formules, die je in het dashboard instelt: maximaal 6 (ochtend, middag, hele dag of anders, elk met een begin en een einde) en seizoenen, periodes met een prijs per formule, per les voor de hele groep. saleMode in GET /unassigned zegt welke van de twee geldt, en lessonFormats geeft de formules en seizoenen (alleen-lezen in de API). Zolang de plek formules verkoopt, is elke privéles ervan een van die formules: een formule zonder prijs in het seizoen van een datum wordt die dag niet verkocht, en op een datum buiten elk seizoen wordt niets verkocht. Een formule heeft de hele tijd een vrije plaats nodig, zoals elke les van de plek, en heeft niet de limiet van 6 uur van lessen per uur. Zo'n plek is te koop zodra de formules en seizoenen compleet zijn, wat de uurprijs ook is. De boekingen ervan hebben format (id en soort), subtotal is de prijs van die formule op die dag, en propose-time verzet zo'n les alleen naar dezelfde tijden op een dag die de formule tegen de betaalde prijs verkoopt (anders 409 format_fixed_time of format_price_differs). In de sandbox accepteert POST /sandbox/bookings op de plek formatId en gebruikt het de formules van je skischool.

Tot de les is toegewezen, neemt de skischool de rol van de skileraar op zich: ze beantwoordt de aanvraag, chat met de klant en spreekt het ontmoetingspunt af. Eenmaal toegewezen is de boeking van de skileraar zoals elke andere, en wat de skischool er nog mee mag doen, volgt uit managedBy.

Een groepsles is een les met plaatsen die losse klanten elk apart kopen: eenmalig (date) of als wekelijkse reeks (dayOfWeek, eventueel met since en until), met een capaciteit, een prijs per plaats voor de hele les, een niveau, een doelgroep (audience: iedereen, kinderen of volwassenen – een kinderles kan een minAge en maxAge noemen, en elke deelnemer die een plaats boekt, moet daarbinnen vallen), een vast ontmoetingspunt en een minimumaantal deelnemers om door te gaan. De groepslessen van een skileraar nemen hun prijs per plaats over uit de eigen instellingen van die skileraar (groupClassesEnabled en groupPricePerStudent, te schrijven via PATCH /instructors/{id}); alleen de plek zonder toegewezen skileraar noemt de prijs bij het aanmaken, en een prijswijziging past de actieve groepslessen aan. Groepslessen worden vanuit het dashboard gepubliceerd, aan een skileraar gegeven en geannuleerd – in de API zijn ze in v1 alleen-lezen – en horen bij een skileraar uit je team of bij de plek zonder toegewezen skileraar.

GET /instructors/{id}/classes (en GET /unassigned/classes) tonen de actieve groepslessen. GET …/classes/expanded?from&to zet ze om in concrete datums met hun bezette plaatsen, inclusief betalingen die nog binnen hun reserveringstijd van 10 minuten lopen – maximaal 62 dagen per aanroep. In de agenda van een skileraar staan de uren van een groepsles in de uitgebreide weergave van de beschikbaarheid ook als busy, en een extern blok erop wordt geweigerd met een 409 booking_conflict: die uren kun je niet elders verkopen. Achter de plek zonder toegewezen skileraar staat een heel team: de groepslessen ervan nemen niets af van de privéplaatsen, lopen ernaast en naast elkaar, en een extern blok botst er nooit mee.

Elke verkochte plaats komt via /bookings binnen als een gewone boeking met een groupClassId, bevestigd op het moment dat ze betaald is (acceptedVia auto). propose-time en assign weigeren een plaats – het tijdstip hoort bij de groepsles en bij alle andere deelnemers, en een groepsles gaat in zijn geheel naar een skileraar, vanuit het dashboard. Een groepsles annuleren (of één datum van een reeks) betaalt elke plaats volledig terug en stuurt één booking.cancelled per plaats; een groepsles die 24 uur voor de start nog onder zijn minStudents zit, wordt op dezelfde manier afgelast, met cancelledBy platform.

Alleen betaalde boekingen bereiken de API: een boeking bestaat voor jou vanaf het moment dat de betaling binnenkomt (paidAt), en een terugbetaalde boeking blijft in de lijst staan met haar paymentStatus. Een klant kiest een skileraar en een tijdslot, betaalt, en de aanvraag komt terecht bij de skileraar of bij de skischool. Vanaf dan wordt ze beantwoord, of ze verloopt zonder antwoord en de klant krijgt zijn geld terug.

De klok: de antwoordtermijn is 48 uur vanaf de betaling, nooit later dan het begin van de les; een voorstel of het afwijzen ervan laat hem opnieuw ingaan (nooit voorbij de vroegste van de oorspronkelijke en de voorgestelde starttijd); een controleronde die elk uur draait, laat verlopen wat over tijd is, dus het verlopen kan tot een uur later vallen. Een bevestigde les wordt upcoming 24 uur voor de start en in_progress terwijl hij bezig is. Hij wordt afgerond als de klant hem bevestigt, of vanzelf 48 uur na het einde; met de afronding komt je deel vrij. De klant kan kosteloos annuleren tot freeCancellationHours uur voor de start: de termijn van de boeking zelf, die het annuleringsbeleid van je skischool had toen ze werd gemaakt (standaard 48), en die de boeking houdt, hoe het beleid later ook verandert.

Over de klant krijg je een korte naam (voornaam en initiaal), de voorkeurstaal en het bericht – genoeg om de les te geven, en wat onze privacyverklaring de klant belooft. E-mailadres, telefoonnummer en accountkenmerken worden nooit verstuurd; het gesprek met de klant blijft in de chat op Alpine Pal, waar de skileraar zit.

GET /bookings toont de betaalde boekingen van je skileraren, oudste wijziging eerst, met filters voor status (een lijst met komma's), instructorId, from en to (lesdatums) en updatedSince (elk ISO 8601-tijdstip; inclusief). Pagina's werken met een keyset op (updatedAt, id): volg nextCursor tot die null is. De cursor is ondoorzichtig en verloopt nooit, maar hoort bij de filters waarmee hij is gemaakt – verander je die, begin dan opnieuw; een verzonnen cursor geeft een 400.

Voor een synchronisatie elke nacht of elk uur is het patroon hetzelfde: onthoud de nieuwste updatedAt die je hebt gezien en vraag alles op sinds dat moment, met de waarde precies zoals je die hebt ontvangen. Webhooks laten je weten op het moment dat er iets verandert; met dit endpoint haal je de achterstand in na een storing. updatedAt verandert ook bij wijzigingen die geen event sturen – de les wordt upcoming of in_progress, er is een herinnering verstuurd – dus een regel kan in een synchronisatie opduiken zonder dat er zichtbaar iets anders is.

Acties staan open voor de skischool bij skileraren die ze beheert en bij haar eigen plek voor lessen zonder toegewezen skileraar; bij een skileraar die zichzelf beheert, is het antwoord 403 not_managed_by_school. Elke actie is een voorwaardelijke update: is de boeking niet meer in de status die de actie verwacht, dan is het antwoord 409 booking_state met de huidige status in details, en verandert er niets. Een actie herhalen is dus veilig, en de manier om na te gaan wat er is gebeurd, is GET /bookings/{id}.

Twee dingen ontbreken hier met opzet: een no-show registreren en een les afronden. Allebei verschuiven ze geld op basis van wat er op de piste is gebeurd, en allebei blijven ze een menselijke handeling in het dashboard.

Registreer een https-URL en we sturen elk boekingsevent daarheen met een POST – dezelfde JSON die de boekingsendpoints teruggeven, verpakt in een event. Tot 10 endpoints per skischool, elk geabonneerd op bepaalde events of met "*" op allemaal. Registreer ze vanuit het dashboard of via de API; het dashboard toont in beide gevallen het bezorglog. De URL moet https zijn, met een hostnaam die een punt bevat, zonder inloggegevens of fragment, en geen privéadres of een adres van ons.

Events. booking.requested – er is een betaalde aanvraag binnengekomen. booking.confirmed – geaccepteerd door de skileraar of de skischool, automatisch bevestigd, of de klant heeft een voorgesteld tijdstip geaccepteerd: acceptedVia zegt welke van de drie, en previousStatus is change_proposed in het laatste geval. booking.time_proposed – de klant heeft een ander tijdstip voorgesteld gekregen. booking.rejected. booking.cancelled – cancelledBy is customer, instructor, school of platform (het account achter de boeking is verwijderd, of een groepsles is afgelast omdat het minimum niet werd gehaald). booking.expired – niemand heeft op tijd geantwoord. booking.completed – de les is afgelopen, no-shows inbegrepen. booking.updated – al het andere dat het melden waard is, met data.reason: proposal_declined, meeting_point_proposed, meeting_point_confirmed, dispute_opened, dispute_resolved, refund_settled (het geld is terug bij de klant), refund_issued (door ons) of instructor_assigned (previousInstructorId noemt de plek waar de les op stond). ping is het testevent, met een lege data; het is geen type waarop je je abonneert. Er gaat geen event uit voor upcoming, in_progress of wijzigingen in het team of in managedBy.

Wat je kunt verwachten. Bezorging gebeurt minstens één keer: een antwoord dat na onze time-out van 10 seconden binnenkomt, telt als mislukt en het event komt opnieuw, dus gebruik de event-id als sleutel en negeer herhalingen. De volgorde is niet gegarandeerd – nieuwe pogingen en de controleronde gooien events door elkaar – dus sorteer op data.booking.updatedAt. Niet elke boeking begint met booking.requested: een boeking bij een skileraar met directe bevestiging (autoAcceptBookings) komt meteen binnen als booking.confirmed, met previousStatus pending_instructor_approval. Maak de boeking in je systeem dus aan bij het eerste event dat je voor die id ziet, welk type het ook is. De payload wordt vastgelegd op het moment dat het event ontstaat; een nieuwe poging bevat wat toen gold, en een later event de nieuwere status. Een event kan verloren gaan als het ons niet lukt het vast te leggen; GET /bookings?updatedSince is het vangnet. Elk event bevat sandbox: true of false. Het log bewaart bezorgingen 30 dagen; met een replay stuur je een eerdere bezorging opnieuw.

Elke bezorging is ondertekend met het secret van het endpoint: de header X-AlpinePal-Signature bevat een tijdstempel en een HMAC-SHA256 van de tijdstempel, een punt en de ruwe body. Verifieer die handtekening voordat je ergens op vertrouwt, vergelijk in constante tijd en weiger tijdstempels die meer dan 5 minuten van je klok afwijken. Het secret krijg je terug bij het aanmaken van het endpoint en via GET /webhooks, en je kunt het vervangen vanuit het dashboard of met POST /webhooks/{id}/rotate-secret; het oude vervalt meteen.

Antwoord binnen 10 seconden met een willekeurige 2xx. Al het andere – ook een 3xx, want we volgen geen redirects – is mislukt: we proberen het opnieuw na 5 minuten, 15 minuten, 1 uur, 4 uur, 12 uur en 24 uur, in totaal ongeveer 42 uur, telkens met dezelfde event-id, zodat je dubbele bezorgingen kunt herkennen. Een endpoint wordt pas uitgezet, en de beheerders van de skischool krijgen pas bericht, als een bezorging bij alle pogingen is mislukt zonder dat er in de tussentijd ook maar één bezorging naar dat endpoint is aangekomen; een korte storing zet het niet uit, hoeveel events er ook onderweg zijn. Zolang het uit staat, worden er geen nieuwe events voor in de wachtrij gezet (met GET /bookings?updatedSince haal je ze in), en een openstaande bezorging waarvan de poging in die tijd aan de beurt is, wordt als mislukt gemarkeerd zonder te worden verstuurd; pogingen die pas na het weer aanzetten aan de beurt zijn, gaan gewoon de deur uit. Stuur de mislukte opnieuw met een replay. POST /webhooks/{id}/test zet een ping in de wachtrij als gewone bezorging, probeert hem meteen en meldt hoe die poging ging: een mislukte ping wordt op dezelfde manier opnieuw geprobeerd, telt als elke bezorging mee voor het uitzetten van het endpoint en wordt bij een endpoint dat uit staat als mislukt gemarkeerd zonder te worden verstuurd. GET /webhooks/{id}/deliveries toont de nieuwste bezorgingen eerst, standaard 50 en met ?limit= tot 100, met het aantal pogingen en zonder body: elk event heeft één bezorging per endpoint, plus één voor elke replay, met dezelfde event-id.

Elke skischool krijgt een testkopie zodra de eigenaar in het dashboard een testsleutel aanmaakt (Koppelingen → Sandbox): een kopie van de skischool met twee verzonnen skileraren – sandbox_ia_…, die aanvragen met de hand beantwoordt, en sandbox_ib_…, met directe bevestiging aan – en de plek voor lessen zonder toegewezen skileraar, elk met een agenda van 09:00–17:00 op alle dagen in de skigebieden van de skischool, 1 tot 6 uur per les, tot 6 deelnemers, zonder buffer en zonder minimale boekingstermijn. Testsleutels beginnen met ap_test_ en bereiken alleen de testkopie; live sleutels nooit. Al het andere is dezelfde API: de skileraren van de testkopie opvragen, hun agenda's schrijven, webhooks registreren, aanvragen beantwoorden, lessen toewijzen.

Wat een klant op de site doet, doet POST /sandbox/bookings voor jou: het maakt een betaalde boeking aan voor de skileraar die je noemt, met dezelfde controles als een echte – gepubliceerde beschikbaarheid, geen overlap – en zonder dat er geld aan te pas komt. Vanaf daar draait het echte systeem, en de acties hieronder nemen de plaats in van de klant en de klok, zodat je elk event binnen enkele minuten kunt zien. Er gaat geen e-mail de sandbox uit, en niets erin is ooit openbaar; elk event dat de sandbox verstuurt, bevat sandbox: true, en GET /me ook. POST /sandbox/reset maakt de sandbox leeg, zodat een testsuite schoon kan beginnen.

Nog buiten bereik in de sandbox: klachten, no-shows, een terugbetaling door ons, een annulering met cancelledBy platform, en het ontmoetingspunt (de events daarvan komen van de site). Sandboxboekingen hebben een lege studentLevels en een klant die Sandbox C. heet en de site in het Engels leest.

De machineleesbare beschrijving staat op https://alpinepal.com/api/v1/openapi.json – elk pad, elke methode, elke parameter en elk schema hierboven, in OpenAPI 3.1. Laat er een generator op los voor een getypeerde client, of importeer het bestand in je HTTP-tool om erdoorheen te bladeren. Het wordt zonder authenticatie geleverd en een uur lang gecachet.

Dit is v1. Binnen v1 voegen we alleen dingen toe: nieuwe velden, nieuwe optionele parameters, nieuwe eventtypes, nieuwe endpoints. Je koppeling moet velden en events negeren die ze niet kent. Alles wat een bestaande client zou breken, komt in een v2 op een nieuwe basis-URL, en v1 blijft draaien terwijl je overstapt.