Leer la disponibilidad | VillaSlot Documentation

GET /api/v1/properties/{propertyId}/availability

Las franjas libres de una villa, para un día local y una duración. Es el mismo motor que usan el calendario y la página de reserva pública: se tienen en cuenta el horario de apertura, las reservas existentes y el margen entre dos sesiones de fotos.

Autorización

Rol en la organización	Este endpoint
`owner`	Permitido
`admin`	Permitido
`member`	Permitido

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
`date`	cadena	sí	Un día local `YYYY-MM-DD` en la zona horaria de la organización — nunca un instante
`durationMinutes`	entero	sí	La duración que quieres reservar

Ejemplo

bash

curl -H "x-api-key: $VILLASLOT_API_KEY" \
  "https://villaslot.app/api/v1/properties/1f0a…/availability?date=2026-09-12&durationMinutes=120"

Respuesta

200 OK — las franjas, como instantes, más la zona horaria en la que se han calculado.

json

{
  "success": true,
  "data": {
    "propertyId": "1f0a…",
    "date": "2026-09-12",
    "timezone": "Asia/Makassar",
    "durationMinutes": 120,
    "slots": [
      {
        "startAt": "2026-09-12T00:00:00.000Z",
        "endAt": "2026-09-12T02:00:00.000Z"
      }
    ]
  }
}

Qué rechaza

422 Unprocessable Entity — date no es YYYY-MM-DD, o durationMinutes no es un entero positivo.
401 Unauthorized — clave ausente o no válida, o clave cuyo portador ha dejado la organización.
404 Not Found — identificador desconocido, o identificador que pertenece a otra organización. Los dos son deliberadamente indistinguibles.
429 Too Many Requests — más de 120 peticiones en un minuto para esta clave.

Notas

Una lista vacía no dice por qué. Una villa cerrada ese día y una villa totalmente reservada responden las dos []. Pregunta al endpoint de creación si necesitas el motivo: indica CLOSED, OUTSIDE_OPENING_HOURS u OVERLAP.
Las franjas se devuelven como instantes; conviértelas con el campo timezone, no con tu propio reloj.