Carregamento de usuários em lote via CSV

Esta funcionalidade permite cadastrar ou atualizar muitos usuários de uma só vez a partir de um arquivo CSV. Antes de gravar qualquer coisa, o sistema mostra uma pré-visualização com a validação de cada linha, para que você confira tudo com segurança.

1. Como chegar na funcionalidade

No menu lateral, abra Usuários e clique em “Carregamento de usuários em lote (CSV)”. Você também pode ir direto pelo endereço abaixo (troque BADIUNET_URL pelo endereço do seu site):

BADIUNET_URL/system/user/loadbatch/index

Para usar a tela é preciso ter permissão de gestão de usuários. Os usuários são sempre criados na entidade (tenant) da sua sessão atual — o arquivo nunca define a entidade.

2. Como funciona, passo a passo

O processo tem quatro momentos. Primeiro você envia o arquivo CSV e escolhe o separador de campos (vírgula ou ponto e vírgula). Em seguida clica em Validar: o sistema lê o arquivo e exibe um resumo com a situação de cada linha — nesse momento nada ainda é gravado. Depois você escolhe a opção de processamento (adicionar novos, atualizar existentes ou os dois). Por fim, clica em Processar e confirma; a tela mostra o progresso e, ao terminar, quantos registros foram inseridos, atualizados, ignorados ou apresentaram erro.

3. O painel de resumo (depois de validar)

Ao validar, cada linha recebe uma situação e o painel mostra os totais por situação. As situações possíveis são:

Pronto para registro — a linha é válida e o usuário ainda não existe; será inserido.
Registro existente — já existe um usuário com o mesmo login, e-mail ou documento no tenant; só será alterado se você escolher atualizar.
Inválido — falta um campo obrigatório ou o CPF é inválido; essa linha é sempre ignorada no processamento.

4. Regras do arquivo

A primeira linha do arquivo é sempre o cabeçalho, com os nomes das colunas escritos exatamente como os campos do usuário (em minúsculas). Colunas que não pertençam ao layout são simplesmente ignoradas, e a coluna entity nunca é aceita do arquivo. Cada arquivo aceita até 50.000 linhas.

O cabeçalho precisa conter, no mínimo, os campos firstname, lastname, email, username e doctype. Os campos auth e docnumber também são exigidos, mas o sistema preenche um valor automático quando você os deixa em branco, conforme a tabela:


	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. Um CPF malformado torna a linha Inválida.

5. Opções de processamento

Depois de validar, você escolhe uma entre três formas de gravar. Adicionar apenas os novos registros insere quem ainda não existe e ignora os já cadastrados. Atualizar apenas os registros já existentes faz o contrário: atualiza quem já existe e ignora os novos. Cadastrar novos e atualizar os existentes faz as duas coisas numa única passagem.

Nos modos que atualizam, há ainda a opção “Forçar atualização de campos vazios”. Marcando-a, uma coluna vazia no CSV passa a limpar o valor já gravado no banco. Mesmo assim, os campos de identidade e de credenciais nunca são apagados — username, email, doctype, docnumber, idnumber, shortname e password ficam sempre preservados. A senha só muda quando o CSV traz um novo valor na coluna password.

6. Exemplo simples

Este é o mínimo para cadastrar dois usuários, usando vírgula como separador:

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

A Ana é um cadastro completo: como não há senha no arquivo, ela recebe md5 do CPF e troca a senha no primeiro acesso. O Bruno tem doctype = EMAIL e o docnumber em branco, então o sistema usa o e-mail como documento; e como auth não veio, ele entra como manual.

7. Exemplo avançado

Quando os dados podem conter vírgulas, prefira o separador ponto e vírgula. O exemplo abaixo traz senha definida, telefone, profissão, idioma e data de nascimento:

firstname;lastname;email;username;doctype;docnumber;auth;password;phonemobile;profession;lang;dateofbirth
Carla;Mendes;carla.mendes@exemplo.com;carla.mendes;CPF;111.444.777-35;manual;Senha@123;(11) 99999-0001;Professora;pt;1990-05-20
Diego;Lima;diego.lima@exemplo.com;diego.lima;CPF;529.982.247-25;manual;;(11) 98888-0002;Analista;pt;15/08/1985

A senha da Carla (Senha@123) é gravada de forma cifrada. O Diego não informou senha, então usa o md5 do CPF e troca no primeiro acesso. As datas podem vir em AAAA-MM-DD ou DD/MM/AAAA (com ou sem hora).

Reimportação: se você enviar o mesmo arquivo de novo, as linhas já cadastradas aparecem como Registro existente. Basta editar os valores no CSV e processar com a opção de atualizar para refletir apenas as mudanças.

8. Boas práticas

Sempre valide antes de processar e confira o painel de resumo. Salve o arquivo em UTF-8 para que os acentos apareçam corretamente, e faça um teste com poucos registros antes de subir a lista completa. Cada inserção ou atualização fica registrada no log do sistema, garantindo a auditoria do que foi importado.