Matricular colaboradores e acompanhar a conclusão

A matriz de treinamentos, o sistema de competências ou o de SST decide quem precisa fazer qual curso — uma NR, a integração, um treinamento de produto. A TAI matricula, o colaborador faz o curso em Treinamentos, e o relatório de conclusão volta para o seu sistema como prova de compliance.


Quando usar	Treinamentos obrigatórios por cargo ou área, reciclagens periódicas, auditoria de quem fez e quem falta fazer
Porta	REST · Webhook assinando eventos · Automação · Agente (MCP)
Você vai precisar	Módulo `LMS`; permissão `LMS_MATRICULA` (matricular e listar matrículas) e `LMS_CURSO` (cursos e relatório de conclusão); token JWT de um usuário de integração

Como funciona

seu sistema ── GET /lms/cursos/page?search= ───────────────▶ TAI  (acha o curso e o status)
seu sistema ── GET /lms/relatorios/conclusao?status=NAO_MATRICULADO ▶ TAI  (quem falta)
seu sistema ── POST /lms/matriculas ───────────────────────▶ TAI  (matricula em lote)
colaborador ── faz o curso em Treinamentos ────────────────▶ TAI  (progresso, nota, certificado)
TAI ── webhook: CURSO_CONCLUIDO, CERTIFICADO_CURSO_EMITIDO ─▶ seu sistema  (na hora)
seu sistema ── GET /lms/relatorios/conclusao?status=CONCLUIDO ─────▶ TAI  (quem concluiu: reconciliação)

Passo a passo

Ache o curso. Quem gerencia cursos vê todos os status e pode filtrar por status.
```
GET /lms/cursos/page?search=NR-35&status=PUBLICADO
Authorization: Bearer $TAI_TOKEN
```
Guarde o id. Só cursos PRONTO ou PUBLICADO recebem matrícula; PUBLICADO também aparece no catálogo para inscrição espontânea.
Descubra quem falta. O relatório de conclusão lista todos os colaboradores ativos e a situação de cada um no curso — inclusive quem nunca se matriculou.
```
GET /lms/relatorios/conclusao?cursoId=12&status=NAO_MATRICULADO&departamentoId=40&size=100
```
Cada linha traz colaboradorId, colaboradorNome, colaboradorEmail, departamento, cargo, status, progressoPercentual, notaFinal, dataInicio e dataConclusao. Os valores de status são NAO_MATRICULADO, PENDENTE, EM_ANDAMENTO, CONCLUIDO e CANCELADO.

Se a lista de pessoas vem do seu sistema, case pelo id da TAI guardado na sincronização de colaboradores ou busque com GET /colaborador/page?search=.
Matricule em lote. Uma chamada por curso, com todos os colaboradores.
```
POST /lms/matriculas
Content-Type: application/json

{
  "cursoId": 12,
  "colaboradorIds": [1043, 1051, 1077],
  "dataExpiracao": "2026-11-30T23:59:00-03:00"
}
```
A resposta é a lista de matrículas criadas, cada uma com id e status PENDENTE. dataExpiracao é opcional: é o prazo para concluir.
Ou matricule numa trilha. A trilha é uma sequência de cursos; matricular nela matricula também em cada curso da trilha (quem já tem matrícula aberta num desses cursos aproveita a existente).
```
POST /lms/matriculas/trilha

{ "trilhaId": 4, "colaboradorIds": [1043, 1051], "dataExpiracao": "2026-12-15T23:59:00-03:00" }
```
A trilha também precisa estar PRONTO ou PUBLICADO e ter ao menos um curso.
Traga a conclusão de volta. Rode o relatório com status=CONCLUIDO (ou sem status, para o retrato inteiro) e atualize o seu sistema. Para uma trilha, use GET /lms/matriculas/trilha?trilhaId=4, que traz cursosCompletos, totalCursos e progressoPercentual por pessoa.

O que muda o status de uma matrícula

PENDENTE ao ser criada; EM_ANDAMENTO quando o colaborador começa.
CONCLUIDO quando todas as aulas obrigatórias estão concluídas — aula de quiz conta quando a nota mínima é atingida. Se o curso emite certificado, ele é gerado nesse momento e pode ser conferido publicamente — veja Validar certificado.
CANCELADO por PATCH /lms/matriculas/{id}/cancelar (ou PATCH /lms/matriculas/trilha/{id}/cancelar). Matrícula concluída não se cancela.

Automatize

A TAI já matricula sozinha em dois casos — sem nenhuma chamada sua:

Rotina	O que faz	Começa ligada?
Matrícula automática na admissão (`lms-regras-matricula`)	Quem é admitido ou cadastrado entra nos cursos das regras de matrícula que casam com o seu departamento e cargo, com o prazo da regra	Sim
Reciclagem e prazo dos cursos (`lms-reciclagem`)	Todo dia de manhã, lembra por e-mail, 7 dias antes, quem ainda não concluiu uma matrícula com prazo	Não — a empresa liga na Central

As regras de matrícula se configuram no curso, em Treinamentos → Cursos, aba Matrículas, quadro Matrícula automática, ou pela API — útil quando a matriz de treinamentos por cargo vive no seu sistema:

POST /lms/regras-matricula
Content-Type: application/json

{ "cursoId": 12, "departamentoId": 40, "cargoId": 77, "prazoDias": 30 }

departamentoId e cargoId vazios valem para todos; prazoDias vai de 1 a 365 e vira a dataExpiracao de cada matrícula. Uma regra igual à existente é recusada com 400. Para matricular quem já trabalha na empresa e casa com a regra, POST /lms/regras-matricula/{id}/aplicar — a resposta traz matriculasCriadas; quem já tem matrícula não cancelada no curso fica de fora. GET /lms/regras-matricula?cursoId=12 lista as regras e DELETE /lms/regras-matricula/{id} exclui (as matrículas feitas continuam). As rotinas ficam em Processos › Central de Automações › Rotinas dos módulos.

Para uma regra que dependa de outro fato, use um fluxo automatizado com o bloco Fazer algo na plataforma: por exemplo, Quando algo acontece com o evento Um colaborador é cadastrado, seguido da operação de criar matrículas, com os parâmetros

{ "body": { "cursoId": 12, "colaboradorIds": ["{{gatilho.colaboradorId}}"] } }

O modelo pronto de quadro Onboarding de quem foi admitido faz o mesmo quando você escolhe um curso de integração. O fluxo nasce em Processos › Fluxos › Novo processo › Fluxo automatizado e só roda depois de Publicar.

Avisar o seu sistema de cada conclusão

Em vez de rodar o relatório toda hora, o seu sistema pode receber cada conclusão assim que ela acontece. Em Processos › Central de Automações, aba Webhooks, crie um Novo webhook e assine Um curso é concluído (CURSO_CONCLUIDO) — e, se usa trilhas, Uma trilha de aprendizagem é concluída (TRILHA_CONCLUIDA). Veja Assinar eventos.

{
  "id": "evt_63340",
  "tipo": "CURSO_CONCLUIDO",
  "descricao": "Um curso é concluído",
  "versao": 1,
  "ocorridoEm": "2026-10-06T20:11:37.845Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "matriculaId": 3318,
    "cursoId": 12,
    "cursoTitulo": "NR-35 — Trabalho em altura",
    "colaboradorId": 1043
  }
}

Para a prova de compliance, assine também Um certificado de curso é emitido (CERTIFICADO_CURSO_EMITIDO): ele traz o codigo do certificado, que qualquer um confere em Validar certificado. Matrículas criadas e canceladas também têm evento (MATRICULA_CURSO_CRIADA, MATRICULA_CURSO_CANCELADA, e os de trilha) — a lista está no catálogo.

Mantenha o relatório do passo 5 como reconciliação: o webhook tenta de novo por cerca de um dia, não para sempre.

Pelo seu agente de IA

“Quem do departamento de Manutenção ainda não concluiu o curso de NR-35? Matricule quem nunca se inscreveu, com prazo até 30/11.”

O agente lê o relatório de conclusão e, com escopo de escrita, cria as matrículas — o seu cliente de IA pede aprovação antes. Com credencial somente leitura, ele só responde quem falta. Veja Escrita e segurança.

Cuidados

O lote é tudo ou nada. Se um dos colaboradores já tem matrícula PENDENTE ou EM_ANDAMENTO no curso, a chamada responde 400 com os ids em conflito e nenhuma matrícula é criada. Filtre antes pelo relatório (passo 2) — é isso que torna a rotina idempotente.
Curso em rascunho responde 400 Curso deve estar PRONTO ou PUBLICADO para matricular.
O prazo é duro. Depois de dataExpiracao, o colaborador perde o acesso ao conteúdo da matrícula. Para dar mais prazo, cancele e matricule de novo.
O progresso é do aluno. Aulas só são marcadas como concluídas pelo próprio colaborador; não há rota para um sistema externo registrar a conclusão em nome dele.
O relatório conta pessoas, não matrículas: uma linha por colaborador ativo. Desligados não aparecem.
Datas com hora vão em ISO 8601 com fuso — veja Datas e formatos.

Referência gerada do contrato da API em 30 de outubro de 2026. taitecnologia.com · Termos de uso · Privacidade