Ir para o conteúdo principal
HubSpot Central de conhecimento
Isenção de responsabilidade de tradução: esse conteúdo foi traduzido para sua conveniência com o uso de software e pode não ter sido revisado por uma pessoa. O texto oficial é a versão em inglês e sempre será o texto mais atualizado. Para ver a versão em inglês, clique aqui.

Migrar contratos para o HubSpot

Ultima atualização: 23 de Julho de 2026

Disponível com qualquer uma das seguintes assinaturas, salvo menção ao contrário:

Assinatura necessária Uma assinatura do Revenue Hub é necessária para migrar contratos.

Licenças necessárias Uma licença do Revenue Hub é necessária para migrar contratos.

Permissões necessárias São necessárias permissões de superadministrador para realizar a migração.

Migre os contratos existentes de um sistema antigo para o HubSpot para gerenciar relatórios de cobrança, faturamento e receita. A migração preserva os métodos de pagamento, o histórico de contratos e as programações de cobrança futuras. Após a migração, você pode usar o HubSpot como fonte centralizada de informações para a receita comprometida. Saiba mais sobre como usar contratos no HubSpot.

Antes de começar

Antes de começar a trabalhar com esse recurso, certifique-se de compreender totalmente quais etapas devem ser executadas com antecedência, bem como as limitações do recurso e as possíveis consequências de usá-lo.

Noções básicas sobre os requisitos

Compreender limitações e considerações

  • Se estiver usando continuidade de receita, teste a importação em um ambiente de testes. Se dados incorretos forem importados para a sua conta, você não poderá corrigir os dados históricos nos relatórios de cascata de receita mensal recorrente.
  • Quando um contrato é ativado, o HubSpot se torna o sistema de registro para cobrança. A migração não pode ser desfeita.
  • Todas as atualizações de contrato devem ser feitas no HubSpot. Saiba mais sobre como exibir e gerenciar contratos.
  • Após a ativação, você pode atualizar a substituição da data de início da cobrança e a ID do método de pagamento somente se o contrato não tiver faturas ou pagamentos pagos.

Escolha o formato da migração

Antes de migrar, selecione um formato de migração com base em como você deseja que a HubSpot gerencie os contratos após a migração. O formato da migração depende do processo de coleta e se você deseja incluir eventos históricos de alteração de contrato (por exemplo, atualizações ou expansões).

Processo de cobrança de pagamento

  • Pagamentos manuais: após a migração, as faturas são geradas para os compradores pagarem manualmente.
  • Pagamentos automáticos: após a migração, as faturas são cobradas automaticamente usando um método de pagamento registrado.

Continuidade da receita

  • Sem continuidade de receita: os contratos são importados sem eventos de alteração de receita.
  • Continuidade de receita: use chaves de rampa para agrupar itens de linha em fases e exibir eventos de alteração (por exemplo, atualizações, expansões, rebaixamentos) na cascata de receita mensal recorrente no HubSpot. Se estiver usando continuidade de receita, teste a importação em um ambiente de testes. Se dados incorretos forem importados para a sua conta, você não poderá corrigir os dados históricos nos relatórios de cascata de receita mensal recorrente.

Rampas

Chaves de rampa

As chaves de rampa agrupam várias linhas de item de linha em fases. As linhas com a mesma chave de rampa são tratadas como uma rampa contínua.

No HubSpot, cada fase de rampa gera eventos de receita mensal recorrente (por exemplo, novos negócios, atualização, expansão) à medida que cada fase começa. A chave de rampa pode ser qualquer string de texto (por exemplo, ramp-a). A mesma string deve ser compartilhada em todas as linhas dessa rampa.

Estruturação de uma rampa

Para migrar rampas com êxito, estruture-as da seguinte maneira:

  • Intervalos de datas não sobrepostos: os termos de cada linha não devem se sobrepor aos termos de outra linha. Se as fases de rampa devem ser contínuas, cada fase deve começar quando a fase anterior terminar.
  • Vigências por fase: a vigência de cada linha abrange apenas essa fase do contrato, não a vigência completa do contrato.
  • Quantidade total em cada linha: insira a quantidade total do item de linha durante essa fase
  • ID de importação de chave de rampa: agrupa os itens de linha na mesma rampa. Saiba mais sobre como criar uma propriedade de rampa personalizada .

Observação:

  • Um contrato pode incluir itens de linha com e sem rampa. Para itens de linha sem rampa, deixe em ramp_key_import_id branco e use o mesmo import_unique_id que as linhas de contrato relacionadas.
  • Um contrato pode ter vários produtos que se movem independentemente. Cada produto deve ter o seu próprio ramp_key_import_id. Cada rampa gera seus próprios eventos de receita mensal recorrente.

Por exemplo, para um contrato de 12 meses com alteração de preço após três meses:

Item de linha Preço unitário Quantidade Vigência Data de início ramp_key_import_id
Serviço mensal US$ 100 1 3 meses 1 de Janeiro de 2026 ramp-a
Serviço mensal US$ 100 2 9 meses 1º de abril de 2026 ramp-a

Possíveis formatos de migração

Formato da migração Processo de coleta Continuidade da receita
Pagamentos manuais sem continuidade de receita Pagamentos manuais Não incluído
Pagamentos manuais com continuidade de receita Pagamentos manuais Inclui
Pagamentos automáticos sem continuidade de receita Pagamentos automáticos Não incluído
Pagamentos automáticos com continuidade de receita Pagamentos automáticos Incluído

Prepare-se para a migração

Antes de iniciar a migração, configure sua conta e prepare seu arquivo CSV com base no formato de migração selecionado.

Criar propriedades personalizadas

Crie as propriedades personalizadas obrigatórias antes de importar seu CSV. As propriedades que você precisa criar dependem do formato de migração selecionado. Saiba mais sobre a criação de propriedades personalizadas.

Formato da migração Objeto Nome da propriedade personalizada Tipo de propriedade personalizada Regras de validação Usado para
Todas as opções Contratos import_unique_id Texto de linha única Exigir valores exclusivos Agrupa todas as linhas que pertencem ao mesmo contrato.
Pagamentos manuais com continuidade de receita ou Pagamentos automáticos com continuidade de receita Itens de linha ramp_key_import_id Texto de linha única Nenhum Agrupa várias linhas de itens de item de linha em fases.

Configurar o arquivo CSV

Configure o arquivo CSV a ser usado com a ferramenta de importação para migrar contratos para o HubSpot.

Arquivos de exemplo CSV

Use os arquivos CSV de exemplo abaixo, dependendo do formato de migração em uso.

Formato da migração Link CSV
Pagamentos manuais, sem continuidade de receita Baixar
Pagamentos manuais com continuidade de receita Baixar
Pagamentos automáticos, sem continuidade de receita Baixar
Pagamentos automáticos com continuidade de receita Baixar
Misto: um produto de rampa e um produto de taxa fixa (sem chave de rampa) Baixar
Várias rampas independentes: Rampa do produto A (ramp-a) e do produto B (ramp-b) separadamente Baixar

Formato CSV

Seu CSV deve incluir as seguintes colunas e propriedades do HubSpot.

Nome da coluna Objeto Propriedade Detalhes
Data de vigência do contrato Contrato hs_contract_effective_date A data em que o contrato produz efeitos jurídicos.
Código da moeda Contrato hs_currency_code Código de moeda, como USD.
Nome Contrato hs_name Nome do contrato.
Cobrança do HubSpot habilitada Contrato hs_hubspot_billing_enabled Deve ser TRUE para todos os contratos que estão sendo migrados.
Processo de coleta Contrato hs_collection_process Manual ou automático. Deve estar alinhado com o formato da migração.
Substituição da data de início da cobrança Contrato hs_billing_start_date_override A data em que a HubSpot começa a faturar. Esta deve ser uma data futura ao migrar. Necessário para todos os formatos de migração.
ID do método de pagamento Contrato hs_external_payment_method_reference_id Deixe em branco para pagamentos manuais. Obrigatório para pagamentos automáticos.
E-mail Contato email O endereço de e-mail do contato de cobrança.
Nome Contato firstname Nome do contato de cobrança.
Sobrenome Contato lastname Sobrenome do contato de cobrança.
Produto Item de linha hs_product_id ID de Registro do produto. A migração faz referência a um registro de produto existente e não cria um novo produto
Item de linha nome Item de linha name Item de linha nome.
Preço unitário Item de linha price Preço unitário na moeda do contrato.
Quantidade Item de linha quantity A quantidade de item de linha durante uma fase.
import_unique_id Item de linha Propriedade personalizada ID compartilhado para todas as linhas no mesmo contrato.
Vigência Item de linha hs_recurring_billing_period O termo do item de linha. Ao usar rampas, insira o prazo para cada segmento.
Frequência de cobrança recorrente Item de linha recurringbillingfrequency Frequência de cobrança (por exemplo, mensal).
Item de linha data de início Item de linha hs_recurring_billing_start_date Data de início da cobrança do item de linha.
ramp_key_import_id Item de linha Propriedade personalizada Agrupa as fases do item de linha em uma rampa. Necessário para continuidade de receita. Deixe em branco para formatos de migração sem continuidade de receita.

Iniciar a migração

Depois de configurar seu CSV, você pode começar a migrar contratos para o HubSpot.

  1. Na sua conta HubSpot, clique em Mais e navegue até Receita > Contratos. Se Mais não aparecer na sua conta, navegue diretamente para Receita > Contratos.
  2. No canto superior direito, clique em Importar.
  3. Na seção Importar um arquivo , clique em Importar dados.
  4. Clique em Importações avançadas (todos os objetos).
  5. Em Objetos, clique em Contratos. O objeto de itens de linha será selecionado automaticamente.
  6. No canto inferior direito, clique em Próximo.
  7. Configure como deseja importar seus dados:
    • Carregar um arquivo: arraste e solte ou clique em Escolher um arquivo e selecione o arquivo de importação.
    • Copiar e colar: clique em Colar diretamente da planilha e cole seus dados. Os dados devem ser copiados de um arquivo de planilha (por exemplo, Numbers, Planilhas Google).
    • Idioma: se você estiver importando dados em um idioma diferente do idioma padrão, clique no menu suspenso Selecione o idioma dos cabeçalhos das colunas no arquivo e selecione o idioma. Selecionar o idioma correto permite que o HubSpot corresponda melhor seus cabeçalhos de coluna às propriedades padrão existentes. Se não houver correspondência no idioma selecionado, o HubSpot pesquisará uma propriedade em inglês para corresponder.
  8. No canto inferior direito, clique em Próximo.
  9. Mapeie as colunas do arquivo de importação às propriedades do HubSpot. Saiba mais sobre os mapeamentos de propriedades CSV.
  10. No canto inferior direito, clique em Próximo.
  11. No campo Nome da importação , insira um nome para a importação.
  12. Clique no menu suspenso Selecione a base jurídica para processar os dados de um contato e selecione uma base jurídica. Saiba mais sobre como rastrear a base jurídica para processar dados no HubSpot.
  13. Clique no menu suspenso Formato de data e selecione um formato de data.
  14. Em seguida, clique no menu suspenso Fuso horário e selecione um fuso horário.
  15. Clique no menu suspenso Formato de número e selecione um formato de número.
  16. Marque a caixa de seleção Definir estes contatos como contatos de marketing se quiser envolver os contatos importados usando as ferramentas de marketing da HubSpot. Saiba mais sobre contatos de marketing.
  17. Marque a caixa de seleção Enriquecer registros para enriquecer os registros durante a importação. Saiba mais sobre o enriquecimento de contatos e empresas.
  18. No canto inferior direito, clique em Concluir importação.

Solução de problemas

Revise erros comuns de importação e as etapas para resolvê-los. Se você encontrar outro erro, revise a formatação do CSV e os mapeamentos de propriedade e tente importar novamente.

Substituição da data de início da cobrança no passado

O erro Substituição da data de início da cobrança no passado ocorre quando a data de início da cobrança de um item de linha no CSV está no passado.

Para resolver esse erro:

  1. Atualize qualquer data de cobrança para uma data futura.
  2. Salve o CSV e inicie a importação novamente.

ID do método de pagamento do Stripe inválido ou ausente

Esse erro ocorre quando a opção de pagamentos automáticos é selecionada como processo de cobrança, mas um ID de método de pagamento do Stripe não foi adicionado ao arquivo CSV.

Para resolver esse erro:

  • Altere as entradas de pagamentos automáticos para pagamentos manuais.
  • Adicione um ID de método de pagamento do Stripe para entradas de pagamentos automáticos no CSV.

Duplicar import_unique_id de uma tentativa anterior

Se uma importação falhar, a HubSpot ainda poderá registrar os import_unique_id valores da importação com falha.

Para resolver esse erro:

  1. Atualize seu arquivo CSV com os novos IDs.
  2. Importe o arquivo CSV atualizado.

Glossário

Revise os seguintes termos antes de migrar contratos para o HubSpot.

Vigência Descrição
Pagamentos automáticos Um processo de cobrança em que as faturas são cobradas automaticamente usando um método de pagamento salvo.
Substituição da data de início da cobrança A data em que a HubSpot deve começar a cobrar o contrato migrado.
Processo de coleta Como os pagamentos são recebidos após a migração. Os pagamentos podem ser recebidos manualmente pelo comprador ou automaticamente usando um método de pagamento registrado.
import_unique_id Uma propriedade personalizada usada para agrupar linhas que pertencem ao mesmo contrato durante a migração.
Pagamentos manuais Um processo de cobrança em que as faturas são geradas no HubSpot e os compradores as pagam manualmente.
Formato da migração A estrutura CSV usada para a importação. O formato da migração depende de como os pagamentos serão recebidos e se você deseja incluir a continuidade da receita.
MRR Receita mensal recorrente. No HubSpot, a receita mensal recorrente é usada para relatar receitas recorrentes de contratos.
Cascata de receita mensal recorrente Um relatório de receita que mostra como a receita recorrente muda ao longo do tempo devido a eventos como novos negócios, atualizações, expansões, rebaixamentos e taxa de cancelamento de clientes.
ID do método de pagamento A referência do método de pagamento externo usado para contratos com pagamentos automáticos.
Rampa Uma alteração de preço ou quantidade que acontece ao longo de um contrato.
Chave de rampa Um valor usado para agrupar linhas de itens de linha relacionados em uma rampa.
Fase de rampa Um período dentro de uma rampa. Cada fase tem seu próprio prazo, preço, quantidade e data de início.
ramp_key_import_id Um item de linha propriedade personalizado usado para agrupar item de linha linhas em fases de rampa durante a migração.
Continuidade da receita Uma opção que inclui alterações de contrato históricas, como atualizações, expansões ou rebaixamentos, para que possam ser refletidas nos relatórios de receita.
Sistema de registro O sistema principal usado para gerenciar e manter informações de contrato e cobrança após a migração.
Esse artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot.

Conteúdo relacionado

Índice /pt/contracts/migrate-contracts-to-hubspot Menu

Conteúdo relacionado

New to HubSpot? Use these guides to get started.