📚Grupos

Grupos são os cursos, conteúdos e comunidades da plataforma. Pela API pública é possível listar, criar e editar grupos; os módulos e as aulas de cada grupo têm rotas próprias.

Todos os endpoints exigem:

Authorization: Bearer {token}

Accept: application/json

Recursos do plano necessários:

Rota	Recurso do plano
`GET /groups`	Public API – List Groups
`POST /groups`	Public API – Create Group
`POST /groups/{id}`	Public API – Update Group

Campos de um grupo

Toda rota de grupos devolve o grupo neste formato:

Campo	Tipo	Descrição
`id`	integer	Identificador do grupo. É ele que identifica o grupo na edição e nas rotas de módulos e aulas.
`title`	string	Título do grupo.
`slug`	string	Endereço amigável do grupo, gerado a partir do título na criação.
`description`	string \| null	Descrição do conteúdo. Aceita HTML.
`subscription_method`	string \| null	Formato de ingresso (ver tabela abaixo).
`visibility`	string	Visibilidade do grupo (ver tabela abaixo).
`logo_vertical`	string \| null	URL da capa vertical.
`logo_horizontal`	string \| null	URL da capa horizontal.

Formato de ingresso (`subscription_method`)

Valor	Na plataforma	Comportamento
`free_access`	Aberto	Qualquer usuário entra no grupo sem aprovação.
`request_access`	Restrito	O usuário pede para entrar e um administrador aprova.
`paid_access`	Pago	O acesso vem da compra de uma oferta.

Visibilidade (`visibility`)

Valor	No painel	Comportamento
`public`	Público	O grupo aparece na vitrine, na busca e nas trilhas. Padrão na criação.
`restricted`	Restrito	O grupo não aparece na vitrine, na busca nem nas trilhas; quem já é membro continua vendo o grupo nos seus conteúdos.
`inactive`	Inativo	O grupo deixa de aparecer também para os membros, nos seus conteúdos, no perfil e no feed.

Capas (`logo_vertical` e `logo_horizontal`)

Cada capa pode ser enviada de dois jeitos:

Arquivo: a requisição vai como multipart/form-data e o campo leva o arquivo. Formatos aceitos: jpeg, png e webp.
Link: a requisição pode ir como application/json e o campo leva a URL http(s) da imagem. A plataforma baixa a imagem e guarda uma cópia; o link enviado não é usado depois. Se a imagem não puder ser baixada, ou se não for jpeg, png ou webp, a requisição é recusada com 422 e nada é alterado.

Nas respostas, as capas vêm sempre como a URL da cópia guardada na plataforma.

📖 Listar grupos

GET /groups

Lista os grupos da plataforma em ordem de criação, com paginação. Grupos arquivados não aparecem.

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`page`	integer	❌	`1`	Número da página.
`per_page`	integer	❌	`15`	Itens por página (mínimo 1).

200

{
  "data": [
    {
      "id": 12,
      "title": "Curso Completo de Marketing",
      "slug": "curso-completo-de-marketing",
      "description": "<p>Do zero à prática: branding, mídia paga e funil.</p>",
      "subscription_method": "paid_access",
      "visibility": "public",
      "logo_vertical": "https://cdn.ensinio.com/sua-plataforma/group/logo/3f1c9a.png",
      "logo_horizontal": null
    }
  ],
  "links": {
    "first": "https://sua-plataforma.ensinio.cloud/public/api/v1/groups?page=1",
    "last": "https://sua-plataforma.ensinio.cloud/public/api/v1/groups?page=10",
    "prev": null,
    "next": "https://sua-plataforma.ensinio.cloud/public/api/v1/groups?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "path": "https://sua-plataforma.ensinio.cloud/public/api/v1/groups",
    "per_page": 15,
    "to": 15,
    "total": 150
  }
}

➕ Criar grupo

POST /groups

Campos

Campo	Tipo	Obrigatório	Descrição
`title`	string	✅	Título do grupo (até 256 caracteres).
`subscription_method`	string	✅	`free_access`, `request_access` ou `paid_access`.
`description`	string	❌	Descrição do conteúdo. Aceita HTML.
`visibility`	string	❌	`public`, `restricted` ou `inactive`. Padrão: `public`.
`logo_vertical`	arquivo ou URL	❌	Capa vertical.
`logo_horizontal`	arquivo ou URL	❌	Capa horizontal.

Body (JSON, capa por link)

{
  "title": "Curso Completo de Marketing",
  "subscription_method": "paid_access",
  "description": "<p>Do zero à prática: branding, mídia paga e funil.</p>",
  "logo_horizontal": "https://meu-site.com/imagens/capa-marketing.png"
}

201: devolve o grupo criado, no formato da listagem, dentro de data. Guarde o id para editar o grupo e cadastrar módulos e aulas.

O que a plataforma faz ao criar o grupo:

O grupo nasce com as mesmas configurações de um grupo criado no painel: página inicial de aulas, mural desligado, conteúdo e lista de membros privados e grupo encontrável na busca.
O autor do grupo é o usuário Master da plataforma. Ninguém é inscrito no grupo nem vira moderador.
O slug é gerado a partir do título; se já existir, recebe um número no fim.
Se o plano tem limite de grupos e ele já foi atingido, a criação é recusada com 422.

✏️ Editar grupo

POST /groups/{id}

A edição usa POST, e não PATCH, para aceitar o envio de capas como arquivo: requisições multipart/form-data só são lidas em POST.

Envie só os campos que quer alterar; os demais ficam como estão. Os campos são os mesmos da criação, todos opcionais:

Campo	Tipo	Descrição
`title`	string	Título do grupo (até 256 caracteres). Não pode ser vazio.
`subscription_method`	string	`free_access`, `request_access` ou `paid_access`.
`description`	string \| null	Descrição do conteúdo. `null` apaga a descrição.
`visibility`	string	`public`, `restricted` ou `inactive`.
`logo_vertical`	arquivo, URL ou null	Nova capa vertical. `null` remove a capa atual.
`logo_horizontal`	arquivo, URL ou null	Nova capa horizontal. `null` remove a capa atual.

Body

{
  "title": "Curso Completo de Marketing Digital",
  "visibility": "restricted"
}

200: devolve o grupo atualizado dentro de data.

Mudar o título não muda o slug do grupo.
Mudar o formato de ingresso não altera as outras regras de privacidade do grupo, como a visibilidade do conteúdo e da lista de membros.
Ao trocar ou remover uma capa, o arquivo anterior é apagado.

Respostas de erro

Status	Quando
`401`	Token ausente ou inválido.
`403`	Recurso não habilitado no plano.
`404`	Grupo não encontrado (edição). Grupos arquivados também respondem `404`.
`422`	Campo inválido, capa que não pôde ser baixada ou não é imagem, ou limite de grupos do plano atingido. Os erros de campo vêm em `errors`, por campo.
`429`	Limite de requisições excedido.

422

{
  "message": "The given data was invalid.",
  "errors": {
    "subscription_method": ["The selected subscription method is invalid."]
  }
}