Trazer cursos de outra plataforma

O conteúdo já existe — num LMS antigo, num portal de treinamentos, numa produtora. Para que os colaboradores o façam em Treinamentos, com matrícula, progresso, quiz e certificado, ele precisa virar um curso da TAI: curso → módulos → aulas. Há dois caminhos: mandar um pacote ZIP com tudo dentro, ou montar o curso pela API, aula por aula.

Quando usar	Migração de catálogo, conteúdo produzido fora, cursos gerados por uma ferramenta sua
Porta	REST
Você vai precisar	Módulo LMS; permissão LMS_CURSO (cursos, módulos e aulas) e LMS_TRILHA (trilhas); token JWT de um usuário de integração

Como funciona

pacote ZIP ── POST /lms/cursos/import ───────────────▶ TAI  (curso + módulos + aulas + quizzes)
   ou
seu sistema ── POST /lms/cursos ─────────────────────▶ TAI  (curso em RASCUNHO)
            ── POST /lms/modulos/curso/{cursoId} ─────▶ TAI  (módulos)
            ── POST /lms/aulas/modulo/{moduloId} ─────▶ TAI  (aulas)
seu sistema ── PATCH /lms/cursos/{id}/status ─────────▶ TAI  (PRONTO → PUBLICADO)

Todo curso nasce em RASCUNHO e segue RASCUNHO → PRONTO → PUBLICADO → ARQUIVADO. PRONTO já aceita matrícula feita pela gestão; PUBLICADO aparece também no catálogo, para inscrição espontânea.

Passo a passo

Pacote ZIP

O pacote leva os arquivos para dentro da TAI — páginas HTML com seus estilos e scripts, PDFs e as questões dos quizzes — e cria a estrutura inteira numa chamada.

1. Monte o ZIP com um manifest.json na raiz:

   curso.zip
   ├── manifest.json
   ├── assets/html/boas-vindas/index.html   (+ css, js, imagens da aula)
   ├── assets/pdf/procedimento.pdf
   └── quizzes/quiz-final.json

   {
     "version": "1.0",
     "protocol": "TCP",
     "curso": {
       "titulo": "Trabalho em altura (NR-35)",
       "descricao": "Conteúdo teórico da NR-35.",
       "cargaHoraria": 480,
       "categoria": "Segurança",
       "tags": "nr35,altura",
       "certificadoHabilitado": true
     },
     "modulos": [
       {
         "titulo": "Fundamentos",
         "descricao": "Conceitos e responsabilidades",
         "ordem": 0,
         "aulas": [
           { "titulo": "Boas-vindas", "descricao": "Apresentação", "tipo": "HTML",
             "recurso": "assets/html/boas-vindas/index.html", "ordem": 0, "obrigatoria": true },
           { "titulo": "Procedimento", "descricao": "Leitura obrigatória", "tipo": "PDF",
             "recurso": "assets/pdf/procedimento.pdf", "ordem": 1 },
           { "titulo": "Avaliação final", "descricao": "Quiz", "tipo": "QUIZ",
             "recurso": "quizzes/quiz-final.json", "ordem": 2,
             "configuracao": { "notaMinima": 70, "maxTentativas": 3 } }
         ]
       }
     ]
   }

   cargaHoraria é em minutos. Numa aula HTML, recurso aponta para o index.html; todos os arquivos da mesma pasta sobem junto.

2. Escreva as questões do quiz. Os tipos são MULTIPLE_CHOICE (uma opção com "correta": true), TRUE_FALSE (respostaCorreta) e MATCHING (pares com esquerda e direita):

   {
     "questoes": [
       {
         "id": "q1", "tipo": "MULTIPLE_CHOICE", "peso": 1,
         "enunciado": "A partir de que altura a NR-35 se aplica?",
         "opcoes": [
           { "id": "q1a", "texto": "1 metro", "correta": false },
           { "id": "q1b", "texto": "2 metros", "correta": true }
         ],
         "feedback": { "correta": "Isso.", "incorreta": "Acima de 2 metros do nível inferior." }
       }
     ]
   }

   A nota vai de 0 a 100, ponderada por peso; notaMinima usa a mesma escala.

3. Envie o pacote.

   curl -X POST https://api.taitecnologia.com/lms/cursos/import \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -F "arquivo=@curso.zip"

   A resposta (201) é o curso criado, em RASCUNHO, com modulos e aulas. Guarde o id.

4. Publique — passo 4 da outra aba.

Para acrescentar conteúdo a um curso que já existe, envie o ZIP para POST /lms/cursos/{id}/upload: os módulos do pacote entram ao lado dos que o curso já tem, e os dados de curso do manifesto atualizam o curso. Vários pacotes de uma vez viram uma trilha com POST /lms/trilhas/from-zips (partes trilha, com titulo e descricao, e arquivos).

Montar pela API

Use quando o conteúdo continua hospedado fora e a TAI só precisa apontar para ele, ou quando o seu sistema gera a estrutura do curso.

1. Crie o curso.

   POST /lms/cursos
   Authorization: Bearer $TAI_TOKEN
   Content-Type: application/json
   
   {
     "titulo": "Atendimento ao cliente",
     "descricao": "Trilha comercial — módulo 1",
     "cargaHoraria": 90,
     "categoria": "Comercial",
     "certificadoHabilitado": true
   }

2. Crie os módulos, na ordem.

   POST /lms/modulos/curso/31
   
   { "titulo": "Primeiro contato", "descricao": "Abertura do atendimento", "ordem": 0 }

3. Crie as aulas. Uma aula HTML pode apontar para uma página hospedada fora: o player abre a URL de conteudoUrl embutida na tela do curso.

   POST /lms/aulas/modulo/57
   
   {
     "titulo": "Como cumprimentar o cliente",
     "descricao": "Vídeo e roteiro",
     "tipo": "HTML",
     "conteudoUrl": "https://treinamentos.suaempresa.com.br/atendimento/aula-1",
     "duracaoSegundos": 600,
     "obrigatoria": true,
     "ordem": 0
   }

4. Marque como pronto e publique.

   PATCH /lms/cursos/31/status
   
   { "status": "PRONTO" }

   PRONTO exige ao menos um módulo com ao menos uma aula. Depois, {"status": "PUBLICADO"} leva o curso ao catálogo.

Trilhas

Uma trilha agrupa cursos PRONTO ou PUBLICADO numa sequência:

POST /lms/trilhas

{ "titulo": "Integração comercial", "descricao": "Os três cursos do primeiro mês" }

PATCH /lms/trilhas/4/cursos

{ "cursos": [
    { "cursoId": 31, "ordem": 0, "obrigatoria": true },
    { "cursoId": 32, "ordem": 1, "obrigatoria": true }
] }

Essa chamada substitui a lista inteira de cursos. Em seguida, PATCH /lms/trilhas/4/status com {"status": "PRONTO"} e depois PUBLICADO. Para matricular pessoas, veja Matricular colaboradores.

Cuidados

• Curso com matrículas pede confirmação para mudar de estrutura: criar ou remover módulo ou aula, ou reenviar o ZIP, responde 400 até você mandar o cabeçalho X-Confirm-Structural-Change: true.
• Não há volta para RASCUNHO. Para tirar um curso do catálogo, arquive (ARQUIVADO, só a partir de PUBLICADO); arquivado não recebe matrícula.
• Conteúdo externo em HTML só aparece se o site de origem permitir ser exibido dentro de outra página (sem X-Frame-Options: DENY nem frame-ancestors restritivo).
• PDF e quiz pelo ZIP. O pacote hospeda o PDF na TAI e carrega as questões do quiz; um quiz importado sem questões é recusado com 400 dizendo qual aula ficou vazia.
• Conclusão é por aula obrigatória: o colaborador conclui o curso quando todas as aulas com obrigatoria: true estão feitas. Aula de quiz conta quando a nota mínima é atingida.
• Tamanho: o ZIP sobe por multipart/form-data, até 150 MB — veja Limites. Corpos JSON acima de 8 KB são barrados pelo firewall; crie aulas uma a uma.
• Duplicidade: POST /lms/cursos/import cria um curso novo a cada chamada, e o /upload acrescenta módulos a cada chamada. Consulte GET /lms/cursos/page?search= antes de reimportar.