API dla szkół narciarskich

Klucze należą do szkoły, a nie do osoby, i tylko właściciel szkoły może je tworzyć i unieważniać – w zakładce Połączenia panelu szkoły. Klucz jest wyświetlany raz, przy tworzeniu; przechowujemy tylko jego skrót (hash) i nie możemy pokazać go ponownie. Szkoła może mieć do 5 kluczy produkcyjnych, więc nowa integracja dostaje własny klucz, a stary można unieważnić bez ruszania pozostałych. Klucze produkcyjne zaczynają się od ap_live_; klucze sandboxa zaczynają się od ap_test_ i są liczone osobno.

Klucz przestaje działać w chwili unieważnienia, a wszystkie klucze dostają 403 school_not_active, gdy tylko szkoła zostanie zamknięta albo nie jest zatwierdzona. Szkoła tylko zawieszona (ukryta w serwisie, bez swojej strony) zachowuje klucze: jej rezerwacje trwają dalej, a wraz z nimi API. Kluczami nie da się zarządzać przez samo API. Aby wymienić klucz: utwórz nowy, przełącz na niego swój system, a potem unieważnij stary – w międzyczasie oba są ważne. Panel pokazuje, kiedy każdy klucz był ostatnio używany, z dokładnością do 5 min. Klucze są dla serwerów: nigdy nie umieszczaj klucza w przeglądarce ani w aplikacji mobilnej.

Każde żądanie przesyła klucz jako token typu Bearer. Bazowy URL to https://alpinepal.com/api/v1; odpowiedzi są w formacie JSON, nigdy nie trafiają do cache, a każda zawiera nagłówek X-Request-Id, który możesz nam podać. Godziny są podawane według czasu ośrodka w formacie HH:mm, daty jako YYYY-MM-DD, a momenty w czasie w ISO 8601, w UTC, z milisekundami.

Treść żądania musi być w formacie JSON, z nagłówkiem Content-Type: application/json (w przeciwnym razie 415), mieć mniej niż 256 KB (413) i jest sprawdzana ściśle: nieznane pole to 400 validation_error z listą błędnych ścieżek. Pusta treść jest odczytywana jako pusty obiekt. Metoda, której ścieżka nie obsługuje, daje 405 z nagłówkiem Allow; ukośnik na końcu ścieżki daje 404.

Nie ma CORS: API działa między serwerami, a żądanie wysłane z przeglądarki się nie powiedzie. To celowe, bo klucz w przeglądarce to klucz, który każdy może odczytać.

Na klucz, w stałych oknach jednominutowych: odczyty (GET): 600 i zapisy (wszystko inne, także DELETE): 120 na minutę. Po przekroczeniu limitu odpowiedzią jest 429 rate_limited z nagłówkiem Retry-After, w sekundach. Klucz testowy ma osobny limit. Nieudane uwierzytelnienia są ograniczone dla każdego adresu IP: 20 w ciągu 10 min; potem każda kolejna próba dostaje 429, zanim klucz zostanie w ogóle sprawdzony. Testy webhooków i ponowne wysłania mają osobny wspólny limit: 10 w ciągu 10 min na klucz, bo każde z nich to żądanie do cudzego serwera.

Każdy błąd ma tę samą kopertę: status HTTP, stały code, według którego możesz rozgałęziać logikę, komunikat dla człowieka i identyfikator żądania. Pięć kodów zawiera details: validation_error wymienia błędne pola jako [{path, message}] (najwyżej 10); booking_state podaje, w jakim stanie jest teraz rezerwacja ({bookingStatus}); booking_conflict wskazuje godziny, które stoją na przeszkodzie, a gdy ta rezerwacja jest opłacona – jej id i numer referencyjny; rate_limited powtarza czas oczekiwania jako {retryAfterSeconds}; inside_notice_window podaje minimalne wyprzedzenie instruktora w godzinach ({hours}).

Identyfikatory. Instruktorzy mają id swojego konta (user_…) albo unclaimed_…, dopóki profil dodany przez twoją szkołę bez konta nie zostanie przejęty; pula lekcji bez przypisanego instruktora ma id pool_<schoolId>; instruktorzy sandboxa to sandbox_ia_… i sandbox_ib_…. Rezerwacje to b_…, zdarzenia evt_…, doręczenia whd_…, endpointy wh_…, żądania req_…. Numery referencyjne mają postać AP-<rok>-<5-cyfrowy numer> dla prawdziwych rezerwacji i SB<6 hex> w sandboxie.

Czas. date, startTime i endTime to czas lokalny strefy resortTimeZone, nigdy UTC; momenty (createdAt, updatedAt, paidAt, instructorResponseDeadline…) są w UTC. Lekcja w noc zmiany czasu przypada na pierwsze wystąpienie godziny, która się powtarza, a godzina, której tej nocy nie ma, przesuwa się do przodu. endTime może wynosić 24:00. To, czy dana godzina jest już w przeszłości, ocenia się według zegara ośrodka.

Pieniądze. subtotal = (hourlyPrice + extraStudentPrice × max(0, numberOfStudents − includedStudents)) × durationHours, zaokrąglone zgodnie z walutą; tyle płaci klient. hourlyPrice to stawka z dnia lekcji: stawka sezonu (seasonPrices), jeśli data w nim wypada, a w przeciwnym razie własna stawka instruktora lub puli; includedStudents mówi, ilu uczniów obejmuje ta stawka, 1, chyba że szkoła ustawi więcej. platformFee to nasza prowizja: 10% albo wyższa, uzgodniona z nami na piśmie przez twoją szkołę; każda rezerwacja zachowuje stawkę, po której została sprzedana. netAmount to reszta dla szkoły (subtotal − platformFee): trafia na saldo twojej szkoły po zakończeniu lekcji – niezależnie od tego, kto ją poprowadził i kto zarządza tą osobą – a przepada, jeśli klient otrzyma zwrot pieniędzy. Każdy instruktor z twojego zespołu pobiera opłaty w walucie twojej szkoły; stawki godzinowe mają minimum zależne od waluty (10 EUR, 11 USD, 10 CHF), a extraStudentPrice wynosi 0 lub więcej. Sprzęt, który klient wypożycza w twojej szkole razem z lekcją, również wlicza się do subtotal (equipment.amount) i jest rozliczany tak jak lekcja.

managedBy to reguła, która decyduje, kto odpowiada: gdy ma wartość instructor, kalendarz i prośby o rezerwację należą do instruktora, a API może je odczytywać, ale nie zapisywać; gdy ma wartość school, kalendarz zapisuje i na prośby odpowiada szkoła – a więc i API – a instruktor ma tylko podgląd. Ustawia ją człowiek, w widoku zespołu w panelu; przez API nie da się jej zmienić. Oddanie kalendarza instruktorowi usuwa bloki zewnętrzne, które zapisał w nim twój system.

Gdy instruktor odchodzi ze szkoły, jego rezerwacje znikają z GET /bookings, a jego zdarzenia przestają przychodzić; to, co już zostało zarobione, zostaje na twoim saldzie. Ani to, ani zmiana managedBy nie wysyła zdarzenia: porównuj GET /instructors przy każdej synchronizacji.

unclaimed oznacza instruktora, którego szkoła dodała w panelu bez konta: nikt nie loguje się jako ten instruktor, więc zawsze ma managedBy school, a szkoła odpowiada za niego we wszystkim, także na czacie. Gdy osoba przejmie profil własnym kontem, unclaimed zmienia się na false, a id instruktora zmienia się na stałe: wszystkie ścieżki i filtr instructorId nadal przyjmują stare id, instruktor ma je w polu previousId, a zdarzenia od tej chwili podają nowe. Żadne zdarzenie tego nie ogłasza: porównuj GET /instructors przy każdej synchronizacji i dopasowuj previousId.

Dostępność instruktora to lista bloków. Blok jest typu available, blocked albo vacation, należy do ośrodka, w którym instruktor uczy, obejmuje czas od startTime do endTime (endTime może wynosić 24:00) i jest zakotwiczony albo w dniu tygodnia (dayOfWeek 0–6, gdzie 0 to niedziela, opcjonalnie z since i until jako pierwszą i ostatnią datą, w której obowiązuje), albo w jednej dacie – dokładnie w jednym z tych dwóch. Nowe godziny available muszą mieścić się między 07:00 a 21:00 czasu ośrodka (w przeciwnym razie 422 outside_ski_day); bloki blocked i vacation mogą obejmować dowolne godziny. Klienci mogą rezerwować tylko w blokach available, których nie zakrywa nic innego.

PUT /instructors/{id}/availability zastępuje cały grafik – każdy ośrodek, każdy blok, do 400 bloków – tym, co wysyłasz, dokładnie tak jak zapisanie kalendarza w panelu. Identyfikatory są opcjonalne: serwer nadaje id blokowi, który go nie ma, zachowuje te, które wysyłasz, i odrzuca duplikaty oraz prefiks xb_ bloków zewnętrznych. Bloków zewnętrznych (zob. niżej) PUT nigdy nie rusza i nie mogą się w nim pojawić. Błędnie zbudowany blok, nieznany ośrodek, oba zakotwiczenia naraz albo since późniejsze niż until bloku to 422 invalid_availability. Bloki, które nie mogą już obowiązywać (data, która minęła, blok tygodniowy po swoim until), są pomijane: PUT ich nie zapisuje, a GET ich nie zwraca. Data mija wtedy, gdy minie wszędzie, czyli o 12:00 UTC następnego dnia.

GET …/availability/expanded liczy za ciebie: dla jednego ośrodka i do 62 dni zwraca dla każdego dnia wolne przedziały, które klient mógłby zarezerwować, oraz zajęte, a każdy zajęty przedział ma etykietę booking (potwierdzona lekcja), pending (opłacona prośba czekająca na odpowiedź) albo external (blok z API). Uwzględnia bufor między lekcjami i minimalne wyprzedzenie ustawione przez instruktora; nie pomija przerw krótszych niż jego minimalna długość lekcji, więc trzydziestominutowa przerwa jest pokazywana jako wolna.

Lekcja sprzedana poza Alpine Pal zajmuje instruktora. Zarejestruj ją jako blok zewnętrzny, a ten termin zniknie z wyszukiwania w każdym ośrodku, w którym instruktor uczy – człowiek nie może być w dwóch dolinach naraz. Bloki wymagają, by instruktorem zarządzała szkoła (managedBy = school).

Każdy blok ma twój własny externalRef. Ponowne wysłanie tej samej wartości externalRef z tą samą datą i godzinami jest idempotentne i zwraca 200 z zapisanym blokiem, niezależnie od przekazanego resortId; ta sama wartość z innymi godzinami to 409 external_ref_exists – usuń blok i utwórz go od nowa. Blok, który nakłada się na aktywną rezerwację, to 409 booking_conflict z godzinami, które stoją na przeszkodzie, a gdy ta rezerwacja jest opłacona – z jej id i numerem referencyjnym: ta lekcja jest już u nas sprzedana.

Licząc od dziś, instruktor może mieć do 400 bloków zewnętrznych; kolejny to 422 limit_reached. Blok, którego data minęła (o 12:00 UTC następnego dnia), znika sam: GET /blocks już go nie zwraca, DELETE na nim daje 404 i przestaje się on liczyć do limitu 400.

Akceptacja prośby o rezerwację ponownie sprawdza termin: blok zewnętrzny w tych godzinach, tak jak aktywna rezerwacja czy lekcja grupowa, daje 409 slot_conflict, a szkoła musi wtedy prośbę odrzucić albo zaproponować inny termin. W puli lekcji bez przypisanego instruktora akceptacja niczego ponownie nie sprawdza: jej miejsca zostały policzone, gdy klient zapłacił. Gdy twój blok dostanie odpowiedź 201, godzina należy do ciebie: płatność, która była już w toku na tę godzinę, zostanie zwrócona, gdy tylko wpłynie, i dotrze do ciebie jako booking.expired.

Szkoła może sprzedawać godziny, nie mówiąc, kto je poprowadzi: klient rezerwuje i płaci, a szkoła przydziela instruktora, kiedy chce – przez API, z panelu albo na miejscu spotkania, z tym, kto akurat jest wolny. W API to własna pula szkoły: ma swój kalendarz, swoją cenę i własny przełącznik natychmiastowego potwierdzenia, nie ma jej na liście /instructors, a jej rezerwacje przychodzą z unassigned: true i instructorId ustawionym na pulę (pool_…). Sprzedaje jednocześnie tyle lekcji, ile miejsc ma jej kalendarz: blok available może mieć capacity (do 50; domyślnie 1), liczone w ośrodku bloku minuta po minucie – bloki konkretnego dnia zastępują tygodniowe w minutach, które obejmują, a w obrębie każdego z tych rodzajów nakładające się bloki się sumują. Lekcja potrzebuje miejsca przez cały swój czas. Lekcje grupowe puli nie zajmują miejsc: odbywają się równolegle z lekcjami prywatnymi i ze sobą nawzajem.

GET /unassigned pokazuje ustawienia; PATCH /unassigned ustawia dowolne z pól hourlyPrice, extraStudentPrice (0 lub więcej; wartość ujemna daje 422 invalid_price), extraStudentPer, durationPrices, seasonPrices, includedStudents, autoAcceptBookings i maximumStudents. Pierwszy PATCH tworzy pulę, a do tego czasu jej endpointy kalendarza i bloków zwracają 404. Nie ma przełącznika: active mówi, czy pula jest w sprzedaży – a jest, gdy tylko jej stawka godzinowa przekracza minimum (albo, jeśli sprzedaje formaty, gdy jej formaty i sezony są kompletne); sprzedaje w godzinach, które otwiera jej kalendarz, więc szkoła, która nie chce takich lekcji, po prostu żadnych nie otwiera. Pole active w PATCH jest ignorowane. Poza tym kalendarz puli działa jak kalendarz instruktora, w ośrodkach szkoły.

Stałe formaty. Zamiast na godziny szkoła może sprzedawać lekcje prywatne swojej puli w stałych formatach, ustawianych w panelu: maksymalnie 6 (rano, po południu, cały dzień albo inny, każdy z godziną rozpoczęcia i zakończenia) oraz sezony, czyli zakresy dat z ceną dla każdego formatu, za lekcję dla całej grupy. saleMode w GET /unassigned mówi, który sposób obowiązuje, a lessonFormats zawiera formaty i sezony (w API tylko do odczytu). Dopóki pula sprzedaje formaty, każda jej lekcja prywatna jest jednym z nich: format bez ceny w sezonie danej daty nie jest sprzedawany tego dnia, a w dniu poza wszystkimi sezonami nic nie jest sprzedawane. Format potrzebuje wolnego miejsca przez cały swój czas, jak każda lekcja puli, i nie obowiązuje go limit 6 godz. lekcji sprzedawanych na godziny. Taka pula jest w sprzedaży, gdy tylko jej formaty i sezony są kompletne, niezależnie od stawki godzinowej. Jego rezerwacje mają pole format (id i rodzaj), subtotal to cena tego formatu w danym dniu, a propose-time przenosi taką lekcję tylko na te same godziny w dniu, w którym jej format jest sprzedawany w zapłaconej cenie (w przeciwnym razie 409 format_fixed_time albo format_price_differs). W sandboxie POST /sandbox/bookings dla puli przyjmuje formatId i korzysta z formatów twojej szkoły.

Dopóki lekcja nie zostanie przypisana, stroną instruktora jest szkoła: odpowiada na prośbę, pisze z klientem na czacie i ustala miejsce spotkania. Po przypisaniu rezerwacja należy do instruktora jak każda inna, a to, co szkoła może jeszcze z nią zrobić, zależy od managedBy.

Lekcja grupowa to wydarzenie z miejscami, które niezależni klienci kupują osobno. Może być jednorazowa (date) albo tworzyć cotygodniową serię (dayOfWeek, opcjonalnie z since i until); ma limit miejsc, cenę za miejsce za całe zajęcia, poziom, grupę docelową (audience: all, children albo adults – zajęcia dla dzieci mogą podawać minAge i maxAge, a każdy uczestnik rezerwujący miejsce musi się w nich mieścić), stałe miejsce spotkania i minimalną liczbę uczestników potrzebną, by zajęcia się odbyły. Zajęcia instruktora biorą cenę za miejsce z jego własnych ustawień (groupClassesEnabled i groupPricePerStudent, zapisywalne przez PATCH /instructors/{id}); tylko pula podaje ją przy tworzeniu zajęć, a zmiana ceny aktualizuje aktywne zajęcia. Zajęcia publikuje się, przekazuje instruktorowi i odwołuje w panelu – w API v1 są tylko do odczytu – i należą do instruktora z zespołu albo do puli lekcji bez przypisanego instruktora.

GET /instructors/{id}/classes (oraz GET /unassigned/classes) zwracają aktywne zajęcia. GET …/classes/expanded?from&to rozwija je w konkretne terminy z liczbą zajętych miejsc, wliczając płatności w toku w ramach ich 10-minutowej blokady – najwyżej 62 dni na wywołanie. W kalendarzu instruktora godziny zajęć są też widoczne jako zajęte (busy) w widoku rozszerzonym dostępności, a blok zewnętrzny na nich zostaje odrzucony z 409 booking_conflict: tych godzin nie możesz sprzedać gdzie indziej. Pula działa jak zespół: jej zajęcia nie zabierają jej miejsc na lekcje prywatne, odbywają się równolegle z nimi i ze sobą nawzajem, a blok zewnętrzny nigdy z nimi nie koliduje.

Każde sprzedane miejsce przychodzi przez /bookings jako zwykła rezerwacja z polem groupClassId, potwierdzona w chwili opłacenia (acceptedVia auto). propose-time i assign odrzucają miejsce – godzina należy do zajęć i do wszystkich pozostałych uczestników, a zajęcia przekazuje się instruktorowi w całości, z panelu. Odwołanie zajęć (albo jednego terminu serii) zwraca pełną kwotę za każde miejsce i wysyła jedno booking.cancelled na miejsce; zajęcia, które 24 godz. przed rozpoczęciem terminu wciąż nie osiągnęły minStudents, są odwoływane w ten sam sposób, z cancelledBy platform.

Do API trafiają tylko opłacone rezerwacje: rezerwacja istnieje dla ciebie od chwili, gdy wpłynie za nią płatność (paidAt), a rezerwacja, za którą zwrócono pieniądze, pozostaje na liście ze swoim paymentStatus. Klient wybiera instruktora i termin, płaci, a prośba trafia do instruktora albo do szkoły. Od tej chwili albo dostaje odpowiedź, albo wygasa bez odpowiedzi, a klient otrzymuje zwrot pieniędzy.

Zegar: termin odpowiedzi to 48 godz. od płatności, nigdy później niż początek lekcji; propozycja innego terminu albo jej odrzucenie liczy go od nowa (nigdy poza wcześniejszy z dwóch początków: pierwotnego i proponowanego); cogodzinne zadanie cykliczne oznacza jako wygasłe to, co przekroczyło termin, więc wygaśnięcie może nastąpić nawet z godzinnym opóźnieniem. Potwierdzona lekcja przechodzi w stan upcoming 24 godz. przed rozpoczęciem i w in_progress na czas trwania. Przechodzi w completed, gdy klient ją potwierdzi, albo sama 48 godz. po zakończeniu; zakończenie zwalnia twoją część. Klient może anulować bezpłatnie do freeCancellationHours godz. przed rozpoczęciem: to termin samej rezerwacji, czyli ten, który miały zasady anulowania twojej szkoły w chwili jej złożenia (domyślnie 48), i rezerwacja zachowuje go bez względu na późniejsze zmiany zasad.

O kliencie dostajesz skrócone imię (imię i inicjał nazwiska), jego preferowany język i jego wiadomość – tyle, ile trzeba, by poprowadzić lekcję, i tyle, ile obiecuje mu nasza polityka prywatności. Adres e-mail, telefon ani żaden identyfikator konta nigdy nie są przesyłane; rozmowa z klientem zostaje na czacie w Alpine Pal, tam gdzie jest instruktor.

GET /bookings zwraca opłacone rezerwacje twoich instruktorów, od najstarszej zmiany, z filtrami status (lista rozdzielona przecinkami), instructorId, from i to (daty lekcji) oraz updatedSince (dowolny moment w ISO 8601, włącznie). Stronicowanie jest typu keyset po (updatedAt, id): podążaj za nextCursor, aż będzie null. Kursor jest nieprzezroczysty i nigdy nie wygasa, ale należy do filtrów, z którymi powstał – jeśli je zmienisz, zacznij od początku; zmyślony kursor to 400.

Wzorzec synchronizacji co noc albo co godzinę jest zawsze ten sam: zapamiętaj najnowsze otrzymane updatedAt i pobierz wszystko od tej chwili, przekazując je dokładnie w takiej postaci, w jakiej przyszło. Webhooki informują cię w chwili, gdy coś się zmienia; GET /bookings pozwala nadrobić zaległości po przerwie w działaniu. updatedAt zmienia się też przy zmianach, które nie wysyłają zdarzenia – lekcja przechodzi w upcoming albo in_progress, zostaje wysłane przypomnienie – więc wiersz może pojawić się w synchronizacji, choć nic się w nim widocznie nie zmieniło.

Akcje są dostępne dla szkoły w przypadku instruktorów, którymi zarządza, oraz jej własnej puli lekcji bez przypisanego instruktora; w przypadku instruktora, który sam sobą zarządza, odpowiedzią jest 403 not_managed_by_school. Każda akcja jest aktualizacją warunkową: jeśli rezerwacja nie jest już w stanie, którego akcja oczekuje, odpowiedzią jest 409 booking_state z aktualnym stanem w details i nic się nie zmienia. Powtórzenie akcji jest więc bezpieczne, a sposobem na sprawdzenie, co się stało, jest GET /bookings/{id}.

Dwóch rzeczy celowo tu nie ma: oznaczania niestawienia się i kończenia lekcji. Obie przesuwają pieniądze na podstawie tego, co wydarzyło się na stoku, i obie pozostają czynnością człowieka w panelu.

Zarejestruj adres URL https, a każde zdarzenie dotyczące rezerwacji wyślemy na niego żądaniem POST – ten sam JSON, który zwracają endpointy rezerwacji, opakowany w zdarzenie. Do 10 endpointów na szkołę; każdy subskrybuje wybrane zdarzenia albo wszystkie przez "*". Rejestruj je w panelu albo przez API; panel w obu przypadkach pokazuje dziennik doręczeń. URL musi używać https, mieć nazwę hosta z kropką, nie zawierać danych logowania ani fragmentu i nie może być adresem prywatnym ani naszym.

Zdarzenia. booking.requested – przyszła opłacona prośba o rezerwację. booking.confirmed – rezerwacja zaakceptowana przez instruktora lub szkołę, potwierdzona automatycznie albo proponowany termin został zaakceptowany przez klienta: acceptedVia mówi, który to przypadek, a w ostatnim previousStatus ma wartość change_proposed. booking.time_proposed – klientowi zaproponowano inny termin. booking.rejected. booking.cancelled – cancelledBy ma wartość customer, instructor, school albo platform (konto stojące za rezerwacją zostało usunięte albo lekcja grupowa została odwołana, bo nie osiągnęła minimalnej liczby uczestników). booking.expired – nikt nie odpowiedział na czas. booking.completed – lekcja się skończyła, także w przypadku niestawienia się. booking.updated – wszystko inne, o czym warto poinformować, z data.reason: proposal_declined, meeting_point_proposed, meeting_point_confirmed, dispute_opened, dispute_resolved, refund_settled (pieniądze wróciły do klienta), refund_issued (zwrot zlecony przez nas) albo instructor_assigned (previousInstructorId wskazuje pulę, w której była lekcja). ping to zdarzenie testowe, z pustym data; nie jest typem, który się subskrybuje. Przejście w upcoming lub in_progress, zmiany w zespole ani zmiany managedBy nie wywołują żadnego zdarzenia.

Czego się spodziewać. Doręczenie następuje co najmniej raz: odpowiedź, która dotrze po upływie naszego limitu czasu (10 s), liczy się jako błąd i zdarzenie przychodzi ponownie, więc traktuj id zdarzenia jako klucz i ignoruj powtórzenia. Kolejność nie jest gwarantowana – ponowne próby i zadanie cykliczne zmieniają kolejność zdarzeń – więc sortuj według data.booking.updatedAt. Nie każda rezerwacja zaczyna się od booking.requested: rezerwacja instruktora z włączonym natychmiastowym potwierdzeniem (autoAcceptBookings) przychodzi od razu jako booking.confirmed, z previousStatus pending_instructor_approval. Twórz więc rezerwację w swoim systemie przy pierwszym zdarzeniu z jej id, niezależnie od jego typu. Payload jest zamrażany w chwili utworzenia zdarzenia; ponowna próba niesie to, co było prawdą wtedy, a późniejsze zdarzenie – nowszy stan. Zdarzenie może przepaść, jeśli nie uda nam się go zapisać; GET /bookings?updatedSince jest siatką bezpieczeństwa. Każde zdarzenie zawiera sandbox: true albo false. Dziennik przechowuje doręczenia przez 30 dni; ponowne wysłanie wysyła dawne doręczenie jeszcze raz.

Każde doręczenie jest podpisane sekretem endpointu: nagłówek X-AlpinePal-Signature zawiera znacznik czasu i HMAC-SHA256 obliczony ze znacznika czasu, kropki i surowej treści. Zweryfikuj podpis, zanim czemukolwiek zaufasz, porównuj w stałym czasie i odrzucaj znaczniki czasu oddalone od twojego zegara o więcej niż 5 min. Sekret jest zwracany przy tworzeniu endpointu i przez GET /webhooks, a zmienić go można w panelu albo przez POST /webhooks/{id}/rotate-secret; stary przestaje działać od razu.

Odpowiedz dowolnym kodem 2xx w ciągu 10 s. Wszystko inne – także 3xx, bo nie podążamy za przekierowaniami – to błąd, a my ponawiamy próby w odstępach: 5 minut, 15 minut, 1 godzina, 4 godziny, 12 godzin i 24 godziny (łącznie około 42 godz.), za każdym razem z tym samym id zdarzenia, żeby można było usuwać duplikaty. Endpoint zostaje wyłączony, a zarządzający szkołą dostają powiadomienie, dopiero gdy któreś doręczenie wyczerpie wszystkie próby i w tym czasie do endpointu nie dotrze ani jedno doręczenie; krótka awaria go nie wyłącza, niezależnie od liczby zdarzeń w drodze. Dopóki jest wyłączony, nowe zdarzenia nie trafiają do jego kolejki (nadrobisz je przez GET /bookings?updatedSince), a oczekujące doręczenie, którego próba przypada w tym czasie, zostaje oznaczone jako nieudane bez wysyłania; próby przypadające już po ponownym włączeniu są wysyłane normalnie. Wyślij ponownie te, które się nie udały. POST /webhooks/{id}/test dodaje ping do kolejki jak zwykłe doręczenie, od razu go wysyła i zwraca, jak poszła ta próba: nieudany ping jest ponawiany tak samo, liczy się jak każde doręczenie przy wyłączaniu endpointu, a na wyłączonym endpoincie zostaje oznaczony jako nieudany bez wysyłania. GET /webhooks/{id}/deliveries pokazuje najnowsze doręczenia najpierw, domyślnie 50, a z ?limit= najwyżej 100, z liczbą prób i bez ich treści: każde zdarzenie ma jedno doręczenie na endpoint i po jednym więcej na każde ponowne wysłanie, z tym samym id zdarzenia.

Każda szkoła dostaje testową kopię w chwili, gdy jej właściciel utworzy w panelu klucz testowy (Połączenia → Środowisko testowe): kopię szkoły z dwoma zmyślonymi instruktorami – sandbox_ia_…, który odpowiada na prośby ręcznie, i sandbox_ib_…, z włączonym natychmiastowym potwierdzeniem – oraz pulą lekcji bez przypisanego instruktora; każdy z nich ma kalendarz 09:00–17:00 codziennie w ośrodkach szkoły, od 1 do 6 godz. na lekcję, do 6 uczestników, bez bufora i bez minimalnego wyprzedzenia. Klucze testowe zaczynają się od ap_test_ i działają tylko w kopii; klucze produkcyjne nigdy. Wszystko inne to to samo API: lista instruktorów kopii, zapisywanie ich kalendarzy, rejestrowanie webhooków, odpowiadanie na prośby, przypisywanie lekcji.

To, co klient robi na stronie, POST /sandbox/bookings robi za ciebie: tworzy opłaconą rezerwację u wskazanego przez ciebie instruktora, z tymi samymi kontrolami co prawdziwa – opublikowana dostępność, brak nakładania się – i bez udziału pieniędzy. Od tej chwili działa prawdziwy mechanizm, a akcje poniżej zastępują klienta i zegar, więc każde zdarzenie można zobaczyć w kilka minut. Z sandboxa nie wychodzi żaden e-mail i nic w nim nigdy nie jest publiczne; każde wysyłane przez niego zdarzenie zawiera sandbox: true, podobnie jak GET /me. POST /sandbox/reset opróżnia go, żeby zestaw testów mógł zacząć od czysta.

W sandboxie nadal niedostępne są: reklamacje, niestawienie się, zwrot zlecony przez nas, anulowanie z cancelledBy platform i miejsce spotkania (jego zdarzenia pochodzą ze strony). Rezerwacje w sandboxie mają puste studentLevels i klienta o imieniu Sandbox C., który korzysta ze strony po angielsku.

Opis do odczytu maszynowego znajdziesz pod adresem https://alpinepal.com/api/v1/openapi.json – każda ścieżka, metoda, parametr i schemat opisane powyżej, w formacie OpenAPI 3.1. Skieruj na niego generator, by uzyskać typowanego klienta, albo zaimportuj go do swojego narzędzia HTTP, żeby go przeglądać. Jest udostępniany bez uwierzytelniania i trzymany w cache przez godzinę.

To jest v1. W jej ramach tylko dodajemy: nowe pola, nowe opcjonalne parametry, nowe typy zdarzeń, nowe endpointy. Twoja integracja powinna ignorować pola i zdarzenia, których nie zna. Wszystko, co zepsułoby działanie istniejącego klienta, trafi do v2 pod nowym bazowym URL-em, a v1 będzie działać dalej, dopóki się nie przeniesiesz.