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

# Comunidades e espaços

> A hierarquia Comunidade > Espaço > Grupo > Post/Curso e o que parceiros podem criar via API.

A Cativa organiza conteúdo numa hierarquia de quatro níveis. Entender essa hierarquia é essencial para saber **qual endpoint chamar** e **o que pode ser criado por API** versus o que é configurado pelo admin no painel.

## A hierarquia

```
Comunidade (a plataforma do tenant inteira)
└── Espaço (área temática, ex: "Trading", "Mentoria")
    └── Grupo (sub-comunidade dentro do espaço)
        ├── Post (publicação no feed)
        ├── Comment (comentário no post)
        └── Curso (sequência de aulas, opcional)
```

Cada tenant tem **uma única Comunidade** (o "site" inteiro do cliente). Dentro dela, o admin cria múltiplos **Espaços**, cada um com seus próprios **Grupos**. Os Grupos contêm **Posts**, **Comentários** e, opcionalmente, **Cursos**.

<Note>
  A diferença entre Espaço e Grupo é fácil de lembrar: **Espaço** é a divisão temática que aparece na navegação principal; **Grupo** é onde a conversa acontece e onde as permissões via badge são aplicadas.
</Note>

## Quem cria o quê

A regra geral: **estrutura é tarefa do admin, conteúdo é tarefa do parceiro**.

| Recurso    | Via API (parceiro)                           | No painel admin                           |
| ---------- | -------------------------------------------- | ----------------------------------------- |
| Comunidade | Não                                          | Sim (criada no provisionamento do tenant) |
| Espaço     | Tipicamente não — apenas com escopo de admin | Sim                                       |
| Grupo      | Tipicamente não — apenas com escopo de admin | Sim                                       |
| Post       | **Sim**                                      | Sim                                       |
| Comment    | **Sim**                                      | Sim                                       |
| Curso      | Tipicamente não — apenas com escopo de admin | Sim                                       |

<Warning>
  Endpoints de criação de Espaço, Grupo e Curso existem mas exigem **escopo administrativo**. Chaves de parceiro com escopo padrão (recomendado) não enxergam essa categoria. Peça ao admin do tenant para criar a estrutura no painel — esse é o fluxo natural.
</Warning>

## Controle de acesso: badge libera grupo

Cada **Grupo** pode exigir um ou mais **badges** para que o usuário entre. Isso é configurado no painel administrativo, na tela de acesso de cada grupo:

```
Grupo "VIP Members"  ──exige──> Badge "Premium"
Grupo "Mentores"     ──exige──> Badge "Mentor"
Grupo "Aberto"       ──não exige badge──> qualquer usuário entra
```

O parceiro **não configura** essa regra — ela vive no admin. Mas o parceiro **dispara** a transição: ao atribuir um badge ao usuário, ele ganha automaticamente acesso a todos os grupos que aceitam aquele badge.

Veja [Badges como permissão](/pt-BR/concepts/badges-as-permissions) para a explicação completa.

## Endpoints de leitura

Mesmo sem poder **criar** estrutura, você quase sempre vai precisar **ler** Espaços e Grupos para mostrar ao usuário no seu app, ou para descobrir IDs antes de criar Posts.

### Listar espaços

```bash theme={null}
curl https://apis.cativalab.digital/tenant/v1/community/spaces \
  -H "Authorization: Bearer cativa_live_..."
```

### Listar grupos (filtrando por espaço)

```bash theme={null}
curl "https://apis.cativalab.digital/tenant/v1/community/groups?spaceId=01HQ0..." \
  -H "Authorization: Bearer cativa_live_..."
```

## Criando posts

Posts ficam dentro de um Grupo. Você precisa do `groupId` antes de chamar — busque-o pela listagem acima ou guarde-o no onboarding.

<Note>
  O autor do post é sempre o usuário associado à credencial autenticada — não é necessário (nem permitido) enviar `authorId` no body.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://apis.cativalab.digital/tenant/v1/community/posts \
    -H "Authorization: Bearer cativa_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "groupId": "01HQ5ABCDEF1234567890XYZ",
      "content": "Bem-vindos ao grupo!"
    }'
  ```

  ```js Node theme={null}
  const res = await fetch('https://apis.cativalab.digital/tenant/v1/community/posts', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      groupId: '01HQ5ABCDEF1234567890XYZ',
      content: 'Bem-vindos ao grupo!'
    })
  });
  const post = await res.json();
  ```
</CodeGroup>

O usuário associado à credencial precisa ter **acesso** ao grupo (pelo menos um badge compatível, ou pertencer ao grupo "Aberto"). Se não tiver, retorna `403 forbidden`.

## Criando comentários

```bash theme={null}
curl -X POST https://apis.cativalab.digital/tenant/v1/community/posts/01HQ8.../comments \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Adorei o post!"
  }'
```

Mesma regra de acesso: o usuário associado à credencial precisa ter permissão para ver o post.

## Antipattern: criar grupos por API a cada cliente que entra

<Warning>
  Não modele "um grupo por cliente". Grupos são entidades **estáticas** definidas pelo admin do tenant — eles representam comunidades de discussão, não containers efêmeros. Para personalizar acesso por cliente, **use badges**: crie um único grupo "VIP Members" e atribua o badge `Premium` aos clientes certos.
</Warning>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Badges como permissão" icon="shield-check" href="/pt-BR/concepts/badges-as-permissions">
    Como usar badges para liberar acesso aos grupos sem criar estrutura nova.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pt-BR/concepts/webhooks">
    Receba eventos quando posts são criados, usuários entram em grupos, etc.
  </Card>
</CardGroup>