API für Skischulen

Schlüssel gehören der Skischule, nicht einer Person, und nur der Inhaber der Skischule kann sie erstellen oder widerrufen, im Reiter Verbindungen des Skischul-Dashboards. Ein Schlüssel wird einmal angezeigt, bei der Erstellung; wir speichern einen Hash und können ihn nicht noch einmal anzeigen. Eine Skischule kann bis zu 5 Live-Schlüssel halten, sodass eine neue Integration ihren eigenen bekommt und ein alter widerrufen werden kann, ohne die übrigen anzurühren. Live-Schlüssel beginnen mit ap_live_; die Schlüssel der Testumgebung beginnen mit ap_test_ und werden getrennt gezählt.

Ein Schlüssel funktioniert ab dem Moment nicht mehr, in dem er widerrufen wird, und alle Schlüssel erhalten ein 403 school_not_active, sobald die Skischule geschlossen oder nicht freigegeben ist. Eine nur gesperrte Skischule (auf der Website ausgeblendet, ohne ihre Seite) behält ihre Schlüssel: Ihre Buchungen laufen weiter, und die API mit ihnen. Schlüssel lassen sich nicht über die API selbst verwalten. Zum Rotieren: Erstelle den neuen Schlüssel, stelle dein System darauf um und widerrufe dann den alten – dazwischen sind beide gültig. Das Dashboard zeigt, wann jeder Schlüssel zuletzt benutzt wurde, auf 5 Minuten genau. Schlüssel sind für Server: Liefere nie einen in einem Browser oder einer Mobile-App aus.

Jede Anfrage trägt den Schlüssel als Bearer-Token. Die Basis-URL ist https://alpinepal.com/api/v1; Antworten sind JSON, werden nie gecacht, und jede trägt eine X-Request-Id, die du uns nennen kannst. Uhrzeiten gelten nach der Ortszeit des Skigebiets als HH:mm, Daten sind YYYY-MM-DD, und Zeitpunkte sind ISO 8601 in UTC mit Millisekunden.

Request-Bodys müssen JSON sein, mit dem Header Content-Type: application/json (sonst 415), unter 256 KB (413), und werden strikt geprüft: Ein unbekanntes Feld ist ein 400 validation_error, der die betroffenen Pfade auflistet. Ein leerer Body wird als leeres Objekt gelesen. Eine Methode, die der Pfad nicht unterstützt, ist ein 405 mit einem Allow-Header; ein Schrägstrich am Ende ist ein 404.

Es gibt kein CORS: Die API ist Server-zu-Server, und eine Anfrage aus einem Browser schlägt fehl. Das ist Absicht, denn ein Schlüssel im Browser ist ein Schlüssel, den jeder lesen kann.

Pro Schlüssel, in festen Fenstern von einer Minute: 600 Lesezugriffe (GET) und 120 Schreibzugriffe (alles andere, DELETE eingeschlossen) pro Minute. Darüber hinaus lautet die Antwort 429 rate_limited mit einem Retry-After-Header, in Sekunden. Ein Test-Schlüssel hat sein eigenes Kontingent. Fehlgeschlagene Authentifizierungen sind pro IP-Adresse begrenzt, 20 in 10 Minuten; danach bekommt jeder weitere Versuch 429, noch bevor der Schlüssel überhaupt nachgeschlagen wird. Webhook-Tests und erneute Zustellungen teilen sich ein eigenes Kontingent von 10 in 10 Minuten pro Schlüssel, denn jede einzelne ist eine Anfrage an einen fremden Server.

Jeder Fehler hat dieselbe Form: einen HTTP-Status, einen stabilen code, nach dem du verzweigen kannst, eine Nachricht für Menschen und die Request-Id. Fünf Codes tragen details: validation_error listet die betroffenen Felder als [{path, message}] (höchstens 10); booking_state sagt, in welchem Zustand die Buchung jetzt ist ({bookingStatus}); booking_conflict nennt die Stunden, die im Weg sind, und, wenn diese Buchung bezahlt ist, ihre Id und Referenz; rate_limited wiederholt die Wartezeit als {retryAfterSeconds}; inside_notice_window nennt die Vorlaufzeit des Skilehrers in Stunden ({hours}).

Ids. Skilehrer tragen die Id ihres Kontos (user_…) oder unclaimed_…, solange ein Profil, das deine Skischule ohne Konto angelegt hat, noch nicht übernommen wurde; der Platz einer Skischule für Unterricht ohne zugewiesenen Skilehrer ist pool_<schoolId>; die Skilehrer der Testumgebung sind sandbox_ia_… und sandbox_ib_…. Buchungen sind b_…, Ereignisse evt_…, Zustellungen whd_…, Endpoints wh_…, Anfragen req_…. Referenzen sind AP-<Jahr>-<5 Ziffern> für echte Buchungen und SB<6 hex> in der Testumgebung.

Zeiten. date, startTime und endTime sind die Ortszeit von resortTimeZone, nie UTC; die Zeitpunkte (createdAt, updatedAt, paidAt, instructorResponseDeadline…) sind UTC. Ein Unterricht in der Nacht der Zeitumstellung wird auf das erste Vorkommen einer doppelten Stunde gelegt, und eine Stunde, die es in dieser Nacht nicht gibt, wird auf die nächstfolgende existierende Stunde verschoben. endTime darf 24:00 sein. Ob eine Zeit in der Vergangenheit liegt, wird nach der Uhr des Skigebiets beurteilt.

Geld. subtotal = (hourlyPrice + extraStudentPrice × max(0, numberOfStudents − includedStudents)) × durationHours, auf die Währung gerundet; das ist, was der Kunde bezahlt. hourlyPrice ist der des Unterrichtsdatums: der einer Saison (seasonPrices), wenn das Datum in eine fällt, sonst der eigene des Skilehrers oder des Platzes; includedStudents gibt an, wie viele Schüler er abdeckt, 1, sofern die Skischule nicht mehr festlegt. platformFee ist unsere Provision: 10 % oder die höhere, die deine Skischule schriftlich mit uns vereinbart hat; jede Buchung behält den Satz, zu dem sie verkauft wurde. netAmount ist der Rest, subtotal − platformFee, der dem Guthaben deiner Skischule gutgeschrieben wird, wenn der Unterricht abgeschlossen ist – wer auch immer ihn gegeben hat und wer auch immer diese Person verwaltet –, und der entfällt, wenn die Buchung erstattet wird. Jeder Skilehrer in deinem Kader rechnet in der Währung deiner Skischule ab; Stundenpreise haben eine Untergrenze pro Währung (10 EUR, 11 USD, 10 CHF), und extraStudentPrice ist 0 oder mehr. Ausrüstung, die der Kunde mit dem Unterricht bei deiner Skischule mietet, kommt ebenfalls zu subtotal hinzu (equipment.amount) und zählt wie der Unterricht.

managedBy ist die Regel, die entscheidet, wer antwortet: Steht dort instructor, gehören Kalender und Anfragen dem Skilehrer, und die API kann lesen, aber nicht schreiben; steht dort school, schreibt die Skischule – und damit die API – den Kalender und beantwortet die Anfragen, und der Skilehrer schaut zu. Gesetzt wird es von einer Person, im Kader des Dashboards; über die API lässt es sich nicht ändern. Gibst du einen Kalender an den Skilehrer zurück, werden die externen Blöcke gelöscht, die dein System darin geschrieben hat.

Verlässt ein Skilehrer die Skischule, verschwinden seine Buchungen aus GET /bookings und seine Ereignisse hören auf, während das, was er schon verdient hat, in deinem Guthaben bleibt. Weder das noch eine Änderung von managedBy sendet ein Ereignis: Vergleiche GET /instructors bei jeder Synchronisation.

unclaimed kennzeichnet einen Skilehrer, den die Skischule im Dashboard ohne Konto angelegt hat: Niemand meldet sich als er an, daher ist er immer managedBy school, und die Skischule ist in allem für ihn zuständig, auch im Chat. Übernimmt die Person das Profil mit ihrem eigenen Konto, wird unclaimed false und die Id des Skilehrers ändert sich in eine dauerhafte: Alle Pfade und der Filter instructorId akzeptieren weiterhin die alte Id, der Skilehrer trägt sie in previousId, und Ereignisse nennen ab dann die neue. Kein Ereignis kündigt das an: Vergleiche GET /instructors bei jeder Synchronisation und ordne previousId zu.

Die Verfügbarkeit eines Skilehrers ist eine Liste von Blöcken. Ein Block ist available, blocked oder vacation, gehört zu einem Skigebiet, in dem der Skilehrer unterrichtet, reicht von startTime bis endTime (endTime darf 24:00 sein) und ist entweder an einen Wochentag gebunden (dayOfWeek 0–6, Sonntag zuerst, optional mit since und until als erstem und letztem Datum, an dem er gilt) oder an ein Datum – genau eines von beiden. Neue available-Stunden müssen zwischen 07:00 und 21:00 Uhr Ortszeit des Skigebiets liegen (sonst 422 outside_ski_day); blocked- und vacation-Blöcke dürfen jede Uhrzeit abdecken. Kunden können nur innerhalb von available-Blöcken buchen, die nichts anderes überdeckt.

PUT /instructors/{id}/availability ersetzt den ganzen Plan – jedes Skigebiet, jeden Block, bis zu 400 – durch das, was du sendest, genau wie das Speichern des Kalenders im Dashboard. Ids sind optional: Der Server vergibt eine an einen Block ohne Id, behält die, die du sendest, und lehnt Duplikate oder das Präfix xb_ der externen Blöcke ab. Externe Blöcke (siehe unten) werden von PUT nie angerührt und dürfen darin nicht vorkommen. Ein fehlerhafter Block, ein unbekanntes Skigebiet, beide Anker zugleich oder ein since nach dem until des Blocks sind ein 422 invalid_availability. Blöcke, die nicht mehr gelten können (ein vergangenes Datum, ein Wochenblock nach seinem until), werden verworfen: PUT speichert sie nicht, GET liefert sie nicht. Ein Datum ist vergangen, wenn es überall vergangen ist, also um 12:00 UTC am Folgetag.

GET …/availability/expanded übernimmt das Rechnen für dich: Für ein Skigebiet und bis zu 62 Tage liefert es pro Tag die freien Bereiche, die ein Kunde buchen könnte, und die belegten, jeder belegte Bereich beschriftet mit booking (ein bestätigter Unterricht), pending (eine bezahlte Anfrage, die auf Antwort wartet) oder external (ein Block aus der API). Es wendet den Puffer zwischen zwei Unterrichtseinheiten und die Vorlaufzeit an, die der Skilehrer eingestellt hat; Lücken, die kürzer sind als seine minimale Unterrichtsdauer, lässt es nicht weg, sodass eine Lücke von dreißig Minuten als frei erscheint.

Ein Unterricht, den du außerhalb von Alpine Pal verkauft hast, belegt den Skilehrer. Trage ihn als externen Block ein, und das Zeitfenster verschwindet aus der Suche, in jedem Skigebiet, in dem der Skilehrer unterrichtet – eine Person kann nicht in zwei Tälern zugleich sein. Blöcke setzen voraus, dass die Skischule den Skilehrer verwaltet (managedBy = school).

Jeder Block trägt deine eigene externalRef. Dieselbe Referenz noch einmal mit demselben Datum und denselben Stunden zu senden ist idempotent und liefert 200 mit dem gespeicherten Block, egal welche resortId du übergibst; dieselbe Referenz mit anderen Stunden ist ein 409 external_ref_exists – löschen und neu anlegen. Ein Block, der sich mit einer aktiven Buchung überschneidet, ist ein 409 booking_conflict mit den Stunden, die im Weg sind, und, wenn diese Buchung bezahlt ist, ihrer Id und Referenz: Dieser Unterricht ist auf unserer Seite schon verkauft.

Ein Skilehrer kann ab heute höchstens 400 externe Blöcke haben; einer mehr ist ein 422 limit_reached. Ein Block, dessen Datum vergangen ist (um 12:00 UTC am Folgetag), verschwindet von selbst: GET /blocks listet ihn nicht mehr, ein DELETE darauf ist ein 404, und er zählt nicht mehr zu den 400.

Das Annehmen einer Buchungsanfrage prüft das Zeitfenster erneut: Ein externer Block auf seinen Stunden ergibt, wie eine aktive Buchung oder ein Gruppenkurs, ein 409 slot_conflict, und die Skischule muss die Anfrage ablehnen oder einen anderen Termin vorschlagen. Auf dem Platz ohne Skilehrer prüft das Annehmen nichts erneut: Seine Plätze wurden gezählt, als der Kunde bezahlt hat. Sobald dein Block mit 201 beantwortet ist, gehört dir die Stunde: Eine Bezahlung, die darauf schon im Gang war, wird erstattet, sobald ihre Zahlung eintrifft, und erreicht dich als booking.expired.

Eine Skischule kann Stunden verkaufen, ohne zu sagen, wer sie geben wird: Der Kunde bucht und bezahlt, und die Skischule weist einen Skilehrer zu, wann immer sie möchte – über die API, aus dem Dashboard oder am Treffpunkt mit dem, der gerade frei ist. In der API ist das der eigene Platz der Skischule: Er hat einen eigenen Kalender, einen eigenen Preis und einen eigenen Schalter für die Sofortbestätigung, er ist nicht unter /instructors aufgeführt, und seine Buchungen kommen mit unassigned: true und instructorId gleich dem Platz (pool_…) an. Er verkauft so viele Privatstunden gleichzeitig, wie es die capacity seines Kalenders erlaubt: Ein available-Block kann sie angeben (bis 50; ohne Angabe 1), gezählt im Skigebiet des Blocks, Minute für Minute: Die eigenen Blöcke eines Tages ersetzen die wöchentlichen in den Minuten, die sie abdecken, und innerhalb beider addieren sich überlappende Blöcke. Eine Privatstunde braucht über ihre ganze Dauer einen freien Platz. Die Gruppenkurse des Platzes belegen keine Plätze: Sie laufen neben den Privatstunden und nebeneinander.

GET /unassigned zeigt die Einstellungen; PATCH /unassigned setzt beliebige von hourlyPrice, extraStudentPrice (0 oder mehr; ein negativer ist ein 422 invalid_price), extraStudentPer, durationPrices, seasonPrices, includedStudents, autoAcceptBookings und maximumStudents. Der erste PATCH erstellt den Platz, und bis dahin sind seine Kalender- und Block-Endpoints 404. Es gibt keinen Schalter: active sagt, ob der Platz im Verkauf ist, und das ist er, sobald sein Stundenpreis über der Untergrenze liegt (oder, wenn er Formate verkauft, seine Formate und Saisons vollständig sind); er verkauft in den Stunden, die sein Kalender öffnet, eine Skischule, die diesen Unterricht nicht will, öffnet also keine. Ein active in einem PATCH wird ignoriert. Ansonsten funktioniert der Kalender des Platzes wie der eines Skilehrers, in den Skigebieten der Skischule.

Feste Formate. Statt nach Stunden kann eine Skischule die Privatstunden ihres Platzes in festen Formaten verkaufen, die im Dashboard eingerichtet werden: bis zu 6 (Vormittag, Nachmittag, ganzer Tag oder andere, jedes mit Beginn und Ende) und Saisons, Zeiträume mit einem Preis pro Format, pro Einheit für die ganze Gruppe. saleMode in GET /unassigned sagt, welches von beiden gilt, und lessonFormats listet Formate und Saisons auf (in der API nur lesbar). Solange der Platz Formate verkauft, ist jede seiner Privatstunden eines davon: Ein Format ohne Preis in der Saison eines Datums wird an diesem Tag nicht verkauft, und an einem Datum außerhalb jeder Saison wird nichts verkauft. Ein Format braucht über seine ganze Zeit einen freien Platz, wie jeder Unterricht auf dem Platz, und hat nicht die Grenze von 6 Stunden des Unterrichts nach Stunden. Ein solcher Platz ist im Verkauf, sobald seine Formate und Saisons vollständig sind, unabhängig von seinem Stundenpreis. Seine Buchungen tragen format (Id und Art), subtotal ist der Preis dieses Formats an diesem Tag, und propose-time verschiebt es nur auf dieselben Zeiten an einem Tag, der sein Format zum bezahlten Preis verkauft (sonst 409 format_fixed_time oder format_price_differs). In der Testumgebung nimmt POST /sandbox/bookings auf dem Platz formatId an und verwendet die Formate deiner Skischule.

Bis der Unterricht zugewiesen ist, übernimmt die Skischule die Skilehrer-Seite: Sie beantwortet die Anfrage, chattet mit dem Kunden und vereinbart den Treffpunkt. Einmal zugewiesen, ist die Buchung die des Skilehrers wie jede andere, und was die Skischule damit noch tun darf, richtet sich nach managedBy.

Ein Gruppenkurs ist ein Termin mit Plätzen, die unabhängige Kunden einzeln kaufen: einmalig (date) oder als wöchentliche Serie (dayOfWeek, optional mit since und until), mit einer Kapazität, einem Preis pro Platz für den ganzen Kurs, einem Niveau, einer Zielgruppe (audience: alle, Kinder oder Erwachsene; ein Kinderkurs kann minAge und maxAge angeben, und jeder Teilnehmer, der einen Platz bucht, muss dazu passen), einem festen Treffpunkt und einer Mindestteilnehmerzahl, damit er stattfindet. Die Kurse eines Skilehrers übernehmen ihren Platzpreis aus dessen eigenen Einstellungen (groupClassesEnabled und groupPricePerStudent, schreibbar über PATCH /instructors/{id}); nur der Platz ohne Skilehrer nennt ihn beim Anlegen, und eine Preisänderung stempelt die aktiven Kurse neu. Kurse werden im Panel veröffentlicht, einem Skilehrer übergeben und abgesagt — auf der API sind sie in v1 nur lesbar — und liegen auf einem Skilehrer des Kaders oder auf dem Platz ohne zugewiesenen Skilehrer.

GET /instructors/{id}/classes (und GET /unassigned/classes) listen die aktiven Kurse. GET …/classes/expanded?from&to löst sie in konkrete Termine mit ihren belegten Plätzen auf, laufende Bezahlvorgänge innerhalb ihrer 10 Minuten Haltefrist eingeschlossen — höchstens 62 Tage pro Aufruf. Im Kalender eines Skilehrers erscheinen die Stunden eines Kurses außerdem als belegt in der erweiterten Verfügbarkeit, und ein externer Block darauf wird mit einem 409 booking_conflict abgelehnt: Diese Stunden kannst du nicht anderswo verkaufen. Der Platz ohne zugewiesenen Skilehrer ist ein Team: Seine Kurse nehmen seinen Privatstunden keine Plätze weg, laufen neben ihnen und nebeneinander, und ein externer Block kollidiert nie mit ihnen.

Jeder verkaufte Platz kommt über /bookings als gewöhnliche Buchung mit ihrer groupClassId, bestätigt in dem Moment, in dem sie bezahlt ist (acceptedVia auto). propose-time und assign lehnen einen Platz ab — die Zeit gehört dem Kurs und allen seinen Teilnehmern, und ein Kurs wandert als Ganzes zu einem Skilehrer, aus dem Panel. Das Absagen eines Kurses (oder eines Tags der Serie) erstattet jeden Platz voll und sendet ein booking.cancelled pro Platz; ein Kurs, der 24 Stunden vor Beginn noch unter seinem minStudents liegt, wird genauso abgesagt, mit cancelledBy platform.

Nur bezahlte Buchungen erreichen die API: Eine Buchung existiert für dich ab dem Augenblick, in dem ihre Zahlung eingeht (paidAt), und eine erstattete bleibt mit ihrem paymentStatus gelistet. Ein Kunde wählt einen Skilehrer und ein Zeitfenster, bezahlt, und die Anfrage landet beim Skilehrer oder bei der Skischule. Von da an wird sie entweder beantwortet, oder sie läuft unbeantwortet ab und der Kunde bekommt sein Geld zurück.

Die Uhr: Die Antwortfrist beträgt 48 Stunden ab Zahlung, nie später als der Beginn des Unterrichts; ein Vorschlag oder dessen Ablehnung setzt sie zurück (nie über die frühere der beiden Anfangszeiten hinaus, der ursprünglichen und der vorgeschlagenen); ein stündlicher Durchlauf lässt ablaufen, was überfällig ist, sodass der Ablauf bis zu eine Stunde verspätet eintreten kann. Ein bestätigter Unterricht wird 24 Stunden vor Beginn zu upcoming und ist in_progress, während er läuft. Er wird abgeschlossen, wenn der Kunde ihn bestätigt, oder von selbst 48 Stunden nach seinem Ende; der Abschluss gibt deinen Anteil frei. Der Kunde kann bis freeCancellationHours Stunden vor Beginn kostenlos stornieren: die Frist der Buchung selbst, also die, die die Stornobedingungen deiner Skischule bei der Buchung vorsahen (standardmäßig 48); die Buchung behält sie, egal wie sich die Bedingungen später ändern.

Vom Kunden erhältst du einen Kurznamen (Vorname und Initiale), seine bevorzugte Sprache und seine Nachricht – genug, um den Unterricht zu geben, und das, was unsere Datenschutzerklärung ihm verspricht. E-Mail, Telefon und jede Kontokennung werden nie gesendet; das Gespräch mit dem Kunden bleibt im Chat auf Alpine Pal, wo der Skilehrer ist.

GET /bookings listet die bezahlten Buchungen deiner Skilehrer, älteste Änderung zuerst, mit Filtern für status (eine kommagetrennte Liste), instructorId, from und to (Unterrichtsdaten) und updatedSince (ein beliebiger ISO-8601-Zeitpunkt; einschließlich). Die Seiten sind Keyset-basiert auf (updatedAt, id): Folge nextCursor, bis er null ist. Der Cursor ist opak und läuft nie ab, aber er gehört zu den Filtern, mit denen er erzeugt wurde – änderst du sie, fängst du von vorn an; ein ausgedachter ist ein 400.

Das Muster für eine nächtliche oder stündliche Synchronisation ist dasselbe: Merke dir das neueste updatedAt, das du gesehen hast, und frage alles seitdem ab, genau so, wie du es erhalten hast. Webhooks sagen dir in dem Moment Bescheid, in dem sich etwas ändert; dieser Endpoint ist der Weg, nach einem Ausfall aufzuholen. updatedAt bewegt sich auch bei Änderungen, die kein Ereignis senden – der Unterricht wird upcoming oder in_progress, eine Erinnerung wurde gesendet –, sodass eine Zeile in einer Synchronisation auftauchen kann, ohne dass sich sichtbar etwas geändert hat.

Aktionen stehen der Skischule bei Skilehrern offen, die sie verwaltet, und bei ihrem eigenen Platz für Unterricht ohne zugewiesenen Skilehrer; bei einem Skilehrer, der sich selbst verwaltet, lautet die Antwort 403 not_managed_by_school. Jede Aktion ist ein bedingtes Update: Ist die Buchung nicht mehr in dem Zustand, den die Aktion erwartet, lautet die Antwort 409 booking_state mit dem aktuellen Zustand in details, und nichts ändert sich. Eine Aktion zu wiederholen ist deshalb ungefährlich, und der Weg zu bestätigen, was passiert ist, ist GET /bookings/{id}.

Zwei Dinge fehlen hier mit Absicht: ein Nichterscheinen vermerken und einen Unterricht abschließen. Beide bewegen Geld aufgrund dessen, was auf der Piste passiert ist, und beide bleiben eine menschliche Handlung im Dashboard.

Registriere eine https-URL, und wir senden jedes Buchungsereignis per POST dorthin – dasselbe JSON, das die Buchungs-Endpoints liefern, verpackt in ein Ereignis. Bis zu 10 Endpoints pro Skischule, jeder abonniert einige Ereignisse oder mit "*" alle. Registriere sie aus dem Dashboard oder über die API; das Dashboard zeigt in beiden Fällen das Zustellprotokoll. Die URL muss https sein, mit einem Hostnamen, der einen Punkt enthält, ohne Zugangsdaten oder Fragment, und weder eine private Adresse noch unsere.

Ereignisse. booking.requested – eine bezahlte Anfrage ist eingetroffen. booking.confirmed – vom Skilehrer oder von der Skischule angenommen, automatisch bestätigt, oder der Kunde hat einen vorgeschlagenen Termin angenommen: acceptedVia sagt, was davon, und previousStatus ist im letzten Fall change_proposed. booking.time_proposed – dem Kunden wurde ein anderer Termin vorgeschlagen. booking.rejected. booking.cancelled – cancelledBy ist customer, instructor, school oder platform (das Konto hinter der Buchung wurde gelöscht, oder ein Gruppenkurs wurde abgesagt, weil er sein Minimum nicht erreicht hat). booking.expired – niemand hat rechtzeitig geantwortet. booking.completed – der Unterricht ist zu Ende, Nichterscheinen eingeschlossen. booking.updated – alles andere, was sich zu melden lohnt, mit data.reason: proposal_declined, meeting_point_proposed, meeting_point_confirmed, dispute_opened, dispute_resolved, refund_settled (das Geld ist wieder beim Kunden), refund_issued (von uns) oder instructor_assigned (previousInstructorId nennt den Platz, auf dem der Unterricht lag). ping ist das Test-Ereignis, mit leerem data; es ist kein Typ, den du abonnierst. Für upcoming, in_progress, Kader- oder managedBy-Änderungen wird kein Ereignis ausgelöst.

Was dich erwartet. Die Zustellung erfolgt mindestens einmal: Eine Antwort, die nach unserem Timeout von 10 Sekunden eintrifft, zählt als Fehlschlag, und das Ereignis kommt erneut; behandle also die Ereignis-Id als Schlüssel und ignoriere Wiederholungen. Die Reihenfolge ist nicht garantiert – Wiederholungsversuche und der Durchlauf ordnen Ereignisse um –, sortiere also nach data.booking.updatedAt. Nicht jede Buchung beginnt mit booking.requested: Die eines Skilehrers mit eingeschalteter Sofortbestätigung (autoAcceptBookings) kommt direkt als booking.confirmed an, mit previousStatus pending_instructor_approval. Lege die Buchung in deinem System also beim ersten Ereignis an, das du für ihre Id siehst, gleich welchen Typs. Der Payload wird beim Erzeugen des Ereignisses eingefroren; ein Wiederholungsversuch trägt, was damals galt, und ein späteres Ereignis den neueren Zustand. Ein Ereignis kann verloren gehen, wenn unser Versuch, es aufzuzeichnen, fehlschlägt; GET /bookings?updatedSince ist das Sicherheitsnetz. Jedes Ereignis trägt sandbox: true oder false. Das Protokoll bewahrt Zustellungen 30 Tage auf; eine erneute Zustellung sendet eine vergangene noch einmal.

Jede Zustellung ist mit dem Secret des Endpoints signiert: Der Header X-AlpinePal-Signature trägt einen Zeitstempel und einen HMAC-SHA256 über den Zeitstempel, einen Punkt und den rohen Body. Verifiziere sie, bevor du irgendetwas vertraust, vergleiche in konstanter Zeit und lehne Zeitstempel ab, die mehr als 5 Minuten von deiner Uhr entfernt sind. Das Secret wird beim Erstellen des Endpoints und von GET /webhooks zurückgegeben und kann aus dem Dashboard oder mit POST /webhooks/{id}/rotate-secret rotiert werden; das alte stirbt sofort.

Antworte mit einem beliebigen 2xx innerhalb von 10 Sekunden. Alles andere – ein 3xx eingeschlossen, denn wir folgen keinen Weiterleitungen – ist ein Fehlschlag: Wir versuchen es erneut nach 5 Minuten, 15 Minuten, 1 Stunde, 4 Stunden, 12 Stunden und 24 Stunden, insgesamt etwa 42 Stunden, jedes Mal mit derselben Ereignis-Id, damit du deduplizieren kannst. Ein Endpoint wird erst abgeschaltet, und die Verwalter der Skischule werden benachrichtigt, wenn eine Zustellung alle Versuche ausgeschöpft hat, ohne dass in der Zwischenzeit eine andere Zustellung angekommen ist; ein kurzer Ausfall schaltet ihn nicht ab, auch wenn viele Ereignisse unterwegs sind. Solange er abgeschaltet ist, werden keine neuen Ereignisse für ihn eingereiht (GET /bookings?updatedSince holt sie nach), und eine ausstehende Zustellung, deren Versuch in dieser Zeit fällig wird, wird als fehlgeschlagen markiert, ohne gesendet zu werden; Wiederholungen, die nach dem Wiedereinschalten fällig werden, gehen normal raus. Stelle die fehlgeschlagenen erneut zu. POST /webhooks/{id}/test reiht einen Ping wie eine gewöhnliche Zustellung ein, versucht ihn sofort und meldet, wie dieser Versuch gelaufen ist: Ein fehlgeschlagener Ping wird genauso wiederholt, zählt wie jede Zustellung für das Abschalten des Endpoints und wird bei einem abgeschalteten Endpoint als fehlgeschlagen markiert, ohne gesendet zu werden. GET /webhooks/{id}/deliveries zeigt die neuesten Zustellungen zuerst, standardmäßig 50 und mit ?limit= bis zu 100, mit ihrer Versuchszahl und ohne ihre Bodys: Jedes Ereignis hat eine Zustellung pro Endpoint, plus eine für jede erneute Zustellung, mit derselben Ereignis-Id.

Jede Skischule bekommt einen Testzwilling, sobald ihr Inhaber im Dashboard einen Test-Schlüssel erzeugt (Verbindungen → Testumgebung): eine Kopie der Skischule mit zwei erfundenen Skilehrern – sandbox_ia_…, der Anfragen von Hand beantwortet, und sandbox_ib_…, mit eingeschalteter Sofortbestätigung – und dem Platz für Unterricht ohne zugewiesenen Skilehrer, jeder mit einem Kalender von 09:00–17:00 an jedem Tag in den Skigebieten der Skischule, 1 bis 6 Stunden pro Unterricht, bis zu 6 Teilnehmer, ohne Puffer und ohne Vorlaufzeit. Test-Schlüssel beginnen mit ap_test_ und erreichen nur den Zwilling; Live-Schlüssel nie. Alles andere ist dieselbe API: die Skilehrer des Zwillings auflisten, ihre Kalender schreiben, Webhooks registrieren, Anfragen beantworten, Unterricht zuweisen.

Was ein Kunde auf der Website tut, erledigt POST /sandbox/bookings für dich: Der Aufruf erstellt eine bezahlte Buchung für den Skilehrer, den du nennst, mit denselben Prüfungen wie eine echte – veröffentlichte Verfügbarkeit, keine Überschneidung – und ohne Geld im Spiel. Von da an läuft die echte Maschinerie, und die Aktionen unten vertreten den Kunden und die Uhr, sodass sich jedes Ereignis in Minuten beobachten lässt. Keine E-Mail verlässt die Testumgebung, und nichts darin ist je öffentlich; jedes Ereignis, das sie sendet, trägt sandbox: true, ebenso GET /me. POST /sandbox/reset leert sie, damit eine Testsuite sauber starten kann.

In der Testumgebung weiterhin außer Reichweite: Reklamationen, Nichterscheinen, eine von uns ausgestellte Erstattung, eine Stornierung mit cancelledBy platform und der Treffpunkt (seine Ereignisse kommen von der Website). Buchungen der Testumgebung tragen ein leeres studentLevels und einen Kunden namens Sandbox C., der die Website auf Englisch liest.

Die maschinenlesbare Beschreibung liegt unter https://alpinepal.com/api/v1/openapi.json – jeder Pfad, jede Methode, jeder Parameter und jedes Schema von oben, in OpenAPI 3.1. Richte einen Generator darauf, um einen typisierten Client zu bekommen, oder importiere sie in dein HTTP-Werkzeug zum Stöbern. Sie wird ohne Authentifizierung ausgeliefert und eine Stunde lang gecacht.

Das ist v1. Innerhalb davon fügen wir nur hinzu: neue Felder, neue optionale Parameter, neue Ereignistypen, neue Endpoints. Deine Integration sollte Felder und Ereignisse ignorieren, die sie nicht kennt. Alles, was einen bestehenden Client brechen würde, kommt in eine v2 unter einer neuen Basis-URL, wobei v1 weiterläuft, während du umziehst.