Importação por planilha
A página Importações sobe a sua carteira por arquivo CSV: primeiro os clientes, depois as cobranças. O processamento roda em segundo plano, linha a linha — linhas com erro não derrubam o restante da planilha.
Formato do arquivo
O formato é o CSV brasileiro do dia a dia, sem exigências exóticas:
- Separador: ponto e vírgula (
;) ou vírgula (,) — detectado automaticamente. - Valores: formato brasileiro, como
1.234,56. - Datas:
DD/MM/AAAAouAAAA-MM-DD. - Cabeçalho: obrigatório na primeira linha; os nomes de coluna não diferenciam maiúsculas de minúsculas. Colunas extras são ignoradas.
O botão Baixar modelo na própria página gera um CSV de exemplo já no formato certo para o tipo selecionado.
Colunas — clientes
| Coluna | Obrigatória | Observação |
|---|---|---|
nome | sim | |
documento | não | CPF (11 dígitos) ou CNPJ (14); pontuação é ignorada |
email | não | vira o e-mail principal |
telefone | não | vira o telefone principal |
external_id | não | ID do cliente no seu sistema |
apelido, observacoes | não | |
tags | não | separadas por ; dentro da célula |
Colunas — cobranças
| Coluna | Obrigatória | Observação |
|---|---|---|
valor | sim | formato brasileiro (1.250,00) |
vencimento | sim | DD/MM/AAAA ou AAAA-MM-DD |
documento_cliente ou external_id_cliente | uma das duas | identifica o cliente dono da cobrança |
descricao, numero_documento, external_id | não | |
juros, multa, desconto | não | somados/subtraídos no valor atual |
emissao | não | padrão: data da importação |
Importe clientes antes de cobranças: a linha de cobrança que referencia um cliente inexistente é rejeitada com o erro "Cliente não encontrado — importe os clientes antes". Cobranças importadas entram com origem planilha e já com o status certo (Pendente ou Vencida, conforme o vencimento).
Deduplicação
Na importação de clientes, o sistema nunca duplica cadastros. Para cada linha ele procura um cliente existente primeiro pelo external_id; se não houver, pelo documento. Encontrou: a linha atualiza o cadastro existente (só os campos preenchidos). Não encontrou: cria. Linhas repetidas dentro do próprio arquivo também são deduplicadas.
Acompanhamento e erros por linha
Depois do upload, a importação aparece na tabela com status (Na fila → Processando → Concluída ou Falhou) e o resultado: quantos registros criados, quantos atualizados e quantos erros. A tela se atualiza sozinha enquanto há processamento em andamento, e você recebe uma notificação no sino quando termina.
Se houver erros, o link Ver erros abre a lista completa, linha por linha, com o número da linha na planilha original e o motivo ("Coluna 'valor' inválida", "Coluna 'nome' é obrigatória"...). Corrija só as linhas rejeitadas e importe novamente apenas elas — as demais já entraram.
LGPD: o arquivo não fica retido
O conteúdo do CSV contém dados pessoais (nomes, documentos, contatos). Por isso, assim que o processamento termina — com sucesso ou falha — o conteúdo do arquivo é apagado do sistema. Ficam apenas os metadados da importação (nome do arquivo, contagens, lista de erros por linha), que são o que você precisa para auditar e corrigir.