Como importar manualmente dados históricos de eventos
O que você vai aprender
Saiba como importar manualmente dados históricos de eventos para o Klaviyo. Embora recomendemos usar integrações criadas pelo Klaviyo com plataformas como Shopify, Magento e BigCommerce, além da nossa API para integrações personalizadas, também é possível adicionar esses dados manualmente. Um exemplo comum disso é adicionar dados históricos de compra de uma plataforma de e-commerce anterior para a qual o Klaviyo não tem uma integração predefinida.
Observe que há um limite de 50 MB para uploads de CSV.
Formate seus dados
O primeiro passo é formatar seus dados corretamente em um arquivo CSV. Use a primeira linha para os cabeçalhos das colunas. Cada linha restante deve representar uma ação ou atividade que alguém realizou, como "Comprou um produto" ou "Inscreveu-se no webinar." Se você tiver vários tipos de ações para acompanhar, faça upload delas como arquivos CSV separados. As colunas podem aparecer em qualquer ordem.
Aqui estão alguns CSVs de eventos de exemplo que você pode consultar ao formatar seus dados.
Campos obrigatórios
Os 2 campos obrigatórios são um carimbo de data/hora para identificar quando o evento ocorreu e uma propriedade do cliente (um e-mail ou um ID exclusivo) para identificar quem realizou a ação.
- Carimbo de data/hora: Um carimbo de data/hora que mostra o dia e a hora do evento. Use o formato YYYY-MM-DD HH:MM:SS. Por exemplo, 13:30 de 14 de novembro de 2012 seria: 2012-11-14 13:30:00.
Se 2 ou mais eventos da mesma pessoa e métrica tiverem o mesmo carimbo de data/hora, inclua um $event_id diferente para cada evento; caso contrário, apenas 1 será importado e o restante será ignorado. Consulte a seção sobre $event_id abaixo.
- Person//Email ou Person//ID: Muito provavelmente, você vai usar um e-mail para identificar seus clientes. Alguns clientes também vão usar um ID exclusivo. Você pode usar os dois, se quiser.
Campos opcionais
Há 2 campos especiais aos quais você deve ficar atento.
- $event_id: este é um identificador exclusivo do evento. Na prática, você deve enviar um
$event_idse tiver um identificador exclusivo para cada evento (por exemplo, um ID de pedido). Você também deve definir o$event_idse espera que vários eventos para a mesma pessoa e métrica ocorram ao mesmo tempo. Isso pode acontecer quando alguém realiza uma ação que você vai fazer uma divisão em vários eventos. Por exemplo, se alguém comprar vários itens, talvez você queira registrar 1 evento para cada item comprado.
Nos 2 conjuntos de dados de exemplo abaixo, há 1 evento Placed Order, junto com 3 eventos Ordered Product (1 para cada produto no pedido realizado). Todos esses eventos têm o mesmo timestamp, mas todos serão importados porque cada um tem um $event_id exclusivo. Se os 3 eventos Ordered Product tivessem valores de $event_id idênticos, ou não tivessem valores de $event_id, apenas 1 evento Ordered Product seria importado. O evento Placed Order pertence a uma métrica diferente e seria importado separadamente.


- $value: Use este campo se o evento que você estiver importando incluir um valor. Por exemplo, se você estiver importando dados do evento Placed Order, cada pedido terá um valor. Use apenas números, sem $ nem qualquer outro símbolo de moeda.
Se você tiver dados adicionais sobre a pessoa que fez algo, eles devem estar em uma coluna cujo rótulo começa com Person// e, em seguida, o tipo de dado que essa coluna contém. Por exemplo, se você tivesse a empresa ou organização à qual cada pessoa pertence, seria melhor rotular essa coluna como Pessoa//Organização. O prefixo especial nos informa que os dados nessa coluna devem ser associados a cada pessoa, e não à atividade. A seguir, estão algumas colunas especiais que você pode usar para ajudar a identificar pessoas:
- Pessoa//Nome: nome
- Pessoa//Sobrenome: sobrenome
- Pessoa//Telefone: número de telefone
- Pessoa//Organização: organização
- Pessoa//Cargo: cargo
Se você tiver dados adicionais sobre cada ação, poderá incluí-los em colunas extras com os rótulos que quiser. Por exemplo, se alguém comprar algo e você quiser incluir qual item a pessoa comprou, pode incluir esses dados em uma coluna com o rótulo Item comprado. A seguir, alguns exemplos.
- Item comprado
- Categoria do item
- Produto
- Local
Se você não tiver dados para uma coluna opcional específica, deixe-a em branco e nós vamos ignorá-la. Por exemplo, se você não souber a organização de alguém, pode deixar a coluna Person//Organization em branco e vamos ignorar o rastreamento dessa propriedade para essa linha nos seus dados.
Quando terminar de formatar seus dados, salve-os em um arquivo CSV.
Fazer upload de um arquivo CSV de dados
Para importar dados, sua função de usuário precisa ter permissão para gerenciar integrações.
- Na Klaviyo, selecione a aba Integrações.
- Selecione Gerenciar dados > Importar via CSV.
- Você será solicitado a fazer upload do seu arquivo CSV e, em seguida, clique em Próxima.
- Insira um nome em Nome do evento/ação. Para adicionar eventos a uma métrica de uma importação de CSV anterior, insira o nome exatamente como está. Corresponder ao nome de uma métrica de outra integração não adiciona dados a essa métrica por si só.
- Selecione o Fuso horário que corresponde aos carimbos de data/hora no seu arquivo. Se seus carimbos de data/hora estiverem em UTC, selecione UTC.

- Revise os nomes das colunas e a primeira linha de valores em Pré-visualize seus dados.
- Quando você estiver pronto para importar seus dados, clique em Próxima. Seu arquivo começará a ser processado, e você poderá sair da página.
- Quando o processamento terminar, confira o número de linhas enviadas. Clique em Concluído para voltar para Integrações.
Observação para loja e-commerce que carregam dados de compra
Se você estiver fazendo upload de dados de compra, você vai querer fazer upload de 2 arquivos: 1 para o pedido geral e um segundo que inclua os dados item por item. Por exemplo, um cliente pode fazer um pedido com vários produtos. Nesse caso, haveria 1 evento de Placed Order e, em seguida, eventos separados para cada um dos Ordered Products. Veja como, normalmente, os cabeçalhos desses arquivos devem ficar:
Pedido Realizado
Pessoa//E-mail | Pessoa//Nome | Pessoa//Sobrenome | Carimbo de data/hora | $event_id | $value | Quantidade | Itens |
John@gmail.com | John | Smith | 10-03-2014 08:55:01 | 12425 | 49,00 | 2 | ["To Kill a Mockingbird", "Pictionary"] |
Produto Encomendado
Pessoa//E-mail | Pessoa//Nome | Pessoa//Sobrenome | Carimbo de data/hora | $event_id | $value | Quantidade | Item |
John@gmail.com | John | Smith | 10-03-2014 08:55:01 | 12425_TKM | 24,00 | 1 | Para matar um sabiá |
John@gmail.com | John | Smith | 10-03-2014 08:55:01 | 12425_P | 25,00 | 1 | Pictionary |
Não usamos o $ como prefixo de valores do pedido. Use apenas números para indicar o preço ou valor de um pedido. Usar o cabeçalho $value vai preencher os dados corretamente na sua conta da Klaviyo.
O motivo para incluir 2 métricas é que isso facilita, mais tarde, disparar e-mails com base tanto em um pedido geral quanto em categorias/itens específicos.
Para eventos de Ordered Product, $event_id precisa ser um identificador exclusivo para cada combinação do pedido e do produto solicitado. Uma forma fácil de criar um identificador exclusivo é combinar o ID do pedido e o ID do produto, como no exemplo acima.
Solução de problemas de importação
Abaixo estão alguns problemas comuns e resoluções que você pode encontrar ao importar manualmente dados históricos de eventos.
Minha importação está demorando muito
As importações podem levar entre 5 minutos e 24 horas, dependendo do tamanho do seu arquivo. Recomendamos iniciar a importação pelo menos 24 horas antes de você precisar dos dados para uma campanha, para que o processo de importação não atrase o envio.
Minha importação falha ou pula linhas
Se o upload do seu arquivo falhar ou se algumas linhas não forem importadas, verifique o seguinte:
- Seu arquivo é um arquivo .csv? Seu arquivo deve estar em .csv formato. Se você tentar fazer upload de um arquivo do Excel ou de um .txt arquivo, a importação falhará.
- Você formatou sua coluna Timestamp corretamente? Use o formato de data e hora YYYY-MM-DD HH:MM:SS. Por exemplo, 13:30 de 14 de novembro de 2012 seria: 2012-11-14 13:30:00. Como uma segunda verificação, abra seu CSV em um editor de texto para garantir que zeros finais (0) nos seus timestamps não sejam removidos ao salvar ou exportar seus arquivos CSV. Se você estiver trabalhando com dados em uma planilha, verifique se as células Timestamp estão definidas com o formato de timestamp correto.

- Todas as colunas obrigatórias têm dados preenchidos em todas as linhas? Inclua uma coluna Timestamp e pelo menos 1 de Person//Email ou Person//ID. Cada linha precisa de um carimbo de data/hora e um identificador do cliente. Se você incluir Person//Email, todas as linhas deverão ter um endereço de e-mail válido, mesmo que Person//ID também esteja presente.
- A sua coluna Person//Email tem endereços de e-mail inválidos? Se os valores na sua coluna Person//Email não estiverem em um formato de endereço de e-mail válido, essas linhas serão ignoradas.
- Todas as suas colunas estão rotuladas corretamente? Faça a correspondência exata entre
Timestampe o cabeçalho do identificador de cliente escolhido (Person//EmailouPerson//ID), incluindo maiúsculas e minúsculas. Remova os espaços extras antes ou depois desses cabeçalhos. São permitidos espaços dentro dos nomes de propriedades, como emPerson//First NameouItem Purchased.
Recursos adicionais
- Formatos aceitáveis de data e carimbo de data/hora para referência de Propriedades do perfil e propriedades de eventos
Saiba quais formatos de data e hora a Klaviyo reconhece em dados de eventos e de perfil enviados pelas nossas APIs ou em um upload de CSV. Observe que isso não se aplica a um carimbo de data/hora de evento enviado pela Track API, que deve ser o horário Unix em segundos.
- Referência de formatação de datas para arquivos CSV
Saiba como editar datas em arquivos do Excel e do Google para corresponder ao formato de data exigido no Klaviyo. Isso tornará o processo de upload de um CSV com dados de clientes mais simples e ajudará você a evitar erros de upload.
- Migrate to Klaviyo