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 é feito pela importação, e o carregamento regular de perfis e eventos a partir de um arquivo por URL, do S3 ou de uma Planilha Google, 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

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 com os cabeçalhos das colunas na primeira linha.
  • Separador: vírgula, ponto e vírgula ou tabulação, detectado automaticamente.
  • Tamanho: até 20 MB.
  • Pelo menos uma coluna com identificador: id do cliente no seu sistema, e-mail ou telefone.

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 CSV 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.

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á.

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.

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.

← Eventos e catálogo de eventos Migração de outras plataformas →