Visão geral
A importação traz clientes de planilhas (.xlsx, .xls, .csv) em lote - ideal para migração de sistema antigo ou cadastro inicial. A exportação baixa a base atual para Excel - útil para backup, análise ou envio ao contador.
Legenda: Arraste a planilha ou clique para selecionar (até 10 MB, 2.000 linhas).
Quando utilizar
Importar:
- Migração de outro sistema/planilha
- Cadastro inicial em massa
- Atualização periódica de lista externa (ex: leads de marketing)
Exportar:
- Backup periódico da base
- Análise no Excel (filtros avançados, tabelas dinâmicas)
- Envio para contador/parceiro
- Mala direta / segmentação externa
Como importar
1. Preparar a planilha
Formatos aceitos: .xlsx (recomendado), .xls, .csv
Limites: até 10 MB e 2.000 linhas por importação
Colunas sugeridas (cabeçalhos):
| Coluna na planilha | Campo no sistema | Obrigatório? |
|---|---|---|
| Nome / Razão Social | name | Sim |
| Não | ||
| Celular / WhatsApp | phone | Não |
| Telefone Fixo | phone_fixed | Não |
| CPF | cpf | PF: sim |
| CNPJ | cnpj | PJ: sim |
| RG | rg | Não |
| IE / Inscrição Estadual | inscricao_estadual | PJ: não |
| Nome Fantasia | nome_fantasia | PJ: não |
| Inscrição Municipal | inscricao_municipal | Não |
| CRT (1/3/4) | crt | PJ: não |
| Contribuinte (1/2/9) | contribuinte | PJ: não |
| CEP | zip_code | Não |
| Endereço / Rua | street | Não |
| Número | number | Não |
| Complemento | complement | Não |
| Bairro | neighborhood | Não |
| Cidade | city | Não |
| UF / Estado | state | Não |
| Tipo Endereço (Casa/Apto/Comercial) | address_type | Não |
| Data Nascimento | birth_date | Não |
| Observações | notes | Não |
| Status (Ativo/Inativo/Bloqueado) | status | Não |
| Tipo Pessoa (PF/PJ) | person_type | Não |
Dica
> Não precisa ter todas as colunas. O sistema mapeia o que você enviar. Colunas não mapeadas são ignoradas.
2. Fazer o upload
- Em Clientes, clique em Importar (botão no cabeçalho).
- Arraste o arquivo ou clique em Selecionar Planilha.
- Aguarde a leitura - mostra total de linhas e colunas detectadas.
3. Revisar o mapeamento
O sistema sugere mapear cada coluna da planilha para um campo do cadastro:
- Confiança - badge colorido: Exato (verde) · Alto (azul) · Médio (laranja) · Baixo (vermelho)
- Ajuste manualmente se o sistema errou
- Colunas sem mapeamento = Ignorada (não importa)
Legenda: Cada linha = coluna da planilha. Escolha o campo do sistema no dropdown.
Campos obrigatórios do sistema (marcados com * no dropdown): `Nome`, `CPF` (se PF), `CNPJ` (se PJ).
4. Preview e importar
- Clique Continuar → abre Preview com os primeiros clientes como ficarão.
- Confira: nomes, documentos, e-mails, endereços.
- Opções antes de importar:
- Pular duplicatas (recomendado ON) - ignora linhas com CPF/CNPJ/e-mail já cadastrados
- Pular erros (recomendado ON) - importa o que der certo, pula linhas com erro de validação
- Clique Importar X cliente(s).
5. Resultado
Tela de sucesso mostra: X de Y clientes importados.
- Botão Ver Clientes → volta para lista
- Botão Nova Importação → repete o processo
Como exportar
Exportar tudo (com filtros atuais)
- Na lista de Clientes, clique Exportar no cabeçalho.
- Modal abre com seleção de colunas (todas marcadas por padrão).
- Desmarque colunas que não quer (ex: `mother_name`, `father_name`).
- Clique Exportar → baixa `.xlsx`.
Dica
> A exportação respeita aba ativa, busca, filtros e ordenação atuais. Para exportar só ativos: aba "Ativo" > Exportar.
Exportar seleção
- Marque clientes na tabela (checkbox) ou grade (seleção múltipla).
- Na barra flutuante inferior, clique Exportar > Selecionados.
- Escolhe colunas > Exportar.
Dicas importantes
- Exporte antes de importar em massa - backup da base atual.
- Limpe a planilha antes - remova linhas vazias, corrija CPF/CNPJ inválidos, padronize telefone (DDD + número).
- Use "Pular duplicatas" - evita erro se rodar a importação duas vezes.
- CPF/CNPJ são chaves únicas - o sistema usa eles (e e-mail) para detectar duplicatas.
- Importação só CRIA - não atualiza clientes existentes. Para atualizar em massa, edite individualmente ou use API.
- Endereços - a importação cria endereço principal; endereço de cobrança diferente não é suportado na importação (cadastre depois manualmente).
Problemas comuns
| Problema | Causa | Solução |
|---|---|---|
| "Erro ao processar arquivo" | Arquivo corrompido, senha, ou formato não suportado | Salve como .xlsx padrão; remova senha; evite .ods |
| Linhas não importadas | Validação falhou (CPF inválido, e-mail malformado) | Ative "Pular erros"; revise linhas no preview; corrija planilha |
| Duplicatas não puladas | CPF/CNPJ com formatação diferente (pontos/tracos) | O sistema normaliza (só números); confira se realmente igual |
| Exportação vazia | Filtro/aba restritiva demais | Limpe busca, filtros, mude para aba "Todos" |
| Planilha > 2.000 linhas | Limite de segurança | Divida em vários arquivos de ≤ 2.000 linhas |
Perguntas frequentes
Posso importar clientes com endereço de cobrança diferente?
Não na importação padrão. Importe o endereço principal; depois edite cada cliente e marque "Endereço de cobrança diferente".