Consultar la disponibilidad a través de la API

Tras leer este artículo podrás consultar a través de la API si una sala o todas las salas de un workspace están libres en un intervalo de tiempo, con lista de conflictos, margen previo, el tiempo de montaje efectivo de cada sala y contexto sobre la ocupación.

Con la interfaz GET /api/v1/availability, tu propio sistema consulta a Univents si un periodo está libre: para una sola sala o para todas las salas de un workspace. Así, tu sitio web, tu herramienta de planificación u otro sistema pueden dar una confirmación sin generar una reserva.

La respuesta es la misma que utilizan la página de reservas y el chat: cuentan todos los eventos de tu workspace (también los borradores y las opciones; solo quedan fuera los cancelados, rechazados y archivados), además de los puntos del programa, los grupos de salas y los periodos de bloqueo. Las solicitudes abiertas no retienen una sala, pero, si quieres, puedes incluirlas en la comprobación como ocupación provisional.

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 solicitud como Authorization: Bearer <Schlüssel>. Una clave sin este permiso recibe un rechazo, no un resultado vacío.

La solicitud

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=true
ParámetroObligatorioSignificado
fromsíInicio del periodo. Fecha (2026-10-01) o fecha con hora (2026-10-01T18:00).
tosíFin del periodo, con la misma notación. Una fecha sin hora significa el día completo.
location_idnoExactamente esta sala. Si falta, la respuesta se refiere a todas las salas del workspace.
buffer_minutesnoMargen previo y posterior en minutos (montaje, desmontaje). 0 (valor por defecto) significa que el periodo solicitado se comprueba al pie de la letra. El valor es un mínimo: si una sala tiene un tiempo de montaje propio en Tiempo de montaje y limpieza (minutos), para esa sala se aplica el mayor de los dos valores, no la suma. La respuesta indica en cada conflicto qué valor se aplicó (consulta effectiveBufferMinutes).
include_soft_holdsnoValor por defecto false: las solicitudes abiertas que aún no se han resuelto no cuentan como ocupadas, igual que al enviar una reserva. Con true las ves como ocupación provisional (soft_hold).

Si no indicas 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 al pie de la letra.

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, considerando todas las salas comprobadas. Si solicitas una sola sala, aparece además locationAvailable.
  • window: lo que se comprobó realmente. Con margen, el intervalo es más amplio por ambos lados que el solicitado; requested_from/requested_to muestran sin cambios lo que enviaste. Se muestra tu buffer_minutes; el tiempo de montaje de una sala no está incluido ahí, sino en cada conflicto, en effectiveBufferMinutes.
  • free_location_ids: las salas que están libres en el intervalo.
  • conflicts: lo que lo impide. type indica el motivo:
typeSignificado
event_overlapHay un evento dentro del intervalo. confirmed indica si ya está confirmado.
schedule_item_overlapUn punto del programa (montaje, desmontaje, entrega) ocupa la sala.
group_cascadeOtra sala del mismo grupo de salas está ocupada; el grupo se retiene como un todo.
soft_holdHay una solicitud abierta. Solo con include_soft_holds=true.
capacitySe ha alcanzado en el intervalo el límite de solicitudes paralelas.
blocked_periodSe aplica un periodo de bloqueo. location_id es aquí null si el bloqueo afecta a todo el workspace.

effectiveBufferMinutes aparece en un conflicto de ocupación en cuanto se aplicó un tiempo de montaje y limpieza para esa sala: es el valor en minutos con el que se calculó, max(buffer_minutes, tiempo de montaje de la sala), como máximo 1440. Si no aparece, la comprobación se hizo sin margen. No aparece en el conflicto blocked_period ni en el límite de solicitudes (capacity).

  • degraded: solo está presente si una parte de la comprobación no se pudo leer. En ese caso la respuesta no es concluyente: no la trates como una confirmación, vuelve a consultar.
  • notes: los matices que conviene conocer para interpretar bien la respuesta; consulta 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 la sala; la propia reserva vuelve a comprobarlo.
  • Sin datos personales. La respuesta indica identificadores de sala 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 página asociada. 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 provisionales. Los periodos de bloqueo y (con include_soft_holds=true) 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

RespuestaSignificado
400Faltan from/to, no se pueden leer o están invertidos; location_id no es un identificador válido; buffer_minutes es negativo o mayor que 1440. La respuesta indica el motivo.
401No hay clave o la clave es desconocida.
403La clave no tiene el permiso Leer espacios.
429Demasiadas solicitudes en poco tiempo.

Un intervalo vacío o una errata en la fecha nunca da como resultado «Libre»: esas solicitudes se rechazan. La descripción completa de la interfaz, con todos los campos, la encuentras en la referencia de la API, en /api/v1/docs.

Newsletter de Univents

Novedades del producto y consejos prácticos para empresas de eventos y catering. Aproximadamente una vez al mes, no más.

La newsletter se envía en inglés.

Temas