Importações

A importação cria ou atualiza registros em lote a partir de um arquivo: uma planilha CSV para a maioria dos tipos, ou um arquivo bancário (remessa, retorno, OFX) para alguns deles. O arquivo é processado em segundo plano, e o resultado de cada linha fica registrado no Histórico de Importações.

Onde fica no painel

• Cadastrar > Importar: um item para cada tipo de importação.
• CRM > Importar Clientes.
• Botão Importar no topo das listas de boletos, clientes e outras.
• Administração > Históricos > Importações: histórico de todas as importações da conta. O ícone de adição ao lado do título Importações abre o mesmo menu de tipos.

Tipos de importação

Tipo	Formatos aceitos
Boletos	.csv, .rem, .txt
Clientes	.csv
Assinaturas	.csv
Carnês	.csv
Pix	.csv
Transferências	.ret, .csv
Pagamentos de Boletos	.csv
Pagamentos de Contas de Consumo	.csv
Pagamentos de Darf	.csv
Pagamentos de GRU Simples	.csv
Pagamentos de Pix	.csv
Pagamentos de ISS	.csv
Extratos	.ret, .ofx, .json (pela conta financeira)

A tela de cada importação mostra os formatos aceitos abaixo da área de envio do arquivo.

Tela de importação

A tela explica o formato aceito e, para planilhas, oferece arquivos de exemplo:

• Baixar Exemplo em CSV
• Baixar Exemplo em Excel
• Acessar no Google Sheets

A tela também mostra uma prévia de uma planilha de exemplo e o mesmo exemplo em CSV.

Passo a passo

1. Abra a tela do tipo de importação (por exemplo, Cadastrar > Importar > Importar Clientes).
2. Arraste o arquivo para a área de envio ou selecione-o.
3. Confira a Pré-visualização do arquivo. Se o arquivo não for válido, a tela avisa "O arquivo não é válido e não pode ser importado."
4. Clique no botão de iniciar a importação.

O painel responde "Arquivo enviado com sucesso, sua importação será finalizada em alguns minutos." e abre o Histórico de Importações.

Regras da planilha CSV

• A primeira linha é o cabeçalho com os nomes das colunas. As demais linhas são os registros.
• O separador pode ser vírgula (,) ou ponto e vírgula (;): o painel identifica qual dos dois a primeira linha usa.
• Campos de texto podem vir entre aspas (") quando o conteúdo tem vírgula ou quebra de linha.
• A ordem das colunas não importa. O painel reconhece cada coluna pelo nome do cabeçalho, sem diferenciar maiúsculas de minúsculas.
• Se faltar uma coluna obrigatória no cabeçalho, a importação inteira é abortada.
• Uma linha com dado incorreto não é importada, e o erro aparece no detalhe da importação. As outras linhas são importadas normalmente.
• Para apagar o valor de um campo na atualização de um registro, escreva NULL na célula. Isso vale para as importações de boletos, clientes, assinaturas, carnês e Pix.
• O arquivo pode ter até 10 MB (planilha CSV, remessa, retorno ou OFX).

Importar clientes

Colunas obrigatórias no cabeçalho: nome, CPF/CNPJ, e-mail, CEP, endereço, bairro, cidade e estado. As células de e-mail podem ficar vazias, mas a coluna precisa existir.

Para cada linha, o painel procura o cliente pelo ID (se a coluna existir e estiver preenchida) ou pelo CNPJ/CPF. Se encontra, atualiza o cadastro; se não encontra, cria um cliente novo. Uma linha que só traz ID ou CPF/CNPJ, sem nenhum outro dado, é registrada como erro ("Nenhum dado para atualizar").

Coluna no cabeçalho	Campo do cliente
ID	Identifica o cliente a atualizar
Nome, Razão Social, Nome do Cliente	Nome/Razão Social
Apelido, Nome Fantasia	Apelido/Nome Fantasia
CPF, CNPJ, CNPJ/CPF	CNPJ/CPF
E-mail	E-mail
E-mail opcional	E-mail opcional
Telefone	Telefone
DDD Celular, Celular (DDD)	Celular (DDD)
Número Celular, Celular	Celular
CEP	CEP
Endereço	Endereço
Endereço para remessa	Endereço para remessa
Número	Número
Complemento	Complemento
Bairro	Bairro
Cidade	Cidade
Estado, UF	Estado
Observações	Observações
Contato	Contato
Código externo	Código externo
Tags, Etiquetas	Etiquetas (Tags)
Dados Personalizados	Dados personalizados, em JSON
Data de Nascimento	Data de Nascimento
Nunca enviar e-mail para este cliente	Bloqueio de e-mail
Nunca enviar SMS para este cliente	Bloqueio de SMS
Nunca enviar Whatsapp para este cliente	Bloqueio de Whatsapp

Cada linha passa pelas mesmas validações do cadastro feito no painel (veja Clientes).

Importar boletos

Colunas obrigatórias no cabeçalho: vencimento, valor e descrição. Os nomes aceitos incluem Vencimento, Valor ou Quantia, e Descrição ou Demonstrativo. A planilha de exemplo da tela traz as demais colunas aceitas, como carteira, dados do pagador, instruções e etiquetas.

Uma linha com a coluna ID preenchida com o ID de um boleto existente atualiza esse boleto em vez de criar um novo.

A importação de boletos também aceita arquivo de remessa (.rem) no formato CNAB 240 ou CNAB 400.

Acompanhar a importação

O Histórico de Importações lista as importações da conta com as colunas ID, Nome do Arquivo, Tipo, Criado em, Importação finalizada em e Situação. O ícone de olho abre o detalhe.

O detalhe tem duas abas:

• Dados: situação, quantidade de linhas processadas, registros afetados (criados, atualizados e falhas) e a lista de erros por linha, no formato Registro "N" seguido das mensagens de cada campo.
• A aba com o nome do tipo (por exemplo, Clientes ou Boletos): os registros que a importação criou ou atualizou.

O detalhe atualiza sozinho enquanto a importação é processada.

Situações

Situação	Significado
Pendente	Arquivo recebido, aguardando processamento.
Enviado pra fila	Aguardando a vez de ser processado.
Iniciado	Em processamento.
Finalizado	Processamento concluído. Pode haver linhas com erro.
Abortado	O arquivo não pôde ser processado (por exemplo, coluna obrigatória faltando ou arquivo ilegível). A mensagem de erro aparece no detalhe.
Erro Fatal	Erro inesperado. A tela orienta a contatar o suporte.
Tentando novamente	A importação está sendo processada de novo depois de uma falha.
Tentativas Esgotadas	As novas tentativas de processamento falharam. A tela orienta a contatar o suporte.

Uma importação que não começa a ser processada em até 24 horas depois de criada é abortada com a mensagem "Importação criada há mais de 24 horas. Por favor, inicie uma nova importação."

Alertas

Ao terminar, a importação gera um alerta em Administração > Históricos > Alertas (veja Históricos):

Resultado	Severidade	Título do alerta
Todas as linhas importadas	Info	"Importação de ... realizada com sucesso"
Parte das linhas com erro	Aviso	"Importação de ... realizada parcialmente"
Importação abortada	Crítico	"Erro na importação de ..."

Permissões

• Importar exige a ação Importar no produto do tipo importado. Por exemplo: CRM > Clientes para clientes, Recebimentos > Boletos para boletos.
• Ver o histórico e o detalhe das importações exige Ações Básicas em Sistema > Histórico de Importações.

Eventos de webhook

Código	Quando ocorre
import.created	Importação criada.
import.processed	Importação chegou a uma situação final (Finalizado, Abortado, Tentativas Esgotadas ou Erro Fatal).
import.deleted	Importação excluída.

Os registros criados pela importação disparam os próprios eventos (por exemplo, customer.created). Veja Eventos de webhook.

Pela API

Importações podem ser criadas e consultadas pela API v1 e pela API v2.