O botão “importar Excel” parece pequeno no escopo, mas frequentemente concentra regras que a operação levou anos para aprender. Uma coluna vazia pode significar ausência, zero ou manutenção do valor atual. Um código com zeros à esquerda pode ser uma identificação, não um número. Uma data pode mudar de interpretação conforme o formato.
Uma importação profissional transforma dados com regras explícitas, permite revisão e preserva a origem de cada alteração. O objetivo não é aceitar qualquer arquivo: é ajudar o usuário a corrigir problemas antes de contaminar a base.
1. Defina o contrato do arquivo
Publique um modelo com versão, colunas, obrigatoriedade, tipo e exemplos. Informe se a operação cria, atualiza ou faz ambos. Documente a chave usada para localizar registros e o significado de células vazias. Não deixe essas decisões implícitas na implementação.
O modelo deve incluir uma aba de instruções e exemplos fictícios. Se o sistema também exporta uma planilha para reimportação, mantenha identificadores estáveis e avise quais colunas são editáveis. Colunas de total calculado não devem virar fonte oficial por acidente.
| Tipo de campo | Regra recomendada | Exemplo de falha |
|---|---|---|
| Identificador | Texto e formato conhecido | Código 0012 vira 12 |
| Data | Formato inequívoco e fuso quando necessário | 03/04 interpretado de duas maneiras |
| Dinheiro | Moeda e separadores definidos | 1.234,56 vira outro valor |
| Referência | Cadastro de destino existente | Produto ligado ao fornecedor errado |
| Vazio | Semântica por operação | Campo apagado sem intenção |
2. Separe leitura e gravação
Receba o arquivo em uma área temporária e atribua um identificador ao lote. Faça a leitura e a validação antes de alterar registros definitivos. A prévia deve mostrar quantidade de criações, atualizações, rejeições e conflitos. O usuário precisa reconhecer o impacto.
A estrutura típica é: arquivo recebido, formato reconhecido, linhas normalizadas, regras verificadas, prévia aprovada e lote aplicado. Para volumes grandes, essas etapas podem ocorrer em tarefas assíncronas. O navegador acompanha o estado; fechar a aba não deve interromper uma operação que já foi assumida pelo servidor.
3. Normalize sem destruir informação
Remover espaços externos de um nome pode ser aceitável; retirar todos os espaços de um código pode alterar sua identidade. Crie normalizações por campo, preserve o valor original para investigação quando apropriado e apresente transformações relevantes na prévia.
Não execute macros nem fórmulas recebidas. Ao exportar dados controlados por usuários, trate valores que uma planilha possa interpretar como fórmula conforme o formato e o consumidor. Um arquivo visualmente simples continua sendo uma entrada não confiável. Limite tamanho, número de linhas e descompressão de formatos compactados.
4. Valide em diferentes níveis
Primeiro confira estrutura e tipos. Depois, relações entre campos: data final anterior à inicial, desconto maior que o permitido ou unidade incompatível. Em seguida, valide referências e permissões. Por fim, procure conflitos entre o lote e o estado atual da base.
Não dependa apenas do frontend. O servidor precisa reaplicar as regras, e o banco deve impor invariantes essenciais. A documentação de restrições do PostgreSQL explica mecanismos para integridade; o desenho das regras permanece específico ao sistema.
5. Defina o tratamento de duplicidades
Distinga duplicidade dentro do arquivo, repetição de um lote anterior e colisão com um cadastro já existente. Cada situação exige uma resposta. Um mesmo cliente pode aparecer em várias linhas por possuir vários endereços; removê-lo automaticamente por nome pode eliminar informação legítima.
Uma chave de importação deve considerar a organização e o domínio. O código de produto de uma empresa não deve atualizar o produto de outra. Ao repetir um lote, exiba o histórico e exija uma intenção clara: retomar, corrigir ou realizar nova operação. Um hash pode ajudar a reconhecer arquivos, mas não define sozinho a semântica.
6. Escolha a política de aplicação
Em cargas pequenas e dependentes, uma transação única pode garantir tudo ou nada. Em cargas grandes, lotes menores reduzem bloqueios, mas exigem acompanhamento de resultados parciais. O usuário deve saber qual política foi escolhida antes de confirmar.
A operação COPY do PostgreSQL oferece recursos para transporte de dados, mas velocidade de carga não substitui validação, autorização e revisão. Não entregue ao usuário privilégios amplos de banco para resolver um requisito de importação.
7. Exemplo de prévia útil
Imagine, de forma hipotética, um arquivo de 2.000 linhas de produtos. A prévia informa 1.500 criações, 400 atualizações, 70 referências ausentes e 30 conflitos de código. Os erros podem ser baixados com número da linha, coluna, valor recebido, motivo e orientação de correção.
O botão de confirmação deve indicar claramente se aplicará somente as 1.900 linhas válidas ou se o lote exige correção integral. Um resumo “100 erros” sem indicar onde estão transfere o trabalho para o suporte. Uma mensagem boa permite corrigir o arquivo sem conhecer o banco.
8. Preserve autoria e possibilidade de compensação
Registre quem enviou e confirmou o lote, versão do modelo, quantidade aplicada e alterações relevantes. Para permitir desfazer, avalie o que aconteceu depois: um produto recém-importado já pode ter sido usado em uma venda. Apagar indiscriminadamente o lote não é uma reversão segura.
Uma compensação pode restaurar determinados campos ou inativar cadastros ainda não utilizados, mediante regras. Se não houver reversão automática confiável, ofereça um procedimento de correção com prévia. Evite prometer um botão universal de desfazer.
Checklist de homologação
- Arquivo vazio, cabeçalho errado e versão desconhecida.
- Identificadores com zeros, acentos e caracteres especiais.
- Datas ambíguas, números negativos e separadores locais.
- Referência inexistente e acesso a outra organização.
- Linhas repetidas e reenvio do mesmo lote.
- Queda durante a aplicação e retomada controlada.
- Relatório de erros que permita correção real.
- Teste de compensação sem apagar relações posteriores.
Checklist para usar com sua equipe
Baixe o checklist editável em CSV e registre responsáveis, verificações e observações da implantação.
Perguntas frequentes
CSV é sempre melhor que Excel?
Não. CSV simplifica o formato, mas exige convenções de codificação, delimitador e tipos. Excel facilita modelos e instruções, porém requer tratamento seguro e atenção à interpretação das células.
Devo importar tudo de uma vez?
Comece por uma amostra representativa com erros intencionais. Depois aumente o volume, medindo tempo, bloqueios e qualidade das mensagens.
O arquivo original deve ser guardado para sempre?
Não. Defina retenção e acesso compatíveis com a finalidade, sensibilidade e obrigações aplicáveis. O histórico técnico também precisa de política.
Se a equipe perde horas corrigindo cargas ou copiando dados manualmente, avalie a importação com a A2CR.
Autoria: Agência A2CR. Revisão editorial: 9 de novembro de 2026. Procedimentos e exemplo elaborados pela A2CR, com referências técnicas indicadas nas seções correspondentes.
