Consultar a disponibilidade através da API

Com a interface GET /api/v1/availability, um sistema próprio consulta a Univents para saber se um período está livre: para um único espaço ou para todos os espaços de um workspace. Assim, o site, a ferramenta de planeamento ou outro sistema pode dar uma confirmação sem desencadear uma reserva.

A informação devolvida é a mesma que a página de reservas e o chat utilizam: contam os eventos ocupados, os pontos do programa, os grupos de espaços, os pedidos em aberto e os períodos de bloqueio.

Chave e permissão

É necessária uma chave de API com a permissão Ler espaços. A chave pode ser criada em Integrações → Programadores → Chaves de API — a configuração está descrita no artigo sobre as chaves de API. Deve ser enviada em cada pedido como Authorization: Bearer <Schlüssel>. Uma chave sem esta permissão é recusada, em vez de devolver um resultado vazio.

O pedido

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

Sem fuso horário, a data e a hora são interpretadas no fuso horário do workspace. Se for acrescentado um Z ou um desfasamento (2026-10-01T18:00Z), o valor é interpretado literalmente.

A resposta

{
  "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 — livre ou não, considerando todos os espaços verificados. Se tiver sido pedido um único espaço, é acrescentado locationAvailable.
• window — o que foi efetivamente verificado. Com margem, a janela é mais ampla de ambos os lados do que o pedido; requested_from/requested_to mostram, sem alterações, o que foi enviado. O seu buffer_minutes é o que aparece aqui; o tempo de preparação de um espaço não consta da janela, mas sim de cada conflito, em effectiveBufferMinutes.
• free_location_ids — os espaços que estão livres na janela.
• conflicts — o que impede a disponibilidade. type indica o motivo:

effectiveBufferMinutes surge num conflito de ocupação sempre que, para esse espaço, foi aplicado um tempo de preparação e limpeza: o valor em minutos com que foi calculado — max(buffer_minutes, tempo de preparação do espaço), no máximo 1440. Se não existir, a verificação foi feita sem margem. No conflito blocked_period e no limite de pedidos (capacity), não surge.

• degraded — só existe quando uma parte da verificação não pôde ser lida. Nesse caso, a resposta não é conclusiva: não deve ser tratada como confirmação, devendo o pedido ser repetido.
• notes — as particularidades que é preciso conhecer para ler corretamente a resposta; ver abaixo.

O que a resposta não é

• Não é uma reserva. A chamada não reserva nada. Entre a consulta e a reserva, outro processo pode ocupar o espaço — a própria reserva volta a verificar.
• Sem dados pessoais. A resposta indica identificadores de espaços e períodos, sem nomes, sem contactos, sem pessoas de contacto.
• Sem limite por página. O limite de pedidos paralelos é definido por página de reservas; uma chamada à API não tem relação com nenhuma página. Por isso, não consta desta resposta — se faltar, isso não significa zero.
• Sem precisão ao minuto nos períodos de bloqueio e nos pedidos em aberto. Os períodos de bloqueio e os pedidos em aberto são avaliados por dia no fuso horário do workspace, ao passo que os eventos são avaliados ao minuto. Por isso, o resultado nunca é mais permissivo do que a página de reservas, mas pode ser mais restritivo. As notes da resposta indicam-no em cada caso concreto.

Casos de erro

Uma janela de tempo vazia ou um erro de escrita na data nunca resulta em «Livre» — esses pedidos são rejeitados. A descrição detalhada da interface, com todos os campos, encontra-se na referência da API, em /api/v1/docs.