Consultar a disponibilidade através da API
Depois de ler este artigo, é possível consultar através da API se um espaço ou todos os espaços de um workspace estão livres num intervalo de tempo — com lista de conflitos, margem de antecedência, o tempo de preparação efetivo de cada espaço e contexto sobre a ocupação.
Com a interface GET /api/v1/availability, o 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 website, a ferramenta de planeamento ou outro sistema pode dar uma confirmação sem desencadear uma reserva.
A resposta é a mesma que a página de reservas e o chat utilizam: contam todos os eventos do workspace (também rascunhos e opções; apenas não contam os cancelados, recusados e arquivados), além de pontos do programa, grupos de espaços e períodos de bloqueio. Os pedidos em aberto não retêm um espaço — mas, se pretendido, podem ser incluídos na verificação como ocupação provisória.
Chave e permissão
É necessária uma chave API com a permissão Ler espaços. Pode ser criada em Integrações → Programadores → Chaves API — a configuração está descrita no artigo sobre as chaves API. A chave deve ser enviada em cada pedido como Authorization: Bearer <Schlüssel>. Uma chave sem esta permissão recebe uma recusa, não 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=true
| Parâmetro | Obrigatório | Significado |
|---|---|---|
from | sim | Início do período. Data (2026-10-01) ou data com hora (2026-10-01T18:00). |
to | sim | Fim do período, com a mesma notação. Uma data simples significa o dia inteiro. |
location_id | não | Exatamente este espaço. Se faltar, a resposta aplica-se a todos os espaços do workspace. |
buffer_minutes | não | Tempo de antecedência e de prolongamento em minutos (montagem, desmontagem). 0 (valor predefinido) significa: o período pedido é verificado literalmente. O valor é um limite mínimo: se um espaço tiver um tempo de preparação próprio em Tempo de preparação e limpeza (minutos), para esse espaço vale o maior dos dois valores, não a soma. A resposta indica, no conflito, qual o valor que foi efetivo (ver effectiveBufferMinutes). |
include_soft_holds | não | Predefinição false: pedidos em aberto, ainda não decididos, não contam como ocupados — tal como ao submeter uma reserva. Com true, são apresentados como ocupação provisória (soft_hold). |
Sem fuso horário, a data e a hora são consideradas no fuso horário do workspace. Se for acrescentado um Z ou um desvio (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, em todos os espaços verificados. Quando é pedido um único espaço, consta tambémlocationAvailable.window— o que foi efetivamente verificado. Com margem, a janela é mais ampla de ambos os lados do que o pedido;requested_from/requested_tomostram, sem alterações, o que foi enviado. O seubuffer_minutesé o valor apresentado; o tempo de preparação de um espaço não está incluído, mas surge em cada conflito, emeffectiveBufferMinutes.free_location_ids— os espaços que estão livres na janela.conflicts— o que impede a disponibilidade.typeindica a causa:
type | Significado |
|---|---|
event_overlap | Um evento decorre dentro da janela. confirmed indica se já está confirmado. |
schedule_item_overlap | Um ponto do programa (montagem, desmontagem, entrega) ocupa o espaço. |
group_cascade | Outro espaço do mesmo grupo de espaços está ocupado — o grupo é retido como um todo. |
soft_hold | Existe um pedido em aberto. Apenas com include_soft_holds=true. |
capacity | O limite de pedidos em paralelo foi atingido na janela. |
blocked_period | Aplica-se um período de bloqueio. Aqui, location_id é null quando o bloqueio afeta todo o workspace. |
effectiveBufferMinutes consta num conflito de ocupação assim que um tempo de preparação e limpeza se tenha aplicado a esse espaço: o valor em minutos com que se calculou — max(buffer_minutes, tempo de preparação do espaço), no máximo 1440. Se não constar, a verificação foi feita sem margem. Não consta no conflito blocked_period nem no limite de pedidos (capacity).
degraded— presente apenas 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, mas sim repetir a consulta.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 em paralelo é definido por página de reservas; uma chamada à API não tem ligação a nenhuma página. Por isso, não consta desta resposta — se faltar, isso não equivale a zero.
- Sem precisão ao minuto nos períodos de bloqueio e nos pedidos provisórios. Os períodos de bloqueio e (com
include_soft_holds=true) 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. Assim, o resultado nunca é mais permissivo do que a página de reservas, mas pode ser mais restritivo. Asnotesda resposta indicam-no em cada caso concreto.
Casos de erro
| Resposta | Significado |
|---|---|
400 | from/to em falta, ilegíveis ou em ordem invertida; location_id não é um identificador válido; buffer_minutes é negativo ou superior a 1440. A resposta indica o motivo. |
401 | Chave inexistente ou desconhecida. |
403 | A chave não tem a permissão Ler espaços. |
429 | Demasiados pedidos num curto espaço de tempo. |
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.