Comunidades e espaços

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 inteira do tenant)
└── 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.

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.

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

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. As seções de escrita abaixo assumem uma chave com escopo administrativo.

Controle de acesso: badge libera grupo

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

Grupo "VIP Members"  --exige-->      Badge "Premium"
Grupo "Mentores"     --exige-->      Badge "Mentor"
Grupo "Aberto"       --sem badge-->  qualquer usuário entra

O parceiro não configura essa regra (ela vive no admin), mas dispara a transição: ao atribuir um badge ao usuário, ele ganha acesso automático a todos os grupos que aceitam aquele badge. Veja Badges como permissão.

Endpoints de leitura

Mesmo sem criar estrutura, você quase sempre precisa ler grupos: para mostrar ao usuário no seu app ou para descobrir IDs antes de criar posts.

Listar grupos

GET /community/groups retorna uma lista paginada. Aceita filtros por espaço e paginação.

curl "https://apis.cativalab.digital/tenant/api/v2/community/groups?spaceId=01HQ0...&pageNumber=1" \
  -H "Authorization: Bearer cativa_live_..."

const res = await fetch(
  'https://apis.cativalab.digital/tenant/api/v2/community/groups?pageNumber=1',
  { headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` } }
);
const page = await res.json();

Resposta ilustrativa (paginada):

{
  "items": [
    {
      "id": "01HQ5ABCDEF1234567890XYZ",
      "ownerId": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
      "name": "VIP Members",
      "coverUrl": "https://cdn.cativalab.digital/groups/vip.png",
      "description": "Grupo exclusivo dos assinantes Premium.",
      "icon": "crown",
      "isPrivate": true,
      "spaceId": "01HQ0ABCDEF1234567890XYZ",
      "courseId": null,
      "onlyModeratorsCanPost": false,
      "hasFeed": true,
      "hasChat": true,
      "membersCount": 128,
      "isInGroup": false,
      "isModerator": false
    }
  ],
  "total": 12,
  "pageNumber": 1,
  "hasNextPage": true
}

Os JSON desta página são ilustrativos. O schema autoritativo campo a campo fica na aba API Reference (tag Group).

Detalhe de um grupo

GET /community/groups/{groupId} traz o grupo completo, incluindo allowedBadges (os badges que liberam entrada) e as flags do próprio usuário (isInGroup, isModerator).

curl https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5... \
  -H "Authorization: Bearer cativa_live_..."

{
  "id": "01HQ5ABCDEF1234567890XYZ",
  "name": "VIP Members",
  "description": "Grupo exclusivo dos assinantes Premium.",
  "isPrivate": true,
  "spaceId": "01HQ0ABCDEF1234567890XYZ",
  "allowedBadges": ["01HQ4ABCDEF1234567890XYZ"],
  "hasFeed": true,
  "hasChat": true,
  "membersCount": 128,
  "isInGroup": false,
  "isModerator": false
}

Listar membros

GET /community/groups/{groupId}/members retorna os membros paginados, com role, flag de moderador e data de expiração do acesso (quando houver).

curl "https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../members?pageNumber=1" \
  -H "Authorization: Bearer cativa_live_..."

{
  "items": [
    {
      "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
      "displayName": "Maria Silva",
      "pictureUrl": "https://cdn.cativalab.digital/avatars/maria.png",
      "role": 0,
      "isModerator": false,
      "expirationDate": "2026-12-31T23:59:59Z",
      "createdAt": "2026-07-10T12:00:00Z"
    }
  ],
  "total": 128,
  "pageNumber": 1,
  "hasNextPage": true
}

CRUD de grupo (escopo administrativo)

Operação	Método e rota
Criar grupo	`POST /community/groups`
Atualizar grupo	`PUT /community/groups/{groupId}`
Excluir grupo	`DELETE /community/groups/{groupId}`

Criar um grupo

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/groups \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Members",
    "description": "Grupo exclusivo dos assinantes Premium.",
    "isPrivate": true,
    "icon": "crown",
    "addNewUsers": false,
    "spaceId": "01HQ0ABCDEF1234567890XYZ",
    "onlyModeratorsCanPost": false,
    "hasFeed": true,
    "hasChat": true,
    "allowedBadges": ["01HQ4ABCDEF1234567890XYZ"]
  }'

const res = await fetch('https://apis.cativalab.digital/tenant/api/v2/community/groups', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CATIVA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'VIP Members',
    description: 'Grupo exclusivo dos assinantes Premium.',
    isPrivate: true,
    icon: 'crown',
    addNewUsers: false,
    spaceId: '01HQ0ABCDEF1234567890XYZ',
    onlyModeratorsCanPost: false,
    hasFeed: true,
    hasChat: true,
    allowedBadges: ['01HQ4ABCDEF1234567890XYZ']
  })
});
const group = await res.json();

Resposta ilustrativa (201 Created):

{
  "id": "01HQ5ABCDEF1234567890XYZ",
  "name": "VIP Members",
  "coverUrl": null,
  "description": "Grupo exclusivo dos assinantes Premium.",
  "icon": "crown",
  "isPrivate": true
}

allowedBadges no create já amarra o grupo aos badges que liberam entrada, sem precisar do painel. Combine com a atribuição de badge para automatizar acesso ponta a ponta.

Membros: entrar, sair, convidar e remover

Operação	Método e rota
Entrar	`POST /community/groups/{groupId}/join`
Sair	`POST /community/groups/{groupId}/leave`
Convidar por `userId`	`POST /community/groups/{groupId}/invite/{invitedUserId}`
Convidar por email	`POST /community/groups/{groupId}/invite/email/{email}`
Remover por `userId` (kick)	`POST /community/groups/{groupId}/kick/{kickedUserId}`
Remover por email (kick)	`POST /community/groups/{groupId}/kick/email/{email}`
Adicionar todos os usuários	`POST /community/groups/{groupId}/add/all`
Adicionar por badges permitidos	`POST /community/groups/{groupId}/add/by-allowed-badges`
Definir expiração de um membro	`PUT /community/groups/{groupId}/members/{userId}/expiration`

Entrar e sair

O join respeita o controle de acesso: se o grupo exige um badge que o usuário não tem, retorna 403.

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../join \
  -H "Authorization: Bearer cativa_live_..."

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../leave \
  -H "Authorization: Bearer cativa_live_..."

Convidar e remover

Convide por email quando você só tem o email; use userId quando já resolveu o usuário.

curl -X POST \
  "https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../invite/email/maria@exemplo.com" \
  -H "Authorization: Bearer cativa_live_..."

curl -X POST \
  "https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../invite/01HQ7..." \
  -H "Authorization: Bearer cativa_live_..."

curl -X POST \
  "https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../kick/01HQ7..." \
  -H "Authorization: Bearer cativa_live_..."

Preenchimento em massa

Para popular um grupo de uma vez, sem convidar um por um:

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../add/all \
  -H "Authorization: Bearer cativa_live_..."

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../add/by-allowed-badges \
  -H "Authorization: Bearer cativa_live_..."

add/by-allowed-badges adiciona todos os usuários que já têm algum dos allowedBadges do grupo. É a forma de “reconciliar” o grupo depois de configurar os badges.

Expiração por membro

Defina uma data em que o acesso daquele membro expira automaticamente:

curl -X PUT \
  "https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../members/01HQ7.../expiration" \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "expirationDate": "2026-12-31T23:59:59Z" }'

Criar posts e comentários

Posts ficam dentro de um Grupo. Você precisa do groupId antes: pegue pela listagem ou guarde no onboarding.

O autor do post é sempre o usuário associado à credencial autenticada. Não é necessário (nem permitido) enviar authorId no body.

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/posts \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "01HQ5ABCDEF1234567890XYZ",
    "content": "Bem-vindos ao grupo!"
  }'

const res = await fetch('https://apis.cativalab.digital/tenant/api/v2/community/posts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CATIVA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    groupId: '01HQ5ABCDEF1234567890XYZ',
    content: 'Bem-vindos ao grupo!'
  })
});
const post = await res.json();

O usuário associado à credencial precisa ter acesso ao grupo (pelo menos um badge compatível, ou pertencer ao grupo aberto). Sem acesso, retorna 403 forbidden. Para comentar, poste em POST /community/posts/{postId}/comments:

curl -X POST https://apis.cativalab.digital/tenant/api/v2/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 precisa poder ver o post.

Erros comuns

403 Forbidden ao entrar ou postar

O usuário não tem um badge que libere o grupo. Atribua o badge certo antes (veja Badges como permissão) ou confirme que o grupo é aberto.

404 Not Found no groupId

O grupo não existe naquele tenant, ou é secreto e não aparece na descoberta. Confirme o groupId na listagem.

403 nas rotas de escrita de grupo

Criar/editar/excluir grupo e adicionar em massa exigem escopo administrativo. Peça a credencial certa ao admin do tenant.

Antipattern: um grupo por cliente via API

Não modele “um grupo por cliente”. Grupos são entidades estáticas definidas pelo admin: 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.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

A hierarquia

Quem cria o quê

Controle de acesso: badge libera grupo

Endpoints de leitura

Listar grupos

Detalhe de um grupo

Listar membros

CRUD de grupo (escopo administrativo)

Criar um grupo

Membros: entrar, sair, convidar e remover

Entrar e sair

Convidar e remover

Preenchimento em massa

Expiração por membro

Criar posts e comentários

Erros comuns

Antipattern: um grupo por cliente via API

Próximos passos

Badges como permissão

Webhooks

​A hierarquia

​Quem cria o quê

​Controle de acesso: badge libera grupo

​Endpoints de leitura

​Listar grupos

​Detalhe de um grupo

​Listar membros

​CRUD de grupo (escopo administrativo)

​Criar um grupo

​Membros: entrar, sair, convidar e remover

​Entrar e sair

​Convidar e remover

​Preenchimento em massa

​Expiração por membro

​Criar posts e comentários

​Erros comuns

​Antipattern: um grupo por cliente via API

​Próximos passos

Badges como permissão

Webhooks

A hierarquia

Quem cria o quê

Controle de acesso: badge libera grupo

Endpoints de leitura

Listar grupos

Detalhe de um grupo

Listar membros

CRUD de grupo (escopo administrativo)

Criar um grupo

Membros: entrar, sair, convidar e remover

Entrar e sair

Convidar e remover

Preenchimento em massa

Expiração por membro

Criar posts e comentários

Erros comuns

Antipattern: um grupo por cliente via API

Próximos passos