OneTrace.pro Central de ajuda

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

  1. Clique em Escolher um arquivo e selecione o arquivo.
  2. 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 city ou bonus_balance.
    • Ignorar: a coluna não é carregada.
  3. 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.

Importação de perfis: mapeamento das colunas do arquivo

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.

Página de importação com o histórico de envios

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/false sã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 como 8 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 Bearer e 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

  1. Abra Dados → Fontes de dados e clique em Nova fonte de dados.
  2. Informe o Nome e escolha a Conexão.
  3. 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).
  4. Clique em Carregar colunas: o OneTrace.pro lê as primeiras linhas.
  5. No campo Importar como, escolha Perfis (cada linha atualiza atributos) ou Eventos (cada linha é um evento).
  6. Escolha o Agendamento: de a cada 15 minutos até uma vez por dia.
  7. Na tabela Colunas, indique o destino de cada coluna, como na importação de CSV.
  8. Clique em Salvar.

Configurações da fonte de dados com o mapeamento das colunas

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.

Fontes de dados: cartões com status e resultado das execuções

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 SELECT nas 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 SELECT e 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.customers ou shop_dwh.customers) ou Consulta própria, ou seja, SELECT ou WITH em 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 id ou customer_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.

Fonte do data warehouse BigQuery: tabela, cursor, chave da linha e colunas

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.