API para escuelas de esquí

Las claves son de la escuela, no de una persona, y solo el titular de la escuela puede crearlas o revocarlas, desde la pestaña Conexiones del panel. Una clave se enseña una sola vez, al crearla; guardamos un hash y no podemos volver a mostrarla. Una escuela puede tener hasta 5 claves vivas, así que cada integración lleva la suya y se puede revocar una vieja sin tocar las demás. Las claves reales empiezan por ap_live_; las del entorno de pruebas empiezan por ap_test_ y se cuentan aparte.

Una clave deja de funcionar en el momento en que se revoca, y todas reciben un 403 school_not_active en cuanto la escuela se cierra o no está aprobada. Una escuela solo suspendida (oculta en la web, sin su página) conserva sus claves: sus reservas siguen adelante, y la API con ellas. Las claves no se gestionan desde la propia API. Para rotar una: crea la nueva, cambia tu sistema a ella y revoca la vieja; entre medias las dos valen. El panel muestra cuándo se usó cada clave por última vez, con 5 minutos de precisión. Las claves son para servidores: nunca metas una en un navegador ni en una app móvil.

Cada petición lleva la clave como bearer token. La URL base es https://alpinepal.com/api/v1; las respuestas son JSON, nunca se cachean, y cada una lleva un X-Request-Id que puedes citarnos. Las horas del día van en el reloj de la estación como HH:mm, las fechas como YYYY-MM-DD y los instantes en ISO 8601 en UTC con milisegundos.

Los cuerpos deben ser JSON con cabecera Content-Type: application/json (415 si no), de menos de 256 KB (413), y se comprueban de forma estricta: un campo desconocido es un 400 validation_error que lista las rutas que sobran. Un cuerpo vacío se lee como un objeto vacío. Un método que la ruta no admite es un 405 con cabecera Allow; una barra final es un 404.

No hay CORS: la API es de servidor a servidor, y una petición desde un navegador fallará. Es a propósito: una clave en un navegador es una clave que cualquiera puede leer.

Por clave, en ventanas fijas de un minuto: 600 lecturas (GET) y 120 escrituras (todo lo demás, DELETE incluido) por minuto. Pasado eso la respuesta es 429 rate_limited con cabecera Retry-After, en segundos. Una clave de prueba tiene su propio cupo. Los fallos de autenticación se limitan por IP, 20 en 10 minutos; a partir de ahí cualquier intento más recibe 429 antes siquiera de buscar la clave. Las pruebas y reenvíos de webhooks comparten un cupo aparte de 10 en 10 minutos por clave, porque cada uno es una petición al servidor de otro.

Todo error es el mismo sobre: un estado HTTP, un code estable para ramificar, un mensaje para una persona y el id de la petición. Cinco códigos llevan details: validation_error lista los campos que fallan como [{path, message}] (10 como máximo); booking_state dice en qué estado está ahora la reserva ({bookingStatus}); booking_conflict nombra las horas que estorban y, si esa reserva está pagada, su id y su referencia; rate_limited repite la espera como {retryAfterSeconds}; inside_notice_window da la antelación del instructor en horas ({hours}).

Ids. Los instructores llevan el id de su cuenta (user_…), o unclaimed_… mientras nadie haya reclamado un perfil que tu escuela añadió sin cuenta; el asiento de clases sin asignar de una escuela es pool_<schoolId>; los instructores del entorno de pruebas son sandbox_ia_… y sandbox_ib_…. Las reservas son b_…, los eventos evt_…, las entregas whd_…, los endpoints wh_…, las peticiones req_…. Las referencias son AP-<año>-<5 dígitos> en las reservas reales y SB<6 hex> en el entorno de pruebas.

Horas. date, startTime y endTime son el reloj de pared de resortTimeZone, nunca UTC; los instantes (createdAt, updatedAt, paidAt, instructorResponseDeadline…) son UTC. Una clase la noche del cambio de hora se resuelve a la primera aparición de una hora ambigua, y una hora que esa noche no existe se adelanta. endTime puede ser 24:00. Si una hora ya pasó se juzga en el reloj de la estación.

Dinero. subtotal = (hourlyPrice + extraStudentPrice × max(0, numberOfStudents − includedStudents)) × durationHours, redondeado a la moneda; es lo que paga el cliente. hourlyPrice es el de la fecha de la clase: el de una temporada (seasonPrices) si la fecha cae en una, y si no el propio del instructor o del asiento; includedStudents es cuántos alumnos cubre, 1 salvo que la escuela ponga más. platformFee es nuestra comisión: el 10 %, o la más alta que tu escuela haya pactado por escrito con nosotros; cada reserva conserva la que tenía al venderse. netAmount es el resto, subtotal − platformFee, que se abona en el libro de tu escuela cuando la clase se completa, la dé quien la dé y la gestione quien la gestione, y se anula si la reserva se reembolsa. Todos los instructores de tu plantilla cobran en la moneda de tu escuela; el precio por hora tiene un mínimo por moneda (10 EUR, 11 USD, 10 CHF) y extraStudentPrice es 0 o más. El material que el cliente alquila a tu escuela con la clase también se suma a subtotal (equipment.amount) y cuenta como la clase.

managedBy es la regla que decide quién responde: cuando dice instructor, el calendario y las solicitudes son suyos y la API puede leer pero no escribir; cuando dice school, la escuela, y por tanto la API, escribe el calendario y responde las solicitudes, y el instructor mira. Se fija desde la plantilla en el panel, por una persona, y no se cambia por API. Devolverle el calendario al instructor borra los bloqueos externos que tu sistema escribió en él.

Cuando un instructor deja la escuela, sus reservas desaparecen de GET /bookings y sus eventos se detienen, mientras que lo que ya ganó se queda en tu libro. Ni eso ni un cambio de managedBy manda evento: compara GET /instructors en cada sincronización.

unclaimed marca a un instructor que la escuela añadió en el panel sin cuenta: nadie inicia sesión como él, así que siempre es managedBy school y la escuela responde por él en todo, también en el chat. Cuando la persona reclama el perfil con su propia cuenta, unclaimed pasa a false y el id del instructor cambia a uno definitivo: todas las rutas y el filtro instructorId siguen aceptando el id antiguo, el instructor lo lleva en previousId y los eventos desde entonces nombran el nuevo. Ningún evento lo anuncia: compara GET /instructors en cada sincronización y casa previousId.

La disponibilidad de un instructor es una lista de bloques. Un bloque es available, blocked o vacation, pertenece a una estación en la que el instructor enseña, va de startTime a endTime (endTime puede ser 24:00), y se ancla o a un día de la semana (dayOfWeek 0–6, domingo primero, opcionalmente con since y until como primera y última fecha en que aplica) o a una fecha concreta: exactamente una de las dos. Las horas available nuevas tienen que caer entre las 07:00 y las 21:00, hora de la estación (si no, 422 outside_ski_day); los bloques blocked y vacation pueden cubrir cualquier hora. Los clientes solo pueden reservar dentro de bloques available que nada más cubra.

PUT /instructors/{id}/availability sustituye todo el horario, todas las estaciones y todos los bloques, hasta 400, por lo que envías, exactamente como guardar el calendario en el panel. Los ids son opcionales: el servidor asigna uno a un bloque sin él, conserva los que envías y rechaza duplicados o el prefijo xb_ de los bloqueos externos. Los bloqueos externos (más abajo) nunca los toca el PUT y no deben aparecer en él. Un bloque mal formado, una estación desconocida, los dos anclajes a la vez o un since posterior al until del bloque son un 422 invalid_availability. Los bloques que ya no pueden aplicarse (una fecha pasada, un bloque semanal pasado su until) se descartan: el PUT no los guarda y el GET no los devuelve. Una fecha ha pasado cuando ha pasado en todas partes, a las 12:00 UTC del día siguiente.

GET …/availability/expanded hace la aritmética por ti: para una estación y hasta 62 días devuelve, por día, los huecos libres que un cliente podría reservar y los ocupados, cada ocupado etiquetado booking (una clase confirmada), pending (una solicitud pagada esperando respuesta) o external (un bloqueo de la API). Aplica el margen entre clases y la antelación que fijó el instructor; no descarta huecos más cortos que su duración mínima, así que un hueco de treinta minutos sale como libre.

Una clase vendida fuera de Alpine Pal ocupa al instructor. Regístrala como bloqueo externo y la franja desaparece de la búsqueda, en todas las estaciones donde enseña: una persona no puede estar en dos valles a la vez. Los bloqueos exigen que la escuela gestione al instructor (managedBy = school).

Cada bloqueo lleva tu propio externalRef. Enviar la misma referencia otra vez con la misma fecha y horas es idempotente y devuelve 200 con el bloqueo guardado, pases el resortId que pases; la misma referencia con otras horas es un 409 external_ref_exists: borra y vuelve a crear. Un bloqueo que solapa una reserva viva es un 409 booking_conflict con las horas que estorban y, si esa reserva está pagada, su id y su referencia: esa clase ya está vendida por nuestro lado.

Un instructor puede tener como mucho 400 bloqueos externos de hoy en adelante; uno más es un 422 limit_reached. Un bloqueo cuya fecha ha pasado (a las 12:00 UTC del día siguiente) se va solo: GET /blocks ya no lo lista, un DELETE sobre él es un 404 y deja de contar para los 400.

Aceptar una solicitud vuelve a comprobar la franja: un bloqueo externo en sus horas, igual que una reserva viva o una clase grupal, da un 409 slot_conflict, y la escuela debe rechazarla o proponer otra hora. En el asiento de clases sin asignar, aceptar no vuelve a comprobar nada: sus plazas se contaron cuando el cliente pagó. Cuando tu bloqueo recibe 201 la hora es tuya: un pago que ya estuviera en curso sobre ella se reembolsa al intentar liquidarse y te llega como booking.expired.

Una escuela puede vender horas sin decir quién dará la clase: el cliente reserva y paga, y la escuela asigna un instructor cuando quiera, por la API, desde el panel o en el punto de encuentro con quien esté libre. En la API esto es el asiento propio de la escuela: tiene calendario, precio e interruptor de confirmación inmediata propios, no aparece en /instructors, y sus reservas llegan con unassigned: true e instructorId igual al asiento (pool_…). Vende tantas clases a la vez como plazas tenga su calendario: un bloque available puede llevar capacity (hasta 50; 1 si no la lleva), contadas en la estación del bloque minuto a minuto: los bloques del propio día sustituyen a los semanales en los minutos que cubren, y dentro de cada capa los que se solapan se suman. Una clase necesita plaza durante todo su tramo. Las clases grupales del asiento no ocupan plazas: van a la vez que las particulares y que otras clases.

GET /unassigned enseña los ajustes; PATCH /unassigned fija cualquiera de hourlyPrice, extraStudentPrice (0 o más; uno negativo es un 422 invalid_price), extraStudentPer, durationPrices, seasonPrices, includedStudents, autoAcceptBookings y maximumStudents. El primer PATCH crea el asiento, y hasta entonces sus endpoints de calendario y bloqueos dan 404. No hay interruptor: active dice si el asiento está a la venta, y lo está en cuanto su precio por hora supera el mínimo (o, si vende formatos, sus formatos y temporadas están completos); vende en las horas que abra su calendario, así que una escuela que no quiera estas clases no abre ninguna. Un active en un PATCH se ignora. Por lo demás, el calendario del asiento funciona como el de un instructor, en las estaciones de la escuela.

Formatos fijos. En vez de por horas, una escuela puede vender las clases particulares de su asiento en formatos fijos, que se configuran en el panel: hasta 6 (mañana, tarde, día completo u otro, cada uno con su inicio y su fin) y temporadas, tramos de fechas con un precio por formato, por clase y para todo el grupo. saleMode en GET /unassigned dice cuál, y lessonFormats lista los formatos y las temporadas (solo lectura en la API). Mientras el asiento vende formatos, cada clase particular suya es uno de ellos: un formato sin precio en la temporada de una fecha no se vende ese día, y una fecha fuera de toda temporada no vende nada. Un formato necesita plaza durante todo su horario, como cualquier clase del asiento, y no tiene el límite de 6 horas de las clases por horas. Un asiento así está a la venta en cuanto sus formatos y temporadas están completos, sea cual sea su precio por hora. Sus reservas llevan format (id y tipo), subtotal es el precio de ese formato ese día, y propose-time solo lo mueve al mismo horario en un día que venda su formato al precio pagado (si no, 409 format_fixed_time o format_price_differs). En el entorno de pruebas, POST /sandbox/bookings sobre el asiento acepta formatId y usa los formatos de tu escuela.

Hasta que la clase se asigna, la escuela es su lado instructor: responde la solicitud, chatea con el cliente y acuerda el punto de encuentro. Una vez asignada, la reserva es del instructor como cualquier otra, y lo que la escuela aún puede hacer con ella sigue a managedBy.

Una clase grupal es un evento con plazas que clientes independientes compran por separado: puntual (date) o serie semanal (dayOfWeek, opcionalmente con since y until), con aforo, precio por plaza para la clase entera, nivel, para quién es (audience: todos, niños o adultos; una clase de niños puede indicar minAge y maxAge, y cada alumno que reserva plaza tiene que encajar), punto de encuentro fijo y un mínimo de asistentes para impartirse. Las clases de un instructor toman su precio por plaza de los ajustes del propio instructor (groupClassesEnabled y groupPricePerStudent, escribibles por PATCH /instructors/{id}); solo el asiento sin asignar lo pone al crear, y un cambio de precio re-estampa las clases activas. Las clases se publican, se entregan a un instructor y se cancelan desde el panel — en la API son de solo lectura en v1 — y viven en un instructor de la plantilla o en el asiento sin asignar.

GET /instructors/{id}/classes (y GET /unassigned/classes) listan las activas. GET …/classes/expanded?from&to las resuelve a fechas concretas con sus plazas ocupadas, pagos en curso dentro de sus 10 minutos de retención incluidos — como mucho 62 días por llamada. En el calendario de un instructor, las horas de una clase salen además como ocupadas en la vista expandida de la disponibilidad, y un bloqueo externo sobre ellas se rechaza con un 409 booking_conflict: esas horas no son tuyas para venderlas fuera. El asiento sin asignar es un equipo: sus clases no le quitan plazas particulares, van a la vez que ellas y que otras clases, y un bloqueo externo nunca choca con ellas.

Cada plaza vendida llega por /bookings como una reserva normal con su groupClassId, confirmada en cuanto se paga (acceptedVia auto). propose-time y assign la rechazan — la hora es de la clase y de todos sus participantes, y una clase se entrega a un instructor entera, desde el panel. Cancelar una clase (o un día de la serie) reembolsa cada plaza íntegra y envía un booking.cancelled por plaza; una clase que 24 horas antes de empezar sigue por debajo de su minStudents se cancela igual, con cancelledBy platform.

A la API solo llegan reservas pagadas: una reserva existe para ti desde el instante en que entra su pago (paidAt), y una reembolsada sigue listada con su paymentStatus. Un cliente elige instructor y franja, paga, y la solicitud aterriza en el instructor o en la escuela. A partir de ahí, o se responde, o caduca sin respuesta y se reembolsa al cliente.

El reloj: el plazo de respuesta son 48 horas desde el pago, nunca más tarde del inicio de la clase; una propuesta o un rechazo de propuesta lo reinician (nunca más allá del inicio más temprano entre el original y el propuesto); un barrido horario caduca lo vencido, así que la caducidad puede llegar hasta una hora tarde. Una clase confirmada pasa a upcoming 24 horas antes de empezar y a in_progress mientras dura. Se completa cuando el cliente la confirma, o sola 48 horas después de acabar; completarse libera tu parte. El cliente puede cancelar gratis hasta freeCancellationHours horas antes del inicio: la ventana de la propia reserva, la que tenía la política de cancelación de tu escuela cuando se hizo (48 por defecto), y que conserva aunque la política cambie después.

Del cliente recibes un nombre corto (nombre e inicial), su idioma preferido y su mensaje: suficiente para dar la clase, y lo que nuestra política de privacidad le promete. Nunca se envían email, teléfono ni identificador de cuenta; la conversación con el cliente sigue en el chat de Alpine Pal, donde está el instructor.

GET /bookings lista las reservas pagadas de tus instructores, del cambio más antiguo al más nuevo, con filtros por status (lista separada por comas), instructorId, from y to (fechas de clase) y updatedSince (cualquier instante ISO 8601; inclusivo). Las páginas van por cursor sobre (updatedAt, id): sigue nextCursor hasta que sea null. El cursor es opaco y no caduca, pero pertenece a los filtros con los que se hizo: si los cambias, empieza de nuevo; uno inventado es un 400.

El patrón de una sincronización nocturna u horaria es el mismo: recuerda el updatedAt más nuevo que hayas visto y pide todo desde ahí, tal cual lo recibiste. Los webhooks te avisan en el momento en que algo cambia; este endpoint es cómo te pones al día tras una caída. updatedAt también se mueve con cambios que no mandan evento (la clase pasa a upcoming o in_progress, o se envía un recordatorio), así que una fila puede aparecer en una sincronización sin nada visible distinto.

Las acciones están abiertas a la escuela sobre los instructores que gestiona y sobre su propio asiento de clases sin asignar; sobre un instructor que se gestiona a sí mismo la respuesta es 403 not_managed_by_school. Cada acción es una actualización condicional: si la reserva ya no está en el estado que la acción espera, la respuesta es 409 booking_state con el estado actual en details, y no cambia nada. Repetir una acción es por tanto seguro, y la forma de confirmar qué pasó es GET /bookings/{id}.

Dos cosas no están aquí a propósito: marcar una ausencia y dar la clase por completada. Las dos mueven dinero por lo que pasó en la pista, y las dos siguen siendo un acto humano en el panel.

Registra una URL https y hacemos POST de cada evento de reserva a ella: el mismo JSON que devuelven los endpoints de reservas, envuelto en un evento. Hasta 10 endpoints por escuela, cada uno suscrito a algunos eventos o a todos con "*". Regístralos desde el panel o por la API; el panel enseña el registro de entregas en ambos casos. La URL debe ser https, con un nombre de host que tenga punto, sin credenciales ni fragmento, y no una dirección privada ni la nuestra.

Eventos. booking.requested: llegó una solicitud pagada. booking.confirmed: aceptada por el instructor o la escuela, confirmada automáticamente, o el cliente aceptó una hora propuesta; acceptedVia dice cuál, y previousStatus es change_proposed en el último caso. booking.time_proposed: se propuso otra hora al cliente. booking.rejected. booking.cancelled: cancelledBy es customer, instructor, school o platform (se borró la cuenta detrás de la reserva, o una clase grupal se canceló por no llegar a su mínimo). booking.expired: nadie respondió a tiempo. booking.completed: la clase acabó, ausencias incluidas. booking.updated: cualquier otra cosa que merezca aviso, con data.reason: proposal_declined, meeting_point_proposed, meeting_point_confirmed, dispute_opened, dispute_resolved, refund_settled (el dinero ya volvió al cliente), refund_issued (por nosotros) o instructor_assigned (previousInstructorId nombra el asiento en que estaba la clase). ping es el evento de prueba, con data vacío; no es un tipo al que suscribirse. No hay evento para upcoming, in_progress, ni cambios de plantilla o de managedBy.

Qué esperar. La entrega es al menos una vez: una respuesta que llega después de nuestros 10 segundos de espera cuenta como fallo y el evento vuelve, así que trata el id del evento como clave e ignora las repeticiones. El orden no está garantizado, los reintentos y el barrido lo alteran, así que ordena por data.booking.updatedAt. No toda reserva empieza con booking.requested: la de un instructor con la confirmación inmediata activada (autoAcceptBookings) llega directamente como booking.confirmed, con previousStatus pending_instructor_approval. Así que da de alta la reserva en tu sistema con el primer evento que veas de su id, sea del tipo que sea. El payload se congela al crear el evento; un reintento trae lo que era cierto entonces, y un evento posterior, el estado más nuevo. Un evento puede perderse si falla nuestro intento de registrarlo; GET /bookings?updatedSince es la red de seguridad. Todo evento lleva sandbox: true o false. El registro guarda las entregas 30 días; un reenvío manda otra vez una pasada.

Cada entrega va firmada con el secreto del endpoint: la cabecera X-AlpinePal-Signature lleva una marca de tiempo y un HMAC-SHA256 de la marca, un punto y el cuerpo en bruto. Verifícala antes de fiarte de nada, compara en tiempo constante y rechaza marcas a más de 5 minutos de tu reloj. El secreto se devuelve al crear el endpoint y en GET /webhooks, y se puede rotar desde el panel o con POST /webhooks/{id}/rotate-secret; el viejo muere al instante.

Responde con cualquier 2xx en 10 segundos. Cualquier otra cosa, un 3xx incluido porque no seguimos redirecciones, es un fallo: reintentamos a los 5 minutos, 15 minutos, 1 hora, 4 horas, 12 horas y 24 horas, unas 42 horas en total, cada vez con el mismo id de evento para que puedas deduplicar. Un endpoint solo se apaga, y se avisa a los administradores de la escuela, cuando una entrega ha agotado todos sus reintentos sin que llegue ninguna otra entrega entretanto; un corte breve no lo apaga, aunque haya muchos eventos en vuelo. Mientras está apagado no se le encolan eventos nuevos (GET /bookings?updatedSince te pone al día), y una entrega pendiente cuyo intento vence en ese tiempo pasa a fallida sin enviarse; los reintentos que vencen después de volver a encenderlo salen con normalidad. Reenvía las que hayan fallado. POST /webhooks/{id}/test encola un ping como una entrega más, lo intenta ahora mismo e informa de cómo fue ese intento: un ping fallido se reintenta igual, cuenta como cualquier entrega para apagar el endpoint y, con el endpoint apagado, pasa a fallido sin enviarse. GET /webhooks/{id}/deliveries enseña las entregas más recientes primero, 50 por defecto y hasta 100 con ?limit=, con su cuenta de intentos y sin sus cuerpos: cada evento tiene una entrega por endpoint, más una por cada reenvío, con el mismo id de evento.

Toda escuela tiene una gemela de pruebas desde que su titular crea una clave de prueba en el panel (Conexiones → Entorno de pruebas): una copia de la escuela con dos instructores ficticios, sandbox_ia_…, que responde las solicitudes a mano, y sandbox_ib_…, con la confirmación inmediata activada, y el asiento de clases sin asignar, cada uno con un calendario de 09:00 a 17:00 todos los días en las estaciones de la escuela, de 1 a 6 horas por clase, hasta 6 alumnos, sin margen ni antelación. Las claves de prueba empiezan por ap_test_ y solo llegan a la gemela; las reales nunca. Todo lo demás es la misma API: listar los instructores de la gemela, escribir sus calendarios, registrar webhooks, responder solicitudes, asignar clases.

Lo que un cliente hace en la web lo hace por ti POST /sandbox/bookings: crea una reserva pagada para el instructor que indiques, con las mismas comprobaciones que una real, disponibilidad publicada y sin solapes, y sin dinero de por medio. A partir de ahí corre la maquinaria real, y las acciones de abajo hacen de cliente y de reloj, así que todos los eventos se ven en minutos. Ningún correo sale del entorno de pruebas y nada de él es público nunca; cada evento que envía lleva sandbox: true, igual que GET /me. POST /sandbox/reset lo vacía para que una batería de pruebas empiece limpia.

Sigue fuera del alcance del entorno de pruebas: disputas, ausencias, un reembolso emitido por nosotros, una cancelación con cancelledBy platform y el punto de encuentro (sus eventos nacen en la web). Las reservas del entorno de pruebas llevan studentLevels vacío y un cliente llamado Sandbox C. que usa la web en inglés.

La descripción legible por máquina vive en https://alpinepal.com/api/v1/openapi.json: cada ruta, método, parámetro y esquema de arriba, en OpenAPI 3.1. Apunta un generador para tener un cliente tipado, o impórtala en tu herramienta HTTP para navegarla. Se sirve sin autenticación y se cachea una hora.

Esto es la v1. Dentro de ella solo añadimos: campos nuevos, parámetros opcionales nuevos, tipos de evento nuevos, endpoints nuevos. Tu integración debe ignorar los campos y eventos que no conozca. Cualquier cosa que rompiera un cliente existente iría a una v2 con otra URL base, con la v1 en marcha mientras migras.