> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cativa.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos

> O ciclo de vida do evento (rascunho > publicado > cancelado), o vínculo opcional a grupo ou curso e a lista de presença via API.

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.

<Note>
  `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}`.
</Note>

## 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:

```bash theme={null}
# 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

```bash theme={null}
# 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_..."
```

<Note>
  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.
</Note>

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Publicar">
    `POST /community/events/{eventId}/publish`. O evento passa a aparecer nas listagens e a aceitar confirmações de presença.
  </Step>

  <Step title="Receber confirmações">
    Os membros chamam `POST .../attend`. Acompanhe quem confirmou pela lista de `attendees`.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
    }'
  ```

  ```js Node theme={null}
  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}` }
  });
  ```
</CodeGroup>

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**:

```json theme={null}
{
  "id": "01HQ5EVENT1234567890XYZ"
}
```

<Warning>
  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.
</Warning>

## 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).

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/pt-BR/concepts/badges-as-permissions)) e repita o `attend`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Comunidades e espaços" icon="users" href="/pt-BR/concepts/communities-and-spaces">
    A hierarquia Comunidade > Espaço > Grupo onde os eventos podem ser vinculados.
  </Card>

  <Card title="Cursos e certificados" icon="graduation-cap" href="/pt-BR/concepts/courses-and-certificates">
    Como vincular um evento a um curso e à sua trilha de aulas.
  </Card>

  <Card title="Posts e comentários" icon="message-square" href="/pt-BR/concepts/posts-and-comments">
    Publique no feed do grupo para anunciar e repercutir um evento.
  </Card>
</CardGroup>