> ## Documentation Index > Fetch the complete documentation index at: https://br.developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # API do CRM | Importações > **[Run in Postman](https://app.getpostman.com/run-collection/f30b00bcfdc29170b2e8)** > **Requisitos de escopo** # 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,](https://br.developers.hubspot.com/docs/guides/crm/understanding-the-crm) [APIs de associações](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md) e [APIs de envolvimento.](https://br.developers.hubspot.com/docs/api-reference/overview.md) Você também pode [importar registros e atividades usando a ferramenta de importação guiada no HubSpot](https://knowledge.hubspot.com/pt/import-and-export/import-objects). Antes de iniciar a importação, saiba mais sobre: * [Requisitos de arquivo](https://knowledge.hubspot.com/pt/import-and-export/set-up-your-import-file#file-requirements-and-technical-limits) * [Propriedades necessárias para importações de registros e atividades](https://knowledge.hubspot.com/pt/import-and-export/set-up-your-import-file#required-properties) * [Propriedades necessárias para importações de participantes de eventos de marketing](https://knowledge.hubspot.com/pt/integrations/import-marketing-event-participants#prepare-your-import-file) > [!WARNING] > > ### Observação: > > Para criar eventos personalizados ou associar eventos a registros, use o [API de eventos personalizados](https://br.developers.hubspot.com/docs/api-reference/events-send-event-completions-v3/guide.md) em vez de importar. ## Iniciar uma importação É possível iniciar uma importação fazendo uma `POST` solicitar `/crm/v3/imports` com um corpo de solicitação que especifica como mapear as colunas do seu arquivo de importação para as propriedades 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](#format-the-importrequest-data): um campo de texto que contém o JSON da solicitação. * [arquivos](#map-file-columns-to-hubspot-properties): um campo de arquivo que contém o arquivo de importação. Para o cabeçalho da solicitação, adicione um cabeçalho `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: ![postman-import-request-no-response0](https://br.hubspot.com/hubfs/Knowledge_Base_2021/Developer/postman-import-request-no-response0.png) ### Formatar dados de importRequest Em sua solicitação, defina os detalhes do arquivo de importação, incluindo o mapeamento das colunas da planilha para os dados do HubSpot. 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](https://knowledge.hubspot.com/pt/import-and-export/view-and-analyze-previous-imports), 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](https://knowledge.hubspot.com/pt/import-and-export/import-objects#choose-how-to-import) para um determinado objeto ou atividade. Inclua o `objectTypeId` para o objeto/atividade e, se você quiser `UPSERT` (criar e atualizar), `CREATE` ou `UPDATE` 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 como `MONTH_DAY_YEAR`, mas você também pode usar `DAY_MONTH_YEAR` ou `YEAR_MONTH_DAY`. * **marketableContactImport**: o [status de marketing](https://knowledge.hubspot.com/pt/records/marketing-contacts) dos contatos no arquivo de importação. Isso é usado apenas ao importar contatos para contas com [acesso aos contatos de marketing](https://knowledge.hubspot.com/pt/records/marketing-contacts#check-your-access-to-marketing-contacts). 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](https://knowledge.hubspot.com/pt/import-and-export/import-objects#create-list-from-import) 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 Dentro da matriz `columnMappings`, inclua uma entrada para cada coluna no seu arquivo de importação, correspondendo à ordem do cabeçalho da coluna da sua 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](https://br.developers.hubspot.com/docs/guides/crm/understanding-the-crm#object-type-id) para obter uma lista completa de valores `objectTypeId`. * **columnName:** o nome do cabeçalho da coluna. Isso deve corresponder exatamente ao nome do cabeçalho da coluna no arquivo. * **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](#import-multiple-files), `propertyName` deve ser `null` quando `toColumnObjectTypeId` é usado. * **columnType:** usado para especificar que uma coluna contém um [propriedade de identificador exclusivo.](https://knowledge.hubspot.com/pt/import-and-export/understand-the-import-tool#unique-identifiers) Dependendo da propriedade e do 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. * **FLEXIBLE\_ASSOCIATION\_LABEL**: inclua este tipo de coluna para indicar que a coluna contém rótulos de associação. * **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, em sua solicitação para uma importação de associação de contatos, a coluna *Contato Associado \\\[ID de e-mail/Registro]* deve ter um `columnType` de `ASSOCIATION_KEYS`. Saiba mais sobre como [configurar o seu arquivo de importação para uma importação de mesma associação de objeto](https://knowledge.hubspot.com/pt/import-and-export/set-up-your-import-file#same-object-association-imports). * **toColumnObjectTypeId**: para importações de [vários arquivos](#import-multiple-files) ou de vários objetos, o nome ou `objectTypeId` do objeto a que pertence a propriedade de [coluna comum](https://knowledge.hubspot.com/pt/import-and-export/set-up-your-import-file#import-associations-in-two-files) ou o rótulo de associação. 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 `toColumnObjectTypeId` para a coluna *E-mail* no arquivo da empresa. * **foreignKeyType**: apenas para [importações de vários arquivos](#import-multiple-files), 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](#import-multiple-files), 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. ## Importar um arquivo com um objeto Veja abaixo um exemplo do corpo de solicitação de importação de um arquivo para criar contatos: ```json example.json theme={null} // Example POST to https://api.hubspot.com/crm/v3/imports // Content-Type header set to multipart/form-data { "name": "November Marketing Event Leads", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } ``` ```python example.py theme={null} # This example a local file named 'test_import.csv' # This file contains a list of contact records to import. import requests import json import os url = "https://api.hubapi.com/crm/v3/imports" YOUR_ACCESS_TOKEN = 'xxxxxxx'; # Content-Type header will be set automatically by the requests library headers = { 'authorization': 'Bearer %s' % YOUR_ACCESS_TOKEN } data = { "name": "November Marketing Event Leads", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": True, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } datastring = json.dumps(data) payload = {"importRequest": datastring} current_dir = os.path.dirname(__file__) relative_path = "./test_import.csv" absolute_file_path = os.path.join(current_dir, relative_path) files = [ ('files', open(absolute_file_path, 'rb')) ] print(files) response = requests.request("POST", url, data=payload, files=files, headers=headers) print(response.text.encode('utf8')) print(response.status_code) ``` ```bash example.sh theme={null} # Using this endpoint requires using sending multi-part form encoded data. Here is an example curl request: # importing a file named import_file.csv # create a variable for the importRequest JSON myJSON=$(cat < [!WARNING] > > ### Observação: > > Ao recuperar importações, a resposta incluirá apenas importações realizadas pelo mesmo aplicativo. Importações concluídas na HubSpot ou por meio de outro aplicativo não serão devolvidas. ## Cancelar uma importação Para cancelar uma importação ativa, faça uma solicitação `POST` para `/crm/v3/imports/{importId}/cancel`. ## Exibir e solucionar erros de importação Para exibir erros de uma importação específica, faça uma solicitação `GET` para `/crm/v3/imports/{importId}/errors`. Saiba mais sobre [erros comuns de importação e como resolvê-los](https://knowledge.hubspot.com/pt/import-and-export/troubleshoot-import-errors). Para erros como *Número incorreto de colunas*, *Não é possível analisar* o JSON ou *404 texto/html não é aceito*: * Verifique se há um cabeçalho para cada coluna no arquivo e se o corpo da solicitação contém um `columnMapping` para cada coluna. Os seguintes critérios devem ser atendidos: * A ordem das colunas no corpo da solicitação e no arquivo de importação devem coincidir. Se a ordem das colunas não coincidir, o sistema tentará reclassificá-las automaticamente, mas poderá não ser bem-sucedido, resultando em um erro quando a importação for iniciada. * Cada coluna precisa ser mapeada. Se uma coluna não for mapeada, a solicitação de importação ainda poderá ser bem-sucedida, mas resultará no erro *Número incorreto de colunas* quando a importação for iniciada. * Verifique se o nome do arquivo e o campo `fileName` na sua solicitação JSON coincidem e se você incluiu a extensão de arquivo no campo `fileName`. Por exemplo, *import\_name.csv.* * Verifique se o cabeçalho inclui `Content-Type` com um valor de `multipart/form-data`. ```json example.json theme={null} Example POST URL: https://api.hubapi.com/crm/v3/imports? Example importRequest JSON data: This example contains 3 columns: - First name, mapped to the firstname contact property - Email, mapped to the email contact property - Company ID, which contains a list of company record IDs that the contact will be assocated with. { "name": "test_import", "files": [ { "fileName": "final_emails.csv", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "ignored": false, "columnName": "First Name", "idColumnType": null, "propertyName": "firstname", "foreignKeyType": null, "columnObjectType": "CONTACT", "associationIdentifierColumn": false }, { "ignored": false, "columnName": "Email", "idColumnType": "HUBSPOT_ALTERNATE_ID", "propertyName": "email", "foreignKeyType": null, "columnObjectType": "CONTACT", "associationIdentifierColumn": false }, { "ignored": false, "columnName": "Company ID", "idColumnType": "HUBSPOT_OBJECT_ID", "propertyName": null, "foreignKeyType": { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 1 }, "columnObjectType": "CONTACT", "associationIdentifierColumn": false } ] } } ] } ``` ```python example.py theme={null} # This example a local file named 'final_emails.csv' # This file contains a list of contact records to import. # Each row in the file contains a column named "Company ID" that contains the companyId # that the contact should be associated with. import requests import json post_url = 'http://api.hubapi.com/crm/v3/imports?hapikey=4324...5432' importRequest = { "name": "test_import", "files": [ { "fileName": "final_emails.csv", "fileImportPage": { "hasHeader": True, "columnMappings": [ { "ignored": False, "columnName": "First Name", "idColumnType": None, "propertyName": "firstname", "foreignKeyType": None, "columnObjectType": "CONTACT", "associationIdentifierColumn": False }, { "ignored": False, "columnName": "Email", "idColumnType": "HUBSPOT_ALTERNATE_ID", "propertyName": "email", "foreignKeyType": None, "columnObjectType": "CONTACT", "associationIdentifierColumn": False }, { "ignored": False, "columnName": "Company ID", "idColumnType": "HUBSPOT_OBJECT_ID", "propertyName": None, "foreignKeyType": { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 1 }, "columnObjectType": "CONTACT", "associationIdentifierColumn": False } ] } } ] ``` ```php example.php theme={null} $csv_file, "importRequest" => $config_json ); $ch = curl_init(); @curl_setopt($ch, CURLOPT_POST, true); @curl_setopt($ch, CURLOPT_URL, $post_url); @curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); $response = @curl_exec($ch); //Log the response from HubSpot as needed. $status_code = @curl_getinfo($ch, CURLINFO_HTTP_CODE); //Log the response status code @curl_close($ch); echo $status_code . " " . $response; ?> ``` ```bash example.sh theme={null} # Using this endpoint requires using sending multi-part form encoded data. Here is an example curl request: # importing a file named import_file.csv # create a variable for the importRequest JSON myJSON=$(cat < [!WARNING] > > ### Observação: > > Se você receber um erro, verifique se há algum cabeçalho duplicado, como `Content-Type`. Isso pode ocorrer se você estiver usando o Postman ou se ele estiver incluído no cabeçalho do seu script Python. Remova o objeto duplicado antes de concluir a solicitação. ## Limites 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.