Cadastro e matrícula em lote via CSV

Trata-se carrega um arquivo CSV para, de uma só vez, cadastrar ou atualizar usuários e matriculá-los em turmas. Cada linha do arquivo pode trazer os dados de um usuário e uma ou mais matrículas em turma. Antes de gravar, o sistema mostra uma pré-visualização com a validação de cada linha.

1. Como chegar na funcionalidade

No menu superior abra GC2, vá em Gestão de Matrícula e clique em “Matrícula em lote (CSV)”. Você também pode acessar diretamente pelo endereço abaixo (troque BADIUNET_URL pelo endereço do seu site):

BADIUNET_URL/tms/enrol/loadbatch/index

É preciso ter permissão de gestão de matrículas. Tudo — usuários e matrículas — é gravado sempre na entidade (tenant) da sua sessão atual; o arquivo nunca define a entidade.

2. Como funciona, passo a passo

O fluxo tem quatro momentos. Primeiro você envia o arquivo CSV e escolhe o separador de campos (vírgula ou ponto e vírgula). Depois clica em Validar: o sistema lê o arquivo, localiza os usuários, resolve as turmas/perfis/status pelos nomes informados e mostra um resumo com a situação de cada linha — nesse momento nada ainda é gravado. Em seguida você escolhe as opções de processamento (separadas para usuário e para matrícula). Por fim, clica em Processar e confirma; a tela mostra o progresso e, ao terminar, quantos usuários foram inseridos/atualizados e quantas matrículas foram criadas, já existentes, ignoradas ou com erro.

3. Os dois jeitos de usar uma linha

Cada linha pode ser usada de duas formas, e o sistema decide automaticamente qual aplicar:

Cadastrar/atualizar o usuário e matricular: quando a linha traz os dados completos do usuário (os campos obrigatórios), o usuário é criado ou atualizado conforme a opção escolhida e, em seguida, é matriculado nas turmas indicadas.
Apenas matricular um usuário que já existe: quando a linha traz somente a chave do usuário — o username, ou então doctype + docnumber — o usuário é apenas localizado (nunca alterado) e só as matrículas são criadas. Se essa chave não encontrar nenhum usuário, a linha fica inválida.

4. O painel de resumo (depois de validar)

Ao validar, cada linha recebe uma situação e o painel mostra os totais, incluindo o número de matrículas que serão processadas. As situações de linha são:

Pronto para registro — linha válida com usuário a cadastrar.
Registro existente — o usuário já existe no tenant (por login, e-mail ou documento), ou a linha é do tipo “apenas localizar”.
Inválido — falta campo obrigatório, o CPF é inválido, o usuário-chave não foi encontrado, ou alguma turma/perfil/status informado não existe no tenant. A linha inteira é ignorada.

Além da situação da linha, cada matrícula tem a sua própria indicação na pré-visualização: nova, já matriculado, a verificar ou inválida.

5. Estrutura do arquivo

A primeira linha é sempre o cabeçalho, com os nomes das colunas em minúsculas. Colunas fora do layout são ignoradas, a coluna entity nunca é aceita, e cada arquivo aceita até 50.000 linhas. O arquivo combina dois grupos de colunas:

Colunas do usuário — são exatamente as mesmas do cadastro de usuários em lote. Para cadastrar/atualizar, o cabeçalho precisa conter ao menos firstname, lastname, email, username e doctype. Os campos auth e docnumber têm preenchimento automático quando vazios:


Campo vazio	O que o sistema faz

`auth`	Assume `manual`.

`docnumber`	Quando `doctype = EMAIL`, herda o e-mail informado.

`password` (usuário novo)	Usa `md5(docnumber)` e marca a conta para trocar a senha no primeiro acesso.

Quando doctype = CPF, o número é validado pelo dígito verificador e a máscara é removida automaticamente; CPF malformado torna a linha Inválida.

Padrão de inscrição de usuário: a lista completa das colunas de usuário aceitas, com todas as regras de campos obrigatórios, valores automáticos e validação, está documentada na tela de carregamento de usuários em lote.
Ver mais detalhes ›

Colunas da matrícula — recebem um número no final para que a mesma linha descreva várias matrículas: ...1 para a primeira turma, ...2 para a segunda, e assim por diante. Cada bloco de matrícula precisa identificar a turma por classeid (o id numérico) ou por classeshortname (o nome curto da turma). As colunas disponíveis por matrícula são:


Coluna (com sufixo)	Significado

`classeidN` ou `classeshortnameN`	Identifica a turma (id ou nome curto). Pelo menos um é obrigatório.

`roleshortnameN`	Perfil na turma. Quando vazio, assume `studentcorporate`.

`statusshortnameN`	Status da matrícula. Quando vazio, assume `activeenrol`.

`timestartN` / `timeendN`	Datas de início e fim na turma (opcionais).

`markerN` / `idnumberN`	Marcador e identificador externo da matrícula (opcionais).

As datas aceitam vários formatos: AAAA-MM-DD, AAAA-MM-DD HH:MM:SS, DD/MM/AAAA e até um timestamp Unix. Se a turma, o perfil ou o status informados não existirem no tenant, a linha fica inválida — por isso vale conferir os nomes curtos antes de importar.

6. Opções de processamento

Aqui há dois conjuntos de opções independentes, porque a linha mexe em duas coisas diferentes.

Para os dados do usuário você escolhe entre inserir apenas os novos, atualizar apenas os já existentes ou cadastrar novos e atualizar os existentes. Há ainda a opção “Forçar atualização de campos vazios”: quando marcada, uma coluna vazia no CSV limpa o valor já gravado do usuário — exceto os campos de identidade e credenciais (username, email, doctype, docnumber, idnumber, shortname, password), que nunca são apagados.

Para as matrículas você escolhe entre criar apenas as novas, atualizar apenas as já existentes ou criar novas e atualizar as existentes. A opção “Forçar atualização de campos vazios” das matrículas limpa as datas vazias (início/fim) de uma matrícula existente; a turma e o perfil, que são a chave da matrícula, nunca são alterados.

As linhas do tipo “apenas localizar usuário” ignoram as opções de usuário: o usuário nunca é inserido nem atualizado, só as matrículas são processadas.

7. Exemplo simples

Cadastrar dois usuários e matricular cada um em uma turma, identificada pelo nome curto da turma — separador vírgula:

firstname,lastname,email,username,doctype,docnumber,classeshortname1
Ana,Silva,ana.silva@exemplo.com,ana.silva,CPF,123.456.789-09,TURMA-MAT-2025
Bruno,Costa,bruno.costa@exemplo.com,bruno.costa,EMAIL,,TURMA-MAT-2025

Os dois são cadastrados (a senha vira md5 do documento, com troca no primeiro acesso) e matriculados na turma TURMA-MAT-2025. Como nenhum perfil ou status foi informado, valem os padrões: perfil studentcorporate e status activeenrol.

8. Exemplos avançados

Duas matrículas na mesma linha, com perfil, status e datas, usando ponto e vírgula como separador:

firstname;lastname;email;username;doctype;docnumber;classeshortname1;roleshortname1;statusshortname1;timestart1;classeshortname2;roleshortname2
Carla;Mendes;carla.mendes@exemplo.com;carla.mendes;CPF;111.444.777-35;TURMA-MAT-2025;studentcorporate;activeenrol;2025-02-01;TURMA-LAB-2025;tutor

A Carla é cadastrada e recebe duas matrículas: aluna na TURMA-MAT-2025 a partir de 01/02/2025, e tutora na TURMA-LAB-2025.

Apenas matricular alguém que já existe, informando só a chave do usuário (login):

username;classeshortname1;statusshortname1
diego.lima;TURMA-MAT-2025;activeenrol

O Diego não é alterado — o sistema só o localiza pelo login e cria a matrícula. Em vez do login, você poderia usar doctype + docnumber para identificá-lo.

9. Boas práticas

Sempre valide antes de processar e confira o painel — em especial as matrículas marcadas como inválidas, que geralmente indicam um nome curto de turma, perfil ou status que não existe no tenant. Salve o arquivo em UTF-8 para os acentos saírem corretos e teste com poucas linhas antes da carga completa. Tanto o cadastro de usuários quanto a criação de matrículas ficam registrados no log do sistema, e a matrícula é propagada para disciplina/oferta/LMS exatamente como em uma matrícula feita manualmente.