Importaciones

ResumenPuntos de terminación

Utiliza la API de importaciones para importar registros y actividades de CRM en tu cuenta de HubSpot, como contactos, empresas y notas. Una vez importado, puedes acceder y actualizar registros y actividades a través de los diversos puntos de terminación de la API de CRM, incluida la API de contactos, la API de asociaciones y las API de compromisos. También puedes importar registros y actividades usando la herramienta de importación guiada en HubSpot.

Antes de iniciar la importación, obtén más información sobre los objetos y las actividades que se pueden importar, así como los requisitos de archivos y propiedades.

Iniciar una importación

Puedes iniciar una importación realizando una solicitud POST a /crm/v3/imports con un cuerpo de solicitud que especifique cómo asignar las columnas de su archivo de importación a las propiedades de CRM asociadas en HubSpot.

Las importaciones de API se envían como solicitudes de tipo de datos de formulario, con el cuerpo de la solicitud que contiene los siguientes campos:

  • importRequest: un campo de texto que contiene la solicitud JSON.
  • files: un campo de archivo que contiene el archivo de importación.

Para el encabezado de solicitud, agrega un encabezado Content-Type con un valor de multipart/form-data.

La siguiente captura de pantalla muestra cómo podría verse tu solicitud cuando usas una aplicación como Postman:

postman-import-request-no-response0

Formatear los datos de importRequest

En la solicitud JSON, define los detalles del archivo de importación, incluida la asignación de las columnas de la hoja de cálculo a los datos de HubSpot. Tu solicitud JSON debe incluir los siguientes campos:

  • name: el nombre del campo. En HubSpot, este es el nombre que se muestra en la herramienta de importaciones, así como el nombre al que puedes hacer referencia en otras herramientas, como listas.
  • importOperations: un campo opcional utilizado para indicar si la importación debe crear y actualizar,solo crear o solo actualizar registros para un determinado objeto o actividad. Incluye el objectTypeId para el objeto/actividad y si deseas UPSERT (crear y actualizar), CREATE o UPDATE registros. Por ejemplo, el campo se vería así en tu solicitud: "importOperations": {"0-1": "CREATE"}. Si no incluyes este campo, el valor predeterminado utilizado para la importación es UPSERT.
  • dateFormat: el formato para las fechas incluidas en el archivo. Por opción predeterminada, esto se establece en MONTH_DAY_YEAR, pero también puedes usar DAY_MONTH_YEAR o YEAR_MONTH_DAY.
  • marketableContactImport: un campo opcional para indicar el estado de marketing de los contactos en tu archivo de importación. Esto se usa solo cuando se importan contactos a cuentas que tienen acceso a contactos de marketing. Para establecer los contactos en el archivo como marketing, usa el valor true. Para establecer los contactos en el archivo como no marketing, usa el valor false. 
  • createContactListFromImport: un campo opcional para crear una lista estática de los contactos de tu importación. Para crear una lista a partir de tu archivo, usa el valor true.
  • files: una matriz que contiene la información del archivo de importación.
    • fileName: el nombre del archivo de importación.
    • fileFormat: el formato del archivo de importación. Para los archivos CSV, usa un valor de CSV. Para los archivos de Excel, usa un valor de SPREADSHEET.
    • fileImportPage: contiene la matriz columnMappings necesaria para asignar datos de tu archivo de importación a datos de HubSpot. Más información sobre el mapeo de columnas a continuación.

Asignar columnas de archivo a propiedades de HubSpot

Dentro de la matriz columnMappings, incluye una entrada para cada columna en tu archivo de importación, que coincida con el orden de tu hoja de cálculo. Para cada columna, incluye los siguientes campos:

  • columnObjectTypeId: el nombre o el valor objectTypeId del objeto o la actividad a la que pertenecen los datos. Consulta este artículo para obtener una lista completa de valores objectTypeId.
  • columnName: el nombre del título de la columna.
  • propertyName: el nombre interno de la propiedad de HubSpot a la que se asignarán los datos. Para la columna común en las importaciones de varios archivos, propertyName debe ser null cuando se utiliza el campo toColumnObjectTypeId.
  • columnType: se utiliza para especificar que una columna contiene una propiedad de identificador único. Dependiendo de la propiedad y el objetivo de la importación, puedes utilizar uno de los siguientes valores:
    • HUBSPOT_OBJECT_ID: el ID de un registro. Por ejemplo, tu archivo de importación de contactos puede contener una columna ID de registro que almacena el ID de la empresa con la que deseas asociar los contactos. 
    • HUBSPOT_ALTERNATE_ID: un identificador único distinto del ID de registro. Por ejemplo, el archivo de importación de contactos puede contener una columna Correo electrónico que almacena las direcciones de correo electrónico de los contactos.
    • ASSOCIATION_KEYS: solo para las importaciones de asociación del mismo objeto, incluye este tipo de columna para el identificador único de los mismos registros de objeto que estás asociando. Por ejemplo, en tu solicitud de importación de una asociación de contactos, la columna Contacto asociado [email/Record ID] debe tener un columnType de ASSOCIATION_KEYS. Obtén más información sobre cómo configurar tu archivo de importación para una misma importación de asociación de objetos.
  • toColumnObjectTypeId: solo para importaciones de varios archivos, el nombre o objectTypeId del objeto al que pertenece la propiedad de columna común. Incluye este campo para la propiedad de columna común (y la columna de etiqueta de asociación si se usa) en el archivo del objeto al que no pertenece la propiedad. Por ejemplo, si estás asociando contactos y empresas en dos archivos con la propiedad de contacto Correo electrónico como columna común, incluye el toColumnObjectTypeId para la columna Correo electrónico en el archivo de empresa.
  • foreignKeyType: solo para importaciones de varios archivos, el tipo de asociación que debe usar la columna común, especificado por associationTypeId y associationCategory. Incluye este campo para la propiedad de columna común en el archivo del objeto al que no pertenece la propiedad. Por ejemplo, si estás asociando contactos y empresas en dos archivos con la propiedad de contacto Correo electrónico como columna común, incluye el foreignKeyType para la columna Correo electrónico en el archivo de empresa. 
  • associationIdentifierColumn: solo para importaciones de varios archivos, indica la propiedad utilizada en la columna común para asociar los registros. Incluye este campo para la propiedad de columna común en el archivo del objeto al que pertenece la propiedad. Por ejemplo, si estás asociando contactos y empresas en dos archivos con la propiedad de contacto Correo electrónico como columna común, establece la associationIdentifierColumn en true para la columna Correo electrónico en el archivo de contacto.

Importar archivo

A continuación, se muestra un cuerpo de solicitud de ejemplo de importación para crear contactos:

// 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" } ] } } ] }# 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) # 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 <<EOF { "name": "November Marketing Event Leads", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "import_file.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" } ] } } ] } EOF ) YOUR_ACCESS_TOKEN="xxx-xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" curl -v \ -F "files=@import_file.csv;type=text/csv" \ -F "importRequest=$myJSON;type=application/json" \ -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" \ https://api.hubapi.com/crm/v3/imports

Importar varios archivos

A continuación se muestra un ejemplo de cuerpo de solicitud de importación y asociación de contactos y empresas en dos archivos, donde la propiedad de contacto Correo electrónico es la columna común en los archivos:

// Example POST to https://api.hubspot.com/crm/v3/imports // Content-Type header set to multipart/form-data { "name": "Contact Company import", "dateFormat": "YEAR_MONTH_DAY", "files": [ { "fileName": "contact-import-file.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", "associationIdentifierColumn": true } ] } }, { "fileName": "company-import-file.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-2", "columnName": "Company name", "propertyName": "name" }, { "columnObjectTypeId": "0-2", "columnName": "Company domain name", "propertyName": "domain", "columnType": "HUBSPOT_ALTERNATE_ID" }, { "columnObjectTypeId": "0-2", "toColumnObjectTypeId": "0-1", "columnName": "Email", "propertyName": null, "foreignKeyType": { "associationTypeId": 280, "associationCategory": "HUBSPOT_DEFINED" } } ] } } ] }

En una solicitud exitosa, la respuesta incluirá un importId que puedes usar para recuperar o cancelar la importación. 

Obtener importaciones anteriores

Para recuperar todas las importaciones desde tu cuenta de HubSpot, haz una solicitud GET a /crm/v3/import/. Para recuperar información para una importación específica, haz una solicitud GET a /crm/v3/import/{importId}.

Cuando recuperes las importaciones, se devolverá la información, incluido el nombre de la importación, el origen, el formato de archivo, el idioma, el formato de fecha y las asignaciones de columnas. También se devolverá el state de la importación, que puede ser cualquiera de los siguientes:

  • STARTED: HubSpot reconoce que la importación existe, pero la importación aún no ha comenzado a procesarse.
  • PROCESSING: la importación se está procesando activamente.
  • DONE: la importación está completa. Todos los objetos, actividades o asociaciones han sido actualizados o creados.
  • FAILED: se produjo un error que no se detectó cuando se inició la importación. La importación no se completó.
  • CANCELED: el usuario canceló la exportación mientras estaba en cualquiera de los estados STARTED, PROCESSING o DEFERRED.
  • DEFERRED: el número máximo de importaciones (tres) se procesan al mismo tiempo. La importación comenzará una vez que una de las otras importaciones termine de procesarse.

Obtén más información sobre la paginación y la limitación de resultados en la pestaña Puntos de terminación en la parte superior de este artículo.

Nota: cuando recuperes importaciones usando un token de acceso a una aplicación privada, la respuesta solo incluirá las importaciones realizadas por esa aplicación privada. No se devolverán las importaciones realizadas en HubSpot o a través de otra aplicación privada.

Cancel an import

To cancel an active import, make a POST request to /crm/v3/imports/{importId}/cancel. 

View and troubleshoot import errors

To view errors for a specific import, make a GET request to /crm/v3/imports/{importId}/errors. Learn more about common import errors and how to resolve them.

For errors such as Incorrect number of columns, Unable to parse JSON or 404 text/html is not accepted:

  • Ensure that there is a column header for each column in your file, and that the request body contains a columnMapping entry for each column. The following criteria should be met:
    • The column order in the request body and import file should match. If the column order doesn't match, the system will attempt to automatically reorder but may be unsuccessful, resulting in an error when the import is started.
    • Every column needs to be mapped. If a column is not mapped, the import request may still be successful, but would result in the Incorrect number of columns error when the import is started.
  • Ensure that the file's name and the fileName field in your request JSON match, and that you've included the file extension in the fileName field. For example, import_name.csv.
  • Ensure that your header includes Content-Type with a value of multipart/form-data.

Nota: si recibes un error, comprueba si hay encabezados duplicados, como Content-Type. Esto puede ocurrir si estás usando Postman o si está incluido en el encabezado de tu script de Python. Elimina el duplicado antes de completar la solicitud. 

Límites

Al usar la API de importaciones, puedes importar hasta 80.000.000 filas por día. Sin embargo, los archivos de importación individuales están limitados a 1.048.576 filas o 512 MB, lo que se alcance primero.

Si tu solicitud supera el límite de fila o tamaño, HubSpot responderá con un error HTTP 429. Cuando te acerques a estos límites, se recomienda dividir tu importación en varias solicitudes.  

¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.