Para una migración puntual, con datos ya limpios y relaciones relativamente simples, un archivo CSV suele ser suficiente. La API conviene cuando necesitas repetir cargas, procesar grandes volúmenes, ejecutar deltas, aplicar transformaciones dinámicas o integrar HubSpot con otros sistemas.
En proyectos complejos, la mejor opción suele ser híbrida: archivos para la carga masiva y API para control, actualización y sincronización.
La comparación parece sencilla: archivo manual contra desarrollo técnico. En realidad, HubSpot ofrece tres caminos distintos:
Esta distinción importa porque “usar API” no siempre significa procesar un contacto por llamada. La Imports API permite automatizar una migración basada en archivos y manejar volúmenes superiores a los del importador manual.
Por eso, la decisión no debería basarse en qué método parece más avanzado. Debe responder al volumen, la complejidad, la repetibilidad y el nivel de control que necesita el proyecto.
El importador de HubSpot funciona bien cuando la migración es puntual, los archivos ya fueron transformados y el equipo necesita revisar visualmente el mapeo antes de ejecutar la carga.
Según HubSpot, las cuentas con Smart CRM o suscripciones Starter, Professional o Enterprise pueden importar archivos de hasta 512 MB, ejecutar hasta 500 importaciones y cargar hasta 10 millones de filas dentro de un periodo móvil de 24 horas. Cada archivo puede contener un máximo de 1.048.576 filas.
El CSV es especialmente útil cuando:
El importador también permite trabajar con varios objetos y asociarlos mediante una columna común.
Por ejemplo, puedes importar contactos y empresas en archivos separados y utilizar una clave compartida para conservar su relación. HubSpot indica que las etiquetas de asociación durante estas importaciones requieren una suscripción Professional o Enterprise.
Su mayor ventaja es la visibilidad. El equipo puede revisar propiedades, formatos y errores sin construir una solución técnica completa.
Su mayor debilidad también es humana: alguien debe preparar, nombrar, mapear, cargar y validar cada archivo. Un CSV mal diseñado sigue siendo una forma muy eficiente de importar errores.
La API gana valor cuando la migración debe ser reproducible, automatizada o conectada con varios sistemas.
También es la opción adecuada cuando necesitas ejecutar cargas delta, registrar cada operación, reintentar errores, controlar dependencias o transformar datos durante el proceso.
Según la documentación oficial de HubSpot actualizada en marzo de 2026, la Imports API admite hasta 80 millones de filas por día. Cada archivo mantiene un límite de 1.048.576 filas o 512 MB, lo que ocurra primero.
HubSpot recomienda dividir la carga en varias solicitudes cuando se aproxima a esos límites.
La API conviene cuando:
No obstante, una API no elimina la necesidad de diseñar el modelo de datos. Solo automatiza la ejecución.
Si las reglas de transformación son incorrectas, el error llegará más rápido y con excelente consistencia. No es exactamente el tipo de eficiencia que buscas.
La Imports API está pensada para cargas masivas basadas en archivos. Resulta útil cuando ya tienes los conjuntos de datos preparados y quieres automatizar su envío, seguimiento y procesamiento.
Las APIs de objetos permiten trabajar con contactos, empresas, negocios, tickets y otros registros de forma más granular.
Son adecuadas para actualizaciones dinámicas, integraciones continuas o lógica registro por registro.
Según HubSpot, los endpoints batch de las APIs de objetos están limitados a 100 registros por solicitud. Una migración masiva ejecutada únicamente mediante estos endpoints puede requerir muchas más llamadas, además de gestión de límites, errores y reintentos.
En 2026, HubSpot también introdujo APIs versionadas por fecha.
La referencia actual utiliza la versión 2026-03, y HubSpot recomienda emplear la versión más reciente en integraciones nuevas. Cada proyecto debería documentar qué versión utiliza para facilitar futuras actualizaciones.
|
Criterio |
Importador CSV |
Imports API |
API de objetos |
|
Ejecución |
Manual |
Automatizada |
Automatizada |
|
Mejor uso |
Carga puntual |
Migración masiva repetible |
Integraciones y deltas |
|
Transformación dinámica |
Limitada |
Previa al archivo |
Alta |
|
Control por registro |
Medio |
Medio |
Alto |
|
Reintentos automáticos |
No nativos |
Programables |
Programables |
|
Complejidad técnica |
Baja |
Media |
Alta |
|
Trazabilidad |
Historial de importación |
IDs y estados de importación |
Logs propios |
|
Velocidad de implementación |
Alta |
Media |
Menor |
La tabla muestra que cada uno resuelve un problema distinto.
Ninguno corrige por sí solo datos mal preparados. Con archivos, HubSpot permite detectar errores durante el mapeo y corregir algunos valores antes de finalizar la importación.
También genera detalles para revisar problemas relacionados con formatos, propiedades obligatorias, asociaciones, propietarios, fechas e identificadores únicos.
Con API, el equipo puede validar reglas antes de enviar datos, guardar las respuestas, separar excepciones y reintentar únicamente los registros fallidos.
La diferencia está en la escala.
Corregir veinte errores manualmente puede ser razonable. Corregir veinte mil deja de ser una tarea y se convierte en una condena administrativa.
En ambos métodos necesitas:
La herramienta ejecuta la carga. No sustituye la arquitectura ni la validación.
En migraciones medianas y empresariales, elegir exclusivamente CSV o API puede ser una falsa disyuntiva.
Una arquitectura híbrida puede utilizar:
Este enfoque evita procesar millones de registros uno por uno y conserva control sobre los cambios que ocurren durante la transición.
También permite ejecutar primero una carga piloto, después un ensayo completo y finalmente el lote de producción con los cambios generados durante el periodo de convivencia.
La API no hace que una migración sea profesional y el CSV no la convierte en básica. La calidad depende del diseño, las pruebas y la capacidad de repetir el proceso sin improvisar.
Utiliza CSV cuando los datos estén preparados, la carga sea puntual y el equipo pueda validar el proceso de forma controlada.
Elige la Imports API cuando necesites automatizar grandes volúmenes, y utiliza las APIs de objetos cuando requieras cargas delta, lógica granular o integración continua.
Si el proyecto incluye varios sistemas, asociaciones complejas o una ventana de corte ajustada, probablemente necesitarás combinar los tres enfoques.
Si estás preparando una migración y no sabes qué método utilizar, agenda una sesión con el equipo de Epic Danta. Revisaremos el volumen, las relaciones y las integraciones para diseñar una estrategia de carga que puedas probar, reconciliar y ejecutar sin convertir el go-live en una apuesta.