Mostrar eventos no próprio website (feed de eventos)

Para mostrar os eventos também no próprio website — com o design do site, e não como uma página incorporada do Univents —, é possível disponibilizar eventos individuais para esse fim. O Univents fornece-os através de um feed público e só de leitura, que o website (ou o da agência) pode obter e apresentar à sua maneira.

Mostrar um evento no website

A disponibilização faz-se diretamente no evento, e não de forma centralizada num único local:

1. Abrir o evento pretendido.
2. No cabeçalho da vista de detalhe, clicar no interruptor Mostrar no website.
3. O Univents guarda a alteração de imediato e confirma com uma breve mensagem.

Com o interruptor ativo, o evento aparece no feed em poucos minutos. Se o desativares de novo ou eliminares o evento, este desaparece do feed da mesma forma, de modo automático. O interruptor atua apenas nesse evento — não existe uma disponibilização em massa para todos os eventos de uma só vez.

O que consta no feed

O feed fornece exclusivamente dados pensados para a apresentação pública num calendário: título, descrição, hora de início e de fim, se a data já é definitiva, local do evento, imagem de capa, etiquetas, uma ligação para a venda de bilhetes (se o evento tiver uma página de bilhetes publicada – em rascunho, faltam a ligação para os bilhetes e o preço), bem como o preço de bilhete mais baixo ainda disponível e um aviso de Esgotado. Dados internos como orçamento interno, número de convidados, notas, dados de contacto, estado ou dados financeiros nunca constam no feed, independentemente de o evento estar publicado ou não. Também as quantidades disponíveis, os nomes das categorias e os números de vendas ficam apenas no sistema — para o exterior seguem só o preço e a informação «Esgotado sim/não».

Preço «a partir de» e Esgotado

Se vendes bilhetes através do Univents, o feed fornece dois dados adicionais, a partir dos quais o website pode compor um «a partir de 25 €» e um «Esgotado»:

• price_from — o preço de bilhete mais baixo que um visitante ainda pode comprar neste momento, como valor com IVA (ou seja, o que aparece na categoria na loja de bilhetes). Se a categoria mais barata estiver esgotada, passa automaticamente a valer a seguinte, mais cara. Assim, o website nunca promete um preço que já não existe na loja.
• price_from_currency — a moeda do teu Workspace, em código abreviado, p. ex. EUR ou CHF.
• tickets_sold_out — true assim que nenhuma categoria de bilhetes puder ser comprada. Enquanto alguma categoria ainda tiver bilhetes, o valor mantém-se false, mesmo que algumas categorias já estejam completas.

Se tudo estiver esgotado, price_from fica vazio (null) — um preço «a partir de» ao lado de «Esgotado» convidaria a uma compra que não existe. Um evento sem venda de bilhetes devolve price_from: null e tickets_sold_out: false: não vende nada, pelo que também não está esgotado.

Se um bilhete for anulado, o lugar fica de novo livre de imediato — a categoria volta a poder ser comprada e volta a entrar no preço «a partir de». Como o feed é guardado brevemente em cache, um evento que acabou de esgotar pode ainda aparecer como disponível no website durante alguns minutos.

Imagem e descrição: do evento, não da página de bilhetes

Para o calendário do website contam a imagem e a descrição do próprio evento — ou seja, o que é mantido no evento em Apresentação. A imagem e a descrição de uma página de reservas ou de bilhetes pertencem a essa página e não passam automaticamente para o calendário do website. Ambas as coisas são intencionais: muitos negócios mostram, de propósito, um motivo diferente na loja de bilhetes e no calendário do próprio website.

Para ter ambas iguais, é preciso indicá-lo uma vez:

1. Abrir a página de reservas ou de bilhetes e, nela, a secção Detalhes.
2. Abaixo da imagem e da descrição encontram-se a indicação e o botão Aplicar também ao calendário do site.
3. Confirmar a pergunta de confirmação. A imagem e a descrição da página são então transferidas para o evento associado; os dados que lá estavam guardados até então são substituídos.

O botão só aparece se a página estiver associada a um evento (nas páginas de bilhetes, isso acontece sempre). É aplicada a última versão guardada da página, e os campos que estejam vazios na página permanecem inalterados no evento — por isso, uma página vazia nunca elimina uma imagem. Até a alteração chegar ao calendário do website, podem passar alguns minutos, porque o feed é guardado brevemente em cache.

O tamanho com que a imagem é apresentada é definido pelo website — o Univents fornece a imagem no tamanho original.

Obter o feed

O feed é público e pode ser obtido sem início de sessão nem chave de API — um website ou uma ferramenta externa pode carregá-lo diretamente com fetch:

GET https://univents.app/api/public/dein-workspace/events
GET https://univents.app/api/public/dein-workspace/events/{eventId}

dein-workspace é o slug do Workspace, que também se encontra na barra de endereço do computador, a seguir a /home/. Com os parâmetros from e to delimita-se o período e, com limit, o número de resultados (por defeito 50, no máximo 100). O limit está agrupado em três níveis — 25, 50 ou 100 —, para que a cache funcione com poucas respostas: um valor pedido é sempre arredondado para o nível imediatamente superior, p. ex. ?limit=10 devolve 25 entradas, tal como ?limit=25, e tudo o que exceda 100 é limitado a 100. Sem indicação, o feed devolve todos os eventos disponibilizados a partir de hoje.

Um exemplo de resposta tem este aspeto:

{
  "workspace": "dein-workspace",
  "count": 2,
  "events": [
    {
      "id": "…",
      "title": "Sommerkonzert",
      "description": "…",
      "start": "2026-08-20T18:00:00Z",
      "end": "2026-08-20T23:00:00Z",
      "date_is_confirmed": true,
      "venue": "Großer Saal",
      "image_url": "https://…",
      "tags": ["Konzert"],
      "ticket_url": "https://univents.app/book/dein-workspace/deine-seite",
      "price_from": 25,
      "price_from_currency": "EUR",
      "tickets_sold_out": false,
      "updated_at": "2026-08-05T09:00:00Z"
    }
  ]
}

Para programadores e agências

O feed foi concebido de propósito para se integrar diretamente num website existente, sem gerir credenciais:

• Sem autenticação, sem chave de API — a rota é de acesso público, mas devolve exclusivamente eventos do respetivo Workspace que tenham o interruptor ativo.
• O CORS está aberto, pelo que um pedido com fetch funciona diretamente a partir do navegador de qualquer website.
• Em cache — as respostas podem ser guardadas em cache por pouco tempo (alguns minutos), para que os acessos frequentes continuem rápidos. Por isso, um evento acabado de disponibilizar não aparece de imediato, mas sim em poucos minutos.
• Com limite de pedidos — perante um número muito elevado de pedidos num curto espaço de tempo a partir da mesma origem, a rota responde com um erro em vez de dados vazios; para uma utilização normal de um website, isto não é relevante.
• Um slug de Workspace desconhecido devolve um erro, e não uma lista vazia — assim, nota-se logo quando o slug está errado.

Perguntas frequentes

Aparecem no feed também espaços que estão apenas ocupados, mas não publicados? Não. O feed mostra exclusivamente eventos em que o interruptor Mostrar no website foi ativado — nunca a ocupação geral dos espaços.

O feed contém preços? Sim, um: o preço de bilhete mais baixo ainda disponível (price_from, com IVA), juntamente com a moeda. A lista de preços completa continua a estar apenas na página de reservas para a qual ticket_url aponta.

Porque é que o meu website mostra um preço mais alto do que ontem? Porque, entretanto, a categoria mais barata esgotou. O feed indica sempre o preço mais baixo que ainda se pode comprar — e não o mais baixo que alguma vez existiu.

Porque é que, num evento sem bilhetes, não aparece «Esgotado»? Porque não vende bilhetes. tickets_sold_out só é true quando existe venda de bilhetes e já não há nada disponível.

É preciso disponibilizar cada evento individualmente? Sim, atualmente não existe disponibilização em massa. O interruptor está de propósito em cada evento, individualmente, para haver controlo total sobre o que fica visível publicamente.

A funcionalidade está associada a um plano específico? O feed mostra exclusivamente o que for disponibilizado — não existem requisitos adicionais além da permissão normal para eventos.

A consulta do feed tem algum custo? Não, o feed é um simples acesso de leitura a dados já disponibilizados — não há custos adicionais.