Conceptos

Disponibilidad y caché

Cómo leer los horarios libres y por qué pueden tener hasta 45 segundos de atraso.

GET /api/v1/disponibilidad devuelve los horarios libres de un servicio con las mismas reglas que la página de reservas de Turnova: horario del negocio y de cada profesional, turnos tomados, bloqueos, boxes, horario de oferta del servicio y duración de los extras.

curl "https://turnovapp.com/api/v1/disponibilidad?servicioId=cmh3s0abc0012&desde=2030-01-10&dias=7" \
  -H "Authorization: Bearer $TURNOVA_CLAVE_SECRETA"

Cómo leer la respuesta

horarios: por fecha (AAAA-MM-DD), las horas de inicio libres con al menos una profesional.
horariosPorProfesional: lo mismo, separado por profesional. Útil si la clienta elige con quién.
diasSinLugar: fechas del rango que ya no tienen ningún horario.
Las fechas y horas están en la zona del negocio (negocio.zonaHoraria del catálogo), no en la del navegador.
Si el servicio tiene opciones, mandá varianteId. Si la clienta suma extras, mandá addOnIds (separados por coma): estiran la duración y cambian los horarios posibles.

Caché

La disponibilidad puede tener hasta 45 segundos de atraso. Turnova guarda cada respuesta ese tiempo por negocio y combinación de parámetros.

Eso no permite reservar dos veces el mismo horario: al crear la reserva, el servidor vuelve a validar todo dentro de una transacción. Si el horario se ocupó en esos segundos, la reserva responde 409 HORARIO_NO_DISPONIBLE con recuperación RELEER_Y_CONFIRMAR: volvé a pedir la disponibilidad y ofrecé otros horarios.

Una reserva creada por la API limpia la caché del negocio, así que la próxima consulta ya la refleja. Lo que se carga desde el panel o desde otra vía se ve al vencer la caché.