🗂️Módulos

Módulos organizam as aulas de um grupo. Cada módulo pertence a um grupo e cada aula pertence a um módulo. Pela API pública é possível listar os módulos de um grupo, criar, editar e excluir módulos.

Todos os endpoints exigem:

Authorization: Bearer {token}

Accept: application/json

Recursos do plano necessários:

Rota	Recurso do plano
`GET /modules`	Public API – List Modules
`POST /modules`	Public API – Create Module
`POST /modules/{id}`	Public API – Update Module
`DELETE /modules/{id}`	Public API – Delete Module

Campos de um módulo

Toda rota de módulos devolve o módulo neste formato:

Campo	Tipo	Descrição
`id`	integer	Identificador do módulo. É ele que identifica o módulo na edição e na criação de aulas.
`group_id`	integer	Grupo ao qual o módulo pertence.
`title`	string	Título do módulo.
`active`	boolean	Status do módulo: `true` ativo, `false` inativo.
`position`	integer	Posição do módulo no grupo; a ordem dos alunos é a crescente.
`cover_image`	string \| null	URL da capa do módulo.

Capa (`cover_image`)

A 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, a capa vem sempre como a URL da cópia guardada na plataforma.

📖 Listar módulos de um grupo

GET /modules?group_id={id}

Lista os módulos do grupo na ordem em que os alunos os veem, com paginação. Módulos inativos também são listados.

Parâmetros de query

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

200

{
  "data": [
    {
      "id": 31,
      "group_id": 12,
      "title": "Introdução",
      "active": true,
      "position": 0,
      "cover_image": "https://cdn.ensinio.com/sua-plataforma/group-topic/cover/8d2e41.png"
    },
    {
      "id": 32,
      "group_id": 12,
      "title": "Mídia paga",
      "active": false,
      "position": 1,
      "cover_image": null
    }
  ],
  "links": {
    "first": "https://sua-plataforma.ensinio.cloud/public/api/v1/modules?group_id=12&page=1",
    "last": "https://sua-plataforma.ensinio.cloud/public/api/v1/modules?group_id=12&page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://sua-plataforma.ensinio.cloud/public/api/v1/modules",
    "per_page": 15,
    "to": 2,
    "total": 2
  }
}

➕ Criar módulo

POST /modules

Campos

Campo	Tipo	Obrigatório	Descrição
`group_id`	integer	✅	Grupo ao qual o módulo será vinculado.
`title`	string	✅	Título do módulo (até 256 caracteres).
`active`	boolean	❌	Status do módulo. Padrão: `true` (ativo).
`cover_image`	arquivo ou URL	❌	Capa do módulo.

Body (JSON, capa por link)

{
  "group_id": 12,
  "title": "Introdução",
  "cover_image": "https://meu-site.com/imagens/capa-introducao.png"
}

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

📌
Orientações

Se o active não for enviado, o módulo é criado ativo.

O módulo novo é sempre adicionado por último no grupo. A posição não pode ser escolhida pela API.

O grupo precisa existir e não pode estar arquivado; caso contrário, a resposta é 422.

✏️ Editar módulo

POST /modules/{id}

A edição usa POST, e não PATCH, para aceitar o envio da capa 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.

Campo	Tipo	Descrição
`title`	string	Título do módulo (até 256 caracteres). Não pode ser vazio.
`active`	boolean	Status do módulo.
`cover_image`	arquivo, URL ou null	Nova capa. `null` remove a capa atual.

Body

{
  "active": false
}

200: devolve o módulo atualizado dentro de data.

O módulo não muda de grupo nem de posição pela edição.
Ao trocar ou remover a capa, o arquivo anterior é apagado.
Ativar ou inativar um módulo marca a taxa de conclusão do grupo para ser recalculada.

🗑️ Excluir módulo

DELETE /modules/{id}

Exclui o módulo e todas as aulas dele.

200

{
  "message": "Módulo excluído com sucesso",
  "deleted_lessons": 4
}

deleted_lessons é a quantidade de aulas excluídas junto com o módulo.

⚠️
Atenção

A exclusão do módulo é definitiva: ele não pode ser restaurado.

As aulas do módulo são excluídas junto com ele e deixam de aparecer para os alunos e nas listagens da API. Os materiais complementares e o progresso dos alunos nessas aulas são mantidos na plataforma.

A taxa de conclusão do grupo é marcada para ser recalculada.

Respostas de erro

Status	Quando
`401`	Token ausente ou inválido.
`403`	Recurso não habilitado no plano.
`404`	Módulo não encontrado (edição e exclusão).
`422`	Campo inválido, grupo inexistente ou arquivado, ou capa que não pôde ser baixada ou não é imagem. Os erros de campo vêm em `errors`, por campo.
`429`	Limite de requisições excedido.

422

{
  "message": "The given data was invalid.",
  "errors": {
    "group_id": ["The selected group id is invalid."]
  }
}

Campos de um módulo

Capa (cover_image)

📖 Listar módulos de um grupo

➕ Criar módulo

Orientações

✏️ Editar módulo

🗑️ Excluir módulo

Atenção

Respostas de erro

Capa (`cover_image`)