Importaciones
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:
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 deseasUPSERT
(crear y actualizar),CREATE
oUPDATE
registros. Por ejemplo, el campo se vería así en tu solicitud:"importOperations": {"0-1": "CREATE"}
. - 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 usarDAY_MONTH_YEAR
oYEAR_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 valorfalse
. - 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 deSPREADSHEET
.
- 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 valoresobjectTypeId
.
- columnName: el nombre del título de la columna.
- propertyName: el nombre interno de la propiedad HubSpot a la que se asignarán los datos.
- idColumnType: se utiliza para especificar que una columna contiene una propiedad de identificador única. Dependiendo de la propiedad, usa 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.
A continuación, se muestra un cuerpo de solicitud de ejemplo de importación para crear contactos:
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 estadosSTARTED
,PROCESSING
oDEFERRED
.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.
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 more general errors, such as 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 column order in the request body and import file should match, and every column needs to be mapped. - Ensure that the file's name and the
fileName
field in your request JSON match, and that you've included the file extension in thefileName
field. For example, import_name.csv. - Ensure that your header includes
Content-Type
with a value ofmultipart/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.
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.
Gracias por tus comentarios, son muy importantes para nosotros.