Eventos

Eventos são encontros com data marcada dentro da comunidade (uma live, uma aula ao vivo, um webinar, um encontro presencial). Pela API pública você lista eventos, lê os detalhes de um evento, confirma ou desmarca a presença de um usuário e, com escopo administrativo, cria e gerencia o ciclo de vida completo. Pense num evento como um convite de festa: primeiro você redige o convite sem mandar (rascunho), depois distribui (publica) e as pessoas confirmam presença (attend); se a festa não vai mais acontecer, você avisa quem confirmou em vez de fingir que o convite nunca existiu (cancela, não apaga).

O ciclo de vida

Todo evento passa por três estados. A transição é sempre para frente (não dá para “despublicar” um evento; para tirá-lo do ar, cancele).

Rascunho ──publish──> Publicado ──cancel──> Cancelado
 (draft)              (visível na           (visível como
                       comunidade)           cancelado)

Rascunho: criado por POST /community/events. Fica invisível para os membros; serve para você montar título, descrição, data e vínculos antes de anunciar.
Publicado: após POST /community/events/{eventId}/publish. Aparece nas listagens públicas e passa a aceitar confirmações de presença.
Cancelado: após POST /community/events/{eventId}/cancel. Continua visível (marcado como cancelado) para que quem confirmou presença saiba que não vai mais acontecer.

publish e cancel são transições de estado, não edições. Para mudar título, data ou descrição de um evento já criado, use PUT /community/events/{eventId}. Para remover o registro por completo (em vez de cancelar), use DELETE /community/events/{eventId}.

Vínculo opcional a grupo ou curso

Um evento pode ser avulso (aparece na agenda geral da comunidade) ou vinculado a um grupo ou a um curso. O vínculo é opcional e serve para dar contexto (o evento de um grupo aparece dentro daquele grupo; o de um curso aparece na trilha do curso).

Evento avulso        ──> agenda geral da comunidade
Evento de grupo      ──> aparece no grupo (groupId)
Evento de curso      ──> aparece no curso (courseId)

Para descobrir os eventos de um grupo ou de um curso específico, use os endpoints de filtro:

# eventos de um grupo
curl https://apis.cativalab.digital/tenant/api/v2/community/events/by-group/01HQ0ABCDEF1234567890XYZ \
  -H "Authorization: Bearer cativa_live_..."

# eventos de um curso
curl https://apis.cativalab.digital/tenant/api/v2/community/events/by-course/01HQ0COURSE1234567890XYZ \
  -H "Authorization: Bearer cativa_live_..."

Endpoints de leitura

# listar eventos da comunidade
curl https://apis.cativalab.digital/tenant/api/v2/community/events \
  -H "Authorization: Bearer cativa_live_..."

# detalhe de um evento
curl https://apis.cativalab.digital/tenant/api/v2/community/events/01HQ5EVENT1234567890XYZ \
  -H "Authorization: Bearer cativa_live_..."

# lista de presença (attendees) do evento
curl https://apis.cativalab.digital/tenant/api/v2/community/events/01HQ5EVENT1234567890XYZ/attendees \
  -H "Authorization: Bearer cativa_live_..."

Não documentamos aqui os nomes dos campos de cada response (eles evoluem). Consulte a aba API Reference, sob a tag Event, para o schema exato de cada retorno.

Criar um evento (escopo admin)

Criar, editar, publicar, cancelar e excluir eventos exige escopo administrativo (organizador). Chaves de parceiro com escopo padrão conseguem ler eventos e confirmar presença, mas não criam nem alteram o ciclo de vida. Use uma chave com permissão de admin/organizador para os endpoints de escrita. O evento nasce como rascunho. Publique num segundo passo, quando estiver pronto para anunciar.

Criar o rascunho

POST /community/events com título, datas e (opcional) groupId ou courseId. A resposta traz o id do evento. Ele nasce invisível para os membros.

Publicar

POST /community/events/{eventId}/publish. O evento passa a aparecer nas listagens e a aceitar confirmações de presença.

Receber confirmações

Os membros chamam POST .../attend. Acompanhe quem confirmou pela lista de attendees.

Cancelar se necessário

POST /community/events/{eventId}/cancel mantém o evento visível como cancelado para quem já tinha confirmado. Para sumir com o registro por completo, use DELETE.

# cria o evento em RASCUNHO; groupId e courseId são opcionais (vínculo)
curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/events \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Live de abertura",
    "description": "Kickoff da turma de julho.",
    "startsAt": "2026-08-01T19:00:00Z",
    "endsAt": "2026-08-01T20:30:00Z",
    "groupId": "01HQ5GROUP1234567890XYZ"
  }'

const res = await fetch('https://apis.cativalab.digital/tenant/api/v2/community/events', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`, // chave com escopo admin/organizador
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Live de abertura',
    description: 'Kickoff da turma de julho.',
    startsAt: '2026-08-01T19:00:00Z',
    endsAt: '2026-08-01T20:30:00Z',
    groupId: '01HQ5GROUP1234567890XYZ' // opcional; omita para evento avulso
  })
});
const event = await res.json();

// segundo passo: publicar quando estiver pronto
await fetch(`https://apis.cativalab.digital/tenant/api/v2/community/events/${event.id}/publish`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

A criação devolve o identificador do evento (use-o nos passos de publish, cancel e attend). Schema completo na aba API Reference, tag Event:

{
  "id": "01HQ5EVENT1234567890XYZ"
}

Sem escopo administrativo, os endpoints de escrita (criar, editar, publicar, cancelar, excluir) retornam 403 forbidden. Isso é esperado: peça ao admin do tenant uma chave de organizador, ou deixe a criação de eventos no painel.

Confirmar presença (attend)

Qualquer usuário com acesso ao evento confirma presença com POST .../attend e desmarca com DELETE .../attend. A presença é sempre do usuário associado à credencial autenticada (não se envia userId no body).

# confirmar presença
curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/events/01HQ5EVENT1234567890XYZ/attend \
  -H "Authorization: Bearer cativa_live_..."

# desmarcar presença
curl -X DELETE https://apis.cativalab.digital/tenant/api/v2/community/events/01HQ5EVENT1234567890XYZ/attend \
  -H "Authorization: Bearer cativa_live_..."

O evento precisa estar publicado e o usuário precisa ter acesso à comunidade (e ao grupo, se o evento for vinculado a um grupo que exige badge). Sem acesso, retorna 403 forbidden. Depois de confirmada, a presença aparece na lista de attendees do evento.

Erros comuns e dúvidas

Criei o evento mas ninguém o vê

Ele provavelmente ainda está em rascunho. Rascunho é invisível para os membros de propósito. Chame POST /community/events/{eventId}/publish para colocá-lo no ar. Só depois de publicado ele aparece nas listagens e aceita confirmações.

Como despublico um evento?

Não existe “despublicar”. A transição é sempre para frente (rascunho, publicado, cancelado). Para tirar do ar um evento já anunciado, use cancel: ele continua visível marcado como cancelado, para que quem confirmou saiba que não vai mais acontecer. DELETE apaga o registro por completo (sem aviso a quem confirmou).

403 forbidden ao criar ou publicar

Escrita (criar, editar, publicar, cancelar, excluir) exige escopo administrativo (organizador). Uma chave de parceiro padrão só lê eventos e confirma presença. Peça ao admin do tenant uma chave de organizador, ou deixe a criação no painel.

403 forbidden ao confirmar presença num evento que eu vejo na listagem

Enxergar na listagem não é o mesmo que ter acesso ao evento. Se o evento é vinculado a um grupo que exige badge, o usuário precisa do badge para confirmar. Atribua o badge (veja Badges como permissão) e repita o attend.

Confirmei presença duas vezes, dá problema?

Não. Confirmar de novo é seguro: a presença é do usuário da credencial e não duplica. DELETE .../attend desmarca; desmarcar algo que não estava marcado não dá erro. Trate o par attend/unattend como idempotente.

Próximos passos

Comunidades e espaços

A hierarquia Comunidade > Espaço > Grupo onde os eventos podem ser vinculados.

Cursos e certificados

Como vincular um evento a um curso e à sua trilha de aulas.

Posts e comentários

Publique no feed do grupo para anunciar e repercutir um evento.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

O ciclo de vida

Vínculo opcional a grupo ou curso

Endpoints de leitura

Criar um evento (escopo admin)

Confirmar presença (attend)

Erros comuns e dúvidas

Próximos passos

Comunidades e espaços

Cursos e certificados

Posts e comentários

​O ciclo de vida

​Vínculo opcional a grupo ou curso

​Endpoints de leitura

​Criar um evento (escopo admin)

​Confirmar presença (attend)

​Erros comuns e dúvidas

​Próximos passos

Comunidades e espaços

Cursos e certificados

Posts e comentários

O ciclo de vida

Vínculo opcional a grupo ou curso

Endpoints de leitura

Criar um evento (escopo admin)

Confirmar presença (attend)

Erros comuns e dúvidas

Próximos passos