Importação de arquivos e fontes de dados
Se os seus clientes já estão em outro sistema (CRM, sistema de gestão, planilha), não é preciso esperar que eles apareçam no site: envie um arquivo. O envio pontual de perfis a partir de um CSV ou Excel é feito pela importação, e o carregamento regular de perfis e eventos a partir de um arquivo por URL, do S3, de uma Planilha Google ou do seu data warehouse, pelas fontes de dados.
As duas ferramentas estão disponíveis para “Proprietário”, “Administrador” e “Gerente”.
Importação de perfis a partir de CSV e Excel
Abra Dados → Importação de perfis no menu ou clique em Importação de perfis no cabeçalho da página Perfis.
Requisitos do arquivo
- CSV ou Excel (.xlsx, .xls — a primeira planilha) com os cabeçalhos das colunas na primeira linha.
- Separador: vírgula, ponto e vírgula ou tabulação, detectado automaticamente.
- Tamanho: CSV até 20 MB, Excel até 10 MB.
- Pelo menos uma coluna com identificador: id do cliente no seu sistema, e-mail ou telefone.
- No Excel, células com formato de data são carregadas como
2026-10-28 18:42:00, e fórmulas, pelo valor. Arquivos do Excel 95 e arquivos protegidos por senha não são aceitos: salve-os como .xlsx ou CSV.
Exemplo:
email;phone;first_name;city;customer_id;bonus
[email protected];+55 11 91234-5678;Ana;São Paulo;1001;350
Como enviar
- Clique em Escolher um arquivo e selecione o arquivo.
- A tabela mostra as colunas do arquivo, exemplos de valores e o campo Destino. Para cada coluna, indique:
- Identificador: User ID, E-mail, Telefone ou Anonymous ID: por ele o perfil é encontrado ou criado. Cada tipo pode ser escolhido uma única vez.
- Atributo: uma propriedade do perfil; ao lado, informe a chave em letras latinas, por exemplo
cityoubonus_balance. - Ignorar: a coluna não é carregada.
- Clique em Iniciar importação.
O OneTrace.pro sugere o destino pelos cabeçalhos: email vira e-mail; cabeçalhos com phone ou mobile viram telefone; customer_id e user_id viram User ID; os nomes de coluna usuais em russo e ucraniano para nome, sobrenome, cidade e país viram os atributos first_name, last_name, city e country. Os demais cabeçalhos viram chaves de atributo em letras minúsculas latinas, com os outros caracteres trocados por sublinhado. Confira as sugestões antes de iniciar.

Andamento da importação
A importação roda em segundo plano: a página mostra uma barra de progresso, o status e o contador “processados N de M, erros: K”. Você pode fechar a página, e a importação continua. As linhas com erro são listadas com os respectivos números. Quando a importação termina, o botão Abrir perfis leva à lista de perfis.
À direita, no bloco Histórico, ficam as 20 últimas importações: arquivo, quem enviou e quando, status (“Enviado”, “Na fila”, “Processando”, “Concluído”, “Falhou”) e resultado.

Como as linhas são processadas
- Se já existir um perfil com esse identificador, ele é atualizado: atributos novos são adicionados, e os que coincidem são sobrescritos. Se uma linha contiver identificadores de dois perfis diferentes, os perfis são mesclados; veja Perfis.
- Células vazias são ignoradas e não apagam valores já conhecidos.
- Números e
true/falsesão salvos como números e valores lógicos. - O e-mail e o telefone do arquivo viram tanto identificadores quanto atributos do perfil.
- Espaços, parênteses e hifens são removidos do telefone. Informe-o com o código do país:
+7 999 123-45-67. Um número como8 999…será salvo com o código errado. - Uma linha sem nenhum identificador válido é ignorada com erro.
A importação cria o evento $identify para cada linha, então as mudanças de atributos podem disparar jornadas com gatilho de alteração de atributo. Se não quiser isso, pause essas jornadas durante a importação.
Fontes de dados
Uma fonte é uma importação regular, conforme agendamento. É útil quando o CRM ou o estoque publica toda noite uma exportação atualizada: o OneTrace.pro a busca sozinho e atualiza os perfis ou adiciona eventos.
Preparação
Primeiro, crie a conexão na seção Integrações (é preciso ter a função “Administrador” ou “Proprietário”):
- Arquivo por URL: um arquivo em um endereço HTTP(S). Se o arquivo for protegido, informe o cabeçalho de autorização, por exemplo
Bearere o token. - Arquivo do S3: bucket da AWS, do Yandex Object Storage, do MinIO e de outros armazenamentos compatíveis.
- Planilha do Google: pela chave de uma conta de serviço do Google. Dê a essa conta acesso de leitura à planilha.
- PostgreSQL, ClickHouse, BigQuery ou Snowflake: uma tabela ou consulta no seu data warehouse; veja Data warehouse.
Formatos de arquivo: CSV, JSON (array de objetos, até 50 MB) e JSON Lines.
Como criar uma fonte
- Abra Dados → Fontes de dados e clique em Nova fonte de dados.
- Informe o Nome e escolha a Conexão.
- Preencha as configurações da conexão: URL do arquivo e Formato, Caminho do arquivo no bucket ou ID da planilha e Intervalo (por exemplo,
Página1!A:F). - Clique em Carregar colunas: o OneTrace.pro lê as primeiras linhas.
- No campo Importar como, escolha Perfis (cada linha atualiza atributos) ou Eventos (cada linha é um evento).
- Escolha o Agendamento: de a cada 15 minutos até uma vez por dia.
- Na tabela Colunas, indique o destino de cada coluna, como na importação de CSV.
- Clique em Salvar.

Para eventos, a tabela de colunas também tem Nome do evento, Propriedade do evento e Horário do evento. A coluna de horário é obrigatória. Defina um único nome de evento para todas as linhas no campo Nome do evento (por exemplo, order_completed) ou escolha a coluna em que ele está.
Para os cupons das lojas, há o modelo Cupons das lojas com um arquivo de exemplo: ele preenche o evento de compra, a propriedade de compra na loja e as dicas de coluna (telefone, cartão de fidelidade, loja, número do cupom, valor e produtos). Veja Lojas e vendas offline.
Funcionamento da fonte
O cartão da fonte mostra o status (“Ativa”, “Pausada”, “Com erro”), o agendamento, o horário da última execução e o resultado: linhas, aceitas, ignoradas, com erro.
- Executar agora: execução fora do agendamento. Também tira a fonte da pausa e do erro.
- Pausar / Retomar: interromper e retomar as execuções agendadas.
- Histórico: lista de execuções, com início, forma de acionamento (“Programado” ou “Manual”), status e os primeiros erros de linha com os respectivos números.

O que é importante saber
- Se o arquivo não mudou desde a última vez, a execução termina com o status “Sem alterações”, e as linhas não são lidas.
- Repetir a mesma linha em até 24 horas não cria duplicatas.
- Para eventos, fica registrado o horário do último evento carregado: as execuções seguintes ignoram as linhas que não forem mais recentes que ele. Por isso, um arquivo de histórico pode simplesmente ser complementado.
- Uma fonte com erro é repetida conforme o agendamento, e o texto do erro aparece no cartão.
- Os eventos carregados contam para a cota mensal do plano.
- Ao excluir a fonte, os dados já carregados são mantidos.
Data warehouse
Se os perfis e pedidos já estão reunidos no seu data warehouse (PostgreSQL, ClickHouse, BigQuery ou Snowflake), a fonte os lê diretamente de lá. Cada execução busca só as linhas alteradas desde a última vez, por isso nem uma tabela grande precisa ser exportada para um arquivo. As alterações chegam aos perfis e eventos, que disparam jornadas e recalculam segmentos. A direção inversa é a exportação para data warehouses.
A leitura de data warehouses está disponível no plano “Empresarial”; veja Planos.
Conexão
Crie a conexão na seção Integrações, no grupo Fontes de dados. Os campos são os mesmos da exportação para esse data warehouse, mas é melhor criar um usuário separado, só de leitura:
- PostgreSQL: host, porta, banco de dados, usuário com permissão
SELECTnas tabelas necessárias. - ClickHouse: endereço da interface HTTP, usuário com permissão de leitura.
- BigQuery: chave da conta de serviço com as funções BigQuery Data Viewer e BigQuery Job User, projeto e local dos dados.
- Snowflake: conta, usuário com par de chaves, função com permissão
SELECTe warehouse de processamento. Para a leitura, o bucket do S3 não é necessário.
O data warehouse deve estar acessível pela internet: o OneTrace.pro não abre endereços de redes internas.
Configurações da fonte
Crie a fonte como descrito acima e escolha a conexão com o data warehouse. As configurações dela:
- O que ler: Tabela (por exemplo,
public.customersoushop_dwh.customers) ou Consulta própria, ou seja,SELECTouWITHem um único comando, sem;. O OneTrace.pro adiciona à consulta uma condição, a ordenação e um limite de linhas, por isso não é possível alterar dados por meio dela. - Coluna de cursor: o horário de alteração da linha, por exemplo
updated_at. Cada execução lê as linhas em que esse horário é posterior ao da execução anterior. Linhas sem esse horário não são lidas. - Chave da linha: uma coluna única, por exemplo
idoucustomer_id. Ela diferencia as linhas com o mesmo horário de alteração. - Coluna de indicador de exclusão: opcional, por exemplo
is_deleted. Veja Exclusão.

O resto é como para um arquivo: Carregar colunas, destino das colunas, perfis ou eventos, agendamento.
Como as alterações são lidas
- A primeira execução lê a tabela inteira; as seguintes, só as linhas alteradas depois da última lida.
- Uma execução lê no máximo 1 milhão de linhas. Se houver mais, a próxima execução começa na hora, sem esperar o agendamento. Assim, a primeira carga de uma tabela grande é feita em várias execuções seguidas.
- Se uma execução for interrompida, as mesmas linhas serão lidas de novo: os perfis apenas são atualizados mais uma vez, e os eventos repetidos não são duplicados.
- Trocar a tabela, a consulta, a coluna de cursor ou a chave faz a leitura recomeçar do início.
- A coluna de horário de alteração deve ser atualizada pelo seu data warehouse: o OneTrace.pro não relê uma linha cujo horário não mudou.
- A consulta roda somente para leitura e com limite de tempo: 10 minutos no PostgreSQL, no ClickHouse e no Snowflake, 15 minutos no BigQuery.
Exclusão
Se, em uma linha de uma fonte de perfis, a Coluna de indicador de exclusão tiver true ou 1, o OneTrace.pro exclui o perfil com os identificadores dessa linha, como em um pedido de GDPR: junto com o histórico, os perfis mesclados e os dados nas exportações. A exclusão é registrada no log de auditoria, e o resultado da execução mostra quantos perfis foram excluídos. Em uma fonte de eventos, as linhas com o indicador são simplesmente ignoradas.
Para uma migração única do Mindbox e de outras plataformas, com o histórico, existe uma ferramenta separada; veja Migração de outras plataformas.