PROC001 Melhoria importação de clientes

	Projeto/Sistema: GerencieAqui	Versão do Template: 1.2
	Processo: PROC001 Melhoria importação de clientes	Versão do Documento: 1.0
	Responsável(eis):  Luís Leite	Data:  26/03/2026

1. Introdução

Este processo visa exemplificar a melhoria para a importação de cadastro de clientes.

2. Processo

Processo	Envolvidos	Dados de Entrada	Dados de Saída
PROC001 Melhoria importação de clientes	-	Arquivo XLSX ou XML	Dados inseridos ou atualizados em banco.

Especificação Funcional

---

PROC001 Melhoria importação de clientes:

Protótipo de Tela:

Imagem I - Exemplo de nova Dialog de guia para importação de clientes.

Imagem II- Exemplo de nova Dialog.

Imagem III - Importação de planilha.

Imagem IV - Exemplo de nova Dialog de importação.

Imagem V - Progresso importação.

Imagem VI - Tela de resultado.

Descrição dos Campos:

Campo	Tipo	Tamanho	Obrig. ?	Máscara	Observações
Dialog inicial de importação
[Baixar Planilha Modelo]	Link	-	-	-	-
Fechar		-	-	-	-
Entendi		-	-	-	-
Dialog de importação
Resolução de conflitos	Check	-	-	-	-
Planilha com Cabeçalho	Botão	-	-	-
Arquivo XLSX/XML	Botão	-	-	-
Coluna da Planilha	Column Header	-	-	-
Escolha uma opção	Column Header	-	-	-	Deve ser um autocomplete com dropdown
Fechar
Importar
Dialog Progresso
Cancelar Importação	Botão	-	-	-	-
Dialog Progresso
Baixar relatório de Erros	Botão	-	-	-	-
Fechar

Regras de Interface:

1. Baixar Planilha Modelo: Executa o download do modelo para guia de importação.
2. Resolução de conflitos: Deve conter as seguintes opções "Atualizar cadastro existente"; "Ignorar duplicados" e "Gerar erro e bloquear".
3. Planilha com Cabeçalho: Por padrão deve vir como , o evento de clique deve alterar o botão para

4. Arquivo XLSX/XML: Ao importar o arquivo deve gerar o Loading da importação do arquivo. Caso seja possível a importação, retornar o popup "Arquivo importado". Caso não seja possível, retornar a mensagem de erro "Não foi possível importar, verifique o arquivo".
5. Fechar (Imagem IV): Deve encerrar a tela sem modificações em base, apenas memoria.
6. Importar: Se possível importar, deve ir para a Imagem V - Progresso importação.
7. Escolha uma opção: O campo para o vínculo entre campo do sistema e coluna de vínculo da planilha deve ser um Autocomplete com Dropdown, pra permitir tanto a busca por digitação quando pelo Dropdown. Deve conter as opções já existentes com a adição do "Regime Tributário". Os campos obrigatórios devem ser listados primeiro:

Opção	Obrigatoriedade
Ignorar ou Escolha o campo	-
Razão Social*	S
CNPJ*	S
Inscrição Estadual	N
Endereço	N
Número	N
Complemento	N
Bairro	N
Cidade	N
IBGE	N
CEP	N
UF	N
Cidade-UF	N
Estado	N
E-mail	N
Tipo	N
Telefone	N
Celular	N
Tipo de Contribuinte	N
CNAE	N
Inscrição Municipal	N
Regime Tributário	N

Tabela I - Tabela de campos para vínculo

8. Importar: Se possível iniciar a importação, a tela deve ser finalizada e deve ser dado sequência para a Dialog da  Imagem V - Progresso importação.
Essa tela deve mostrar o progresso tanto em percentual quanto de registros sendo salvos.
9. Cancelar Importação: A ação deve abrir uma tela de confirmação pro usuário "Deseja interromper o processo de importação?" caso o usuário clique em 'Não', deve ser fechada a tela de confirmação e o processo continuado. Caso clique em 'Sim' a tela de importação deve ser encerrada.
10. Tela de resultado: Deve exibir a quantidade de registros no arquivo, importados com sucesso e registros com erro. Caso houverem erros exibir a mensagem:

Alguns registros não puderam ser importados. Verifique o relatório para mais detalhes.

10.1 Baixar relatório de Erros: Deve ser renderizado apenas se existirem erros na importação. Mais detalhes nas regras de negócio.

Regras de Negócio:

1. Baixar Planilha Modelo: Deve fazer o download de uma planilha XLSX contendo a coluna com todos os campos disponíveis para vínculo no sistema, conforme Tabela I - Tabela de campos para vínculo.
2. Arquivo XLSX/XML: Deve validar o formato do arquivo, se é XLSX ou XML e se o arquivo não supera 2MB . Caso for um formato diferente desses, não dar sequência na tentativa de importação.
3. Importar: Validar se os campos obrigatórios do sistema possuem vínculo com a coluna da planilha. Se estiverem vinculados, deve ser validado a "Resolução de conflitos"

• Se for "Atualizar cadastro existente", novos registros devem gerar uma Inserção na base de dados. Registros existentes devem ser Atualizados. O Critério para isso é o CNPJ.
  
• Se for "Ignorar duplicados", os registros conflitantes/já existentes na base de dados devem ser ignorados no momento da importação dos registros da planilha.
  
• Se "Gerar erro e bloquear", quando um registro já existir em banco, a importação deve ser interrompida, não realizando mais inserções no banco.
  

4. Deve ser gerado um log de registro da importação, contendo dados básicos 'data/hora', 'modulo', 'Usuário' e 'Descrição'. Inserir a descrição como "Realizada importação de planilha {nome_arquivo} de clientes com total de {numero_total_registros}, importados com sucesso: {numero_total_sucesso}, com erro: {numero_total_erro}"

5. Cancelar Importação:  A ação deve interromper a importação até que o usuario confirme alguma ação. Caso o usuário confirme o cancelamento da importação, deve ser interrompida as inserções e alterações na base de dados.

5. Baixar relatório de Erros -  Esse relatório deverá conter:

• • número da linha na planilha
  • campo que apresentou erro
  • descrição do erro encontrado

Linha	Campo	Erro
15	CNPJ	Formato inválido
22	E-mail	Formato inválido

Questões Técnicas:

1. Tabela onde deve ser inserido ou alterado o cliente: 'cliente' e 'enderecos'.

2. Baixar Planilha Modelo: Planilha de padrão XLSX, deve conter cabeçalho com os campos para vínculo. os campos obrigatórios como CNPJ e Razão Social devem ter o asterisco (*) indicando obrigatoriedade.

3. Baixar relatório de Erros: Relatório temporário gerado por HTML, deve listar apenas as rejeições e a linha onde ocorreu a rejeição da importação. 

©SOFTEN SISTEMAS 2026.