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âmetroObrigatórioSignificado
fromsimInício do período. Data (2026-10-01) ou data com hora (2026-10-01T18:00).
tosimFim do período, com a mesma notação. Uma data simples significa o dia inteiro.
location_idnãoExatamente este espaço. Se faltar, a resposta aplica-se a todos os espaços do workspace.
buffer_minutesnãoTempo 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_holdsnãoPredefiniçã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ém 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 valor apresentado; o tempo de preparação de um espaço não está incluído, mas surge em cada conflito, em effectiveBufferMinutes.
  • free_location_ids — os espaços que estão livres na janela.
  • conflicts — o que impede a disponibilidade. type indica a causa:
typeSignificado
event_overlapUm evento decorre dentro da janela. confirmed indica se já está confirmado.
schedule_item_overlapUm ponto do programa (montagem, desmontagem, entrega) ocupa o espaço.
group_cascadeOutro espaço do mesmo grupo de espaços está ocupado — o grupo é retido como um todo.
soft_holdExiste um pedido em aberto. Apenas com include_soft_holds=true.
capacityO limite de pedidos em paralelo foi atingido na janela.
blocked_periodAplica-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. As notes da resposta indicam-no em cada caso concreto.

Casos de erro

RespostaSignificado
400from/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.
401Chave inexistente ou desconhecida.
403A chave não tem a permissão Ler espaços.
429Demasiados 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.

Newsletter Univents

Novidades do produto e dicas práticas para empresas de eventos e catering. Cerca de uma vez por mês, não mais.

A newsletter é enviada em inglês.

Temas