API per le scuole di sci

Le chiavi sono della scuola, non di una persona, e solo il titolare della scuola può crearle o revocarle, dalla scheda API del pannello. Una chiave si mostra una sola volta, alla creazione; conserviamo un hash e non possiamo mostrarla di nuovo. Una scuola può avere fino a cinque chiavi attive, così ogni integrazione ha la sua e una vecchia si revoca senza toccare le altre. Le chiavi reali iniziano con ap_live_; quelle dell'ambiente di prova iniziano con ap_test_ e si contano a parte.

Una chiave smette di funzionare nel momento in cui viene revocata, e tutte smettono se la scuola viene disattivata o chiusa. Le chiavi non si gestiscono dall'API stessa. Per ruotarne una: crea la nuova, passa il tuo sistema a quella e revoca la vecchia; nel frattempo valgono entrambe. Il pannello mostra quando ogni chiave è stata usata l'ultima volta, con cinque minuti di precisione. Le chiavi sono per i server: non metterne mai una in un browser o in un'app mobile.

Ogni richiesta porta la chiave come bearer token. L'URL di base è https://alpinepal.com/api/v1; le risposte sono JSON, mai in cache, e ognuna porta un X-Request-Id che puoi citarci. Le ore del giorno sono sull'orologio della stazione come HH:mm, le date come YYYY-MM-DD e gli istanti in ISO 8601 in UTC con millisecondi.

I corpi devono essere JSON con intestazione Content-Type: application/json (altrimenti 415), sotto i 256 KB (413), e vengono controllati in modo stretto: un campo sconosciuto è un 400 validation_error che elenca i percorsi di troppo. Un corpo vuoto si legge come oggetto vuoto. Un metodo che il percorso non ammette è un 405 con intestazione Allow; una barra finale è un 404.

Non c'è CORS: l'API è da server a server, e una richiesta da un browser fallirà. È voluto: una chiave in un browser è una chiave che chiunque può leggere.

Per chiave, in finestre fisse di un minuto: 600 letture (GET) e 120 scritture (tutto il resto, DELETE compreso) al minuto. Oltre, la risposta è 429 rate_limited con intestazione Retry-After, in secondi. Una chiave di prova ha una quota propria. I fallimenti di autenticazione si limitano per IP, venti in dieci minuti; da lì in poi ogni altro tentativo riceve 429 prima ancora che la chiave venga cercata. Test e reinvii dei webhook condividono una quota a parte di dieci in dieci minuti per chiave, perché ognuno è una richiesta al server di qualcun altro.

Ogni errore è la stessa busta: uno stato HTTP, un code stabile su cui ramificare, un messaggio per una persona e l'id della richiesta. Quattro codici portano details: validation_error elenca i campi sbagliati come [{path, message}] (al massimo dieci); booking_state dice in che stato è ora la prenotazione ({bookingStatus}); booking_conflict indica le ore che intralciano e, se quella prenotazione è pagata, il suo id e riferimento; rate_limited ripete l'attesa come {retryAfterSeconds}.

Id. I maestri portano l'id del loro account (user_…); il posto per lezioni non assegnate di una scuola è pool_<schoolId>; i maestri dell'ambiente di prova sono sandbox_ia_… e sandbox_ib_…. Le prenotazioni sono b_…, gli eventi evt_…, le consegne whd_…, gli endpoint wh_…, le richieste req_…. I riferimenti sono AP-<anno>-<5 cifre> per le prenotazioni reali e SB<6 hex> nell'ambiente di prova.

Orari. date, startTime ed endTime sono l'orologio a muro di resortTimeZone, mai UTC; gli istanti (createdAt, updatedAt, paidAt, instructorResponseDeadline…) sono UTC. Una lezione nella notte del cambio d'ora si risolve alla prima occorrenza di un'ora ambigua, e un'ora che quella notte non esiste va avanti. endTime può essere 24:00. Se un'ora è passata si giudica sull'orologio della stazione.

Denaro. subtotal = (hourlyPrice + extraStudentPrice × (numberOfStudents − 1)) × durationHours, arrotondato alla valuta; è ciò che paga il cliente. platformFee è il nostro 10 %. netAmount è il 90 % accreditato sul registro della tua scuola quando la lezione si completa, chiunque l'abbia tenuta e chiunque lo gestisca, e annullato se la prenotazione viene rimborsata. Ogni maestro nel tuo organico fattura nella valuta della tua scuola; i prezzi orari hanno un minimo per valuta (10 EUR, 11 USD) ed extraStudentPrice è 0 o più.

managedBy è la regola che decide chi risponde: quando dice instructor, calendario e richieste sono suoi e l'API può leggere ma non scrivere; quando dice school, la scuola, e quindi l'API, scrive il calendario e risponde alle richieste, e il maestro guarda. Si imposta dall'organico nel pannello, da una persona, e non si cambia via API. Restituire il calendario al maestro cancella i blocchi esterni che il tuo sistema vi aveva scritto.

Quando un maestro lascia la scuola, le sue prenotazioni spariscono da GET /bookings e i suoi eventi si fermano, mentre ciò che ha già guadagnato resta sul tuo registro. Né questo né un cambio di managedBy manda un evento: confronta GET /instructors a ogni sincronizzazione.

La disponibilità di un maestro è una lista di blocchi. Un blocco è available, blocked o vacation, appartiene a una stazione in cui il maestro insegna, va da startTime a endTime (endTime può essere 24:00), ed è ancorato o a un giorno della settimana (dayOfWeek 0–6, domenica per prima, opzionalmente con until come ultima data in cui vale) o a una data precisa: esattamente uno dei due. I clienti possono prenotare solo dentro blocchi available che nient'altro copre.

PUT /instructors/{id}/availability sostituisce l'intero orario, ogni stazione e ogni blocco, fino a 400, con ciò che invii, esattamente come salvare il calendario nel pannello. Gli id sono facoltativi: il server ne assegna uno a un blocco che non ce l'ha, conserva quelli che invii e rifiuta duplicati o il prefisso xb_ dei blocchi esterni. I blocchi esterni (sotto) non vengono mai toccati dal PUT e non devono comparirvi. Un blocco malformato, una stazione sconosciuta o i due ancoraggi insieme sono un 422 invalid_availability.

GET …/availability/expanded fa i conti per te: per una stazione e fino a 62 giorni restituisce, per giorno, le fasce libere che un cliente potrebbe prenotare e quelle occupate, ognuna etichettata booking (una lezione confermata), pending (una richiesta pagata in attesa di risposta) o external (un blocco dall'API). Applica il margine tra le lezioni e il preavviso fissato dal maestro; non scarta i buchi più corti della sua durata minima, quindi un buco di trenta minuti risulta libero.

Una lezione venduta fuori da Alpine Pal occupa il maestro. Registrala come blocco esterno e la fascia sparisce dalla ricerca, in ogni stazione in cui insegna: una persona non può stare in due valli insieme. I blocchi richiedono che la scuola gestisca il maestro (managedBy = school).

Ogni blocco porta il tuo externalRef. Inviare lo stesso riferimento con la stessa data e le stesse ore è idempotente e restituisce 200 con il blocco salvato, qualunque resortId tu passi; lo stesso riferimento con altre ore è un 409 external_ref_exists: cancella e ricrea. Un blocco che si sovrappone a una prenotazione viva è un 409 booking_conflict con le ore che intralciano e, se quella prenotazione è pagata, il suo id e riferimento: quella lezione è già venduta da noi.

Accettare una richiesta non ricontrolla i blocchi: se la richiesta è arrivata prima del tuo blocco, la scuola deve rifiutarla o proporre un altro orario. Un blocco e un pagamento in gara sulla stessa ora possono riuscire entrambi: quando il tuo blocco riceve 201, rielenca le prenotazioni del maestro se l'ora conta.

Una scuola può vendere ore senza dire chi terrà la lezione: il cliente prenota e paga, e la scuola assegna un maestro quando vuole, via API, dal pannello o al punto d'incontro con chi è libero. Nell'API questo è il posto della scuola stessa: ha un calendario, un prezzo e un interruttore di conferma immediata propri, non compare in /instructors, e le sue prenotazioni arrivano con unassigned: true e instructorId uguale al posto (pool_…). Una lezione per fascia oraria.

GET /unassigned mostra le impostazioni; PATCH /unassigned imposta uno qualsiasi tra active, hourlyPrice, extraStudentPrice, autoAcceptBookings e maximumStudents. Il primo PATCH crea il posto, e fino ad allora i suoi endpoint di calendario e blocchi danno 404. Accenderlo richiede un prezzo sopra il minimo nella stessa chiamata o in una precedente e le stazioni della scuola scelte nel pannello; spegnerlo è sempre permesso. Il calendario del posto funziona esattamente come quello di un maestro, nelle stazioni della scuola.

Finché la lezione non è assegnata, la scuola è il suo lato maestro: risponde alla richiesta, chatta con il cliente e concorda il punto d'incontro. Una volta assegnata, la prenotazione è del maestro come qualsiasi altra, e ciò che la scuola può ancora farne segue managedBy.

All'API arrivano solo prenotazioni pagate: una prenotazione esiste per te dall'istante in cui entra il pagamento (paidAt), e una rimborsata resta elencata con il suo paymentStatus. Un cliente sceglie maestro e fascia, paga, e la richiesta arriva al maestro o alla scuola. Da lì, o riceve risposta, o scade senza risposta e il cliente viene rimborsato.

L'orologio: il termine di risposta è 48 ore dal pagamento, mai oltre l'inizio della lezione; una proposta o un suo rifiuto lo azzerano (mai oltre il primo tra l'inizio originale e quello proposto); una scansione oraria fa scadere ciò che è in ritardo, quindi la scadenza può arrivare fino a un'ora dopo. Una lezione confermata diventa upcoming 24 ore prima dell'inizio e in_progress mentre si svolge. Si completa quando il cliente la conferma, o da sola 48 ore dopo la fine; il completamento libera la tua parte. Il cliente può annullare gratis fino a 48 ore prima dell'inizio.

Del cliente ricevi un nome breve (nome e iniziale), la lingua preferita e il messaggio: quanto basta per tenere la lezione, e ciò che la nostra informativa sulla privacy gli promette. Email, telefono e qualsiasi identificativo dell'account non vengono mai inviati; la conversazione con il cliente resta nella chat di Alpine Pal, dov'è il maestro.

GET /bookings elenca le prenotazioni pagate dei tuoi maestri, dalla modifica più vecchia alla più nuova, con filtri per status (lista separata da virgole), instructorId, from e to (date della lezione) e updatedSince (qualsiasi istante ISO 8601; inclusivo). Le pagine vanno per cursore su (updatedAt, id): segui nextCursor finché è null. Il cursore è opaco e non scade, ma appartiene ai filtri con cui è stato creato: se li cambi, ricomincia; uno inventato è un 400.

Lo schema per una sincronizzazione notturna o oraria è lo stesso: ricorda l'updatedAt più recente che hai visto e chiedi tutto da lì, così come l'hai ricevuto. I webhook ti avvisano nel momento in cui qualcosa cambia; questo endpoint è come ti rimetti in pari dopo un'interruzione. updatedAt si muove anche per cambi che non mandano eventi (la lezione che diventa upcoming o in_progress, un promemoria inviato, un punto d'incontro proposto), quindi una riga può comparire in una sincronizzazione senza nulla di visibilmente diverso.

Le azioni sono aperte alla scuola sui maestri che gestisce e sul proprio posto per lezioni non assegnate; su un maestro che si gestisce da sé la risposta è 403 not_managed_by_school. Ogni azione è un aggiornamento condizionale: se la prenotazione non è più nello stato che l'azione si aspetta, la risposta è 409 booking_state con lo stato attuale in details, e non cambia nulla. Ripetere un'azione è quindi sicuro, e il modo per confermare cosa è successo è GET /bookings/{id}.

Due cose non ci sono di proposito: segnare un'assenza e dare una lezione per completata. Entrambe muovono denaro in base a ciò che è successo in pista, ed entrambe restano un atto umano nel pannello.

Registra un URL https e facciamo POST di ogni evento di prenotazione lì: lo stesso JSON che restituiscono gli endpoint delle prenotazioni, avvolto in un evento. Fino a dieci endpoint per scuola, ognuno iscritto ad alcuni eventi o a tutti con "*". Registrali dal pannello o via API; il pannello mostra il registro delle consegne in entrambi i casi. L'URL deve essere https, con un nome host che abbia un punto, senza credenziali né frammento, e non un indirizzo privato né il nostro.

Eventi. booking.requested: è arrivata una richiesta pagata. booking.confirmed: accettata dal maestro o dalla scuola, confermata automaticamente, o il cliente ha accettato un orario proposto; acceptedVia dice quale, e previousStatus è change_proposed nell'ultimo caso. booking.time_proposed: al cliente è stato proposto un altro orario. booking.rejected. booking.cancelled: cancelledBy è customer, instructor, school o platform (l'account dietro la prenotazione è stato eliminato). booking.expired: nessuno ha risposto in tempo. booking.completed: la lezione è finita, assenze comprese. booking.updated: qualsiasi altra cosa che meriti un avviso, con data.reason: proposal_declined, meeting_point_proposed, meeting_point_confirmed, dispute_opened, dispute_resolved, refund_settled (il denaro è tornato al cliente), refund_issued (da noi) o instructor_assigned (previousInstructorId indica il posto su cui stava la lezione). ping è l'evento di prova, con data vuoto; non è un tipo a cui iscriversi. Nessun evento per upcoming, in_progress, né per cambi di organico o di managedBy.

Cosa aspettarsi. La consegna è almeno una volta: una risposta che arriva dopo i nostri dieci secondi di attesa conta come fallimento e l'evento torna, quindi tratta l'id dell'evento come chiave e ignora le ripetizioni. L'ordine non è garantito, i nuovi tentativi e la scansione lo alterano, quindi ordina per data.booking.updatedAt. Il payload è congelato alla creazione dell'evento; un nuovo tentativo porta ciò che era vero allora, e un evento successivo lo stato più nuovo. Un evento può andare perso se fallisce il nostro tentativo di registrarlo; GET /bookings?updatedSince è la rete di sicurezza. Ogni evento porta sandbox: true o false. Il registro conserva le consegne trenta giorni; un reinvio manda di nuovo una consegna passata.

Ogni consegna è firmata con il segreto dell'endpoint: l'intestazione X-AlpinePal-Signature porta una marca temporale e un HMAC-SHA256 della marca, un punto e il corpo grezzo. Verificala prima di fidarti di qualsiasi cosa, confronta in tempo costante e rifiuta marche a più di cinque minuti dal tuo orologio. Il segreto viene restituito alla creazione dell'endpoint e da GET /webhooks, e si può ruotare dal pannello o con POST /webhooks/{id}/rotate-secret; il vecchio muore all'istante.

Rispondi con un qualsiasi 2xx entro dieci secondi. Qualsiasi altra cosa, un 3xx compreso perché non seguiamo i reindirizzamenti, è un fallimento: riproviamo dopo 5 minuti, 15 minuti, 1 ora, 4 ore, 12 ore e 24 ore, circa 42 ore in tutto, ogni volta con lo stesso id di evento così puoi deduplicare. Un endpoint che fallisce dieci tentativi di fila viene spento e i gestori della scuola avvisati; le sue consegne in sospeso passano a fallite e non vengono inviate quando lo riaccendi: reinvia quelle che ti servono. POST /webhooks/{id}/test manda un ping subito e riferisce com'è andata, e GET /webhooks/{id}/deliveries mostra le ultime cento consegne (una per evento ed endpoint, con il conteggio dei tentativi) senza i corpi.

Ogni scuola ha una gemella di prova dal momento in cui il titolare crea una chiave di prova nel pannello (Collega il tuo sistema di prenotazioni → Ambiente di prova): una copia della scuola con due maestri fittizi, sandbox_ia_…, che risponde alle richieste a mano, e sandbox_ib_…, con la conferma immediata attiva, e il posto per lezioni non assegnate, ciascuno con un calendario 09:00–17:00 tutti i giorni nelle stazioni della scuola, da 1 a 6 ore per lezione, fino a 6 allievi, senza margine né preavviso. Le chiavi di prova iniziano con ap_test_ e raggiungono solo la gemella; le chiavi reali mai. Tutto il resto è la stessa API: elencare i maestri della gemella, scrivere i loro calendari, registrare webhook, rispondere alle richieste, assegnare lezioni.

Quello che un cliente fa sul sito lo fa per te POST /sandbox/bookings: crea una prenotazione pagata per il maestro che indichi, con gli stessi controlli di una vera, disponibilità pubblicata e nessuna sovrapposizione, e senza soldi di mezzo. Da lì gira la macchina vera, e le azioni qui sotto fanno le veci del cliente e dell'orologio, così ogni evento si vede in pochi minuti. Nessuna email esce dall'ambiente di prova e niente di esso è mai pubblico; ogni evento che invia porta sandbox: true, come GET /me. POST /sandbox/reset lo svuota perché una batteria di test parta pulita.

Resta fuori dalla portata dell'ambiente di prova: reclami, assenze, un rimborso emesso da noi, un annullamento con cancelledBy platform e il punto d'incontro (i suoi eventi nascono sul sito). Le prenotazioni dell'ambiente di prova portano studentLevels vuoto e un cliente chiamato Sandbox C. che usa il sito in inglese.

La descrizione leggibile da una macchina vive su https://alpinepal.com/api/v1/openapi.json: ogni percorso, metodo, parametro e schema qui sopra, in OpenAPI 3.1. Puntaci un generatore per avere un client tipizzato, o importala nel tuo strumento HTTP per sfogliarla. Si serve senza autenticazione e resta in cache per un'ora.

Questa è la v1. Al suo interno aggiungiamo soltanto: campi nuovi, parametri facoltativi nuovi, tipi di evento nuovi, endpoint nuovi. La tua integrazione deve ignorare i campi e gli eventi che non conosce. Qualsiasi cosa che romperebbe un client esistente andrebbe in una v2 con un altro URL di base, con la v1 in funzione mentre migri.