Exportando Corretamente do HubSpot: O Que o Export Nativo Deixa Para Trás

Uma equipe de RevOps executou uma migração exemplar. Quarenta mil contatos exportados de forma limpa, empresas correspondidas, estágios de negócio mapeados corretamente. No day one no novo CRM, os reps abriram seus registros de negócio e não encontraram nenhum contato vinculado. Nem um único link de negócio para contato tinha sobrevivido à migração.

O culpado foi o export nativo do HubSpot. Ele exporta Contatos. Exporta Empresas. Exporta Negócios. Mas não exporta as associações entre eles. Essas ficam em uma camada de dados separada que a ferramenta de export padrão não toca. A equipe de vendas perdeu o contexto do Pipeline no day one porque ninguém sabia que precisava perguntar sobre as associações.

Este guia cobre tudo que o export via interface deixa para trás e como obtê-lo antes de migrar.

---

Como os Dados do HubSpot Funcionam Internamente

O HubSpot organiza os dados em objetos e associações. Entender os dois é o que separa um export completo de um quebrado.

Objetos:

• Contatos: pessoas físicas
• Empresas: organizações (o equivalente a Contas no HubSpot)
• Negócios: oportunidades de venda em um Pipeline
• Tickets: registros de suporte ou atendimento
• Objetos personalizados: qualquer coisa que seu portal tenha construído além dos quatro padrão

Associações são uma camada de dados separada. Um Contato pode estar associado a uma Empresa, a um Negócio e a um Ticket simultaneamente. Mas nenhum desses links fica dentro do próprio registro do Contato. Eles são armazenados no grafo de associações do HubSpot. Quando você exporta um Contato para CSV, as associações não vêm junto. A documentação da API de Associações do HubSpot CRM explica o modelo completo de objetos de associação e como recuperar os dados de relacionamento programaticamente.

Eventos de timeline são o registro de atividades. Cada e-mail enviado, ligação registrada, reunião agendada e submissão de formulário fica na timeline de um contato. Esses também são separados do registro de Contato e exigem métodos diferentes de export.

Conhecer essa arquitetura desde o início explica por que um processo de export em três etapas é necessário, não opcional. E isso define como você aborda o mapeamento de campos entre o HubSpot e seu sistema de destino: as associações são um desafio de mapeamento separado das propriedades dos objetos.

---

Etapa 1: Export Nativo: O Que Cobre e Quando Usar

O export nativo do HubSpot (Contatos > Exportar, Negócios > Exportar, etc.) fornece CSVs planos dos seus registros de objetos. É confiável para contagens de registros e propriedades principais. É o ponto de partida certo.

O que o export nativo cobre bem:

• Todas as propriedades de contatos (padrão e personalizadas)
• Todas as propriedades de empresas
• Todas as propriedades de negócios, incluindo Pipeline e estágio
• Todas as propriedades de tickets
• Valores de propriedades personalizadas em qualquer objeto

O que incluir em cada export:

Quando o HubSpot pedir para você selecionar as propriedades a exportar, não aceite a seleção padrão. Escolha "Todas as propriedades" ou selecione manualmente cada propriedade que você quer. Exports padrão frequentemente omitem propriedades personalizadas a menos que você as inclua explicitamente.

O que o export nativo não cobre:

• Associações Contato-Empresa
• Associações Contato-Negócio
• Associações Negócio-Empresa
• Associações entre múltiplos objetos (um Negócio associado a múltiplos Contatos)
• Registros de engajamento (ligações, e-mails, reuniões, notas)
• Registros de objetos personalizados

Use o export nativo para obter seus arquivos de registros base. Em seguida, trate as associações e o histórico de engajamento separadamente. Antes de começar, confirme seu escopo com as orientações em preparando seus dados antes de migrar qualquer coisa: as decisões que você toma lá determinam quais propriedades do HubSpot realmente importam.

Comparação dos métodos de export:

---

Etapa 2: Exportar Associações Separadamente

Os dados de associação do HubSpot exigem a API ou uma configuração específica de export. Veja as duas opções.

Opção A: usar o export de Associações dentro do HubSpot

Ao exportar Contatos, procure uma opção "Incluir registros associados" no diálogo de export. Em algumas versões do portal, o HubSpot permite incluir o nome da Empresa e o nome do Negócio associados no export de Contatos. Verifique se a versão do seu portal suporta isso. Se suportar, economiza uma chamada de API.

Mas atenção: "incluir nomes associados" não é o mesmo que exportar o grafo completo de associações. Você obterá Empresa.Nome e Negócio.Nome na linha do Contato, mas não um mapeamento adequado de muitos para muitos de quais Contatos estão em quais Negócios.

Opção B: obter associações via API do HubSpot

A API de Associações retorna todos os pares de associações para um determinado tipo de objeto. Um membro técnico da equipe (ou alguém de RevOps familiarizado com ferramentas de API como o Postman) pode extrair isso programaticamente.

Os principais endpoints:

• GET /crm/v4/associations/contacts/companies/batch/read: pares Contato-Empresa
• GET /crm/v4/associations/contacts/deals/batch/read: pares Contato-Negócio
• GET /crm/v4/associations/deals/companies/batch/read: pares Negócio-Empresa

Exporte-os como arquivos separados e trate-os como tabelas de junção. No CRM de destino, você usará esses arquivos para restabelecer os relacionamentos após importar os registros base.

Se você não tiver recursos de desenvolvimento:

Ferramentas como Coupler.io, Supermetrics e o próprio Data Sync do HubSpot conseguem exports estruturados que incluem dados de associações sem programação de API. São mais lentas e às vezes custam mais, mas são genuinamente úteis para equipes não técnicas. Depois de ter os dados de associações, testando a migração com uma importação paralela é como você verifica se as associações estão intactas antes de comprometer com a migração completa.

---

Etapa 3: Exportar Histórico de Engajamento e Atividades

O HubSpot chama as atividades registradas de "engajamentos" e as armazena em uma timeline separada do registro do contato. Esses dados não podem ser exportados via export padrão da interface. Exigem a API.

O que conta como dado de engajamento:

• Ligações registradas (com notas e resultado)
• E-mails registrados
• Reuniões agendadas e realizadas
• Notas adicionadas manualmente pelos reps
• Tarefas com dados de conclusão
• Submissões de formulários

O que a timeline também contém (geralmente ignore):

• Eventos de abertura e clique de e-mail (registrados automaticamente pelo rastreamento do HubSpot)
• Eventos de visualização de página
• Histórico de inscrições em Workflows

A primeira categoria são dados inseridos pelos reps: contexto real de vendas. A segunda categoria são dados de eventos gerados pelo sistema. Na maioria das migrações, você quer a primeira e deve ignorar a segunda. Migrar centenas de milhares de eventos de visualização de página cria ruído no CRM de destino sem nenhum valor de negócio.

Endpoint de API:

GET /crm/v3/objects/engagements retorna registros de engajamento com seu tipo (CALL, EMAIL, MEETING, NOTE, TASK), IDs de contato/empresa/negócio associados e o conteúdo do engajamento.

Alternativa prática para equipes não técnicas:

Se você não consegue acessar a API, documente a decisão explicitamente: você não vai migrar o histórico de engajamento, e o portal de origem do HubSpot continuará acessível em modo read-only por 90 dias após a migração para quem precisar de contexto histórico. Um relatório de pesquisa da Forrester sobre migração de dados de CRM observa que a completude do histórico de engajamento está entre os cinco principais fatores que determinam a velocidade de adoção pelos reps após uma troca de CRM. É uma decisão legítima de negócio. Nem toda migração precisa carregar o histórico completo de engajamento. O fundamental é tomar a decisão de forma intencional, e não descobrir a lacuna após o go-live. Para tudo que você decidir não migrar, arquivamento de longo prazo de dados legados do CRM cobre como manter o acesso sem pagar o licenciamento completo do HubSpot indefinidamente.

---

Etapa 4: Lidar com Objetos Personalizados

Se o seu portal HubSpot tem objetos personalizados (comum em portais customizados para Workflows específicos do setor), esses objetos exigem seu próprio processo de export.

Como verificar se o seu portal tem objetos personalizados:

Configurações > Objetos > Objetos personalizados. Se não houver nada aqui, pule esta seção.

Exportando objetos personalizados:

Objetos personalizados no HubSpot não podem ser exportados via export padrão da interface. As opções são:

1. API do HubSpot: mesmo padrão dos objetos padrão. Use GET /crm/v3/objects/{customObjectType} com o nome interno do objeto personalizado.
2. HubSpot Data Sync: a ferramenta de sincronização nativa do HubSpot pode exportar para planilhas ou bancos de dados, incluindo objetos personalizados.
3. Conectores de terceiros: ferramentas como Airbyte ou Fivetran têm conectores HubSpot que lidam com objetos personalizados nativamente.

Para a maioria das equipes sem um engenheiro de dados dedicado, um conector de terceiros é a abordagem mais confiável para exports de objetos personalizados.

---

Etapa 5: Valide a Completude Antes de Sair do HubSpot

Não comece a limpar ou importar até ter verificado que o export cobre tudo que deveria. Uma validação de 30 minutos agora previne semanas de reconciliação depois.

Checklist de validação:

• Contagem de Contatos no CSV corresponde ao total de contatos do HubSpot (Configurações > Padrões da Conta > Contatos)
• Contagem de Empresas no CSV corresponde ao total de empresas do HubSpot
• Contagem de Negócios no CSV corresponde ao total de negócios do HubSpot (verifique por Pipeline se houver múltiplos Pipelines)
• Arquivos de export de associações existem para: Contato-Empresa, Contato-Negócio, Negócio-Empresa
• Definições de propriedades personalizadas exportadas (Configurações > Propriedades: exporte a lista de propriedades separadamente)
• Export de engajamento cobre os tipos principais: ligações, e-mails, reuniões, notas
• Campos de GDPR/opt-out incluídos no export de Contatos (procure por "Opt-out de e-mail", "Base legal para processamento", campos de "Consentimento GDPR")
• Campo de ciclo de vida incluído no export de Contatos

Verificação de amostra de associações:

Escolha 10 Negócios do seu export. Para cada um, verifique:

1. Os IDs de Contato no seu arquivo de associações correspondem a contatos no export de Contatos
2. Os IDs de Empresa correspondem a empresas no export de Empresas
3. Conte o número de Contatos por Negócio: parece correto comparando com a interface do HubSpot?

Inconsistências aqui significam que o export de associações está incompleto. Corrija antes de limpar.

Completude das propriedades personalizadas:

Exporte suas definições de propriedades (Configurações > Propriedades > Download) e compare os nomes das propriedades com os cabeçalhos de coluna do seu CSV. Colunas ausentes indicam propriedades que não foram incluídas no export. Repita com essas propriedades adicionadas.

---

Armadilhas Comuns

Exportar contatos sem empresas. Se os registros de Empresa não estiverem no export, cada Contato perde a associação com a empresa. Exporte Empresas primeiro, depois Contatos com Empresa.Nome incluído.

Perder o histórico do ciclo de vida. O campo Ciclo de vida é atualizado ao longo do tempo, mas o HubSpot armazena apenas o valor atual, não o histórico de quando mudou. Se a progressão do ciclo de vida importa para a configuração do CRM de destino, documente os valores do estado atual no momento do export. Você não pode recuperar o histórico depois.

Esquecer as definições das propriedades personalizadas. Ao importar no CRM de destino, você precisará recriar todas as suas propriedades personalizadas. O HubSpot permite exportar a lista de definições de propriedades, não apenas os valores. Baixe: vai economizar horas durante o mapeamento de campos.

Esquecer os flags de consentimento GDPR. Se o seu portal rastreia consentimento de e-mail ou base legal de GDPR, esses campos precisam estar no seu export. Eles não aparecem nas colunas de export padrão. Adicione-os explicitamente. Perder registros de consentimento pode criar problemas de conformidade no sistema de destino. A visão geral do GDPR na Wikipedia cobre as categorias de base legal e as obrigações de direito ao apagamento que se aplicam aos dados de contatos do CRM.

Não considerar registros deletados. O HubSpot não tem uma lixeira facilmente acessível via export. Se você precisar migrar registros que foram deletados, precisará trabalhar com o suporte do HubSpot ou usar o endpoint de registros arquivados da API.

---

O Que Fazer a Seguir

Um export validado do HubSpot significa que você tem arquivos de registros base mais dados de associações e engajamento. Mas nada disso está pronto para importação ainda.

O próximo passo é limpeza de dados: deduplicação, normalização e enriquecimento. As organizações no HubSpot acumulam duplicatas, valores de propriedades inconsistentes e problemas de formatação ao longo dos anos de uso. Limpe antes de importar. De acordo com os dados de mercado de CRM da Statista, mais de 91% das empresas com mais de 11 colaboradores usam software de CRM, e os desafios de qualidade de dados que se acumulam em instâncias de CRM com longa história são consistentes independente do fornecedor.

Se você estiver levando o histórico de engajamento adiante, lidando com atividades históricas, notas e e-mails cobre o framework de decisão sobre o que realmente migrar versus o que arquivar.

E se você ainda não terminou o inventário pré-migração, preparando seus dados antes de migrar qualquer coisa é onde essas decisões são tomadas antes do export começar.

---

Saiba Mais

• Limpeza de dados: deduplicação, normalização, enriquecimento
• Lidando com atividades históricas, notas e e-mails
• Preparando seus dados antes de migrar qualquer coisa
• Mapeamento de campos entre sistemas legados e novos
• Rollout e adoção do CRM: fazendo sua equipe realmente usá-lo
• Modelo de maturidade de RevOps: onde sua equipe está e o que vem a seguir