🎬Aulas

Aulas são o conteúdo dos módulos: cada aula pertence a um módulo, e o módulo a um grupo. Pela API pública é possível listar as aulas de um grupo, criar, editar e excluir aulas, e gerenciar os materiais complementares de cada aula.

Todos os endpoints exigem:

Authorization: Bearer {token}

Accept: application/json

Recursos do plano necessários:

Rota	Recurso do plano
`GET /lessons`	Public API – List Lessons
`POST /lessons`	Public API – Create Lesson
`POST /lessons/{id}`	Public API – Update Lesson
`DELETE /lessons/{id}`	Public API – Delete Lesson
`GET`, `POST` e `DELETE` em `/lessons/{id}/materials`	Public API – Manage Lesson Materials

Campos de uma aula

A criação e a edição devolvem a aula neste formato:

Campo	Tipo	Descrição
`id`	integer	Identificador da aula.
`group_id`	integer	Grupo da aula, que é sempre o grupo do módulo.
`module_id`	integer	Módulo ao qual a aula pertence.
`title`	string	Título da aula.
`subtitle`	string \| null	Subtítulo da aula.
`position`	integer	Posição da aula no módulo; a ordem dos alunos é a crescente.
`video_link`	string \| null	Link do vídeo da aula (ver abaixo).
`video_type`	string \| null	Provedor identificado a partir do `video_link`, como `youtube`, `vimeo` ou `panda`.
`text_content`	string \| null	Descrição da aula.
`html_content`	string \| null	Conteúdo em HTML.
`thumbnail`	string \| null	URL da capa da aula.
`has_assignment`	boolean	Se a aula tem tarefa.
`is_assignment_required`	boolean	Se o aluno precisa enviar o quiz e a tarefa para concluir a aula.
`allow_private_comments`	boolean	Se a aula aceita comentários privados.
`completion_date`	string \| null	Prazo de conclusão da aula (ISO 8601).
`allow_completion_after_date`	boolean	Se a aula pode ser concluída depois do prazo.

Vídeo (`video_link`)

O vídeo da aula é o link de um provedor externo. Provedores aceitos: YouTube, Vimeo, Panda Video, Loom, Wistia, Kaltura, FanHero, StreamYard, ScaleUp/SmartPlayer, vturb (ConverteAI), Bunny e SafeVideo. Um link de outro provedor é recusado com 422.

Os vídeos hospedados no player da Ensinio não podem ser vinculados pela API. Ao enviar um video_link para uma aula que usava um vídeo do player da Ensinio, o link enviado passa a ser o vídeo da aula.

Capa (`thumbnail`)

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 aulas de um grupo

GET /lessons?group_id={id}

Lista as aulas do grupo na ordem em que os alunos as veem (pela posição do módulo e depois pela posição da aula), com paginação. O module_id de cada aula identifica o módulo dela. Aulas de módulos inativos também são listadas.

Parâmetros de query

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

200

{
  "data": [
    { "id": 501, "group_id": 12, "module_id": 31, "title": "Boas-vindas", "position": 0 },
    { "id": 502, "group_id": 12, "module_id": 31, "title": "Como o curso funciona", "position": 1 },
    { "id": 510, "group_id": 12, "module_id": 32, "title": "Funil de vendas", "position": 0 }
  ],
  "links": {
    "first": "https://sua-plataforma.ensinio.cloud/public/api/v1/lessons?group_id=12&page=1",
    "last": "https://sua-plataforma.ensinio.cloud/public/api/v1/lessons?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/lessons",
    "per_page": 15,
    "to": 3,
    "total": 3
  }
}

➕ Criar aula

POST /lessons

Campos

Campo	Tipo	Obrigatório	Padrão	Descrição
`module_id`	integer	✅	—	Módulo ao qual a aula será vinculada.
`title`	string	✅	—	Título da aula (até 256 caracteres).
`subtitle`	string	❌	—	Subtítulo (até 256 caracteres).
`video_link`	string	❌	—	Link do vídeo em um provedor aceito.
`text_content`	string	❌	—	Descrição da aula.
`html_content`	string	❌	—	Conteúdo em HTML.
`thumbnail`	arquivo ou URL	❌	—	Capa da aula.
`has_assignment`	boolean	❌	`false`	Habilita a tarefa.
`is_assignment_required`	boolean	❌	`false`	Exige o envio do quiz e da tarefa para concluir a aula.
`allow_private_comments`	boolean	❌	`true`	Habilita os comentários privados.
`completion_date`	string (data)	❌	—	Prazo de conclusão, como `2026-12-31` ou `2026-12-31 18:00:00`.
`allow_completion_after_date`	boolean	❌	`false`	Permite concluir depois do prazo.

Body

{
  "module_id": 32,
  "title": "Funil de vendas",
  "video_link": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "text_content": "Como montar um funil do topo ao fundo.",
  "has_assignment": true,
  "completion_date": "2026-12-31"
}

201: devolve a aula criada dentro de data.

📌
Orientações

A aula nova é sempre adicionada por último no módulo. A posição não pode ser escolhida pela API.

O grupo da aula é o grupo do módulo; não é preciso enviá-lo.

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

Os campos opcionais não enviados ficam com os padrões da tabela. Comentários, avaliação da aula (CSAT), tempo mínimo, conclusão ao fim do vídeo e reprodução automática seguem as configurações do grupo, como numa aula criada no painel.

Os arquivos complementares da aula são adicionados depois, pelas rotas de materiais complementares, descritas mais abaixo.

✏️ Editar aula

POST /lessons/{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. Os campos são os mesmos da criação, todos opcionais, exceto o module_id: a aula não muda de módulo nem de posição pela edição.

title não pode ser vazio.
subtitle, video_link, text_content, html_content e completion_date aceitam null para apagar o valor.
thumbnail aceita null para remover a capa atual. Ao trocar ou remover a capa, o arquivo anterior é apagado.

Body

{
  "title": "Funil de vendas na prática",
  "allow_completion_after_date": true
}

200: devolve a aula atualizada dentro de data.

🗑️ Excluir aula

DELETE /lessons/{id}

Exclui a aula: ela deixa de aparecer para os alunos e nas listagens da API. Os materiais complementares e o progresso dos alunos na aula são mantidos na plataforma. A taxa de conclusão do grupo é marcada para ser recalculada.

Para excluir todas as aulas de um módulo de uma vez, exclua o módulo.

200

{ "message": "Aula excluída com sucesso" }

📎 Materiais complementares

Arquivos de apoio da aula, como apostilas, planilhas e slides, que o aluno baixa na página da aula. Os três endpoints usam o mesmo recurso do plano, Public API – Manage Lesson Materials.

Cada material vem neste formato:

Campo	Tipo	Descrição
`id`	integer	Identificador do material. É ele que identifica o material na remoção.
`lesson_id`	integer	Aula do material.
`title`	string	Nome do material exibido ao aluno.
`url`	string	URL do arquivo guardado na plataforma.
`file_size`	integer	Tamanho do arquivo, em bytes.

Listar materiais

GET /lessons/{id}/materials

Lista todos os materiais da aula, sem paginação.

200

{
  "data": [
    {
      "id": 88,
      "lesson_id": 510,
      "title": "apostila-funil.pdf",
      "url": "https://cdn.ensinio.com/sua-plataforma/group-material/file/apostila-funil.pdf",
      "file_size": 482133
    }
  ]
}

Adicionar materiais

POST /lessons/{id}/materials

Adiciona um ou mais materiais à aula. Os materiais que a aula já tem continuam lá.

Campo	Tipo	Descrição
`files[]`	arquivos	Arquivos enviados em `multipart/form-data`. O nome do material é o nome do arquivo.
`links[]`	lista	Até 10 links por requisição, cada um com `url` (obrigatório, `http` ou `https`) e `title` (opcional, até 255 caracteres). A plataforma baixa o arquivo e guarda uma cópia. Sem `title`, o nome do material é o nome do arquivo no link.

É preciso enviar files, links ou os dois.

Body (JSON, por link)

{
  "links": [
    { "url": "https://meu-site.com/materiais/apostila-funil.pdf" },
    { "url": "https://meu-site.com/download?id=7", "title": "Checklist de lançamento" }
  ]
}

201: devolve os materiais criados dentro de data, primeiro os arquivos enviados e depois os links. Guarde os id para remover os materiais depois.

📌
Orientações

Cada arquivo precisa respeitar o tamanho máximo de material do plano.

Ou todos os materiais da requisição são adicionados, ou nenhum: se um link não puder ser baixado ou se algum arquivo passar do tamanho máximo, a resposta é 422 e nada é adicionado.

Materiais em PDF entram na base de conhecimento do Agente Tutor quando a aula já faz parte dela.

Remover material

DELETE /lessons/{id}/materials/{materialId}

Remove o material e apaga o arquivo dele.

200

{ "message": "Material removido com sucesso" }

Respostas de erro

Status	Quando
`401`	Token ausente ou inválido.
`403`	Recurso não habilitado no plano.
`404`	Aula não encontrada (edição, exclusão e materiais) ou material não encontrado naquela aula.
`422`	Campo inválido, módulo ou grupo inexistente ou arquivado, vídeo de provedor não aceito, capa que não pôde ser baixada ou não é imagem, material que não pôde ser baixado ou acima do tamanho máximo do plano. Os erros de campo vêm em `errors`, por campo.
`429`	Limite de requisições excedido.

422

{
  "message": "The given data was invalid.",
  "errors": {
    "video_link": ["Video Provider unidentified or not supported. Valid providers: Ensinio Play, YouTube, Loom, Wistia, Vimeo, Panda, FanHero and StreamYard."]
  }
}

Campos de uma aula

Vídeo (video_link)

Capa (thumbnail)

📖 Listar aulas de um grupo

➕ Criar aula

Orientações

✏️ Editar aula

🗑️ Excluir aula

📎 Materiais complementares

Listar materiais

Adicionar materiais

Orientações

Remover material

Respostas de erro

Vídeo (`video_link`)

Capa (`thumbnail`)