Pular para o conteúdo principal

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.

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.
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.
RecursoVia API (parceiro)No painel admin
ComunidadeNãoSim (criada no provisionamento do tenant)
EspaçoTipicamente não — apenas com escopo de adminSim
GrupoTipicamente não — apenas com escopo de adminSim
PostSimSim
CommentSimSim
CursoTipicamente não — apenas com escopo de adminSim
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.

​
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 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

curl https://apis.cativalab.digital/social/v1/community/spaces \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Cativa-Customer: comunidade-do-pedro"

​
Listar grupos (filtrando por espaço)

curl "https://apis.cativalab.digital/social/v1/community/groups?spaceId=01HQ0..." \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Cativa-Customer: comunidade-do-pedro"

​
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.
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/social/v1/community/posts \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Cativa-Customer: comunidade-do-pedro" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "01HQ5ABCDEF1234567890XYZ",
    "content": "Bem-vindos ao grupo!"
  }'
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

curl -X POST https://apis.cativalab.digital/social/v1/community/posts/01HQ8.../comments \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Cativa-Customer: comunidade-do-pedro" \
  -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

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.

​
Próximos passos

Badges como permissão

Como usar badges para liberar acesso aos grupos sem criar estrutura nova.

Webhooks

Receba eventos quando posts são criados, usuários entram em grupos, etc.