Consultar la disponibilidad a través de la API

Con la interfaz GET /api/v1/availability, tu propio sistema consulta a Univents si un periodo está libre: para un único espacio o para todos los espacios de un workspace. Así, tu web, tu herramienta de planificación u otro sistema pueden dar una confirmación sin generar una reserva.

La respuesta es la misma que usan la página de reservas y el chat: cuentan los eventos ocupados, los puntos del programa, los grupos de espacios, las solicitudes abiertas y los periodos de bloqueo.

Clave y permiso

Necesitas una clave de API con el permiso Leer espacios. Puedes crearla en Integraciones → Desarrolladores → Claves de API; la configuración se explica en el artículo sobre las claves de API. Envíala en cada petición como Authorization: Bearer <Schlüssel>. Una clave sin este permiso recibe un rechazo, no un resultado vacío.

La petición

GET /api/v1/availability?from=2026-10-01&to=2026-10-03
GET /api/v1/availability?from=2026-10-01T18:00&to=2026-10-01T23:00&location_id=<Raum-ID>
GET /api/v1/availability?from=2026-10-01&to=2026-10-03&buffer_minutes=120&include_soft_holds=false

Sin zona horaria, la fecha y la hora se interpretan en la zona horaria de tu workspace. Si añades una Z o un desfase (2026-10-01T18:00Z), el valor se toma tal cual.

La respuesta

{
  "available": false,
  "window": {
    "requested_from": "2026-10-01",
    "requested_to": "2026-10-03",
    "from": "2026-09-30T22:00:00.000Z",
    "to": "2026-10-03T22:00:00.000Z",
    "buffer_minutes": 120
  },
  "free_location_ids": ["…"],
  "locationAvailable": false,
  "conflicts": [
    {
      "type": "event_overlap",
      "location_id": "…",
      "from": "2026-10-02T15:00:00.000Z",
      "to": "2026-10-02T22:00:00.000Z",
      "confirmed": true
    },
    {
      "type": "soft_hold",
      "location_id": "…",
      "from": null,
      "to": null
    }
  ],
  "notes": ["Soft holds (open, non-archived requests) are counted per day …"]
}

• available: libre o no, teniendo en cuenta todos los espacios comprobados. Si has consultado un único espacio, también aparece locationAvailable.
• window: lo que se ha comprobado realmente. Con margen, la ventana es más amplia por ambos lados que la consultada; requested_from/requested_to muestran sin cambios lo que enviaste. Tu buffer_minutes es el que aparece ahí; el tiempo de montaje de un espacio no está incluido, sino que figura en cada conflicto, en effectiveBufferMinutes.
• free_location_ids: los espacios que están libres en la ventana.
• conflicts: lo que lo impide. type indica el motivo:

effectiveBufferMinutes aparece en un conflicto de ocupación en cuanto se ha aplicado un tiempo de montaje y limpieza a ese espacio: es el valor en minutos con el que se calculó, es decir, max(buffer_minutes, tiempo de montaje del espacio), con un máximo de 1440. Si falta, la comprobación se hizo sin margen. No aparece en el conflicto blocked_period ni en el límite de solicitudes (capacity).

• degraded: solo aparece cuando una parte de la comprobación no se ha podido leer. En ese caso la respuesta no es concluyente: no la trates como una confirmación, sino que repite la consulta.
• notes: los detalles que conviene conocer para interpretar bien la respuesta; véase más abajo.

Lo que la respuesta no es

• No es una reserva. La llamada no reserva nada. Entre la consulta y la reserva, otro proceso puede ocupar el espacio; la propia reserva vuelve a comprobarlo.
• Sin datos personales. La respuesta incluye identificadores de espacios y periodos, pero ningún nombre, contacto ni persona de contacto.
• Sin límite por página. El límite de solicitudes paralelas se configura en cada página de reservas, y una llamada a la API no tiene relación con ninguna página. Por eso no aparece en esta respuesta: si falta, no significa que sea cero.
• Sin precisión al minuto en periodos de bloqueo y solicitudes abiertas. Los periodos de bloqueo y las solicitudes abiertas se evalúan por días en la zona horaria del workspace, mientras que los eventos se evalúan al minuto. Por eso el resultado nunca es más permisivo que la página de reservas, pero puede ser más estricto. Las notes de la respuesta lo indican en cada caso concreto.

Casos de error

Una ventana vacía o una errata en la fecha nunca da como resultado «Libre»: esas peticiones se rechazan. La descripción detallada de la interfaz, con todos sus campos, está en la referencia de la API, en /api/v1/docs.