Gestão de Vendedores: Como fazer a importação de vendedores via CSV?

Criada por Brenda Souza, Modificado em Ter, 14 Jul na (o) 3:55 PM por Mariana Benites

Neste artigo você encontrará o guia completo sobre como realizar a Importação de Vendedores via CSV no App Dito. Você aprenderá o passo a passo da importação, a estrutura obrigatória do arquivo, as regras críticas de validação (Full Load) e como o sistema gerencia a criação/atualização de vendedores e lojas de forma massiva e segura, garantindo a consistência da sua base de dados.

Nível de Acesso: Administrador, Administrador de Dados, Editor.
Persona: Administrador de Dados, Analista de E-commerce, Gerente de Operações.

Como fazer a importação via CSV?

Onde acessar a importação?

Para encontrar a funcionalidade de importação de vendedores, siga os passos abaixo:

1. No menu lateral do App Dito, acesse Configurações.

2. Clique em Lojas, depois em Lista de vendedores e, por fim, acesse a aba Lista de importações.

Como realizar uma nova importação?

1. Na aba Lista de Importações, clique em Importar CSV.

2. Envie o arquivo clicando na caixa ou arrastando o arquivo para dentro dela e aguarde a validação da estrutura.

3. Se o arquivo for válido, clique em Continuar para iniciar o processamento. Se o arquivo tiver erros de estrutura (ex.: cabeçalho errado), o sistema exibirá um alerta imediatamente.

Regra importante: não é possível iniciar uma nova importação enquanto outra está em processamento. Se o status atual for “Processando” o sistema bloqueia a criação de uma nova importação. Isso evita duplicações e inconsistência de dados.

Estrutura obrigatória do arquivo CSV

Para garantir o sucesso da importação, é necessário seguir o formato obrigatório do arquivo e suas configurações:

Formato: CSV UTF-8, delimitado por vírgula (,)
Tamanho máximo: 10 MB
Máximo: 50.000 linhas

Baixe o arquivo modelo (estrutura correta): modelo CSV

Ordem obrigatória do cabeçalho

O cabeçalho do seu arquivo CSV deve seguir exatamente a ordem e a nomenclatura abaixo:

Importante: O nome das colunas precisa seguir essa nomenclatura exata e a ordem precisa ser respeitada.

Validando a estrutura do arquivo

Antes de iniciar o processamento, o sistema valida:

Formato do arquivo (precisa ser CSV)
Tamanho (menor ou igual a 10MB)
Delimitador (vírgula)
Cabeçalho completo e na ordem correta
Arquivo não pode estar vazio

Se houver erro nessa fase, a importação não avança e nenhum dado é alterado.

Validando o conteúdo do arquivo

Nessa etapa, cada linha é validada individualmente, de acordo com as seguintes regras por campo:

Código do vendedor (codigo_vendedor)

Não pode estar vazio.
Deve ter até 50 caracteres.
A combinação de codigo_vendedor + codigo_loja deve ser única por linha.

Nome (nome)

Campo obrigatório.
Deve ter no máximo 150 caracteres.

CPF (cpf)

Campo obrigatório.
Deve conter os 11 dígitos.

Cargo (cargo)

Campo obrigatório.
Valores permitidos: VENDEDOR ou GERENTE.
Um vendedor deve ter um único cargo, mesmo que atue em várias lojas.

Código da loja (codigo_loja)

Campo obrigatório.
Deve ter no máximo 50 caracteres.
Se a loja não existir, ela será criada automaticamente.
Se a loja já existir, o nome será atualizado caso seja diferente do cadastrado.

Nome da loja (nome_da_loja)

Campo obrigatório.
Deve ter no máximo 150 caracteres.

Status (status)

Valores permitidos: ATIVO ou INATIVO.
O sistema normaliza o valor para maiúsculas (UPPERCASE).

Regras de processamento (FULL LOAD)

Toda importação substitui o estado atual da base de dados, ou seja, a importação é total (Full Load), não incremental. Na prática, isso significa:

1. Todos os vendedores ativos devem estar no arquivo

O arquivo CSV deve ser uma representação completa e atual da sua base de vendedores.

2. Vendedores ausentes no arquivo serão inativados

Qualquer vendedor que exista na base da Dito, mas não esteja presente no arquivo CSV, será automaticamente atualizado para o status INATIVO, independentemente do seu status anterior.

3. Criação e atualização de vendedores e lojas

Criação de vendedores: Se um codigo_vendedor enviado no arquivo não existir na base, um novo vendedor será criado.
Atualização de vendedores: Se um codigo_vendedor já existir, seus dados (nome, CPF, cargo, lojas, status) serão atualizados conforme o arquivo.
Criação de lojas: Se um codigo_loja não existir, uma nova loja será criada automaticamente.
Atualização de lojas: Se uma loja já existir e o nome enviado for diferente do cadastrado, o nome da loja será atualizado.

4. A importação só é aplicada se 100% do arquivo for válido

Se houver ao menos 1 linha inválida em todo o arquivo:

❌ Nenhum vendedor é criado ou atualizado.
❌ Nenhuma loja é criada ou alterada.
❌ O arquivo é completamente rejeitado e a base de dados permanece inalterada.
O status final da importação será INVÁLIDO.

5. A alteração só ocorre com o status CONCLUÍDO

Os dados da sua base só são efetivamente alterados quando o status da importação é exibido como CONCLUÍDO.

Multilojas via CSV

O CSV permite cadastrar vendedores que atuam em múltiplas lojas. Para isso, o mesmo codigo_vendedor pode aparecer em várias linhas, cada uma com um codigo_loja diferente.

Regras para o Multilojas:

O cargo do vendedor deve ser o mesmo em todas as linhas (lojas).
Cada linha representa um vínculo único entre vendedor e loja.
O status (ATIVO/INATIVO) é controlado por linha, permitindo que um vendedor esteja ativo em uma loja e inativo em outra.

Cenário de concatenação (COD_LOJA:COD_VEND)

Para marcas que utilizam o código do vendedor concatenado com o código da loja nos eventos de compra, as seguintes regras se aplicam à importação:

O campo codigo_vendedor no CSV deve conter exatamente o código concatenado.
Neste cenário, cada vendedor só pode estar associado a uma única loja por linha.
O cadastro multiloja (várias linhas para o mesmo código concatenado) não é permitido.

Logs e acompanhamento da Lista de Importações

Após enviar um arquivo, um registro é criado automaticamente na Lista de Importações, exibindo em tempo real o andamento do processo.

A lista exibe:

Nome do arquivo
Usuário que importou
Data da importação
Status (Ex: Processando, Concluído, Inválido)
Quantidade de linhas com erro
Quantidade total de linhas
Botão para baixar log de erros (disponível apenas para status Inválido)

Arquivo de Log (CSV de erros)

Quando o status da importação for Inválido, você poderá baixar um arquivo de log em formato CSV. Este arquivo contém apenas as linhas que apresentaram erro, com uma coluna adicional indicando a descrição do problema encontrado. Linhas válidas não aparecem no log.

Materiais de Apoio

FAQ – Perguntas Frequentes

1. Pergunta: Se eu remover um vendedor que já está inativo do meu arquivo CSV, o que acontece?
Resposta: Como o processamento é Full Load (substituição total), se um vendedor não está presente no arquivo, ele será atualizado para INATIVO, mesmo que já estivesse com esse status. É crucial que o arquivo sempre contenha a lista completa de vendedores que devem permanecer ATIVOS.

2. Pergunta: Se meu arquivo tem 10.000 linhas e apenas uma está com o CPF incorreto, qual é o resultado?
Resposta: O resultado será INVÁLIDO. O sistema rejeitará o arquivo completamente e nenhuma das 10.000 linhas será processada. Nenhuma alteração será feita na sua base. Você deve baixar o log de erros, corrigir a linha e reenviar o arquivo completo.

3. Pergunta: Como o sistema identifica um vendedor multiloja?
Resposta: A identificação é feita pela combinação única de codigo_vendedor + codigo_loja. Um vendedor é reconhecido como o mesmo indivíduo pelo seu codigo_vendedor, e cada linha no CSV define uma associação (e um status) com uma loja específica.

4. Pergunta: O que acontece se eu enviar no CSV uma loja que ainda não existe na Dito?
Resposta: O sistema irá criar a nova loja automaticamente, utilizando o codigo_loja e o nome_da_loja informados na linha do CSV. Isso garante que o vendedor seja associado à unidade correta, mesmo que ela seja nova.

5. Pergunta: Se eu enviar um vendedor multiloja com cargos diferentes (Ex: Vendedor na Loja A e Gerente na Loja B), o que acontecerá?
Resposta: O arquivo será rejeitado. A regra de validação exige que um mesmo vendedor (identificado pelo seu codigo_vendedor) possua um único cargo (VENDEDOR ou GERENTE) em todos os seus vínculos com as lojas.

Ficou com alguma dúvida ou identificou algum problema? Acione nosso time pelo chat disponível no app dito. (Horário de Atendimento de Segunda a Sexta das 9hrs as 18hrs)