Importações

Use a API de importações para importar registros e atividades do CRM para sua conta da HubSpot, como contatos, empresas e observações. Depois da importação, você pode acessar e atualizar os registros e atividades por meio dos vários endpoints da API do CRM, incluindo as APIs de contato, APIs de associações e APIs de envolvimento. Você também pode importar registros e atividades usando a ferramenta de importação guiada no HubSpot.

Antes de iniciar a importação, saiba mais sobre os objetos e atividades que podem ser importados, bem como os requisitos de arquivo e propriedade.

Iniciar uma importação

Você pode iniciar uma importação fazendo uma solicitação POST para /crm/v3/imports com um corpo de solicitação que especifique como mapear as colunas do arquivo de importação para as propriedades do CRM associadas no HubSpot.

As importações de API são enviadas como solicitações de tipo de dados de formulário, com o corpo de solicitação contendo os seguintes campos:

• importRequest: um campo de texto que contém o JSON da solicitação.
• arquivos: um campo de arquivo que contém o arquivo de importação.

Para o cabeçalho da solicitação, adicione um cabeçalho de Content-Type com um valor de multipart/form-data.

A captura de tela a seguir mostra como a solicitação pode parecer ao usar um aplicativo como o Postman:

Formatar os dados de importRequest

No JSON da solicitação defina os detalhes do arquivo de importação, incluindo o mapeamento das colunas da planilha para os dados do HubSpot. O JSON da sua solicitação deve incluir os seguintes campos:

• nome: o nome da importação. No HubSpot, esse é o nome exibido na ferramenta de importação, bem como o nome que você pode usar em outras ferramentas, como listas.
• importOperations: um campo opcional usado para indicar se a importação deve apenas criar e atualizar, apenas criar ou apenas atualizar registros para um determinado objeto ou atividade. Inclua o objectTypeId do objeto/atividade e se deseja apenas UPSERT (criar e atualizar), CREATE ou UPDATE os registros. Por exemplo, o campo ficaria assim na solicitação: "importOperations": {"0-1": "CREATE"}. Se você não incluir este campo, o valor padrão usado para a importação será UPSERT.
• dateFormat: o formato para datas incluídas no arquivo. Por padrão, isso é definido para MONTH_DAY_YEAR, mas você também pode usar DAY_MONTH_YEAR ou YEAR_MONTH_DAY.
• marketableContactImport: o status de marketing dos contatos no arquivo de importação. Isso é usado apenas ao importar contatos para contas com acesso aos contatos de marketing. Para definir os contatos no arquivo como autorizados para marketing, use o valor true. Para definir os contatos no arquivo como não autorizados para marketing, use o valor false. 
• createContactListFromImport: um campo opcional para criar uma lista estática dos contatos da sua importação. Para criar uma lista a partir do seu arquivo, use o valor true.
• arquivos: uma matriz que contém as informações do arquivo de importação.
  
  • fileName: o nome do arquivo de importação.
  • fileFormat: o formato do arquivo de importação. Para arquivos CSV, use o valor CSV. Para planilhas do Excel, use o valor SPREADSHEET.
  • fileImportPage: contém a matriz columnMappings necessária para mapear os dados do seu arquivo de importação para os dados do HubSpot. Saiba mais sobre o mapeamento de colunas abaixo.

Mapear colunas de arquivo para propriedades do HubSpot

Na matriz columnMappings, inclua uma entrada para cada coluna no arquivo de importação, que corresponda à ordem da planilha. Para cada coluna, inclua os seguintes campos:

• columnObjectTypeId: o nome ou valor objectTypeId do objeto ou atividade ao qual os dados pertencem. Consulte este artigo para obter uma lista completa de valores objectTypeId.
• columnName: o nome do cabeçalho da coluna.
• propertyName: o nome interno da propriedade do HubSpot para a qual os dados serão mapeados. Para a coluna comum em importações de vários arquivos, o propertyName deve ser null quando o campo toColumnObjectTypeId é usado.
• columnType: usado para especificar que uma coluna contém uma propriedade de identificador exclusivo. Dependendo da propriedade e da meta da importação, use um dos seguintes valores:
  • HUBSPOT_OBJECT_ID: o ID de um registro. Por exemplo, o arquivo de importação de contatos pode conter uma coluna de ID do registro, que armazena o ID da empresa à qual você deseja associar os contatos. 
  • HUBSPOT_ALTERNATE_ID: um identificador exclusivo que não seja o ID do registro. Por exemplo, o arquivo de importação de contatos pode conter uma coluna de E-mail, que armazena os endereços de e-mail dos contatos.
  • ASSOCIATION_KEYS: apenas para as importações de uma mesma associação de objeto, inclua este tipo de coluna para o identificador exclusivo dos mesmos registros de objeto que você está associando. Por exemplo, na solicitação de importação de uma associação de contatos, a coluna Contato associado [e-mail/ID de registo] deve ter o columnType ASSOCIATION_KEYS. Saiba mais sobre como configurar o seu arquivo de importação para uma importação de mesma associação de objeto.
• toColumnObjectTypeId: apenas para importações de vários arquivos, o nome ou objectTypeId do objeto ao qual a propriedade de coluna comum pertence. Inclua esse campo para a propriedade de coluna comum (e coluna de rótulo de associação se estiver usando) no arquivo do objeto ao qual a propriedade não pertence. Por exemplo, se estiver associando contatos e empresas em dois arquivos com o E-mail da propriedade do contato como a coluna comum, inclua toColumnObjectTypeId para a coluna E-mail no arquivo da empresa.
• foreignKeyType: apenas para importações de vários arquivos, o tipo de associação que a coluna comum deve usar, especificada pelo associationTypeId e associationCategory. Inclua esse campo para a propriedade de coluna comum no arquivo do objeto ao qual a propriedade não pertence. Por exemplo, se estiver associando contatos e empresas em dois arquivos com o E-mail da propriedade do contato como a coluna comum, inclua foreignKeyType para a coluna E-mail no arquivo da empresa.
• associationIdentifierColumn: apenas para importações de vários arquivos, indica a propriedade usada na coluna comum para associar os registros. Inclua esse campo para a propriedade de coluna comum no arquivo do objeto ao qual a propriedade pertence. Por exemplo, se estiver associando contatos e empresas em dois arquivos com o E-mail da propriedade do contato como a coluna comum, defina associationIdentifierColumn como true para a coluna de E-mail no arquivo do contato.
  

Veja abaixo um exemplo do corpo de solicitação de importação de um arquivo para criar contatos:

Veja abaixo um exemplo de corpo de solicitação de importação e associação de contatos e empresas em dois arquivos, onde o E-mail da propriedade do contato é a coluna comum nos arquivos:

Em uma solicitação bem-sucedida, a resposta incluirá um importId, que poderá ser usado para recuperar ou cancelar a importação. 

Obter importações anteriores

Para recuperar todas as importações da sua conta da HubSpot, faça uma solicitação GET para /crm/v3/imports/. Para recuperar informações para uma importação específica, faça uma solicitação GET para /crm/v3/imports/{importId}.

Ao recuperar importações, as informações serão retornadas, incluindo o nome, a fonte, o formato de arquivo, o idioma, o formato de data e os mapeamentos de coluna da importação. O estado da importação também será retornado, que pode ser qualquer um dos seguintes:

• INICIADO: o HubSpot reconhece que a importação existe, mas a importação ainda não começou a ser processada.
  
• PROCESSANDO: A importação está sendo processada ativamente.
  
• CONCLUÍDO: A importação está completa. Todos os objetos, atividades ou associações foram atualizados ou criados.
  
• FALHOU: Ocorreu um erro que não foi detectado quando a importação foi iniciada. A importação não foi concluída.
  
• CANCELADO: o usuário cancelou a exportação enquanto estava em qualquer um dos estados INICIADO, PROCESSANDO ou DIFERIDO.
  
• DIFERIDO: O número máximo de importações (três) estão sendo processadas ao mesmo tempo. A importação começará assim que uma das outras importações terminar o processamento.

Saiba mais sobre a paginação e limitação de resultados na guia Endpoints, na parte superior deste artigo.

Ao usar a API de importações, você pode importar até 80.000.000 linhas por dia. No entanto, os arquivos de importação individuais são limitados a 1.048.576 linhas ou 512 MB, o que ocorrer primeiro.

Se a solicitação exceder o limite de linhas ou de tamanho, o HubSpot emitirá um erro 429 HTTP. Ao se aproximar desses limites, é recomendável dividir sua importação em várias solicitações.